mirror of https://github.com/garrytan/gstack.git
2 Commits
| Author | SHA1 | Message | Date |
|---|---|---|---|
Alex Evenson
|
2e19cf7ee5 |
fix(ios-qa): DebugBridge templates — clean install on Swift 6.x + no private SPI leak into Release
Fixes five template bugs that break a fresh `/ios-qa` DebugBridge install on
Swift 6.x toolchains, the most serious of which compiles private
UITouch/UIEvent/IOKit SPIs into iOS Release builds (App Store Guideline 2.1
rejection class).
1. gen-accessors-tool/Package.swift: drop the GenAccessorsTests testTarget —
Tests/ doesn't exist, so `swift build` failed with "invalid custom path".
2. Package.swift.template: move `// swift-tools-version:5.9` to line 1. Swift
6.0+ rejects a misplaced directive ("manifest is backward-incompatible with
Swift < 6.0").
3. Package.swift.template: drop the DebugBridgeCoreTests testTarget — never
populated by the installer; same invalid-custom-path failure.
4. Delete DebugBridgeWiring.swift.template — it imported a non-existent
`DebugBridge` module, referenced symbols that don't exist
(AccessibilityScanner/SnapshotCapture/MutationDispatcher), and called a
start(appState:recording:) overload that doesn't exist. Bridges.swift's
`DebugBridgeUIWiring.installAll()` already does the real wiring; updated the
DebugBridgeManager comment (template + fixture) to point there.
5. DebugBridgeTouch.m.template: gate the iOS impl behind
`#if TARGET_OS_IOS && defined(DEBUG)` (was `#if TARGET_OS_IOS`), and add a
cSettings DEBUG define to the DebugBridgeTouch target in
Package.swift.template. swiftSettings do not reach Obj-C translation units,
so the prior gate leaked the private SPIs into iOS Release binaries — the
exact failure that forced a DebugBridge removal downstream.
Fixture parity: applied the same .m gate + Package cSettings to the FixtureApp
so the template↔fixture parity test stays green, and added host-independent
static guards (gate present, cSettings present, tools-version on line 1) to
test/skill-e2e-ios-swift-build.test.ts — the iOS-Release leak can't be caught
by the macOS nm-scan since DebugBridgeTouch links UIKit.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
|
Garry Tan
|
1d9b9c4cfc
|
v1.43.0.0 feat: iOS device-farm (5 skills, Mac daemon, Tailscale) (#1574)
* feat(ios): author 5 iOS device-farm skill templates + generated docs
Authors ios-qa, ios-fix, ios-design-review, ios-clean, ios-sync as upstream gstack skills. Each follows the standard SKILL.md.tmpl pattern with preamble-tier:3 frontmatter. The fork at time-attack/gstack shipped these but as byte-identical .md/.tmpl pairs that wouldn't pass skill-docs.yml — this commit fixes that by authoring proper templates and regenerating through gen-skill-docs.
* feat(ios): Swift templates for StateServer + DebugOverlay v2 + structural Release guard
StateServer is loopback-only (::1 + 127.0.0.1) with boot-token rotation, per-device session lock (sliding on mutations only), snapshot/restore with schema-hash envelope, and 1MB body cap. DebugOverlay v2 has animated brand border + agent attribution chip (display-only) + recording watermark. Package.swift enforces structural Release-build exclusion via .when(configuration: .debug). Includes Tailscale ACL example doc.
* feat(ios): Mac-side daemon (bun/TS) for Tailscale identity gating + USB proxy
On-demand daemon spawns when /ios-qa needs it (single-instance flock + readiness protocol). Owns tailnet ingress: fail-closed tailscaled LocalAPI probe, dual-track /auth/mint (self-service for allowlisted identities, owner-granted via CLI), capability-tier allowlist (observe/interact/mutate/restore), 1h default session TTL (24h hard cap), audit log of every authenticated mutating tailnet request, hashed-identity attempts log. iOS StateServer never directly binds tailnet — identity validation lives Mac-side because iPhones can't reach tailscaled. 67 unit/integration tests covering session-lock concurrency, capability enforcement, fail-closed probe, identity canonicalization, body limits, and boot-token leak proofs.
* feat(ios): gen-accessors codegen tool (SwiftPM + TS port)
Replaces fork's regex-based codegen with SwiftPM swift-syntax tool (production) plus a TS port (test + fast first-run). Composite cache key: sha256(source || swift_version || tool_git_rev || platform_triple). Codex flagged that source-only hash misses generator-logic changes — this hash invalidates correctly across all four dimensions. 20 tests cover the 3 known regex failure modes (computed properties, generics, multi-line types) plus full cache hit/miss/prune coverage.
* test(ios): high-level E2E + touchfile registration
8 E2E scenarios: codegen against SwiftUI fixture, daemon spawn + stub StateServer, schema-mismatch rejection, full agent loop, multi-agent contention, tailnet allowlist gating, capability-tier enforcement. Registered as gate-tier in E2E_TOUCHFILES + E2E_TIERS so diff-based selection picks up iOS work without slowing every PR.
* chore: bump version and changelog (v1.40.0.0)
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* test(ios): real Swift compile + XCTest fixture; device-path probe; loopback bind fix
Closes the gap from prior commits where E2E tests stubbed the Swift StateServer
in TypeScript. Now there's a real SwiftPM fixture at test/fixtures/ios-qa/FixtureApp/
that compiles the production templates and runs an XCTest suite against the
actual StateServer implementation. Three new test layers:
- swift build invariants (periodic-tier): debug-config build succeeds, XCTest
suite passes (validates real Swift impl over Foundation + Network), release-config
build has zero DebugBridge symbols (structural #if DEBUG gate works end-to-end).
- Real-device probe (periodic-tier, GSTACK_HAS_IOS_DEVICE=1): devicectl can list
+ pair the connected iPhone. Surfaces actionable instructions when the trust
dialog hasn't been confirmed yet.
- Fixture sources copied from ios-qa/templates/ — Package.swift splits the
bridge into DebugBridgeCore (Foundation+Network, cross-platform) and
DebugBridgeUI (UIKit/SwiftUI, iOS-only) so swift build can validate the
bulk of the production code on macOS without an iPhone or simulator.
Also fixes a real bug the XCTest unit suite caught: NWListener with
requiredLocalEndpoint on params silently fails to bind for listening (it's
an outbound-connection concept). Replaced with .requiredInterfaceType=.loopback
+ .acceptLocalOnly=true + a per-connection peer-address check. The fork's
inherited code had this bug; we shipped it untouched in v1.41.0.0 and the
new XCTest suite caught it immediately.
* fix(ios): 3 architecture bugs surfaced by real-iPhone device test
End-to-end verification on a connected iPhone 17 Pro Max via CoreDevice
tunnel exposed three bugs the TS-stubbed and macOS-XCTest layers missed:
1. acceptLocalOnly=true was too tight. Network.framework's "local" gate
only allows ::1 / 127.0.0.1, silently dropping CoreDevice tunnel peers
(the very transport the architecture is designed for). The device log
showed "Ignoring non-local connection from fd72:8347:2ead::2" — the
Mac's tunnel-side address. Replaced with explicit per-connection ULA
gate (RFC 4193 fc00::/7) in isLoopbackPeer.
2. DebugBridgeCore (Foundation+Network) referenced DebugOverlayWindow
which lives in DebugBridgeUI (UIKit). Backwards module dep. Compiled
on macOS only because canImport(UIKit) stripped it; broke on iOS.
Moved the overlay install responsibility to the consuming app's
wiring (DebugBridgeWiring.swift.template already shows the pattern).
3. @Observable macro + @Snapshotable property wrapper conflict. Both
try to synthesize backing storage; can't coexist on the same property.
The production guidance is: nest snapshot-eligible state in a struct
inside an ObservableObject (or use the canonical-state-struct atomicity
strategy). Fixture switched to a plain class to demonstrate.
Smoke loop on the real device now passes 7/8 endpoints:
- /healthz (200), /tap unauth (401), /auth/rotate (200), boot-token reuse
rejected (401), /session/acquire (200), /state/snapshot (200 with schema
envelope), /session/release (200). /tap with valid session returns 200
HTTP + op:false because the FixtureApp doesn't wire MutationBridge.resolver
to a real UI tap — expected for a minimal fixture; the production wiring
template handles it.
Also adds:
- test/fixtures/ios-qa/FixtureApp/Sources/FixtureApp/FixtureAppApp.swift
(SwiftUI @main entry that boots StateServer)
- test/fixtures/ios-qa/FixtureApp/Sources/FixtureApp/Info.plist
- test/fixtures/ios-qa/FixtureApp/project.yml (xcodegen project spec
with DEVELOPMENT_TEAM 623FYQ2M88, bundle id com.gstack.iosqa.fixture)
End-to-end verified path:
xcodegen generate
xcodebuild -allowProvisioningUpdates -allowProvisioningDeviceRegistration
devicectl device install app
devicectl device process launch
devicectl device copy from --source tmp/gstack-ios-qa.token
curl -6 http://[<corodevice-ipv6>]:9999/...
* feat(ios): real daemon tunnelProvider + KIF-derived UITouch synthesis
Closes two layers of the device-control gap:
L1 — Mac daemon's tunnelProvider is now real, not a stub. New files:
- ios-qa/daemon/src/devicectl.ts: thin wrappers around `xcrun devicectl`
(list, info, launch, install, copy-from) with spawn+resolve injection
for unit testability.
- ios-qa/daemon/src/tunnel-bootstrap.ts: orchestrates find-device →
launch-app → resolve IPv6 → wait-for-healthz → copy-boot-token →
POST /auth/rotate → return DeviceTunnel with rotated bearer.
- ios-qa/daemon/test/tunnel-bootstrap.test.ts: 7 tests covering every
error branch (no_devices, no_paired_device, device_locked,
state_server_unreachable, resolve_failed, happy path, explicit-udid).
- index.ts wired to use bootstrapTunnel() when running as CLI; tests
keep using injected stubs.
L2 — In-process touch synthesis for non-UIControl widgets. New target
in the fixture SPM package:
- DebugBridgeTouch (Objective-C): KIF-derived UITouch + IOHIDEvent
synthesis. Loads IOKit dynamically via dlopen/dlsym (IOKit is a
private framework on iOS, can't link statically). Uses iOS 18+
_UIHitTestContext for SwiftUI hit-testing. Public Swift-callable
API: DebugBridgeTouch.sendTap(at:in:). MIT-attributed to
kif-framework/KIF.
- DebugBridgeUI/Bridges.swift: rewritten MutationBridge.handleTap to
delegate to DebugBridgeTouch. ScreenshotBridge + ElementsBridge
implementations also land here.
- FixtureApp/Sources/FixtureApp/FixtureAppApp.swift: wires the bridges
on app launch under #if DEBUG.
Real-iPhone evidence (Conductor sandbox → CoreDevice IPv6 → live app):
- /healthz returns 200 with on-device JSON body
- /screenshot returns 427KB PNG that decodes to your actual phone screen
- Boot-token rotation kills the original token (401 boot_token_invalid
on reuse — the load-bearing security property verified live)
- Session lock + auth gate (401/423/200 paths all work)
- Schema-versioned state envelope (_schema_version + _accessor_hash)
Known partial: synthesized UITouch reaches SwiftUI's host view per
device-side syslog ("non-local connection from fd...:2" earlier showed
the per-connection peer gate working), and HTTP returns 200 ok:true,
but SwiftUI Button onTap handler doesn't fire. UIControl widgets DO
work via UIControl.sendActions. Next step is attaching lldb to the
live app on device to diagnose which validation SwiftUI's gesture
recognizer is failing. The architectural primary path
(`POST /state/<key>` to mutate @Snapshotable fields) is unaffected
and is the recommended control vector.
Documented sources for the KIF-derived synthesis:
- https://github.com/kif-framework/KIF (MIT)
- UITouch-KIFAdditions.m: init flow with _setLocationInWindow:,
setGestureView:, _setIsFirstTouchForView:
- IOHIDEvent+KIF.m: digitizer event construction
- iOS 18+ _UIHitTestContext path for SwiftUI hit-testing
* fix(ios): SwiftUI Button synthesized tap on iOS 18+
DBT_HitTestView was filtering _hitTestWithContext: results by
isKindOfClass:UIView and dropping the new SwiftUI.UIKitGestureContainer
(a UIResponder, not UIView). SwiftUI Buttons live behind that container
on iOS 18+, so every synthesized tap returned ok:true but onTap never
fired.
Mirror KIF PR #1323: return id, pass the responder through to
UITouch.setView: directly (the setter accepts non-UIView responders).
Verified: real iPhone 17 Pro Max, iOS 26.5, FixtureApp counter
incremented 0 → 1 → 4 over four /tap requests at the button location.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(ios): hoist DebugBridgeTouch into canonical templates
Bridges.swift.template imports DebugBridgeTouch but no .m/.h template
shipped — consuming apps installing the canonical drop-in would hit a
linker error. Closes that gap with the fixture's verified working code.
Changes:
- New ios-qa/templates/DebugBridgeTouch.{h,m}.template files (carbon
copies of the fixture sources, including the iOS-18+ SwiftUI hit-test
fix verified on iPhone 17 Pro Max).
- Package.swift.template splits into 3 product targets: DebugBridgeCore
(Swift, cross-platform), DebugBridgeUI (Swift, iOS-only), DebugBridgeTouch
(Obj-C, iOS-only). Consuming app adds one dependency on DebugBridgeUI;
Core + Touch come in transitively.
- DebugBridgeTouch sources wrap their body in #if TARGET_OS_IOS so the
cross-platform `swift build` on macOS host doesn't choke on UIKit. On
iOS the real implementation is active; on macOS sendTapAtPoint: is a
no-op returning NO.
- New parity tests pin template ↔ fixture content so future fixture
fixes propagate or fail loudly.
- Restrict swift-build host tests to DebugBridgeCore (the only target
buildable on macOS) and bring up the previously broken XCTest run via
--filter.
Verified post-change: real iPhone 17 Pro Max, iOS 26.5, three /tap
requests against the rebuilt app — counter went 0 → 3, SwiftUI Button
onTap fires every time. Templates now sufficient to ship to any
consuming iOS app.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(ios): ship gstack-ios-qa-daemon + gstack-ios-qa-mint launchers
The skill doc has been telling users to run `gstack-ios-qa-daemon` and
`gstack-ios-qa-mint` since v1.41.0.0, but neither binary actually existed.
Anyone following the install flow hit "command not found" immediately
after the Swift template install.
Adds the missing pieces:
- bin/gstack-ios-qa-daemon — bash shim that execs
`bun run ios-qa/daemon/src/index.ts`. Loopback by default;
`--tailnet` to additionally open the Tailscale-facing listener with
capability-tier allowlist enforcement.
- bin/gstack-ios-qa-mint — owner-grant CLI for the tailnet allowlist
(grant / revoke / list). Writes ~/.gstack/ios-qa-allowlist.json at
mode 0600. Self-service POST /auth/mint reads from this file; remote
agents never auto-allowlist.
- ios-qa/daemon/src/cli-mint.ts — TS implementation behind the shim.
Handles --capability tier validation, --ttl expiry, --note metadata,
and --allowlist-path override for tests.
- ios-qa/daemon/src/allowlist.ts — treat empty files as "no entries
yet" (caught while writing the CLI tests; previously bombed with a
JSON parse error on the first grant against a freshly-mktemp'd path).
Tests: 7 new end-to-end launcher tests (--help shape, grant/list/revoke
roundtrip, missing --remote, unknown capability, --ttl persistence,
launcher executability, missing-bun preflight). All 81 daemon tests
pass.
This is the last gap between "templates installed" and "I can drive
any connected iPhone over USB or tailnet" — the user-facing CLI surface
now matches the install instructions byte-for-byte.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs: surface ios-qa CLIs + add end-to-end how-to walkthrough
The two CLIs that ship with the iOS device-farm capability —
gstack-ios-qa-daemon and gstack-ios-qa-mint — were mentioned only
inside ios-qa/SKILL.md. Anyone reading README or AGENTS to figure
out how to drive an iPhone hit a wall: skills are listed, binaries
aren't.
This commit closes the coverage gap surfaced by /document-release's
Diataxis audit:
- README.md, AGENTS.md: both CLIs added to the binary tables with
one-line capability summaries.
- docs/howto-ios-testing-with-gstack.md (new): end-to-end how-to —
prerequisites, architecture in one breath, install the templates,
build + install + launch on device, spin up the daemon, drive
the HTTP surface, optional Tailscale remote-agent mode via
gstack-ios-qa-mint, /ios-clean before release, common failures.
Pulled directly from the real iPhone 17 Pro Max / iOS 26.5
verification run.
- README + AGENTS link to the new how-to from the iOS skill row.
No CHANGELOG entry change — the consolidated 1.43.0.0 entry is /ship
work. No VERSION bump — already at 1.43.0.0 covering all branch work.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test(e2e-plan): tolerate transient error_api with zero-turn signature
GitHub Actions run 26170760809 failed on /plan-review-report (3 retries
all error_api, 1 turn, 0 tokens each) and /plan-ceo-review-expansion-energy
(1 transient failure, recovered on retry 2). The prior run on the same
branch (
|