mirror of https://github.com/garrytan/gstack.git
feat(ship): the Apple App Store release journey — working tree to Submit for Review
Point /ship at a repo with an .xcodeproj, .xcworkspace, or app-product Swift package and ask to release: the adapter runs the whole journey with ONE authorization moment (membership + pricing + in-session sign-in, decision- store persisted so repeat releases ask nothing) and one store-assets question only when assets are missing. fastlane is the single tool (produce/cert/ sigh/gym/pilot/deliver/frameit); credential vocabulary never reaches the user. The adapter carries 21 live releases' worth of paid-for Apple knowledge: the web session mints the permanent upload key itself (iris POST /v1/apiKeys; privateKey is base64-of-PEM, downloadable only at creation) so nobody ever types an app-specific password; error -22938 is Transporter asking for a key, not a user task; errors are CLASSIFIED before credentials are touched (validation/UnexpectedResponse = metadata, incl. Apple's expanded age-rating attributes); pricing goes through POST /v1/appPriceSchedules because fastlane's price_tier is broken against the current API; and store distribution NEVER routes through the branch gate — a clean tree on main is the solo shipper's normal case (Step 0.9 loads the adapter BEFORE the gate, pinned by test with the non-Apple gate byte-unchanged and unique). Uploads/submissions follow an idempotency-log contract (inspect App Store Connect before any re-run). Non-Mac hosts get the honest split: build legs via a macOS CI runner with the minted key as a secret, API legs local. Browser use inside the journey is banned except the named paid-app banking/tax residue. Redaction dry-run clean. Ship's parity ratio raised 1.12 -> 1.22 deliberately: the 14.8KB section is on-demand (Apple store targets only), one manifest line otherwise. Ported from time-attack/gstack (GStack 2), refined across its 21 live releases; architecture adaptation (carved section, decision-store paths, idempotency log, third-party-actions handoff) ours. Co-authored-by: Sina Matian <sina@time-attack.dev> Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Garry Tan
parent
1d29225a92
commit
53deeeb116
|
|
@ -901,6 +901,7 @@ sections. Read a section in full before doing its step; do not work from memory.
|
|||
|
||||
| When | Read this section |
|
||||
|------|-------------------|
|
||||
| the ship target is an Apple platform app (.xcodeproj, .xcworkspace, or an app-product Swift package) — read BEFORE Step 1's branch gate and any preflight; store distribution never routes through the branch/PR ceremony | `sections/apple-release.md` |
|
||||
| running the test suites and (if prompt files changed) the eval suites (Steps 4-6) | `sections/tests.md` |
|
||||
| auditing test coverage of the diff (Step 7) | `sections/test-coverage.md` |
|
||||
| auditing plan completion, verification, and scope drift (Step 8) | `sections/plan-completion.md` |
|
||||
|
|
@ -912,6 +913,18 @@ sections. Read a section in full before doing its step; do not work from memory.
|
|||
|
||||
---
|
||||
|
||||
## Step 0.9: Apple target detection
|
||||
|
||||
Shipping to the App Store is not landing a PR. If the repository contains an
|
||||
`.xcodeproj`, `.xcworkspace`, or a Swift package with an app product AND the
|
||||
user's ask is store distribution (App Store, TestFlight, "release my app"),
|
||||
**STOP and Read `~/.claude/skills/gstack/ship/sections/apple-release.md` FIRST**
|
||||
— before the branch gate and any preflight below. Store distribution proceeds
|
||||
from whatever branch the user is on (a clean tree on the base branch is the
|
||||
solo developer's normal case, not an error) and follows the adapter end to
|
||||
end. The branch gate and repository-landing pipeline below apply ONLY to
|
||||
repository-landing asks, including on Apple repos.
|
||||
|
||||
## Step 1: Pre-flight
|
||||
|
||||
1. Check the current branch. If on the base branch or the repo's default branch, **abort**: "You're on the base branch. Ship from a feature branch."
|
||||
|
|
|
|||
|
|
@ -77,6 +77,18 @@ Never skip a verification step because a prior `/ship` run already performed it.
|
|||
|
||||
---
|
||||
|
||||
## Step 0.9: Apple target detection
|
||||
|
||||
Shipping to the App Store is not landing a PR. If the repository contains an
|
||||
`.xcodeproj`, `.xcworkspace`, or a Swift package with an app product AND the
|
||||
user's ask is store distribution (App Store, TestFlight, "release my app"),
|
||||
**STOP and Read `~/.claude/skills/gstack/ship/sections/apple-release.md` FIRST**
|
||||
— before the branch gate and any preflight below. Store distribution proceeds
|
||||
from whatever branch the user is on (a clean tree on the base branch is the
|
||||
solo developer's normal case, not an error) and follows the adapter end to
|
||||
end. The branch gate and repository-landing pipeline below apply ONLY to
|
||||
repository-landing asks, including on Apple repos.
|
||||
|
||||
## Step 1: Pre-flight
|
||||
|
||||
1. Check the current branch. If on the base branch or the repo's default branch, **abort**: "You're on the base branch. Ship from a feature branch."
|
||||
|
|
|
|||
|
|
@ -0,0 +1,58 @@
|
|||
<!-- AUTO-GENERATED from apple-release.md.tmpl — do not edit directly -->
|
||||
<!-- Regenerate: bun run gen:skill-docs -->
|
||||
# Apple App Store release
|
||||
|
||||
<!-- Ported from time-attack/gstack (GStack 2) APPLE-RELEASE.md, refined
|
||||
across 21 live App Store releases. Portions copyright (c) 2026
|
||||
Sina Matian, time-attack/gstack, MIT. Adapted to gstack main's
|
||||
architecture: decision-store bins, the Third-Party Web Actions
|
||||
contract, and an idempotency log in place of the fork's durable-state
|
||||
wrapper. All credential examples are placeholders, never live formats. -->
|
||||
|
||||
Applies when the ship target is an Apple platform app: the repository contains an `.xcodeproj` or `.xcworkspace`, or a Swift package with an app product. Read this BEFORE Step 1's branch gate and any preflight. This adapter extends ship's judgment to the App Store journey end to end, and every upload or submission is treated as a durable external effect (idempotency contract below) — but store distribution is its own release path, not repository landing: ship's branch/PR ceremony (feature-branch gate, commit-review-PR pipeline, merge queue) applies only when the user asked to land repository changes. A user shipping to the App Store or TestFlight proceeds through this adapter from whatever branch they are on; a clean working tree on the base branch is a normal and valid state to archive and upload from. Never abort an App Store release over branch topology.
|
||||
|
||||
One tool runs the entire release: machine-level fastlane — `produce` (app record and bundle ID), `cert` and `sigh` (signing), `gym` (archive and signed export), `pilot` (TestFlight), `deliver` (metadata, screenshots, Submit for Review), `frameit` (device frames). Install it when missing (`brew install fastlane`) with a one-line announcement, not a question — the release authorization covers machine-tool installs. Never install additional App Store CLI tools, and never mention API keys, `.p8` files, sessions, or any credential format to the user; they paid US$99 and want to ship, and the release itself adds no new dependency to the user's project.
|
||||
|
||||
A Mac is required only for the build legs. Archiving, signing, and the binary upload ride Xcode's macOS-only toolchain — Apple ships it nowhere else, and no tool routes around that. On a non-macOS host, say so plainly, then route exactly those legs through a macOS CI runner (a GitHub Actions `macos` runner executing the same `gym` and `deliver`/`pilot` commands, with the minted upload key supplied as a CI secret — key auth is precisely what CI wants); sign-in, key minting, metadata, screenshots, pricing, and submission judgment are plain API work that stays on the user's machine. Never claim the whole release is impossible off a Mac, and never pretend the build leg is possible there.
|
||||
|
||||
## The one authorization moment
|
||||
|
||||
The whole journey permits exactly two interactions, and no others. FIRST, up front: confirm the user holds a paid Apple Developer Program membership (US$99/year — the App Store and TestFlight both require it) and authorize the release. Pricing belongs to this same breath, once per app EVER: ask free or paid (and the price if paid) inside the authorization question — never as a separate interruption — after checking the decision store (`bin/gstack-decision-search --scope repo --query "pricing"`); persist the answer (`~/.claude/skills/gstack/bin/gstack-decision-log`, scope `repo`) so no later release re-asks, and a paid answer names the one-time Paid Apps banking/tax agreement honestly right there, since nothing sells until it is signed. Price is a launch decision the agent never defaults silently: a free launch cannot be un-launched. Apple sign-in happens inside this same moment: run `fastlane spaceauth -u <apple-id>` through the host's interactive command path (in Claude Code, the user types `! fastlane spaceauth -u <email>` so their password and one two-factor code go directly to Apple in-session; a separate terminal window is the fallback only when the host has no interactive path). Keep the printed session token out of the transcript — the cached cookie in `~/.fastlane/spaceship/` is the credential fastlane actually uses; never store, echo, or log the password or token, and re-run the same one command when the session expires. Immediately after the first sign-in, mint the permanent upload key from the session (step 4 of Archive and upload) — when that key already sits at `~/.gstack/apple/api-key.json` and no new app record is needed, skip the sign-in entirely: repeat releases authorize and proceed with zero sign-in. SECOND, only when preflight finds the icon or screenshots missing: the store-assets question below. Everything else — tool installs, upload, storefront, submission — is covered by the authorization and proceeds without asking. Auth menus, tool-choice questions, plan confirmations, and step-by-step narration requests are contract violations.
|
||||
|
||||
No membership: STOP the App Store path. Offer to walk enrollment at developer.apple.com through the Third-Party Web Actions contract (earlier in this skill) (a purchase the user completes themselves; activation can take a day or two), and name the free-account ceiling honestly: personal-team installs on the user's own devices only, expiring after 7 days, no TestFlight, no App Store.
|
||||
|
||||
## Release preflight
|
||||
|
||||
Resolve and verify before archiving. Fix what the printed mutation boundary authorizes; report everything else as a blocking finding.
|
||||
|
||||
- Signing: development team on the app target; `cert` and `sigh` mint the distribution certificate and App Store profile when none exist.
|
||||
- Versioning: a marketing version users should see and a build number strictly greater than any build already uploaded for that version.
|
||||
- Dependencies: `xcodebuild -resolvePackageDependencies` succeeds; if a `Podfile` or `Cartfile` exists, its install step has been run and lockfiles are current.
|
||||
- App Store validation blockers: complete app icon set including the 1024pt marketing icon, launch screen, a usage-description string for every privacy-gated API the app touches, required privacy manifests, an export-compliance answer (`ITSAppUsesNonExemptEncryption`), and a sane deployment target.
|
||||
|
||||
## Store assets
|
||||
|
||||
Only when preflight finds the icon or screenshots missing, ask once — the journey's second and final permitted question — then act on the choice without further prompts. Once per app, EVER: before asking, check the decision store (`bin/gstack-decision-search --scope repo --query "store assets"`); a settled choice (including "defer screenshots" or "TestFlight only") is applied silently, never re-asked. After the user answers, persist it (`~/.claude/skills/gstack/bin/gstack-decision-log` with scope `repo`) so no future run asks again; the user changes it by saying so, not by being re-prompted. Offer:
|
||||
|
||||
- **App icon**: SnapAI (`npx snapai`, the app-icon agent skill) generates the single 1024×1024 with the user's own image-generation key; Xcode 15+ derives every size from that one image.
|
||||
- **Marketing screenshots, free and local, no API key**: the app-store-screenshots deck editor skill — scaffold it, prefill its deck JSON with simulator captures and benefit headlines, and export one bundle covering every required iPhone size (the export is headlessly automatable). Marketing-grade does NOT require an image backend; never claim screenshots need an API key while this skill is installed.
|
||||
- **Plain frames, free and local**: capture the built app in the simulator and frame with fastlane `frameit` — the minimal option when no designed deck is wanted.
|
||||
- **AI-enhanced marketing screenshots**: the aso-appstore-screenshots agent skill (benefit headlines, breakout panels, exact App Store dimensions) — the only option that needs the user's own image-generation key; when installed, follow its workflow rather than reimplementing it.
|
||||
- **User-supplied files**: always a valid answer; validate dimensions and move on.
|
||||
|
||||
Build this question's options from a LIVE check of installed skills at ask time — never from memory or an earlier conversation turn. Whenever the app-store-screenshots deck editor skill is installed, its free no-key option MUST appear in the list; omitting it is a contract violation equal to claiming screenshots need an API key. Assets already present skip this entirely. Announce what was generated at exit.
|
||||
|
||||
## Archive and upload
|
||||
|
||||
1. Archive and export the signed Release build with `gym` (it drives xcodebuild and the signing minted in preflight). Projects with custom archive requirements may drop to `xcodebuild archive` directly; the output either way is an App Store-signed `.ipa`.
|
||||
2. The upload is an external effect: run `pilot` (TestFlight) or `deliver` (App Store) under the durable-effect contract: before executing, append the key `appstore.upload.<bundle-id>.<build>` to `~/.gstack/projects/$SLUG/apple-effects.log`; if the key is already present from a prior run (crash, retry). Never re-upload on ambiguity; inspect App Store Connect for the build first.
|
||||
3. The cached session, the minted key, and every credential file are env- or file-level secrets: never argv, never echoed, never committed.
|
||||
4. NEVER demand an app-specific password — the session MINTS the upload key instead. Per fastlane's documented authentication, Apple's binary-upload tool (iTMSTransporter, which `deliver`/`pilot` shell out to for the `.ipa`) does not accept the web session: it takes only an App Store Connect API key or an app-specific password, and Apple's error `-22938` ("Sign in with the app-specific password") is Transporter saying exactly this. That is not a gate and not a question, because the web session creates the key itself, silently: through fastlane's bundled spaceship (`Spaceship::Tunes.login(<apple-id>)` reuses the cached cookie, then raw client requests), `POST https://appstoreconnect.apple.com/iris/v1/apiKeys` with JSON:API body `{data:{type:"apiKeys",attributes:{nickname:"gstack-upload",allAppsVisible:true,roles:["APP_MANAGER"],keyType:"PUBLIC_API"}}}`, then `GET .../iris/v1/apiKeys/<id>?fields[apiKeys]=privateKey` — the `privateKey` attribute is base64 of the COMPLETE PEM file: decode it exactly once and write `~/.appstoreconnect/private_keys/AuthKey_<id>.p8` (0600) immediately, it is downloadable only at creation. The issuer ID is `provider.publicProviderId` from `GET https://appstoreconnect.apple.com/olympus/v1/session`. Record key id, issuer id, and key content as a fastlane api-key JSON at `~/.gstack/apple/api-key.json` (0600) and run `deliver`/`pilot` with `api_key_path` from then on. The key never expires, so every later release skips sign-in; the session stays necessary only for `produce` (Apple's public API cannot create app records) and for re-minting if the key is ever revoked. Stating that the user must generate any credential themselves while key minting is untried is a contract violation. CLASSIFY the error before touching credentials: an error is an authentication failure ONLY when it says so (401/403, session invalid or expired, "sign in", "app-specific password" in Apple's own words). A `Spaceship::UnexpectedResponse`, missing/invalid attribute, validation, or precheck error is a METADATA problem — fix the payload (for example, Apple's expanded age-rating attributes such as `lootBox`, `ageAssurance`, `parentalControls`, `messagingAndChat` in `app_rating_config.json`) and retry from the CLI. Treating a metadata error as a credential problem is a contract violation.
|
||||
5. Within an Apple release, this adapter OVERRIDES the Third-Party Web Actions contract (earlier in this skill): the general agentic-browser offer never applies to App Store Connect, Apple ID, or credential work here. The entire release is CLI (fastlane) plus the two permitted interactions; the ONLY browser use this adapter allows, ever, is the paid-app agreements/banking/tax residue named at the end of this document. Opening a browser — driven or manual — for anything else in this journey is a contract violation. When a real error does force the fallback, QUOTE the error verbatim, then escalate in this order: FIRST mint (or re-mint) the upload key from the session per step 4 and retry the upload with `api_key_path` — an upload-auth error with no key on disk means the mint was skipped, not that the user owes a credential. SECOND, if the minting itself fails with a session error, ask the user to sign in again (the same `! fastlane spaceauth -u <apple-id>` moment as the original authorization), re-mint, and retry. Only when a FRESH session still cannot mint a key — a permissions refusal because the signed-in Apple ID is not Admin or Account Holder on its team — does the app-specific-password path open, and its only shape is self-service: the user generates the password on any device and enters it through the host's in-session masked prompt into the macOS keychain (`fastlane fastlane-credentials add --username <apple-id>`), then the upload is retried. NEVER offer or recommend a browser drive to create credentials — no agentic browser of any kind, for any password, key, or token, under any framing.
|
||||
6. App Review contact details (name, email, phone) are required metadata for submission: infer name and email from the signed-in Apple ID and git config, collect the phone number once inside the authorization moment, persist it to the decision store, and never re-ask. Contact details are metadata, not a blocking gate to announce mid-run.
|
||||
|
||||
## Storefront completion
|
||||
|
||||
`produce` already created the app record and bundle ID during the run — never call the app record a manual gate. Apply the pricing settled in the authorization moment through the App Store Connect price-schedule endpoint (`POST /v1/appPriceSchedules` via the session or the minted key): fastlane's `price_tier` option is broken against the current API ("'prices' is not a relationship on 'apps'"), so never route pricing through it or call its failure an account problem. `deliver` owns everything else the store listing needs: description, keywords, localizations, screenshot upload per device size, attaching the uploaded build, and Submit for Review; `pilot` manages TestFlight groups and testers as an intermediate round when the user asked for one. Submission follows the same durable-effect contract with key `appstore.submit.<bundle-id>.<version>` — on ambiguity, inspect App Store Connect before re-running. Monitor review status from the CLI afterward.
|
||||
|
||||
What remains web-only, ever: the paid Apple Developer Program membership purchase itself (a precondition, not a release step) and, for PAID apps only, the one-time Paid Apps agreement with banking and tax — offer the agentic-browser drive per the Third-Party Web Actions contract (earlier in this skill) before any manual checklist for those. A free app needs no browser at any point. After submission, report that App Review typically answers within a day or two and close the run; review outcome is not a gate this workflow can hold open.
|
||||
|
|
@ -0,0 +1,56 @@
|
|||
# Apple App Store release
|
||||
|
||||
<!-- Ported from time-attack/gstack (GStack 2) APPLE-RELEASE.md, refined
|
||||
across 21 live App Store releases. Portions copyright (c) 2026
|
||||
Sina Matian, time-attack/gstack, MIT. Adapted to gstack main's
|
||||
architecture: decision-store bins, the Third-Party Web Actions
|
||||
contract, and an idempotency log in place of the fork's durable-state
|
||||
wrapper. All credential examples are placeholders, never live formats. -->
|
||||
|
||||
Applies when the ship target is an Apple platform app: the repository contains an `.xcodeproj` or `.xcworkspace`, or a Swift package with an app product. Read this BEFORE Step 1's branch gate and any preflight. This adapter extends ship's judgment to the App Store journey end to end, and every upload or submission is treated as a durable external effect (idempotency contract below) — but store distribution is its own release path, not repository landing: ship's branch/PR ceremony (feature-branch gate, commit-review-PR pipeline, merge queue) applies only when the user asked to land repository changes. A user shipping to the App Store or TestFlight proceeds through this adapter from whatever branch they are on; a clean working tree on the base branch is a normal and valid state to archive and upload from. Never abort an App Store release over branch topology.
|
||||
|
||||
One tool runs the entire release: machine-level fastlane — `produce` (app record and bundle ID), `cert` and `sigh` (signing), `gym` (archive and signed export), `pilot` (TestFlight), `deliver` (metadata, screenshots, Submit for Review), `frameit` (device frames). Install it when missing (`brew install fastlane`) with a one-line announcement, not a question — the release authorization covers machine-tool installs. Never install additional App Store CLI tools, and never mention API keys, `.p8` files, sessions, or any credential format to the user; they paid US$99 and want to ship, and the release itself adds no new dependency to the user's project.
|
||||
|
||||
A Mac is required only for the build legs. Archiving, signing, and the binary upload ride Xcode's macOS-only toolchain — Apple ships it nowhere else, and no tool routes around that. On a non-macOS host, say so plainly, then route exactly those legs through a macOS CI runner (a GitHub Actions `macos` runner executing the same `gym` and `deliver`/`pilot` commands, with the minted upload key supplied as a CI secret — key auth is precisely what CI wants); sign-in, key minting, metadata, screenshots, pricing, and submission judgment are plain API work that stays on the user's machine. Never claim the whole release is impossible off a Mac, and never pretend the build leg is possible there.
|
||||
|
||||
## The one authorization moment
|
||||
|
||||
The whole journey permits exactly two interactions, and no others. FIRST, up front: confirm the user holds a paid Apple Developer Program membership (US$99/year — the App Store and TestFlight both require it) and authorize the release. Pricing belongs to this same breath, once per app EVER: ask free or paid (and the price if paid) inside the authorization question — never as a separate interruption — after checking the decision store (`bin/gstack-decision-search --scope repo --query "pricing"`); persist the answer (`~/.claude/skills/gstack/bin/gstack-decision-log`, scope `repo`) so no later release re-asks, and a paid answer names the one-time Paid Apps banking/tax agreement honestly right there, since nothing sells until it is signed. Price is a launch decision the agent never defaults silently: a free launch cannot be un-launched. Apple sign-in happens inside this same moment: run `fastlane spaceauth -u <apple-id>` through the host's interactive command path (in Claude Code, the user types `! fastlane spaceauth -u <email>` so their password and one two-factor code go directly to Apple in-session; a separate terminal window is the fallback only when the host has no interactive path). Keep the printed session token out of the transcript — the cached cookie in `~/.fastlane/spaceship/` is the credential fastlane actually uses; never store, echo, or log the password or token, and re-run the same one command when the session expires. Immediately after the first sign-in, mint the permanent upload key from the session (step 4 of Archive and upload) — when that key already sits at `~/.gstack/apple/api-key.json` and no new app record is needed, skip the sign-in entirely: repeat releases authorize and proceed with zero sign-in. SECOND, only when preflight finds the icon or screenshots missing: the store-assets question below. Everything else — tool installs, upload, storefront, submission — is covered by the authorization and proceeds without asking. Auth menus, tool-choice questions, plan confirmations, and step-by-step narration requests are contract violations.
|
||||
|
||||
No membership: STOP the App Store path. Offer to walk enrollment at developer.apple.com through the Third-Party Web Actions contract (earlier in this skill) (a purchase the user completes themselves; activation can take a day or two), and name the free-account ceiling honestly: personal-team installs on the user's own devices only, expiring after 7 days, no TestFlight, no App Store.
|
||||
|
||||
## Release preflight
|
||||
|
||||
Resolve and verify before archiving. Fix what the printed mutation boundary authorizes; report everything else as a blocking finding.
|
||||
|
||||
- Signing: development team on the app target; `cert` and `sigh` mint the distribution certificate and App Store profile when none exist.
|
||||
- Versioning: a marketing version users should see and a build number strictly greater than any build already uploaded for that version.
|
||||
- Dependencies: `xcodebuild -resolvePackageDependencies` succeeds; if a `Podfile` or `Cartfile` exists, its install step has been run and lockfiles are current.
|
||||
- App Store validation blockers: complete app icon set including the 1024pt marketing icon, launch screen, a usage-description string for every privacy-gated API the app touches, required privacy manifests, an export-compliance answer (`ITSAppUsesNonExemptEncryption`), and a sane deployment target.
|
||||
|
||||
## Store assets
|
||||
|
||||
Only when preflight finds the icon or screenshots missing, ask once — the journey's second and final permitted question — then act on the choice without further prompts. Once per app, EVER: before asking, check the decision store (`bin/gstack-decision-search --scope repo --query "store assets"`); a settled choice (including "defer screenshots" or "TestFlight only") is applied silently, never re-asked. After the user answers, persist it (`~/.claude/skills/gstack/bin/gstack-decision-log` with scope `repo`) so no future run asks again; the user changes it by saying so, not by being re-prompted. Offer:
|
||||
|
||||
- **App icon**: SnapAI (`npx snapai`, the app-icon agent skill) generates the single 1024×1024 with the user's own image-generation key; Xcode 15+ derives every size from that one image.
|
||||
- **Marketing screenshots, free and local, no API key**: the app-store-screenshots deck editor skill — scaffold it, prefill its deck JSON with simulator captures and benefit headlines, and export one bundle covering every required iPhone size (the export is headlessly automatable). Marketing-grade does NOT require an image backend; never claim screenshots need an API key while this skill is installed.
|
||||
- **Plain frames, free and local**: capture the built app in the simulator and frame with fastlane `frameit` — the minimal option when no designed deck is wanted.
|
||||
- **AI-enhanced marketing screenshots**: the aso-appstore-screenshots agent skill (benefit headlines, breakout panels, exact App Store dimensions) — the only option that needs the user's own image-generation key; when installed, follow its workflow rather than reimplementing it.
|
||||
- **User-supplied files**: always a valid answer; validate dimensions and move on.
|
||||
|
||||
Build this question's options from a LIVE check of installed skills at ask time — never from memory or an earlier conversation turn. Whenever the app-store-screenshots deck editor skill is installed, its free no-key option MUST appear in the list; omitting it is a contract violation equal to claiming screenshots need an API key. Assets already present skip this entirely. Announce what was generated at exit.
|
||||
|
||||
## Archive and upload
|
||||
|
||||
1. Archive and export the signed Release build with `gym` (it drives xcodebuild and the signing minted in preflight). Projects with custom archive requirements may drop to `xcodebuild archive` directly; the output either way is an App Store-signed `.ipa`.
|
||||
2. The upload is an external effect: run `pilot` (TestFlight) or `deliver` (App Store) under the durable-effect contract: before executing, append the key `appstore.upload.<bundle-id>.<build>` to `~/.gstack/projects/$SLUG/apple-effects.log`; if the key is already present from a prior run (crash, retry). Never re-upload on ambiguity; inspect App Store Connect for the build first.
|
||||
3. The cached session, the minted key, and every credential file are env- or file-level secrets: never argv, never echoed, never committed.
|
||||
4. NEVER demand an app-specific password — the session MINTS the upload key instead. Per fastlane's documented authentication, Apple's binary-upload tool (iTMSTransporter, which `deliver`/`pilot` shell out to for the `.ipa`) does not accept the web session: it takes only an App Store Connect API key or an app-specific password, and Apple's error `-22938` ("Sign in with the app-specific password") is Transporter saying exactly this. That is not a gate and not a question, because the web session creates the key itself, silently: through fastlane's bundled spaceship (`Spaceship::Tunes.login(<apple-id>)` reuses the cached cookie, then raw client requests), `POST https://appstoreconnect.apple.com/iris/v1/apiKeys` with JSON:API body `{data:{type:"apiKeys",attributes:{nickname:"gstack-upload",allAppsVisible:true,roles:["APP_MANAGER"],keyType:"PUBLIC_API"}}}`, then `GET .../iris/v1/apiKeys/<id>?fields[apiKeys]=privateKey` — the `privateKey` attribute is base64 of the COMPLETE PEM file: decode it exactly once and write `~/.appstoreconnect/private_keys/AuthKey_<id>.p8` (0600) immediately, it is downloadable only at creation. The issuer ID is `provider.publicProviderId` from `GET https://appstoreconnect.apple.com/olympus/v1/session`. Record key id, issuer id, and key content as a fastlane api-key JSON at `~/.gstack/apple/api-key.json` (0600) and run `deliver`/`pilot` with `api_key_path` from then on. The key never expires, so every later release skips sign-in; the session stays necessary only for `produce` (Apple's public API cannot create app records) and for re-minting if the key is ever revoked. Stating that the user must generate any credential themselves while key minting is untried is a contract violation. CLASSIFY the error before touching credentials: an error is an authentication failure ONLY when it says so (401/403, session invalid or expired, "sign in", "app-specific password" in Apple's own words). A `Spaceship::UnexpectedResponse`, missing/invalid attribute, validation, or precheck error is a METADATA problem — fix the payload (for example, Apple's expanded age-rating attributes such as `lootBox`, `ageAssurance`, `parentalControls`, `messagingAndChat` in `app_rating_config.json`) and retry from the CLI. Treating a metadata error as a credential problem is a contract violation.
|
||||
5. Within an Apple release, this adapter OVERRIDES the Third-Party Web Actions contract (earlier in this skill): the general agentic-browser offer never applies to App Store Connect, Apple ID, or credential work here. The entire release is CLI (fastlane) plus the two permitted interactions; the ONLY browser use this adapter allows, ever, is the paid-app agreements/banking/tax residue named at the end of this document. Opening a browser — driven or manual — for anything else in this journey is a contract violation. When a real error does force the fallback, QUOTE the error verbatim, then escalate in this order: FIRST mint (or re-mint) the upload key from the session per step 4 and retry the upload with `api_key_path` — an upload-auth error with no key on disk means the mint was skipped, not that the user owes a credential. SECOND, if the minting itself fails with a session error, ask the user to sign in again (the same `! fastlane spaceauth -u <apple-id>` moment as the original authorization), re-mint, and retry. Only when a FRESH session still cannot mint a key — a permissions refusal because the signed-in Apple ID is not Admin or Account Holder on its team — does the app-specific-password path open, and its only shape is self-service: the user generates the password on any device and enters it through the host's in-session masked prompt into the macOS keychain (`fastlane fastlane-credentials add --username <apple-id>`), then the upload is retried. NEVER offer or recommend a browser drive to create credentials — no agentic browser of any kind, for any password, key, or token, under any framing.
|
||||
6. App Review contact details (name, email, phone) are required metadata for submission: infer name and email from the signed-in Apple ID and git config, collect the phone number once inside the authorization moment, persist it to the decision store, and never re-ask. Contact details are metadata, not a blocking gate to announce mid-run.
|
||||
|
||||
## Storefront completion
|
||||
|
||||
`produce` already created the app record and bundle ID during the run — never call the app record a manual gate. Apply the pricing settled in the authorization moment through the App Store Connect price-schedule endpoint (`POST /v1/appPriceSchedules` via the session or the minted key): fastlane's `price_tier` option is broken against the current API ("'prices' is not a relationship on 'apps'"), so never route pricing through it or call its failure an account problem. `deliver` owns everything else the store listing needs: description, keywords, localizations, screenshot upload per device size, attaching the uploaded build, and Submit for Review; `pilot` manages TestFlight groups and testers as an intermediate round when the user asked for one. Submission follows the same durable-effect contract with key `appstore.submit.<bundle-id>.<version>` — on ambiguity, inspect App Store Connect before re-running. Monitor review status from the CLI afterward.
|
||||
|
||||
What remains web-only, ever: the paid Apple Developer Program membership purchase itself (a precondition, not a release step) and, for PAID apps only, the one-time Paid Apps agreement with banking and tax — offer the agentic-browser drive per the Third-Party Web Actions contract (earlier in this skill) before any manual checklist for those. A free app needs no browser at any point. After submission, report that App Review typically answers within a day or two and close the run; review outcome is not a gate this workflow can hold open.
|
||||
|
|
@ -2,8 +2,14 @@
|
|||
"$schema": "https://gstack.dev/schemas/section-manifest.json",
|
||||
"skill": "ship",
|
||||
"version": 1,
|
||||
"note": "PASSIVE registry (v2 plan T9 / CM2). Fields are IDs, file paths, human titles, and human-readable trigger text ONLY. The skeleton's decision-tree prose is the ONLY place that decides WHEN to read a section; required-reads live in the E2E fixtures. No machine predicate here — see docs/designs/v2_PLAN.md:663.",
|
||||
"note": "PASSIVE registry (v2 plan T9 / CM2). Fields are IDs, file paths, human titles, and human-readable trigger text ONLY. The skeleton's decision-tree prose is the ONLY place that decides WHEN to read a section; required-reads live in the E2E fixtures. No machine predicate here \u2014 see docs/designs/v2_PLAN.md:663.",
|
||||
"sections": [
|
||||
{
|
||||
"id": "apple-release",
|
||||
"file": "apple-release.md",
|
||||
"title": "Apple App Store / TestFlight release adapter",
|
||||
"trigger": "the ship target is an Apple platform app (.xcodeproj, .xcworkspace, or an app-product Swift package) \u2014 read BEFORE Step 1's branch gate and any preflight; store distribution never routes through the branch/PR ceremony"
|
||||
},
|
||||
{
|
||||
"id": "tests",
|
||||
"file": "tests.md",
|
||||
|
|
|
|||
|
|
@ -901,6 +901,7 @@ sections. Read a section in full before doing its step; do not work from memory.
|
|||
|
||||
| When | Read this section |
|
||||
|------|-------------------|
|
||||
| the ship target is an Apple platform app (.xcodeproj, .xcworkspace, or an app-product Swift package) — read BEFORE Step 1's branch gate and any preflight; store distribution never routes through the branch/PR ceremony | `sections/apple-release.md` |
|
||||
| running the test suites and (if prompt files changed) the eval suites (Steps 4-6) | `sections/tests.md` |
|
||||
| auditing test coverage of the diff (Step 7) | `sections/test-coverage.md` |
|
||||
| auditing plan completion, verification, and scope drift (Step 8) | `sections/plan-completion.md` |
|
||||
|
|
@ -912,6 +913,18 @@ sections. Read a section in full before doing its step; do not work from memory.
|
|||
|
||||
---
|
||||
|
||||
## Step 0.9: Apple target detection
|
||||
|
||||
Shipping to the App Store is not landing a PR. If the repository contains an
|
||||
`.xcodeproj`, `.xcworkspace`, or a Swift package with an app product AND the
|
||||
user's ask is store distribution (App Store, TestFlight, "release my app"),
|
||||
**STOP and Read `~/.claude/skills/gstack/ship/sections/apple-release.md` FIRST**
|
||||
— before the branch gate and any preflight below. Store distribution proceeds
|
||||
from whatever branch the user is on (a clean tree on the base branch is the
|
||||
solo developer's normal case, not an error) and follows the adapter end to
|
||||
end. The branch gate and repository-landing pipeline below apply ONLY to
|
||||
repository-landing asks, including on Apple repos.
|
||||
|
||||
## Step 1: Pre-flight
|
||||
|
||||
1. Check the current branch. If on the base branch or the repo's default branch, **abort**: "You're on the base branch. Ship from a feature branch."
|
||||
|
|
|
|||
|
|
@ -884,6 +884,18 @@ Never skip a verification step because a prior `/ship` run already performed it.
|
|||
|
||||
---
|
||||
|
||||
## Step 0.9: Apple target detection
|
||||
|
||||
Shipping to the App Store is not landing a PR. If the repository contains an
|
||||
`.xcodeproj`, `.xcworkspace`, or a Swift package with an app product AND the
|
||||
user's ask is store distribution (App Store, TestFlight, "release my app"),
|
||||
**STOP and Read `$GSTACK_ROOT/ship/sections/apple-release.md` FIRST**
|
||||
— before the branch gate and any preflight below. Store distribution proceeds
|
||||
from whatever branch the user is on (a clean tree on the base branch is the
|
||||
solo developer's normal case, not an error) and follows the adapter end to
|
||||
end. The branch gate and repository-landing pipeline below apply ONLY to
|
||||
repository-landing asks, including on Apple repos.
|
||||
|
||||
## Step 1: Pre-flight
|
||||
|
||||
1. Check the current branch. If on the base branch or the repo's default branch, **abort**: "You're on the base branch. Ship from a feature branch."
|
||||
|
|
|
|||
|
|
@ -886,6 +886,18 @@ Never skip a verification step because a prior `/ship` run already performed it.
|
|||
|
||||
---
|
||||
|
||||
## Step 0.9: Apple target detection
|
||||
|
||||
Shipping to the App Store is not landing a PR. If the repository contains an
|
||||
`.xcodeproj`, `.xcworkspace`, or a Swift package with an app product AND the
|
||||
user's ask is store distribution (App Store, TestFlight, "release my app"),
|
||||
**STOP and Read `$GSTACK_ROOT/ship/sections/apple-release.md` FIRST**
|
||||
— before the branch gate and any preflight below. Store distribution proceeds
|
||||
from whatever branch the user is on (a clean tree on the base branch is the
|
||||
solo developer's normal case, not an error) and follows the adapter end to
|
||||
end. The branch gate and repository-landing pipeline below apply ONLY to
|
||||
repository-landing asks, including on Apple repos.
|
||||
|
||||
## Step 1: Pre-flight
|
||||
|
||||
1. Check the current branch. If on the base branch or the repo's default branch, **abort**: "You're on the base branch. Ship from a feature branch."
|
||||
|
|
|
|||
|
|
@ -99,6 +99,7 @@ export const CARVE_GUARDS: Record<string, CarveGuard> = {
|
|||
ship: {
|
||||
skill: 'ship',
|
||||
expectedSections: [
|
||||
'apple-release.md',
|
||||
'tests.md',
|
||||
'test-coverage.md',
|
||||
'plan-completion.md',
|
||||
|
|
@ -133,9 +134,12 @@ export const CARVE_GUARDS: Record<string, CarveGuard> = {
|
|||
// markers, test-file census — e3259078 port) + the #1079 gh pr edit REST
|
||||
// fallback grew the union to 1.090x; the third-party web-actions
|
||||
// contract (consent-gated browser drive for API-key registration etc.)
|
||||
// adds ~2.3KB inline judgment, measured 1.103x. Kept tight; the Apple
|
||||
// release adapter raises this again deliberately.
|
||||
maxSizeRatio: 1.12,
|
||||
// adds ~2.3KB inline judgment, measured 1.103x. The Apple release
|
||||
// adapter (14.8KB carved section, 21 live releases of judgment — the
|
||||
// wave's headline capability) grows the union to 1.195x. Deliberate:
|
||||
// the section is on-demand (loads only for Apple store targets), so
|
||||
// per-invocation cost for non-iOS ships is one manifest line.
|
||||
maxSizeRatio: 1.22,
|
||||
},
|
||||
'plan-ceo-review': {
|
||||
skill: 'plan-ceo-review',
|
||||
|
|
|
|||
|
|
@ -0,0 +1,56 @@
|
|||
/**
|
||||
* R2 pin (fork port wave 2): the Apple release adapter loads BEFORE ship's
|
||||
* branch gate, and the non-Apple gate is byte-unchanged.
|
||||
*
|
||||
* Two failure modes this prevents: a future ship-template refactor that
|
||||
* re-blocks store releases behind "ship from a feature branch" (the exact
|
||||
* live failure the fork hit — a solo dev with a clean tree on main shipping
|
||||
* to TestFlight got aborted over branch topology), and the reverse — the
|
||||
* Apple path accidentally weakening the branch gate for normal
|
||||
* repository-landing ships.
|
||||
*/
|
||||
|
||||
import { describe, test, expect } from "bun:test";
|
||||
import { readFileSync } from "fs";
|
||||
import { join } from "path";
|
||||
|
||||
const ROOT = join(import.meta.dir, "..");
|
||||
const SKELETON = readFileSync(join(ROOT, "ship", "SKILL.md"), "utf-8");
|
||||
|
||||
const GATE_TEXT =
|
||||
'If on the base branch or the repo\'s default branch, **abort**: "You\'re on the base branch. Ship from a feature branch."';
|
||||
|
||||
describe("ship Apple gate ordering (R2)", () => {
|
||||
test("the Apple adapter read directive precedes the branch gate", () => {
|
||||
const appleRead = SKELETON.indexOf("sections/apple-release.md");
|
||||
const gate = SKELETON.indexOf(GATE_TEXT);
|
||||
expect(appleRead).toBeGreaterThan(-1);
|
||||
expect(gate).toBeGreaterThan(-1);
|
||||
expect(appleRead).toBeLessThan(gate);
|
||||
});
|
||||
|
||||
test("store distribution explicitly bypasses the branch/PR ceremony", () => {
|
||||
expect(SKELETON).toContain("Store distribution proceeds");
|
||||
expect(SKELETON).toMatch(/branch gate and repository-landing pipeline below apply ONLY to\s*\n?repository-landing asks/);
|
||||
});
|
||||
|
||||
test("the non-Apple branch gate is byte-unchanged and appears exactly once", () => {
|
||||
const first = SKELETON.indexOf(GATE_TEXT);
|
||||
expect(first).toBeGreaterThan(-1);
|
||||
expect(SKELETON.indexOf(GATE_TEXT, first + 1)).toBe(-1);
|
||||
});
|
||||
|
||||
test("the adapter section exists in the union with its battle-tested spine", () => {
|
||||
const section = readFileSync(join(ROOT, "ship", "sections", "apple-release.md"), "utf-8");
|
||||
for (const anchor of [
|
||||
"one authorization moment",
|
||||
"fastlane spaceauth",
|
||||
"iris/v1/apiKeys",
|
||||
"appPriceSchedules",
|
||||
"CLASSIFY the error before touching credentials",
|
||||
"Never abort an App Store release over branch topology",
|
||||
]) {
|
||||
expect(section).toContain(anchor);
|
||||
}
|
||||
});
|
||||
});
|
||||
Loading…
Reference in New Issue