feat: add build onboarding for automated iOS credential setup (#547)

* feat: add `build onboarding` command for automated iOS credential setup

Interactive Ink-based CLI flow that automates iOS certificate and
provisioning profile creation via the App Store Connect API.

User provides ONE API key (.p8 file), and the CLI handles:
- CSR generation and iOS Distribution certificate creation
- Bundle ID registration (or reuse)
- App Store provisioning profile creation
- Credential saving to ~/.capgo-credentials/credentials.json
- Optional first build kick-off with live log streaming

Key features:
- macOS native file picker for .p8 selection
- Auto-detect Key ID from .p8 filename
- Progress persistence in ~/.capgo-credentials/onboarding/<appId>.json
- Resume from interruption without losing progress
- Smart cert/profile conflict resolution (revoke & recreate)
- Ctrl+O to open App Store Connect in browser

Also refactors requestBuildInternal to use a BuildLogger callback
interface instead of direct @clack/prompts logging, enabling clean
integration with the Ink UI without stdout interception hacks.

* fix: address code review findings from PR #547

- Fix ESLint import order: ink before react in command.ts
- Use explicit process import and @clack/prompts log instead of
  console.error for consistent CLI output
- Only treat ENOENT as "no progress" in loadProgress, rethrow
  JSON corruption and permission errors
- Clear onboarding progress when user skips credential overwrite
  to prevent stale resume state
- Fix stale JSDoc: @param silent → @param logger in fetchWithRetry

* fix: preserve silent build behavior by skipping log streaming

When silent=true and no custom logger is provided, pass undefined
to streamBuildLogs so the early return kicks in. This restores
the pre-refactor behavior where silent SDK callers go directly
to REST polling without WebSocket overhead.

* docs: add build onboarding to native-builds skill documentation

Documents the new `build onboarding` command, its architecture,
conflict resolution behavior, and the BuildLogger callback interface.

* fix(onboarding): incremental progress, backup credentials, early overwrite check

- Save progress incrementally at each input step (p8Path, keyId, issuerId)
  so interrupted onboarding resumes at the right step
- Show completed partial steps as checkmarks when resuming
- Check for existing credentials at start (after platform select) instead
  of at the end — avoids creating orphaned certs/profiles
- Backup existing credentials to credentials-DATE.copy.json before proceeding
- Remove old overwrite prompt at save step
- Fix: don't save keyId from filename extraction until user confirms
- Fix: move async backup to useEffect to avoid Select onChange re-fire

* fix(onboarding): exit instantly after completion screen

* fix(onboarding): add TTY guard to fail fast in CI/pipes

* fix(onboarding): sanitize appId in progress file path to prevent traversal

* fix(onboarding): use capacitor config to resolve iOS platform directory

Instead of hardcoding `ios/`, use `getPlatformDirFromCapacitorConfig`
to respect custom `ios.path` settings in capacitor.config.ts.

* chore: remove unused readdir import from progress.ts

* fix(request): use block-style if, eslint-disable for console.log, fix hardcoded platform in error messages

* fix(onboarding): show correct completion message based on build status

Branch on buildUrl: if set, show "building in the cloud" + track link.
If not (skipped, failed, no API key), show "credentials saved and ready".

* fix: resolve all ESLint errors in onboarding and request modules

- Fix import ordering (perfectionist/sort-imports, sort-named-imports)
- Split multi-statement lines (style/max-statements-per-line)
- Add explicit node:process and node:buffer imports
- Use top-level type-only imports (import/consistent-type-specifier-style)

* fix: address Copilot review findings

- Replace process.exit() with Ink's exit() inside the Ink app to ensure
  proper terminal teardown
- Fix verifyApiKey: include HTTP status in ascFetch error messages so
  401/403 matching actually works
- Fix P12 password JSDoc to match actual DEFAULT_P12_PASSWORD behavior
- Update skill docs: existing credentials flow is backup+proceed or exit
- Implement uploadProgress in default BuildLogger (10% interval logging)
  to restore upload feedback for non-onboarding build requests
- Remove duplicate ❯ prompt wrappers around FilteredTextInput
- Fix FilteredTextInput paste handling: strip forbidden chars from
  accumulated string, not just individual keystrokes

* fix(request): restore upload spinner in default BuildLogger

Replace the log.info() upload progress (printed separate lines at 10%
intervals) with the original @clack/prompts spinner that shows a live
animated percentage update on a single line.

Author: WcaleNieWolny

build.mjs

@@ -254,6 +254,20 @@ const noopSupabaseNodeFetch = {
   },
 }
 
+// Stub react-devtools-core — Ink optionally imports it for dev mode
+const stubReactDevtools = {
+  name: 'stub-react-devtools',
+  setup(build) {
+    build.onResolve({ filter: /^react-devtools-core$/ }, args => ({
+      path: args.path,
+      namespace: 'stub-react-devtools',
+    }))
+    build.onLoad({ filter: /.*/, namespace: 'stub-react-devtools' }, () => ({
+      contents: 'export default {}; export const connectToDevTools = () => {};',
+    }))
+  },
+}
+
 // Fix for @capacitor/cli path assumptions in bundled builds
 // - __dirname gets baked in as the build machine path
 // - loadCLIConfig reads package.json from cliRootDir
