aiblueprint-cli 1.4.80 → 1.4.82

package/agents-config/skills/appstore-connect/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: appstore-connect
+description: Interact with App Store Connect via the asc CLI - apps, builds, TestFlight, beta testers, reviews, sales/analytics, metadata, IAP, signing, submissions. Use for "check my app", "App Store Connect", "TestFlight status", "app review", "my app sales", or "asc".
+---
+
+# App Store Connect (asc)
+
+Read, manage, and ship any of the user's App Store apps through the **`asc`** CLI (App Store Connect CLI by Rork). `asc` covers nearly the entire ASC surface; reach for the raw API only for the rare gap.
+
+<auth>
+`asc` is already authenticated on this machine (a default keychain profile). Verify before doing real work:
+
+```bash
+asc auth status            # shows stored credential profiles + which is default
+asc auth status --validate # confirms a credential actually works
+asc doctor                 # diagnose auth/config issues
+```
+
+- Multiple accounts/teams: `asc --profile <name> <command>` selects a profile.
+- A NEW account with no stored key: run the `appstore-connect-setup` skill (locates the `.p8`, key id, and issuer id, then `asc auth login`). Never print or commit `.p8` keys, key ids, or issuer ids.
+</auth>
+
+<how_to_drive>
+Do NOT guess flags. `asc` is large and self-documenting — discover, then act:
+
+```bash
+asc --help                 # the full command map (areas below)
+asc <area> --help          # subcommands + flags for an area, e.g. `asc builds --help`
+asc docs list              # embedded guides; `asc docs <topic>` to read one
+```
+
+- **Read before you write.** List/inspect/validate first; mutate second.
+- **Machine output:** most commands accept `--output json` (or `--output table` for humans) — use JSON when you need to parse ids.
+- Resolve an app id once and reuse it: `asc apps list --output json` → the numeric App Store app id.
+</how_to_drive>
+
+<command_map>
+| Goal | Area |
+| --- | --- |
+| List/inspect apps, app id | `asc apps`, `asc status --app <id>` |
+| Builds (processing, ids) | `asc builds` |
+| TestFlight: beta groups, testers, distribute a build | `asc testflight` |
+| Versions / release state | `asc versions`, `asc release`, `asc status` |
+| Metadata, localizations, keywords | `asc metadata`, `asc localizations` |
+| Screenshots / previews | `asc screenshots`, `asc video-previews` |
+| Pricing & availability | `asc pricing` |
+| In-app purchases / subscriptions | `asc iap`, `asc subscriptions` |
+| Age rating / privacy / encryption / EULA | `asc age-rating`, `asc encryption`, `asc eula` |
+| Submission readiness + submit | `asc validate`, `asc review`, `asc submit`, `asc publish` |
+| Customer reviews | `asc reviews` |
+| Sales / analytics / finance | `asc analytics`, `asc insights`, `asc finance`, `asc performance` |
+| Signing: certs, profiles, bundle ids | `asc signing`, `asc certificates`, `asc profiles`, `asc bundle-ids` |
+| Team / users / devices | `asc users`, `asc devices`, `asc account` |
+| Xcode Cloud, webhooks, workflows | `asc xcode-cloud`, `asc webhooks`, `asc workflow` |
+</command_map>
+
+<common_tasks>
+```bash
+# What apps do I have / what's an app's id?
+asc apps list --output table
+
+# Where is an app in the release pipeline?
+asc status --app <APP_ID> --output table
+
+# Latest builds and processing state
+asc builds list --app <APP_ID> --output json
+
+# TestFlight: see groups, add a tester, distribute a build
+asc testflight groups list --app <APP_ID>
+asc publish testflight --app <APP_ID> --ipa <path.ipa> --group "<GROUP_ID>" --wait
+
+# Is a version ready to submit? (fix every error it reports first)
+asc validate --app <APP_ID> --version <VERSION> --platform IOS --output table
+
+# Read customer reviews / respond
+asc reviews list --app <APP_ID> --output table
+
+# Sales & analytics
+asc analytics --help        # request/download reports
+asc insights --help         # weekly/daily insights
+```
+</common_tasks>
+
+<safety>
+- **Confirm before any mutation that is externally visible or hard to reverse:** `asc submit`, `asc publish ... --submit`, `asc review submit`, `asc pricing` changes, `asc iap`/`asc subscriptions` edits, `asc users` invites/removals, certificate/profile deletion. State the app id, version, and exact change, and get explicit user approval.
+- Prefer dry runs / validation first: many commands accept `--dry-run`; always run `asc validate` before submitting.
+- Never delete a signing certificate or provisioning profile without confirmation — it can break other apps signed with it.
+- Never print or commit `.p8` keys, key ids, issuer ids, app-specific passwords, or downloaded financial reports with PII.
+- This skill manages the store side only. Producing the build (.ipa/.aab) and project config belongs to the app's own deploy workflow.
+</safety>
+
+<raw_api_fallback>
+For the rare endpoint `asc` doesn't expose, call the App Store Connect API directly with the bundled helper (zero deps, ES256 JWT). Credentials come from env vars — never hardcode them:
+
+```bash
+export ASC_KEY_ID=...        # 10-char key id (from the AuthKey_<KEY_ID>.p8 filename)
+export ASC_ISSUER_ID=...     # team issuer UUID (App Store Connect > Users and Access > Integrations)
+export ASC_P8_PATH=/path/to/AuthKey_<KEY_ID>.p8
+node "$SKILL_DIR/scripts/asc-api.mjs" GET "/v1/apps?filter[bundleId]=com.example.app"
+node "$SKILL_DIR/scripts/asc-api.mjs" POST /v1/betaGroups body.json
+```
+
+`$SKILL_DIR` is this skill's directory. The helper prints `{"status", "body"}` and exits non-zero on HTTP >= 400.
+</raw_api_fallback>

