| 1 | # Findings — SplitFire AI apps release session (KaroKowe Jam TestFlight) (closed) |
| 2 | |
| 3 | Context: shipping a macOS build (KaroKowe Jam) to TestFlight via the `asc` |
| 4 | CLI. Concrete app id / bundle id / build number are omitted — this is a public |
| 5 | repo; keep plan files to generalizable `asc` findings, not per-app identifiers. |
| 6 | |
| 7 | ## 1. The release `asc` binary can silently lag `development` — DOC-NOTE ✅ SHIPPED |
| 8 | |
| 9 | The installed/release `asc` predated the `testflight` subcommand, yet |
| 10 | `asc apps upload` still worked — because upload only shells out to `altool` |
| 11 | and doesn't touch the newer code paths. So an upload succeeding is **not** |
| 12 | evidence that the binary is current. |
| 13 | |
| 14 | **Rule:** before relying on a newly-added subcommand (e.g. `testflight`), |
| 15 | rebuild `asc` from `development` first (`cargo build --release`), or you'll hit |
| 16 | `unrecognized subcommand` on a binary that otherwise looks healthy. |
| 17 | |
| 18 | **Where this lives:** the rule is captured in `AGENTS.md` § "Verify before |
| 19 | relying on a freshly built `asc`" so a future session doesn't relearn it. |
| 20 | |
| 21 | ## 2. `testflight groups` takes a nested subcommand, not an app id — ✅ SHIPPED |
| 22 | |
| 23 | `asc testflight groups <APP_ID>` would have failed with |
| 24 | `error: unrecognized subcommand '<APP_ID>'`. Confirmed command surface: |
| 25 | |
| 26 | ``` |
| 27 | asc testflight groups list <APP_ID> |
| 28 | asc testflight groups get <GROUP_ID> |
| 29 | asc testflight groups add-build --build-id <BUILD_ID>... <GROUP_ID> |
| 30 | |
| 31 | asc testflight app-review-detail get <APP_ID> |
| 32 | asc testflight app-review-detail update ... # contact + demo-account details |
| 33 | |
| 34 | asc testflight app-review-submissions list <BUILD_ID> |
| 35 | asc testflight app-review-submissions submit <BUILD_ID> |
| 36 | ``` |
| 37 | |
| 38 | Notes: |
| 39 | - `groups add-build` and `app-review-submissions submit` are **CLI-only** by |
| 40 | design (adding a build to an external group / submitting to Beta App Review |
| 41 | can trigger review — not something an MCP tool call should do unattended). |
| 42 | - Both support `--dry-run` to print the request body before writing. |
| 43 | |
| 44 | ## 3. Finish-the-release recipe — DOC-NOTE |
| 45 | |
| 46 | 1. Upload: `asc apps upload <PKG> --wait` (always `--p8-file-path`; never the |
| 47 | script's raw `altool`, which can pick a stale `AuthKey_<id>.p8` → 401). |
| 48 | 2. Poll to VALID: `asc apps builds <APP_ID> --version <BUILD_NUMBER>` → grab the |
| 49 | build id once `processingState` is VALID. |
| 50 | 3. Beta review contact details: `asc testflight app-review-detail update ...`. |
| 51 | 4. Submit: find the Public Link group via `asc testflight groups list <APP_ID>`, |
| 52 | then either `groups add-build --build-id <BUILD_ID> <GROUP_ID>` or |
| 53 | `app-review-submissions submit <BUILD_ID>`. |
| 54 | |
| 55 | This recipe is folded into the "Builds API (CLI)" section of `AGENTS.md` |
| 56 | under the upload + processing sequence. |
| 57 | |
| 58 | ## 4. Process note — DOC-NOTE ✅ SHIPPED |
| 59 | |
| 60 | Plan files and any other changes land on a feature branch and go in through a |
| 61 | PR — never a direct commit to `development` (or `main`). It's easy to slip when |
| 62 | a change feels like "just docs"; treat the branching rule as unconditional. |
| 63 | See the **Git branching workflow** section of `AGENTS.md`. |
| 64 | |
| 65 | ## Status |
| 66 | Closed. Finding #2 shipped as code (testflight CLI tree plus |
| 67 | build-localizations for "What to Test"). Findings #1, #3, #4 are now |
| 68 | doc-notes absorbed into `AGENTS.md`. The recipe in #3 is the operational |
| 69 | TL;DR for what `AGENTS.md` already documents command-by-command. |