Implement Ink-based onboarding experience (#549)

* feat(init): implement Ink-based onboarding experience with interactive prompts and progress tracking

- Added onboarding steps and UI components for a guided setup process.
- Introduced runtime management for session state, logging, and prompts.
- Created reusable prompt components for confirmation, text input, and selection.
- Enhanced user experience with progress indicators and session management.
- Updated documentation to reflect new onboarding features and functionality.

* feat(init): enhance onboarding process with framework detection and Capacitor initialization

* feat(init): rename `build onboarding` to `build init` and enhance onboarding flow with improved error handling and file picker integration

Co-authored-by: Copilot <copilot@github.com>

* feat(init): improve apikey handling in initApp function with fallback to saved key

* feat(init): enhance onboarding and prompt handling with improved type safety and error management

* feat(init): enhance web directory validation for Next.js and Nuxt.js in setup process

---------

Co-authored-by: Copilot <copilot@github.com>

Author: riderx

skills/native-builds/SKILL.md

@@ -9,13 +9,14 @@ Use this skill for Capgo Cloud native iOS and Android build workflows.
 
 ## Onboarding (automated iOS setup)
 
-### `build onboarding`
+### `build init` (alias: `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`
+- Example: `npx @capgo/cli@latest build init`
+- Backward compatibility: `npx @capgo/cli@latest build onboarding` still works.
 - Notes:
-  - Uses Ink (React for terminal) for the interactive UI — only command that uses Ink; all other commands use `@clack/prompts`.
+  - Uses Ink (React for terminal) for the interactive UI, alongside the main `init` onboarding flow.
   - 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.

skills/usage/SKILL.md

@@ -24,7 +24,7 @@ TanStack Intent skills should stay focused and under the validator line limit, s
 
 ### Project setup and diagnostics
 
-- `init [apikey] [appId]`: guided first-time setup for Capgo in a Capacitor app. In interactive use, onboarding can also offer a final `npx skills add https://github.com/Cap-go/capgo-skills -g -y` install step before the GitHub support prompt; if accepted, the support menu includes `Cap-go/capgo-skills` alongside the updater-only and all-Capgo choices. If iOS sync validation fails during onboarding, the CLI can offer to run a one-line native reset command, wait for you to type `ready` after a manual fix, and offer cancellation every third failed retry.
+- `init [apikey] [appId]`: guided first-time setup for Capgo in a Capacitor app. The interactive flow now runs as a real Ink-based fullscreen onboarding so it uses the same UI stack as `build init` (alias: `build onboarding`), with a persistent dashboard, phase roadmap, progress cards, shared log area, and resume support. When dependency auto-detection fails on macOS, the flow opens a native file picker for `package.json` before falling back to manual path entry. If the user reuses a pending app that was already created in the web onboarding flow, the CLI syncs that selected dashboard app ID back into `capacitor.config.*` before the remaining steps continue. Outside that reused pending-app path, the CLI keeps using the local Capacitor app ID. It can also offer a final `npx skills add https://github.com/Cap-go/capgo-skills -g -y` install step before the GitHub support prompt; if accepted, the support menu includes `Cap-go/capgo-skills` alongside the updater-only and all-Capgo choices. If iOS sync validation fails during onboarding, the CLI can offer to run a one-line native reset command, wait for you to type `ready` after a manual fix, and offer cancellation every third failed retry.
 - `login [apikey]`: store an API key locally.
 - `doctor`: inspect installation health and gather troubleshooting details.
 - `probe`: test whether the update endpoint would deliver an update.

src/build/onboarding/command.ts

@@ -8,10 +8,10 @@ import { getPlatformDirFromCapacitorConfig } from '../platform-paths.js'
 import { loadProgress } from './progress.js'
 import OnboardingApp from './ui/app.js'
 
-export async function onboardingCommand(): Promise<void> {
+export async function onboardingBuilderCommand(): Promise<void> {
   // Ink requires an interactive terminal — fail fast in CI/pipes
   if (!process.stdin.isTTY || !process.stdout.isTTY) {
-    console.error('Error: `build onboarding` requires an interactive terminal.')
+    console.error('Error: `build init` requires an interactive terminal.')
     console.error('It cannot run in CI, pipes, or non-TTY environments.')
     console.error('Use `build credentials save` for non-interactive credential setup.')
     process.exit(1)

src/build/onboarding/file-picker.ts

@@ -1,31 +1,19 @@
 // src/build/onboarding/file-picker.ts
 import { execFile } from 'node:child_process'
+import { basename } from 'node:path'
 import { platform } from 'node:process'
 
-/**
- * Returns true if we're on macOS and can use the native file picker.
- */
-export function canUseFilePicker(): boolean {
-  return platform === 'darwin'
-}
-
-/**
- * Open the macOS native file picker dialog filtered to .p8 files.
- * Returns the selected file path, or null if the user cancelled.
- * Non-blocking — uses async execFile so Ink spinners keep animating.
- */
-export function openFilePicker(): Promise<string | null> {
+function openMacFilePicker(script: string): Promise<string | null> {
   if (!canUseFilePicker())
     return Promise.resolve(null)
 
   return new Promise((resolve) => {
     execFile(
       'osascript',
-      ['-e', 'POSIX path of (choose file of type {"p8"} with prompt "Select your .p8 API key file")'],
+      ['-e', script],
       { encoding: 'utf-8', timeout: 120000 },
       (err, stdout) => {
         if (err) {
-          // User cancelled the dialog or osascript failed
           resolve(null)
           return
         }
@@ -35,3 +23,28 @@ export function openFilePicker(): Promise<string | null> {
     )
   })
 }
+
+/**
+ * Returns true if we're on macOS and can use the native file picker.
+ */
+export function canUseFilePicker(): boolean {
+  return platform === 'darwin'
+}
+
+/**
+ * Open the macOS native file picker dialog filtered to .p8 files.
+ * Returns the selected file path, or null if the user cancelled.
+ * Non-blocking — uses async execFile so Ink spinners keep animating.
+ */
+export function openFilePicker(): Promise<string | null> {
+  return openMacFilePicker('POSIX path of (choose file of type {"p8"} with prompt "Select your .p8 API key file")')
+}
+
+export function openPackageJsonPicker(): Promise<string | null> {
+  return openMacFilePicker('POSIX path of (choose file with prompt "Select your package.json file")')
+    .then((selectedPath) => {
+      if (!selectedPath)
+        return null
+      return basename(selectedPath).toLowerCase() === 'package.json' ? selectedPath : null
+    })
+}

src/build/onboarding/ui/app.tsx

@@ -49,15 +49,9 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir }) => {
   const [existingCerts, setExistingCerts] = useState<Array<{ id: string, name: string, serialNumber: string, expirationDate: string }>>([])
   const [certToRevoke, setCertToRevoke] = useState<string | null>(null)
   const pickerOpenedRef = useRef(false)
+  const exitRequestedRef = useRef(false)
   // overwriteConfirmedRef removed — credential check happens at start now
 
-  // Open browser on Ctrl+O (FilteredTextInput ignores ctrl keys, so no conflict)
-  useInput((input, key) => {
-    if (key.ctrl && input === 'o' && (step === 'api-key-instructions' || step === 'input-issuer-id')) {
-      open('https://appstoreconnect.apple.com/access/integrations/api')
-    }
-  })
-
   // Collected data — restore p8Path from progress if resuming
   const [p8Path, setP8Path] = useState(initialProgress?.p8Path || '')
   const [p8Content, _setP8Content] = useState('')
@@ -100,6 +94,27 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir }) => {
     setLog(prev => [...prev, { text, color }])
   }, [])
 
+  const exitOnboarding = useCallback((message?: string) => {
+    if (exitRequestedRef.current)
+      return
+    exitRequestedRef.current = true
+    if (message)
+      addLog(message, 'yellow')
+    setTimeout(() => exit(), 50)
+  }, [addLog, exit])
+
+  // Open browser on Ctrl+O (FilteredTextInput ignores ctrl keys, so no conflict)
+  useInput((input, key) => {
+    if (key.ctrl && input === 'c') {
+      process.kill(process.pid, 'SIGINT')
+      return
+    }
+
+    if (key.ctrl && input === 'o' && (step === 'api-key-instructions' || step === 'input-issuer-id')) {
+      open('https://appstoreconnect.apple.com/access/integrations/api')
+    }
+  })
+
   /** Save partial progress so the user can resume mid-flow */
   const savePartialProgress = useCallback(async (updates: { p8Path?: string, keyId?: string, issuerId?: string }) => {
     const existing = await loadProgress(appId) || {
@@ -193,10 +208,10 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir }) => {
     else {
       // Second failure — exit
       addLog(`✖ ${message}`, 'red')
-      addLog('Run `capgo build onboarding` to retry from where you left off.', 'yellow')
-      setTimeout(() => exit(), 100)
+      addLog('Run `capgo build init` to retry from where you left off.', 'yellow')
+      setTimeout(() => exitOnboarding(), 100)
     }
-  }, [retryCount, addLog, exit])
+  }, [retryCount, addLog, exitOnboarding])
 
   // ── Credential save logic ──
 
@@ -686,7 +701,7 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir }) => {
               }
               else {
                 addLog('Exiting onboarding.', 'yellow')
-                setTimeout(() => exit(), 50)
+                exitOnboarding()
               }
             }}
           />