package/agents-config/skills/appstore-connect/scripts/asc-api.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * Minimal App Store Connect API client. Zero dependencies.
+ * Used by the setup-testflight / deploy-ios-app skills to manage certificates,
+ * provisioning profiles, beta groups, and testers without the web UI.
+ *
+ * Credentials come from env vars (never hardcode them):
+ *   ASC_KEY_ID     - 10-char API key ID (from the AuthKey_<KEY_ID>.p8 filename)
+ *   ASC_ISSUER_ID  - team issuer UUID (App Store Connect > Users and Access > Integrations)
+ *   ASC_P8_PATH    - absolute path to the AuthKey_*.p8 private key file
+ *
+ * Usage:
+ *   node scripts/asc-api.mjs GET "/v1/apps?filter[bundleId]=com.example.app"
+ *   node scripts/asc-api.mjs POST /v1/betaGroups body.json
+ *   node scripts/asc-api.mjs DELETE /v1/profiles/<id>
+ *
+ * Prints {"status": <http status>, "body": <json|null>} on stdout.
+ * Exits non-zero on HTTP >= 400 so shell scripts can chain safely.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+
+const KEY_ID = process.env.ASC_KEY_ID;
+const ISSUER_ID = process.env.ASC_ISSUER_ID;
+const P8_PATH = process.env.ASC_P8_PATH;
+
+if (!KEY_ID || !ISSUER_ID || !P8_PATH) {
+  console.error(
+    "Missing credentials. Set ASC_KEY_ID, ASC_ISSUER_ID, and ASC_P8_PATH env vars.\n" +
+      "Key ID is in the .p8 filename (AuthKey_<KEY_ID>.p8); issuer ID is in\n" +
+      "App Store Connect > Users and Access > Integrations > App Store Connect API.",
+  );
+  process.exit(2);
+}
+if (!fs.existsSync(P8_PATH)) {
+  console.error(`ASC_P8_PATH not found: ${P8_PATH}`);
+  process.exit(2);
+}
+
+const b64url = (buf) =>
+  Buffer.from(buf)
+    .toString("base64")
+    .replace(/=/g, "")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_");
+
+function makeJwt() {
+  const header = { alg: "ES256", kid: KEY_ID, typ: "JWT" };
+  const now = Math.floor(Date.now() / 1000);
+  const payload = {
+    iss: ISSUER_ID,
+    iat: now,
+    exp: now + 900,
+    aud: "appstoreconnect-v1",
+  };
+  const signingInput = `${b64url(JSON.stringify(header))}.${b64url(JSON.stringify(payload))}`;
+  const key = crypto.createPrivateKey(fs.readFileSync(P8_PATH, "utf8"));
+  const sig = crypto.sign("sha256", Buffer.from(signingInput), {
+    key,
+    dsaEncoding: "ieee-p1363",
+  });
+  return `${signingInput}.${b64url(sig)}`;
+}
+
+const [method, apiPath, bodyFile] = process.argv.slice(2);
+if (!method || !apiPath) {
+  console.error("usage: asc-api.mjs <GET|POST|PATCH|DELETE> </v1/...> [bodyFile.json]");
+  process.exit(2);
+}
+
+const res = await fetch(`https://api.appstoreconnect.apple.com${encodeURI(apiPath)}`, {
+  method: method.toUpperCase(),
+  headers: {
+    Authorization: `Bearer ${makeJwt()}`,
+    "Content-Type": "application/json",
+  },
+  body: bodyFile ? fs.readFileSync(bodyFile, "utf8") : undefined,
+});
+
+const text = await res.text();
+let body = null;
+try {
+  body = text ? JSON.parse(text) : null;
+} catch {
+  body = { raw: text.slice(0, 2000) };
+}
+console.log(JSON.stringify({ status: res.status, body }, null, 2));
+if (res.status >= 400) process.exit(1);

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

