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
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/...
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.
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.
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.
Garry Tan