aiblueprint-cli 1.4.88 → 1.4.90

package/agents-config/skills/appstore-connect/references/setup.md

@@ -1,156 +0,0 @@
-# App Store Connect Setup (asc auth)
-
-Read this when `asc` is **not yet authenticated** — `asc auth status --validate` reports no working credential, the user asks to "log in to App Store Connect", or credentials are unknown before TestFlight/App Store release work.
-
-<objective>
-`asc auth login` needs three things: a **key ID**, an **issuer ID**, and a **.p8 private key file**. Users rarely remember where these are. This is a battle-tested workflow for finding all three without asking the user to dig through App Store Connect manually.
-
-Key insight from a real session: the `.p8` files and key IDs live on disk, but the **issuer ID is almost never stored locally** — it only exists in the App Store Connect web UI. The trick is to read it from the user's already-signed-in browser session via CDP, since Apple login requires 2FA and cannot be automated.
-</objective>
-
-<credentials_anatomy>
-| Credential | What it looks like | Where it lives |
-| --- | --- | --- |
-| Key ID | 10 chars, e.g. `T397KWC8K7` | In the `.p8` filename: `AuthKey_<KEY_ID>.p8` |
-| Issuer ID | UUID, e.g. `35b197bd-...` | App Store Connect → Users and Access → Integrations → App Store Connect API (top of Keys page). Team-level, same for all keys. |
-| Private key | `AuthKey_*.p8` file, ~257 bytes | User's disk — Downloads is the most common spot (Apple only lets you download it once) |
-
-Beware look-alikes that are NOT API auth keys:
-- `SubscriptionKey_*.p8` — in-app purchase key, won't work for `asc auth login`.
-- `.p8` files for APNs (push notifications).
-</credentials_anatomy>
-
-<step n="1" title="Check if already authenticated">
-
-```bash
-asc auth status --validate
-```
-
-If a credential validates as "works", stop — nothing to do.
-</step>
-
-<step n="2" title="Hunt for .p8 files on disk">
-
-```bash
-# Standard locations first
-ls ~/.asc ~/private_keys ~/.appstoreconnect/private_keys 2>/dev/null
-
-# Then the places people actually put them (Downloads wins in practice)
-find ~/Downloads ~/Documents ~/Desktop ~/Developer -maxdepth 5 -name "*.p8" 2>/dev/null
-```
-
-Real finding: keys were in `~/Downloads/AuthKey_X.p8` and `~/Downloads/Dev/AuthKey_Y.p8`, downloaded months earlier. The key ID is the filename suffix.
-</step>
-
-<step n="3" title="Try to find the issuer ID locally (usually fails)">
-
-Worth 30 seconds, but expect nothing:
-
-```bash
-grep -riE "issuer" ~/Developer --include="*.json" --include="*.env*" --include="*.rb" --include="*.yml" -l 2>/dev/null | grep -v node_modules
-grep -iE "issuer" ~/.zsh_history 2>/dev/null
-grep -ri "issuer" ~/.fastlane ~/.expo 2>/dev/null
-```
-
-Real finding: zero hits across the entire `~/Developer` tree, shell history, fastlane and expo config. Docs in repos only contain `ISSUER_ID` placeholders. **Do not burn time here — go to step 4.**
-</step>
-
-<step n="4" title="Read the issuer ID from the user's signed-in browser (the key move)">
-
-Apple login = password + 2FA, so never try to log in yourself. Instead, attach to the browser where the user is **already signed in** and read the page.
-
-**4a. Confirm with the user** which browser is signed in to App Store Connect (Chrome, Helium, etc.).
-
-**4b. Check if the browser exposes CDP:**
-
-```bash
-curl -s http://127.0.0.1:9222/json/version   # Chrome default
-curl -s http://127.0.0.1:9334/json/version   # custom port
-```
-
-**4c. If not (the usual case), quit and relaunch it with a debug port.** Session cookies survive a graceful quit, and `--restore-last-session` brings the tabs back:
-
-```bash
-osascript -e 'quit app "Helium"'   # or "Google Chrome"
-sleep 3
-nohup "/Applications/Helium.app/Contents/MacOS/Helium" --remote-debugging-port=9334 --restore-last-session >/dev/null 2>&1 &
-sleep 5
-curl -s http://127.0.0.1:9334/json/version | head -3   # must answer before continuing
-```
-
-**4d. Navigate to the API keys page and extract the issuer ID:**
-
-```bash
-dev-browser --browser helium --connect http://127.0.0.1:9334 --timeout 60 <<'EOF'
-const page = await browser.getPage("asc");
-await page.goto("https://appstoreconnect.apple.com/access/integrations/api", { waitUntil: "domcontentloaded" });
-await page.waitForTimeout(8000);
-const text = await page.evaluate(() => document.body.innerText);
-const m = text.match(/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/i);
-console.log(JSON.stringify({ issuerId: m ? m[1] : null, loggedOut: page.url().includes("/login") }));
-EOF
-```
-
-If `loggedOut` is true, ask the user to sign in in that browser window, then re-run.
-
-**4e. Cross-check which keys are actually ACTIVE.** The same page lists active keys with their key IDs. A `.p8` found on disk may belong to a revoked key — match the filename key ID against the active list before using it:
-
-```bash
-dev-browser --browser helium --connect http://127.0.0.1:9334 --timeout 30 <<'EOF'
-const page = await browser.getPage("asc");
-const text = await page.evaluate(() => document.body.innerText);
-console.log(text);  // active keys table: NAME / KEY ID / LAST USED / ACCESS
-EOF
-```
-
-Real finding: the first `.p8` we picked (`AuthKey_6QD5RMPU9F.p8`) was NOT in the active list — login would have failed. The second one matched an active Admin key and worked.
-</step>
-
-<step n="5" title="Organize keys, then log in">
-
-Move keys to the canonical folder so the next agent finds them instantly:
-
-```bash
-mkdir -p ~/Developer/app-store
-mv ~/Downloads/AuthKey_*.p8 ~/Developer/app-store/ 2>/dev/null
-chmod 600 ~/Developer/app-store/*.p8
-```
-
-Then authenticate and verify end-to-end.
-
-**Naming the credential:** use a stable, descriptive name tied to the machine + user, not the app — the same ASC API key is team-level and works across every app, so naming it per-app is misleading. Convention: `asc-macos-<user>-key` (e.g. `asc-macos-melvynx-key`). **Prefer a key with Admin access** when several active keys exist (Admin can read/write everything the release flow needs); check the ACCESS column from step 4e and pick the Admin key.
-
-```bash
-asc auth login \
-  --name "asc-macos-melvynx-key" \
-  --key-id "KEY_ID" \
-  --issuer-id "ISSUER_ID" \
-  --private-key ~/Developer/app-store/AuthKey_KEY_ID.p8 \
-  --network
-
-asc auth status --validate   # must report "works"
-asc apps list                # must list the target app
-```
-</step>
-
-<step n="6" title="Persist the findings">
-
-Record in the agent memory / AGENTS.md so this hunt never happens twice:
-
-- The keys folder (`~/Developer/app-store/`), each key ID and whether it is active
-- The issuer ID (team-level, stable)
-- The `asc` credential name (convention `asc-macos-<user>-key`), its access level (prefer Admin), and that it is stored in the system keychain
-- The app's numeric App Store Connect ID and bundle ID from `asc apps list`
-</step>
-
-<critical_safety>
-- Never commit `.p8` files or paste their contents anywhere. `chmod 600` them.
-- Never attempt the Apple login form yourself — 2FA makes it pointless and looks like account takeover. Always reuse the user's signed-in session, with their explicit OK to attach to/restart their browser.
-- Restarting the browser closes the user's windows; warn them and rely on session restore.
-</critical_safety>
-
-<success_criteria>
-- `asc auth status --validate` reports the credential as "works".
-- `asc apps list` returns the expected app(s).
-- Keys live in `~/Developer/app-store/` and the findings are written to memory/AGENTS.md.
-</success_criteria>