@@ -0,0 +1,159 @@
+---
+name: appstore-connect-setup
+description: Find and configure App Store Connect API credentials for asc auth. Use when asc auth is missing, credentials are unknown, the user says login to App Store Connect, or before TestFlight/App Store release work.
+---
+
+# App Store Connect Setup
+
+<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 skill 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/{commands/prompts/create-vitejs-app.md → skills/create-vitejs-app/SKILL.md}

@@ -1,6 +1,7 @@
 ---
+name: create-vitejs-app
 description: Create a Vite.js app with Tailwind CSS v4 and shadcn/ui in the current directory
-argument-hint: [template]
+argument-hint: "[template]"
 ---
 
 <objective>

package/agents-config/skills/environments-manager/SKILL.md

@@ -235,7 +235,7 @@ python3 -c "import json; json.load(open('.claude/settings.json'))"
 
 After the shared scripts are written, for each IDE selected in Step 2, load the matching reference file and apply only its linking config:
 
-- **Claude Code** → [references/claude.md](references/claude.md) - `.claude/settings.json` SessionStart hook + custom slash commands as actions.
+- **Claude Code** → [references/claude.md](references/claude.md) - `.claude/settings.json` worktree hooks + optional project action skills.
 - **Cursor** → [references/cursor.md](references/cursor.md) - `.cursor/worktrees.json` setup keys.
 - **Codex** → [references/codex.md](references/codex.md) - `.codex/environments/environment.toml` setup, cleanup, and actions.
 
@@ -256,11 +256,11 @@ examples/
 ├── claude/
 │   ├── .worktreeinclude           # native env-file copy list
 │   ├── settings.json              # WorktreeCreate + WorktreeRemove hooks
-│   └── commands/                  # optional slash-command actions
-│       ├── dev.md
-│       ├── typecheck.md
-│       ├── test.md
-│       └── lint.md
+├── skills/                        # optional project action skills
+│   ├── dev/SKILL.md
+│   ├── typecheck/SKILL.md
+│   ├── test/SKILL.md
+│   └── lint/SKILL.md
 ├── cursor/
 │   └── worktrees.json             # setup-worktree-unix -> scripts/worktree-up.sh
 └── codex/

package/agents-config/skills/environments-manager/examples/{claude/commands/dev.md → skills/dev/SKILL.md}

@@ -1,5 +1,6 @@
 ---
-description: Start the dev server on a free port
+name: dev
+description: Start the dev server on a free port for this project.
 ---
 
 Run `scripts/dev.sh` from the project root. Stream output until the dev server is listening, then return the URL.

package/agents-config/skills/environments-manager/examples/{claude/commands/lint.md → skills/lint/SKILL.md}

@@ -1,5 +1,6 @@
 ---
-description: Run the linter
+name: lint
+description: Run the linter for this project and report violations.
 ---
 
 Run the project's lint command (`pnpm lint:ci`, `bun run lint`, or equivalent). Report any violations.

package/agents-config/skills/environments-manager/examples/{claude/commands/test.md → skills/test/SKILL.md}