@@ -967,7 +982,7 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir }) => {
             onChange={(value) => {
               if (value === '__exit__') {
                 addLog('Exiting. Revoke a certificate manually, then re-run onboarding.', 'yellow')
-                setTimeout(() => exit(), 50)
+                exitOnboarding()
               }
               else {
                 setCertToRevoke(value)
@@ -1012,7 +1027,7 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir }) => {
               }
               else {
                 addLog('Exiting. Delete duplicate profiles manually in the Apple Developer Portal, then re-run onboarding.', 'yellow')
-                setTimeout(() => exit(), 50)
+                exitOnboarding()
               }
             }}
           />
@@ -1118,8 +1133,8 @@ const OnboardingApp: FC<AppProps> = ({ appId, initialProgress, iosDir }) => {
                     setStep('welcome')
                   }
                   else {
-                    setError('Run `capgo build onboarding` to resume.')
-                    setTimeout(() => exit(new Error('User exited onboarding')), 50)
+                    setError('Run `capgo build init` to resume.')
+                    exitOnboarding()
                   }
                 }}
               />

src/index.ts

@@ -10,7 +10,7 @@ import { listApp } from './app/list'
 import { setApp } from './app/set'
 import { setSetting } from './app/setting'
 import { clearCredentialsCommand, listCredentialsCommand, migrateCredentialsCommand, saveCredentialsCommand, updateCredentialsCommand } from './build/credentials-command'
-import { onboardingCommand } from './build/onboarding/command'
+import { onboardingBuilderCommand } from './build/onboarding/command'
 import { requestBuildCommand } from './build/request'
 import { cleanupBundle } from './bundle/cleanup'
 import { checkCompatibility } from './bundle/compatibility'
@@ -731,9 +731,10 @@ const build = program
    npx @capgo/cli build credentials save --appId <your-app-id> --platform android`)
 
 build
-  .command('onboarding')
+  .command('init')
+  .alias('onboarding')
   .description('Set up iOS build credentials interactively (creates certificates and profiles automatically)')
-  .action(onboardingCommand)
+  .action(onboardingBuilderCommand)
 
 build
   .command('request [appId]')