package/agents-config/skills/appstore-connect/references/testflight.md

@@ -1,212 +0,0 @@
-# TestFlight: build an iOS app and ship it to TestFlight
-
-Loaded for `appstore-connect testflight`. Takes an Expo / React Native iOS app from local dev to an installable TestFlight build, fully non-interactively.
-
-**Two key insights that make this automatable:**
-
-1. **ASC API key signing avoids Apple ID 2FA.** Interactive `eas build` credential setup needs Apple ID 2FA and cannot be scripted. Creating the distribution certificate + App Store provisioning profile through the App Store Connect API (`$SKILL_DIR/scripts/asc-api.mjs`) avoids 2FA entirely.
-2. **`eas build --local` avoids Expo cloud build credits.** Default to the local Mac build with `credentialsSource: "local"`; use `--expo` only when the user explicitly wants a cloud build.
-
-`$SKILL_DIR` is the `appstore-connect` skill directory; `<APP_DIR>` is the Expo project root (often the repo root, or `mobile-app/` / `apps/<name>/` in a monorepo).
-
-## Arguments
-
-- **default** (`appstore-connect testflight`): run setup → local build → upload → verify.
-- **`--expo`**: use the EAS **cloud** build instead of local (consumes EAS build quota — confirm once).
-- **setup-only** (`testflight setup`, "prepare credentials"): run phases A–D, then stop and report readiness.
-
-## Prerequisites (ask once, as a group — the agent cannot create these)
-
-1. **Apple Developer Program** membership (paid, enrolled).
-2. **App Store Connect API key**: the `AuthKey_<KEY_ID>.p8` file, its key ID, and the team issuer ID (App Store Connect → Users and Access → Integrations; needs Admin or App Manager). If unknown, follow [setup.md](setup.md).
-3. **Expo account** logged in: `npx eas-cli@latest whoami` (else `login`).
-4. **App record** in App Store Connect for the bundle ID. The public API **cannot** create app records — if missing, the user creates it once at appstoreconnect.apple.com (My Apps → + → New App). Verified in Phase D.
-5. **`asc` CLI** (`brew install asc`) — used only for the final upload.
-6. For the default local build: macOS with Xcode CLT + CocoaPods (`xcodebuild -version`, `command -v pod`). If missing, stop and ask whether to use `--expo`.
-
-## Critical safety
-
-- Never commit or print `.p8` keys, `.p12` files, p12 passwords, provisioning profiles, or `credentials.json`. Verify `.gitignore` excludes them before any commit.
-- Export ASC credentials as env vars for `asc-api.mjs`; never write them into repo files.
-- Get explicit confirmation before: creating Apple certificates (low per-account limit), `--expo` cloud builds (consumes credits), and the TestFlight upload.
-- Env vars are **baked in at build time** — confirm the production config points at prod backends before building, or testers ship with a dev backend.
-
-## Phase A — Preflight
-
-```bash
-cd <APP_DIR>
-npx tsc --noEmit && npm run lint        # whatever checks the project has
-npx expo-doctor                          # surface config problems early
-npx eas-cli@latest whoami                # Expo account logged in?
-command -v asc && asc version
-xcodebuild -version && command -v pod    # required for default local builds
-```
-
-Confirm the permanent values with the user: app `title`, `bundleId`, Apple `teamId`. The bundle ID is permanent once the app record exists.
-
-Export ASC credentials for the rest of the session:
-
-```bash
-export ASC_KEY_ID="<10-char key id>"
-export ASC_ISSUER_ID="<issuer uuid>"
-export ASC_P8_PATH="/path/to/AuthKey_<KEY_ID>.p8"
-```
-
-## Phase B — EAS project init
-
-Skip if the project already has a real `eas.projectId` (a UUID).
-
-```bash
-cd <APP_DIR>
-npx eas-cli@latest project:init --non-interactive --force
-npx eas-cli@latest project:info
-```
-
-Write the printed project ID into the Expo config (`app.json`/`app.config.ts` → `extra.eas.projectId`, or your project config).
-
-## Phase C — Production env + eas.json
-
-Point the build at production. Set every required production backend env var (auth secrets, API keys, URLs), then wire the prod values into `<APP_DIR>/eas.json → build.production`:
-
-```json
-"production": {
-  "autoIncrement": true,
-  "credentialsSource": "local",
-  "env": {
-    "EXPO_PUBLIC_API_URL": "https://<prod-backend>"
-  }
-}
-```
-
-`credentialsSource: "local"` is what makes Phase E fully non-interactive.
-
-## Phase D — Apple signing credentials via the ASC API
-
-All calls: `node "$SKILL_DIR/scripts/asc-api.mjs" <METHOD> <path> [body.json]` with the Phase A env vars. Work in a directory **outside** the repo (e.g. `~/ios-credentials/<slug>/`) so nothing secret can be committed.
-
-**1. Resolve the app record (hard gate):**
-
-```bash
-node "$SKILL_DIR/scripts/asc-api.mjs" GET "/v1/apps?filter[bundleId]=<bundle_id>"
-```
-
-Empty `data` → STOP: tell the user to create the app record (My Apps → + → New App) with this exact bundle ID, then resume. Otherwise save `app_id = data[0].id`.
-
-**2. Bundle ID registration + capabilities:**
-
-```bash
-node "$SKILL_DIR/scripts/asc-api.mjs" GET "/v1/bundleIds?filter[identifier]=<bundle_id>"
-# if missing: POST /v1/bundleIds {"data":{"type":"bundleIds","attributes":{"identifier":"<bundle_id>","name":"<title>","platform":"IOS"}}}
-# enable capabilities the app uses (IN_APP_PURCHASE, APPLE_ID_AUTH, PUSH_NOTIFICATIONS) via POST /v1/bundleIdCapabilities
-```
-
-**3. Distribution certificate** (Apple caps these at ~2–3 per account — check first):
-
-```bash
-node "$SKILL_DIR/scripts/asc-api.mjs" GET "/v1/certificates?filter[certificateType]=DISTRIBUTION"
-```
-
-Reuse only if the user has its private key/.p12 locally. Otherwise create one (with confirmation):
-
-```bash
-openssl req -new -newkey rsa:2048 -nodes -keyout dist.key -out dist.csr \
-  -subj "/emailAddress=<user-email>/CN=<title> Distribution/C=US"
-node -e "const fs=require('fs');fs.writeFileSync('cert-req.json',JSON.stringify({data:{type:'certificates',attributes:{certificateType:'DISTRIBUTION',csrContent:fs.readFileSync('dist.csr','utf8')}}}))"
-node "$SKILL_DIR/scripts/asc-api.mjs" POST /v1/certificates cert-req.json
-# save body.data.id (cert id) and body.data.attributes.certificateContent (base64) -> dist.cer
-```
-
-**4. App Store provisioning profile:**
-
-```bash
-node -e "const fs=require('fs');fs.writeFileSync('profile-req.json',JSON.stringify({data:{type:'profiles',attributes:{name:'<title> AppStore',profileType:'IOS_APP_STORE'},relationships:{bundleId:{data:{type:'bundleIds',id:'<BUNDLE_DB_ID>'}},certificates:{data:[{type:'certificates',id:'<CERT_ID>'}]},devices:{data:[]}}}}))"
-node "$SKILL_DIR/scripts/asc-api.mjs" POST /v1/profiles profile-req.json
-# save body.data.attributes.profileContent (base64) -> appstore.mobileprovision
-```
-
-**5. Build the `.p12` (the `-legacy` flag is mandatory — Apple tooling rejects OpenSSL 3.x default ciphers):**
-
-```bash
-echo "<certificateContent-b64>" | base64 -d > dist.cer
-P12PASS=$(openssl rand -hex 12)
-openssl x509 -inform der -in dist.cer -out dist.pem 2>/dev/null || cp dist.cer dist.pem
-openssl pkcs12 -export -in dist.pem -inkey dist.key -out dist.p12 \
-  -name "<title> Distribution" -passout pass:"$P12PASS" -legacy
-echo "<profileContent-b64>" | base64 -d > appstore.mobileprovision
-```
-
-**6. Wire into the project (gitignored paths only):**
-
-```bash
-mkdir -p <APP_DIR>/credentials
-cp dist.p12 appstore.mobileprovision <APP_DIR>/credentials/
-node -e "const fs=require('fs');fs.writeFileSync('<APP_DIR>/credentials.json',JSON.stringify({ios:{provisioningProfilePath:'credentials/appstore.mobileprovision',distributionCertificate:{path:'credentials/dist.p12',password:process.argv[1]}}},null,2))" "$P12PASS"
-git check-ignore <APP_DIR>/credentials.json <APP_DIR>/credentials/dist.p12   # MUST print both
-```
-
-**Setup-only mode STOPS here** — report readiness (app record, cert, profile, credentials.json, eas.json) and the next command.
-
-## Phase E — Local iOS build (default)
-
-Uses the local Mac/Xcode toolchain; does **not** consume Expo cloud credits.
-
-```bash
-cd <APP_DIR>
-npx eas-cli@latest build --platform ios --profile production \
-  --local --non-interactive --output /tmp/<slug>.ipa
-```
-
-If `expo-doctor` blocks on dependency patch mismatches, run `npx expo install --check`, apply the minimal patch updates, re-run `npx tsc --noEmit && npm run lint`, then rebuild. Don't blindly upgrade deps mid-release.
-
-## Phase E (--expo) — EAS cloud build
-
-Only when the user passes `--expo` (confirm once — consumes EAS credits):
-
-```bash
-cd <APP_DIR>
-npx eas-cli@latest build --platform ios --profile production --non-interactive --no-wait
-npx eas-cli@latest build:list --platform ios --limit 1 --json --non-interactive   # poll to FINISHED/ERRORED
-curl -sL -o /tmp/<slug>.ipa "<artifacts.buildUrl>"                                  # download on FINISHED
-```
-
-## Phase F — TestFlight upload
-
-**1. Internal beta group** (`asc publish testflight` fails without `--group`):
-
-```bash
-node -e "const fs=require('fs');fs.writeFileSync('group-req.json',JSON.stringify({data:{type:'betaGroups',attributes:{name:'Internal',isInternalGroup:true,hasAccessToAllBuilds:true},relationships:{app:{data:{type:'apps',id:'<app_id>'}}}}}))"
-node "$SKILL_DIR/scripts/asc-api.mjs" POST /v1/betaGroups group-req.json
-# 409 "already exists" is fine — fetch the id: GET "/v1/apps/<app_id>/betaGroups"
-```
-
-**2. Upload and wait** (`asc auth status --validate`, else `asc auth login` with the same ASC key):
-
-```bash
-asc publish testflight --app "<app_id>" --ipa /tmp/<slug>.ipa --group "<BETA_GROUP_ID>" --wait --timeout 45m
-```
-
-**3. Add testers** (internal testers must be ASC team members; external emails work via groups):
-
-```bash
-node -e "const fs=require('fs');fs.writeFileSync('tester-req.json',JSON.stringify({data:{type:'betaTesters',attributes:{email:'<tester-email>'},relationships:{betaGroups:{data:[{type:'betaGroups',id:'<BETA_GROUP_ID>'}]}}}}))"
-node "$SKILL_DIR/scripts/asc-api.mjs" POST /v1/betaTesters tester-req.json
-```
-
-**4. Verify:** `asc status --app "<app_id>" --output table` shows the build processed and attached to the group. Report build number, group, and testers.
-
-## Failure modes
-
-- **`.p12` rejected during signing** → exported without `-legacy`. Re-export with `-legacy`.
-- **Certificate creation 409 / limit reached** → list existing DISTRIBUTION certs; ask which to revoke (`DELETE /v1/certificates/<id>`) or whether the user has its `.p12` to reuse. Never revoke without confirmation — it breaks other apps.
-- **Local build fails before Xcode archive** → check `xcodebuild -version`, `xcode-select -p`, `command -v pod`. If unavailable and the user accepts cloud quota, rerun with `--expo`.
-- **Build asks for credentials** → `credentialsSource: "local"` missing in `eas.json`, or `credentials.json` paths wrong (relative to `<APP_DIR>`).
-- **`asc publish testflight` "--group is required"** → create the beta group first (Phase F step 1).
-- **Upload rejected: missing export compliance** → answer the encryption question once in App Store Connect, or add `"ITSAppUsesNonExemptEncryption": false` to `infoPlist` in the Expo config.
-- **App opens but can't reach backend** → built before `eas.json` had prod URLs, or prod env vars missing. Env is baked at build time — rebuild after fixing.
-- **User insists on EAS-managed credentials (Apple ID login)** → that needs interactive 2FA; run `npx eas-cli@latest credentials` in a real terminal with the user present. Do not script the 2FA prompt.
-
-## Success metrics
-
-- Default local build produces `/tmp/<slug>.ipa` with no interactive prompt; `--expo` cloud builds reach FINISHED.
-- The build shows as processed in TestFlight, attached to a beta group with at least one tester.
-- `git status` shows no credential files staged; nothing secret printed in the transcript.