@@ -1,5 +1,6 @@
 ---
-description: Run unit tests
+name: test
+description: Run unit tests for this project and summarize failures.
 ---
 
 Run the project's unit test command (`pnpm test:ci`, `bun test`, or equivalent). Report failures with file:line references.

package/agents-config/skills/environments-manager/examples/{claude/commands/typecheck.md → skills/typecheck/SKILL.md}

@@ -1,5 +1,6 @@
 ---
-description: Typecheck the project
+name: typecheck
+description: Typecheck this project and report errors with file references.
 ---
 
 Run the project's typecheck command (`pnpm ts`, `bun run typecheck`, or equivalent based on the lockfile). Report any errors with file:line references.

package/agents-config/skills/environments-manager/references/claude.md

@@ -25,12 +25,13 @@ There is no separate `PostWorktreeCreate` hook (feature request #27744 is open).
 ```text
 .worktreeinclude                  # gitignore-syntax list of files to auto-copy
 .claude/
-├── settings.json                 # WorktreeCreate + WorktreeRemove hooks
-└── commands/                     # optional: per-action slash commands
-    ├── dev.md
-    ├── typecheck.md
-    ├── test.md
-    └── lint.md
+└── settings.json                 # WorktreeCreate + WorktreeRemove hooks
+.agents/
+└── skills/                       # optional: per-action project skills
+    ├── dev/SKILL.md
+    ├── typecheck/SKILL.md
+    ├── test/SKILL.md
+    └── lint/SKILL.md
 scripts/
 ├── claude-worktree-create.sh     # WorktreeCreate hook wrapper
 ├── claude-worktree-remove.sh     # WorktreeRemove hook wrapper
@@ -123,11 +124,14 @@ The `WorktreeCreate` hook **only fires for `claude --worktree` from the CLI**. T
 
 Also: **`.claude/settings.json` changes only take effect after restarting Claude.** A running session keeps the old hook config. Tell the user to restart before testing.
 
-## Custom Slash Commands as Actions (optional)
+## Project Action Skills (optional)
 
-Claude Code does not have a top-bar action menu. To expose the standard actions, write one file per action under `.claude/commands/`. Each is a tiny prompt that tells Claude to run the matching shared script or package-manager command.
+To expose standard project actions consistently, write one skill per action
+under `.agents/skills/<name>/SKILL.md`. Each skill tells the agent to run the
+matching shared script or package-manager command.
 
-See `examples/claude/commands/` for the four standard ones (`dev.md`, `typecheck.md`, `test.md`, `lint.md`).
+See `examples/skills/` for the four standard ones (`dev`, `typecheck`, `test`,
+`lint`).
 
 ## Guardrails
 

package/agents-config/skills/environments-manager/references/cursor.md

@@ -14,7 +14,7 @@ Three setup keys are supported (Cursor picks the first one that matches the host
 
 Cursor does **not** support a cleanup script. Cleanup is timer-based via global settings (`cursor.worktreeCleanupIntervalHours`, `cursor.worktreeMaxCount`). To get a real cleanup hook, expose `scripts/worktree-down.sh` as a project command the user runs manually before `/delete-worktree`.
 
-Built-in worktree slash commands the user already has: `/worktree`, `/best-of-n`, `/apply-worktree`, `/delete-worktree`.
+Cursor includes built-in worktree actions for creating, comparing, applying, and deleting worktrees.
 
 ## Environment Variables
 
@@ -72,7 +72,7 @@ Inline is fine for two-line setups. For anything more, use a script - the worktr
 
 - Do not put fragile multi-line setup inline. If it does not fit in two clean array entries, call the script.
 - Do not put `.cursor/worktrees.json` only in a worktree - it must be on the source checkout / main branch so future worktrees pick it up.
-- Do not rely on a cleanup hook - Cursor does not have one. Tell the user to run `scripts/worktree-down.sh` before `/delete-worktree`, or document it in the project README.
+- Do not rely on a cleanup hook - Cursor does not have one. Tell the user to run `scripts/worktree-down.sh` before deleting a worktree, or document it in the project README.
 - Do not use `$CURSOR_WORKTREE_PATH` - that variable is not documented and not guaranteed. Use `pwd` inside the worktree.
 
 ## Verification