@@ -309,6 +323,7 @@ const buildCLI = Bun.build({
     noopSupabaseRealtimeJs,
     stubPrompts,
     noopSupabaseAuthJs,
+    stubReactDevtools,
   ],
 })
 

bun.lock

@@ -91,8 +91,11 @@
     "@supabase/supabase-js": "^2.79.0",
     "@tanstack/intent": "^0.0.23",
     "@types/adm-zip": "^0.5.7",
+    "@types/jsonwebtoken": "^9.0.10",
     "@types/node": "^25.0.0",
+    "@types/node-forge": "^1.3.14",
     "@types/prettyjson": "^0.0.33",
+    "@types/react": "^18.3.28",
     "@types/tmp": "^0.2.6",
     "@vercel/ncc": "^0.38.4",
     "adm-zip": "^0.5.16",
@@ -111,5 +114,13 @@
     "typescript": "^5.9.3",
     "ws": "^8.18.3",
     "zod": "^4.3.6"
+  },
+  "dependencies": {
+    "@inkjs/ui": "^2.0.0",
+    "ink": "^5.2.1",
+    "ink-spinner": "^5.0.0",
+    "jsonwebtoken": "^9.0.3",
+    "node-forge": "^1.3.3",
+    "react": "^18.3.1"
   }
 }

package.json

@@ -1,12 +1,71 @@
 ---
 name: native-builds
-description: Use when working with Capgo Cloud native iOS and Android build requests, credential storage, credential updates, and build output upload settings.
+description: Use when working with Capgo Cloud native iOS and Android build requests, onboarding, credential storage, credential updates, and build output upload settings.
 ---
 
 # Capgo CLI Native Builds
 
 Use this skill for Capgo Cloud native iOS and Android build workflows.
 
+## Onboarding (automated iOS setup)
+
+### `build onboarding`
+
+- Interactive command that automates iOS certificate and provisioning profile creation.
+- Reduces iOS setup from ~10 manual steps to 1 manual step (creating an API key) + 1 command.
+- Example: `npx @capgo/cli@latest build onboarding`
+- Notes:
+  - Uses Ink (React for terminal) for the interactive UI — only command that uses Ink; all other commands use `@clack/prompts`.
+  - Requires running inside a Capacitor project directory with an `ios/` folder.
+  - The user creates ONE App Store Connect API key (.p8 file), then the CLI handles everything else.
+  - On macOS, offers a native file picker dialog for .p8 selection.
+  - Auto-detects Key ID from .p8 filename (e.g. `AuthKey_XXXX.p8`).
+  - Progress persists in `~/.capgo-credentials/onboarding/<appId>.json` — safe to interrupt and resume.
+  - Saves credentials to the same `~/.capgo-credentials/credentials.json` used by `build request`.
+  - Optionally kicks off the first build at the end.
+
+#### What it automates (iOS)
+
+1. Verifies the API key with Apple
+2. Generates CSR + creates an `IOS_DISTRIBUTION` certificate via the App Store Connect API
+3. Registers or reuses the bundle ID
+4. Creates an `IOS_APP_STORE` provisioning profile
+5. Saves all credentials (certificate as .p12, profile, API key, team ID)
+6. Requests the first cloud build
+
+#### Conflict resolution
+
+- **Certificate limit reached**: lists existing certs, tags ones created by Capgo onboarding, lets the user pick one to revoke, then retries.
+- **Duplicate provisioning profiles**: detects profiles matching the `Capgo <appId> AppStore` naming pattern, deletes them, and retries.
+- **Existing credentials**: offers to backup existing credentials before proceeding, or exit onboarding.
+
+#### Architecture
+
+- `src/build/onboarding/command.ts` — entry point, launches Ink
+- `src/build/onboarding/apple-api.ts` — JWT auth + App Store Connect API (verify, create cert, create profile, revoke, delete)
+- `src/build/onboarding/csr.ts` — CSR generation + P12 creation via `node-forge`
+- `src/build/onboarding/progress.ts` — per-app progress persistence
+- `src/build/onboarding/file-picker.ts` — macOS native file picker via `osascript`
+- `src/build/onboarding/ui/app.tsx` — Ink app (state machine)
+- `src/build/onboarding/ui/components.tsx` — reusable UI components
+
+#### BuildLogger callback interface
+
+`requestBuildInternal` accepts an optional `BuildLogger` to receive log output via callbacks instead of writing directly to stdout. This enables clean integration with the Ink UI:
+
+```typescript
+interface BuildLogger {
+  info: (msg: string) => void
+  error: (msg: string) => void
+  warn: (msg: string) => void
+  success: (msg: string) => void
+  buildLog: (msg: string) => void
+  uploadProgress: (percent: number) => void
+}
+```
+
+---
+
 ## Core build request
 
 ### `build request [appId]`