gstack/skills/ship/references/legacy/ios-sync.md

Host-neutral runtime bindings

These assignments select stable paths only; they do not install anything or grant consent:

GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
GSTACK_ROOT="$GSTACK_HOME"
GSTACK_STATE_ROOT="$GSTACK_HOME"
GSTACK_BIN="$GSTACK_HOME/bin"
BUN_CMD="$GSTACK_BIN/bun"
B="$GSTACK_BIN/browse"
D="$GSTACK_BIN/gstack-design"
P="$GSTACK_BIN/make-pdf"

Resync the iOS debug bridge

After $qa --mode Report --module ios-qa is installed in an app, the user may:

1. Add new @Observable classes or properties that need accessor coverage.
2. Upgrade gstack to a newer version with hardening fixes.
3. Move the @Snapshotable marker to a different field.

This skill regenerates the relevant artifacts in place.

Templates live in upstream gstack. This skill resolves them from references/artifacts/ios-qa/templates/ (or the worktree's ios-qa/templates/ when developing gstack itself). The fork's HTTP-fetch pattern is gone.

Phase 1: Detect installed version

1. Read <app>/DebugBridgeGenerated/.gstack-version (written by $qa --mode Report --module ios-qa during install). If missing, treat the install as "unknown old version".
2. Read upstream version from the version reported by $GSTACK_BIN/gstack --version.
3. If versions match AND no new @Observable classes were added, exit early with "already up to date".

Phase 2: Regenerate codegen output

Run gstack-ios-qa-regen (or the underlying SwiftPM tool directly):

swift run --package-path "$($GSTACK_BIN/gstack runtime path ios-qa/scripts/gen-accessors-tool)" \
  gen-accessors --input "$APP_SOURCE_DIR" --output "$APP_SOURCE_DIR/DebugBridgeGenerated"

The composite-hash cache key handles whether anything actually needs regenerating; if Swift version, generator git rev, lockfile, source content, and platform triple all match the cache, this is a ~50ms no-op.

Phase 3: Update templated Swift files in place

For each file that comes from ios-qa/templates/*.swift.template:

1. Read the current installed file at <app>/DebugBridgeGenerated/<Name>.swift.
2. Read the upstream template at references/artifacts/ios-qa/templates/<Name>.swift.template.
3. If the installed file has a // GSTACK-EDIT-LINE marker, fold the user's edits forward.
4. Otherwise, replace the file outright with the new template (after AskUserQuestion if the diff is non-trivial).

Phase 4: Verify

1. swift build succeeds against the app's package.
2. xcodebuild -scheme <SchemeName> succeeds.
3. Re-launch the app on the device; daemon connects + rotates token.
4. GET /state/snapshot returns the new accessor schema hash.

Failure modes

Symptom	Action
Swift compile fails after regen	Revert via git restore + AskUserQuestion: surface the compile error
Schema hash unchanged after adding new @Observable	The new class isn't marked @Snapshotable — the codegen excludes it correctly. If the user wanted it snapshotted, add the wrapper.
--input source dir contains test fixtures	gen-accessors scans the input dir recursively; exclude test/ via --exclude

Upstream judgment port: PR #679

Match the user language

User-language rule

Write questions, progress updates, reports, and artifacts in the language used by the user. Source material, code identifiers, commands, and quotations may remain in their original language when translating them would reduce accuracy.