@capgo/cli 8.3.0 → 8.4.0

package/dist/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@capgo/cli",
   "type": "module",
-  "version": "8.3.0",
+  "version": "8.4.0",
   "description": "A CLI to upload to capgo servers",
   "author": "Martin martin@capgo.app",
   "license": "Apache 2.0",
@@ -109,12 +109,36 @@
     "test:apple-api-import-helpers": "bun test/test-apple-api-import-helpers.mjs",
     "test:bundle-id-detector": "bun test/test-bundle-id-detector.mjs",
     "test:apple-api-app-list": "bun test/test-apple-api-app-list.mjs",
+    "test:apple-api-cert-create": "bun test/test-apple-api-cert-create.mjs",
     "test:app-verification": "bun test/test-app-verification.mjs",
     "test:pbxproj-parser": "bun test/test-pbxproj-parser.mjs",
     "test:manifest-path-encoding": "bun test/test-manifest-path-encoding.mjs",
     "test:self-update": "bun test/test-self-update.mjs",
     "test:update-prompt": "bun test/test-update-prompt.mjs",
-    "test": "bun run build && bun run test:helper-dce && bun run test:version-detection:setup && bun run test:bundle && bun run test:functional && bun run test:semver && bun run test:version-edge-cases && bun run test:regex && bun run test:upload && bun run test:fail-on-incompatible && bun run test:credentials && bun run test:credentials-validation && bun run test:android-service-account-validation && bun run test:build-zip-filter && bun run test:checksum && bun run test:build-needed && bun run test:ci-prompts && bun run test:ci-secrets && bun run test:android-onboarding-progress && bun run test:onboarding-telemetry && bun run test:v2-event-migration && bun run test:analytics && bun run test:analytics-error-category && bun run test:analytics-org-resolver && bun run test:supabase-perf && bun run test:preview-qr && bun run test:mcp-analytics && bun run test:app-created-source && bun run test:doctor-analytics && bun run test:posthog-exception && bun run test:build-platform-selection && bun run test:onboarding-recovery && bun run test:onboarding-progress && bun run test:onboarding-run-targets && bun run test:run-device-command && bun run test:init-app-conflict && bun run test:init-guardrails && bun run test:prompt-preferences && bun run test:esm-sdk && bun run test:mcp && bun run test:version-detection && bun run test:platform-paths && bun run test:payload-split && bun run test:manifest-path-encoding && bun run test:macos-signing && bun run test:apple-api-import-helpers && bun run test:bundle-id-detector && bun run test:apple-api-app-list && bun run test:app-verification && bun run test:pbxproj-parser && bun run test:ai-log-capture && bun run test:ai-analyze-flow && bun run test:ai-sse-parser && bun run test:ai-render-markdown && bun run test:ai-stream-markdown && bun run test:ai-onboarding-mode && bun run test:ai-fit && bun run test:platform-layout && bun run test:frame-fit && bun run test:onboarding-min-size && bun run test:min-size-gate && bun run test:shell-size-gate && bun run test:build-log-sanitize && bun run test:build-output-viewport && bun run test:diff-viewer-viewport && bun run test:build-complete-exit && bun run test:ai-analyze-stream && bun run test:support-mailto && bun run test:support-redact && bun run test:support-internal-log && bun run test:support-help-menu && bun run test:support-contact && bun run test:support-bundle-files && bun run test:self-update && bun run test:update-prompt",
+    "test:android-tail-engine": "bun test/test-android-tail-engine.mjs",
+    "test:android-tail-render": "bun test/test-android-tail-render.mjs",
+    "test:android-tail-routing": "bun test/test-android-tail-routing.mjs",
+    "test:dev-gate-stripped": "bun test/test-dev-gate-stripped.mjs",
+    "test:frame-fit-ios-shared": "bun test/test-frame-fit-ios-shared.mjs",
+    "test:ios-confirm-app-id": "bun test/test-ios-confirm-app-id.mjs",
+    "test:ios-create-new": "bun test/test-ios-create-new.mjs",
+    "test:ios-e2e": "bun test/test-ios-e2e.mjs",
+    "test:ios-flow-contract": "bun test/test-ios-flow-contract.mjs",
+    "test:ios-import-discovery": "bun test/test-ios-import-discovery.mjs",
+    "test:ios-import-export": "bun test/test-ios-import-export.mjs",
+    "test:ios-import-pickers": "bun test/test-ios-import-pickers.mjs",
+    "test:ios-import-recovery": "bun test/test-ios-import-recovery.mjs",
+    "test:ios-recovery": "bun test/test-ios-recovery.mjs",
+    "test:ios-resume": "bun test/test-ios-resume.mjs",
+    "test:ios-tail-handoff": "bun test/test-ios-tail-handoff.mjs",
+    "test:ios-tui-render": "bun test/test-ios-tui-render.mjs",
+    "test:p8-error": "bun test/test-p8-error.mjs",
+    "test:ios-tui-routing": "bun test/test-ios-tui-routing.mjs",
+    "test:ios-updater-sync-validation": "bun test/test-ios-updater-sync-validation.mjs",
+    "test:ios-verify-app": "bun test/test-ios-verify-app.mjs",
+    "test:platform-flow-contract": "bun test/test-platform-flow-contract.mjs",
+    "test:tail-engine-shared": "bun test/test-tail-engine-shared.mjs",
+    "test": "bun run build && bun run test:helper-dce && bun run test:version-detection:setup && bun run test:bundle && bun run test:functional && bun run test:semver && bun run test:version-edge-cases && bun run test:regex && bun run test:upload && bun run test:fail-on-incompatible && bun run test:credentials && bun run test:credentials-validation && bun run test:android-service-account-validation && bun run test:build-zip-filter && bun run test:checksum && bun run test:build-needed && bun run test:ci-prompts && bun run test:ci-secrets && bun run test:android-onboarding-progress && bun run test:onboarding-telemetry && bun run test:v2-event-migration && bun run test:analytics && bun run test:analytics-error-category && bun run test:analytics-org-resolver && bun run test:supabase-perf && bun run test:preview-qr && bun run test:mcp-analytics && bun run test:app-created-source && bun run test:doctor-analytics && bun run test:posthog-exception && bun run test:build-platform-selection && bun run test:onboarding-recovery && bun run test:onboarding-progress && bun run test:onboarding-run-targets && bun run test:run-device-command && bun run test:init-app-conflict && bun run test:init-guardrails && bun run test:prompt-preferences && bun run test:esm-sdk && bun run test:mcp && bun run test:version-detection && bun run test:platform-paths && bun run test:payload-split && bun run test:manifest-path-encoding && bun run test:macos-signing && bun run test:apple-api-import-helpers && bun run test:bundle-id-detector && bun run test:apple-api-app-list && bun run test:app-verification && bun run test:pbxproj-parser && bun run test:ai-log-capture && bun run test:ai-analyze-flow && bun run test:ai-sse-parser && bun run test:ai-render-markdown && bun run test:ai-stream-markdown && bun run test:ai-onboarding-mode && bun run test:ai-fit && bun run test:platform-layout && bun run test:frame-fit && bun run test:onboarding-min-size && bun run test:min-size-gate && bun run test:shell-size-gate && bun run test:build-log-sanitize && bun run test:build-output-viewport && bun run test:diff-viewer-viewport && bun run test:build-complete-exit && bun run test:ai-analyze-stream && bun run test:support-mailto && bun run test:support-redact && bun run test:support-internal-log && bun run test:support-help-menu && bun run test:support-contact && bun run test:support-bundle-files && bun run test:self-update && bun run test:update-prompt && bun run test:apple-api-cert-create && bun run test:android-tail-engine && bun run test:android-tail-render && bun run test:android-tail-routing && bun run test:dev-gate-stripped && bun run test:frame-fit-ios-shared && bun run test:ios-confirm-app-id && bun run test:ios-create-new && bun run test:ios-e2e && bun run test:ios-flow-contract && bun run test:ios-import-discovery && bun run test:ios-import-export && bun run test:ios-import-pickers && bun run test:ios-import-recovery && bun run test:ios-recovery && bun run test:ios-resume && bun run test:ios-tail-handoff && bun run test:ios-tui-render && bun run test:p8-error && bun run test:ios-tui-routing && bun run test:ios-updater-sync-validation && bun run test:ios-verify-app && bun run test:platform-flow-contract && bun run test:tail-engine-shared",
     "test:build-platform-selection": "bun test/test-build-platform-selection.mjs",
     "test:ai-log-capture": "bun test/test-ai-log-capture.mjs",
     "test:ai-analyze-flow": "bun test/test-ai-analyze-flow.mjs",

package/dist/src/build/mobileprovision-parser.d.ts

@@ -1,3 +1,4 @@
+import { Buffer } from 'node:buffer';
 export interface MobileprovisionInfo {
     name: string;
     uuid: string;
@@ -33,3 +34,11 @@ export declare function parseMobileprovisionFromBase64(base64Content: string): M
  *   - SHA1 of each embedded developer certificate (used for cert↔profile matching)
  */
 export declare function parseMobileprovisionDetailed(filePath: string): MobileprovisionDetail;
+/**
+ * Buffer-based variant of {@link parseMobileprovisionDetailed} — parses the raw
+ * .mobileprovision bytes directly instead of reading a path. Used by the iOS
+ * onboarding engine's import-provide-profile-path effect, which reads the file
+ * via its injected `readFile` dep (so the IO stays at the boundary) and parses
+ * the returned Buffer here. `source` is a label used only in error messages.
+ */
+export declare function parseMobileprovisionBufferDetailed(data: Buffer, source?: string): MobileprovisionDetail;

package/dist/src/build/onboarding/android/flow.d.ts

@@ -0,0 +1,505 @@
+import type { Buffer } from 'node:buffer';
+import type { AndroidOnboardingProgress, AndroidOnboardingStep } from './types.js';
+import type { KeystoreOptions, KeystoreResult, ListAliasesResult, ProbeKeyPasswordResult } from './keystore.js';
+import type { ValidateOptions, ValidationResult } from './service-account-validation.js';
+import type { GcpProject, GcpServiceAccount, GcpServiceAccountKey } from './gcp-api.js';
+import type { GoogleOAuthTokens, GoogleUserInfo, PendingOAuthSession, RunOAuthFlowOptions } from './oauth-google.js';
+import type { BuildCredentials } from '../../../schemas/build.js';
+import type { BuildLogger, BuildRequestOptions, BuildRequestResult } from '../../request.js';
+import type { AsyncCommandRunner, CiSecretDiscovery, CiSecretEntry, CiSecretSetupAdvice, CiSecretTarget, CommandRunner } from '../ci-secrets.js';
+import type { EnvExportOpts, EnvExportResult } from '../env-export.js';
+import type { BuildScriptChoice, GeneratedWorkflow, PackageManager, WorkflowGeneratorOpts } from '../workflow-generator.js';
+import type { WorkflowWriteOptions, WorkflowWriteResult } from '../workflow-writer.js';
+/**
+ * Pure helper: given persisted progress, validated OAuth tokens and the user's
+ * profile, return a NEW progress object (immutable spread) with:
+ *   - `_oauthRefreshToken` set to `tokens.refreshToken`
+ *   - `completedSteps.googleSignInComplete` set to `{ email, googleSubject, scope }`
+ *
+ * This is the single canonical place where Google sign-in state is written to
+ * progress — shared by the Ink core effect (`google-sign-in-running`) and the
+ * MCP bridge so both produce identical progress objects.
+ */
+export declare function applyGoogleSignIn(progress: AndroidOnboardingProgress, tokens: GoogleOAuthTokens, info: GoogleUserInfo): AndroidOnboardingProgress;
+export type AndroidStepKind = 'auto' | 'input' | 'choice' | 'done' | 'error';
+export interface AndroidStepOption {
+    value: string;
+    label?: string;
+    note?: string;
+}
+export interface AndroidStepView {
+    step: AndroidOnboardingStep;
+    kind: AndroidStepKind;
+    title?: string;
+    prompt?: string;
+    collect?: string[];
+    options?: AndroidStepOption[];
+    message?: string;
+}
+export interface AndroidStepCtx {
+    appId: string;
+    detectedPackageIds?: string[];
+    gcpProjects?: {
+        projectId: string;
+        name: string;
+        projectNumber?: string;
+    }[];
+    detectedAliases?: string[];
+    saValidation?: {
+        ok: false;
+        kind: string;
+        message: string;
+    } | {
+        ok: true;
+    };
+    /**
+     * Task 3 — keystore-existing-key-password prompt boundary.
+     * Set to true in AndroidEffectResult.transient when the auto-probe could not
+     * resolve the key password and the driver should show the manual input.
+     * After the user submits, applyAndroidInput records keystoreKeyPassword and
+     * re-running the effect finds it set and completes the phase.
+     */
+    needsKeyPasswordPrompt?: boolean;
+    /**
+     * Task 4 — fresh access token returned from google-sign-in-running so the
+     * driver can seed its token cache and avoid an immediate refresh on the next
+     * step. If the driver ignores it, deps.getAccessToken() will mint one —
+     * behaviorally identical.
+     */
+    accessToken?: string;
+    /**
+     * keystore-existing-detecting-alias wrong-password signal.
+     * Set to true in AndroidEffectResult.transient when listKeystoreAliases returns
+     * { ok: false, reason: 'wrong-password' }. The driver (app.tsx) maps this to
+     * the original UX: setError + setRetryStep('keystore-existing-store-password')
+     * + setStep('error') WITHOUT calling handleError (no retryCount bump).
+     */
+    wrongPassword?: boolean;
+    /** CI-secret entries built at saving-credentials (key/value/masked). */
+    ciSecretEntries?: CiSecretEntry[];
+    /**
+     * Full saved-credential map written at saving-credentials (the 5 build-cred
+     * fields, NO CAPGO_TOKEN). The Ink TUI holds the same in its `savedCredentials`
+     * React state and the env-export effects write it verbatim. Transient only —
+     * never persisted to progress.json (it carries the raw keystore/SA secrets).
+     */
+    savedCredentials?: Record<string, string>;
+    /** CI-secret destinations discovered at detecting-ci-secrets. */
+    ciSecretTargets?: CiSecretTarget[];
+    /** Per-destination setup advice surfaced when no target is reachable. */
+    ciSecretSetupAdvice?: CiSecretSetupAdvice[];
+    /** Resolved owner/repo (GitHub) the CLI will push secrets to. */
+    ciSecretRepoLabel?: string | null;
+    /** Which secret keys already exist on the remote (checking-ci-secrets). */
+    ciSecretExistingKeys?: string[];
+    /** Human summary of the upload (uploading-ci-secrets). */
+    ciSecretUploadSummary?: string;
+    /** Absolute path of the written .env file (exporting-env). */
+    envExportPath?: string;
+    /** Set when env-export found nothing to write or threw — routed to build-complete, never thrown (exporting-env / overwrite-and-export-env). */
+    envExportError?: string;
+    /** Absolute path of the written workflow file (writing-workflow-file). */
+    workflowFilePath?: string;
+    /** The queued build URL (requesting-build). */
+    buildUrl?: string;
+    /** Streamed build-request log lines (requesting-build). */
+    buildOutput?: string[];
+    /** Captured AI-analysis job id surfaced on a failed build (requesting-build). */
+    aiJobId?: string;
+    /** Detected package manager from the project's lockfile (pick-package-manager). */
+    detectedPackageManager?: string;
+    /** All scripts from package.json (pick-build-script picker). */
+    availableScripts?: Record<string, string>;
+    /** Project-type recommendation surfaced at the top of pick-build-script. */
+    recommendedScript?: string | null;
+    /** Default `.env` export path shown at ask-export-env (defaultExportPath). */
+    defaultEnvExportPath?: string;
+}
+export declare const KIND_TABLE: Record<AndroidOnboardingStep, AndroidStepKind>;
+/**
+ * Pure function: given an explicit step name, persisted progress (or null),
+ * and the current runtime context, return a UI-framework-neutral description
+ * of the step.
+ *
+ * This is the primary entry-point for drivers that already know the step
+ * (e.g. the MCP bridge). `androidStepView` is a thin wrapper that resolves
+ * the step from progress first.
+ *
+ * Dynamic kind for `android-package-select`:
+ *   - ctx.detectedPackageIds === undefined  → 'auto'  (preload not yet done)
+ *   - ctx.detectedPackageIds.length > 0     → 'choice' (options = the ids)
+ *   - ctx.detectedPackageIds.length === 0   → 'input'  (user must type it)
+ *
+ * All other steps use KIND_TABLE[step] unchanged.
+ *
+ * No I/O; no mutation of progress.
+ */
+export declare function androidViewForStep(step: AndroidOnboardingStep, progress: AndroidOnboardingProgress | null, ctx: AndroidStepCtx): AndroidStepView;
+export type AndroidInput = {
+    step: 'credentials-exist';
+    value: 'backup' | 'cancel';
+} | {
+    step: 'keystore-method-select';
+    value: 'existing' | 'generate' | 'learn';
+} | {
+    step: 'keystore-existing-path';
+    path: string;
+} | {
+    step: 'keystore-existing-store-password';
+    password: string;
+} | {
+    step: 'keystore-existing-alias-select';
+    alias: string;
+} | {
+    step: 'keystore-existing-alias';
+    alias: string;
+} | {
+    step: 'keystore-existing-key-password';
+    password: string;
+} | {
+    step: 'keystore-new-alias';
+    alias: string;
+} | {
+    step: 'keystore-new-password-method';
+    value: 'random' | 'manual';
+} | {
+    step: 'keystore-new-store-password';
+    password: string;
+} | {
+    step: 'keystore-new-key-password';
+    password: string;
+} | {
+    step: 'keystore-new-cn';
+    cn: string;
+} | {
+    step: 'service-account-method-select';
+    value: 'generate' | 'existing';
+} | {
+    step: 'sa-json-existing-path';
+    path: string;
+} | {
+    step: 'sa-json-validation-failed';
+    value: 'retry' | 'oauth';
+} | {
+    step: 'sa-json-validation-failed';
+    value: 'save-anyway';
+    serviceAccountKeyBase64: string;
+} | {
+    step: 'play-developer-id-input';
+    rawDeveloperIdOrUrl: string;
+} | {
+    step: 'gcp-projects-select';
+    gcpProject: {
+        projectId: string;
+        name: string;
+        projectNumber?: string;
+    };
+} | {
+    step: 'gcp-project-create-name';
+    displayName: string;
+} | {
+    step: 'android-package-select';
+    packageName: string;
+    source: 'gradle' | 'capacitor-config' | 'user-input';
+    serviceAccountMethod: 'generate' | 'existing';
+} | {
+    step: 'ci-secrets-setup';
+    value: 'retry' | 'skip';
+} | {
+    step: 'ci-secrets-target-select';
+    ciSecretTarget: CiSecretTarget | null;
+} | {
+    step: 'ask-ci-secrets';
+    value: 'yes' | 'no';
+} | {
+    step: 'confirm-ci-secret-overwrite';
+    value: 'replace' | 'skip';
+} | {
+    step: 'ci-secrets-failed';
+    value: 'retry' | 'continue';
+} | {
+    step: 'ask-github-actions-setup';
+    value: 'with-workflow' | 'secrets-only' | 'declined';
+} | {
+    step: 'confirm-secrets-push';
+    value: 'confirm' | 'cancel';
+} | {
+    step: 'ask-export-env';
+    value: 'no';
+} | {
+    step: 'ask-export-env';
+    value: 'yes';
+    envExportTargetPath: string;
+} | {
+    step: 'confirm-env-export-overwrite';
+    value: 'replace' | 'skip';
+} | {
+    step: 'pick-package-manager';
+    selectedPackageManager: PackageManager;
+} | {
+    step: 'pick-build-script';
+    value: '__custom__';
+} | {
+    step: 'pick-build-script';
+    buildScriptChoice: BuildScriptChoice;
+} | {
+    step: 'pick-build-script-custom';
+    command: string;
+} | {
+    step: 'preview-workflow-file';
+    value: 'write' | 'view' | 'cancel';
+} | {
+    step: 'view-workflow-diff';
+    value: 'close';
+} | {
+    step: 'ask-build';
+    value: 'yes' | 'no';
+};
+export declare function applyAndroidInput(step: AndroidOnboardingStep, progress: AndroidOnboardingProgress, input: AndroidInput): AndroidOnboardingProgress;
+export interface AndroidEffectDeps {
+    generateKeystore: (opts: KeystoreOptions) => KeystoreResult;
+    listKeystoreAliases: (bytes: Uint8Array, password: string) => ListAliasesResult;
+    tryUnlockPrivateKey: (bytes: Uint8Array, password: string) => ProbeKeyPasswordResult;
+    validateServiceAccountJson: (opts: ValidateOptions) => Promise<ValidationResult>;
+    updateSavedCredentials: (appId: string, platform: 'ios' | 'android', credentials: Record<string, string>) => Promise<void>;
+    loadSavedCredentials: (appId: string) => Promise<unknown>;
+    saveAndroidProgress: (appId: string, progress: AndroidOnboardingProgress) => Promise<void>;
+    loadAndroidProgress: (appId: string) => Promise<AndroidOnboardingProgress | null>;
+    deleteAndroidProgress: (appId: string) => Promise<void>;
+    readFile: (path: string) => Promise<Buffer>;
+    copyFile: (src: string, dest: string) => Promise<void>;
+    /**
+     * Run the full browser OAuth flow. The driver pre-binds OAuth client config
+     * (clientId, clientSecret, scopes) so the core never sees credentials —
+     * config/scope policy lives in the driver.
+     *
+     * Signature mirrors RunOAuthFlowOptions from oauth-google.ts (minus
+     * timeoutMs/signal which the driver controls internally).
+     */
+    runOAuthFlow: (callbacks: Pick<RunOAuthFlowOptions, 'onAuthUrl' | 'onStatus'>) => Promise<GoogleOAuthTokens>;
+    /**
+     * Non-blocking OAuth starter (MCP fire-and-poll). Opens the browser and
+     * starts the loopback listener, then returns a PendingOAuthSession immediately
+     * without waiting for sign-in to complete. The MCP bridge uses this to
+     * avoid blocking a single tool call on the full OAuth round-trip.
+     *
+     * Optional — only provided by the MCP driver. The Ink driver uses the
+     * blocking `runOAuthFlow` instead and does not need this dep.
+     *
+     * The driver pre-binds OAuth client config (clientId, clientSecret, scopes).
+     */
+    startOAuthFlow?: (callbacks?: Pick<RunOAuthFlowOptions, 'onAuthUrl' | 'onStatus'>) => Promise<PendingOAuthSession>;
+    /** Fetch the signed-in user's profile (email, sub). */
+    fetchUserInfo: (accessToken: string) => Promise<GoogleUserInfo>;
+    /**
+     * Mint a fresh access token from the stored refresh token. Called before
+     * each cloud step that needs one. The driver owns the token cache and
+     * handles expiry.
+     */
+    getAccessToken: () => Promise<string>;
+    /**
+     * Revoke a Google OAuth refresh token. Best-effort — the core swallows
+     * failures (non-fatal; the token expires on its own).
+     */
+    revokeToken: (refreshToken: string) => Promise<void>;
+    /**
+     * List GCP projects the user has access to.
+     * Mirrors gcp-api.ts: listProjects(accessToken).
+     */
+    listProjects: (accessToken: string) => Promise<GcpProject[]>;
+    /**
+     * Create a GCP project and wait for the operation to finish.
+     * Mirrors gcp-api.ts: createProject(accessToken, projectId, displayName).
+     */
+    createProject: (accessToken: string, projectId: string, displayName: string) => Promise<GcpProject>;
+    /**
+     * Enable an API on a project (idempotent).
+     * Mirrors gcp-api.ts: enableService(accessToken, projectId, serviceName).
+     */
+    enableService: (accessToken: string, projectId: string, serviceName: string) => Promise<void>;
+    /**
+     * Find or create the Capgo service account in a project.
+     * Mirrors gcp-api.ts: ensureServiceAccount(args).
+     */
+    ensureServiceAccount: (args: {
+        accessToken: string;
+        projectId: string;
+        accountId: string;
+        displayName?: string;
+        description?: string;
+    }) => Promise<{
+        account: GcpServiceAccount;
+        created: boolean;
+    }>;
+    /**
+     * Create a JSON key for a service account.
+     * Mirrors gcp-api.ts: createServiceAccountKey(args).
+     */
+    createServiceAccountKey: (args: {
+        accessToken: string;
+        projectId: string;
+        serviceAccountEmail: string;
+    }) => Promise<GcpServiceAccountKey>;
+    /**
+     * Invite the service account into the Play Console developer account.
+     * Mirrors play-api.ts: inviteServiceAccount(args).
+     */
+    inviteServiceAccount: (args: {
+        accessToken: string;
+        developerId: string;
+        serviceAccountEmail: string;
+        developerAccountPermissions?: readonly string[];
+        grants?: ReadonlyArray<{
+            packageName: string;
+            permissions: readonly string[];
+        }>;
+    }) => Promise<void>;
+    /**
+     * Find applicationId values in the Android Gradle build files.
+     * The driver pre-binds `androidDir` so this dep is argless from the core's
+     * perspective. The driver calls findAndroidApplicationIds(androidDir) under
+     * the hood.
+     */
+    findAndroidApplicationIds: () => Promise<string[]>;
+    /**
+     * Build the CI-secret entries (key/value/masked) from the saved credentials.
+     * Mirrors ci-secrets.ts: createCiSecretEntries(credentials, apiKey?).
+     */
+    createCiSecretEntries?: (credentials: Partial<BuildCredentials>, apiKey?: string) => CiSecretEntry[];
+    /**
+     * Detect which CI-secret destinations (GitHub/GitLab) are reachable.
+     * Mirrors ci-secrets.ts: detectCiSecretTargets(runner?). The driver pre-binds
+     * the command runner, so the core calls this with no args.
+     */
+    detectCiSecretTargets?: (runner?: CommandRunner) => CiSecretDiscovery;
+    /**
+     * Resolve the concrete `owner/repo` (GitHub) or `group/project` (GitLab) the
+     * CLI will target, so the user can confirm before any secret is overwritten.
+     * Mirrors ci-secrets.ts: getCiSecretRepoLabelAsync(target, runner?).
+     */
+    getCiSecretRepoLabelAsync?: (target: CiSecretTarget, runner?: AsyncCommandRunner) => Promise<string | null>;
+    /**
+     * List which of `keys` already exist as secrets/variables on the remote.
+     * Mirrors ci-secrets.ts: listExistingCiSecretKeysAsync(target, keys, runner?).
+     */
+    listExistingCiSecretKeysAsync?: (target: CiSecretTarget, keys: string[], runner?: AsyncCommandRunner) => Promise<string[]>;
+    /**
+     * Push the CI-secret entries to the target, reporting per-key progress.
+     * Mirrors ci-secrets.ts: uploadCiSecretsAsync(target, entries, existingKeys?, runner?, onProgress?).
+     */
+    uploadCiSecretsAsync?: (target: CiSecretTarget, entries: CiSecretEntry[], existingKeys?: string[], runner?: AsyncCommandRunner, onProgress?: (current: number, total: number, keyName: string) => void) => Promise<void>;
+    /**
+     * Write the credentials to a local 0o600 `.env` file (no git operation).
+     * Mirrors env-export.ts: exportCredentialsToEnv(opts).
+     */
+    exportCredentialsToEnv?: (opts: EnvExportOpts) => EnvExportResult;
+    /**
+     * Resolve the default `.env` export path for an app + platform (pure).
+     * Mirrors env-export.ts: defaultExportPath(appId, platform).
+     */
+    defaultExportPath?: (appId: string, platform: 'ios' | 'android') => string;
+    /**
+     * Generate the GitHub Actions workflow YAML (pure).
+     * Mirrors workflow-generator.ts: generateWorkflow(opts).
+     */
+    generateWorkflow?: (opts: WorkflowGeneratorOpts) => GeneratedWorkflow;
+    /**
+     * Generate + write the workflow file to `.github/workflows/capgo-build.yml`.
+     * Mirrors workflow-writer.ts: writeWorkflowFile(opts, writeOptions?).
+     */
+    writeWorkflowFile?: (opts: WorkflowGeneratorOpts, writeOptions?: WorkflowWriteOptions) => WorkflowWriteResult;
+    /**
+     * Fire the actual `capgo build request`. The driver pre-binds the logger /
+     * silent flag it owns; the core supplies appId + options.
+     * Mirrors request.ts: requestBuildInternal(appId, options, silent?, logger?).
+     */
+    requestBuildInternal?: (appId: string, options: BuildRequestOptions, silent?: boolean, logger?: BuildLogger) => Promise<BuildRequestResult>;
+    /**
+     * The streaming BuildLogger the TUI threads into requestBuildInternal (the 4th
+     * arg) so every build line streams into `setBuildOutput`. Forwarded verbatim.
+     */
+    logger?: BuildLogger;
+    /**
+     * The build VIEWER sink — the android TUI feeds this into `setBuildOutput` (the
+     * dedicated build output pane, DISTINCT from the `onLog` side-log). The shared
+     * tail writes the build header / blank+queued / ⚠ failure / no-key UX / catch
+     * lines here. Forwarded verbatim through `toTailDeps`. No-op when absent.
+     */
+    onBuildOutput?: (line: string) => void;
+    /**
+     * Resolves the Capgo API key the build request should use, mirroring the
+     * android tail's CLI-flag-over-saved precedence. Returns undefined when no key
+     * is resolvable (the no-key UX finishes at build-complete). Forwarded verbatim.
+     */
+    resolveApikey?: () => string | undefined;
+    /**
+     * Per-key CI-secret upload progress, forwarded as the 5th arg of
+     * uploadCiSecretsAsync. The android tail feeds this into
+     * `setCiSecretUploadProgress`. No-op when absent.
+     */
+    onCiSecretUploadProgress?: (current: number, total: number, keyName: string) => void;
+    /**
+     * The 2-phase checking-ci-secrets status text. The android tail feeds this into
+     * `setCiSecretCheckPhase`. No-op when absent.
+     */
+    onCiSecretCheckPhase?: (phase: string) => void;
+    /**
+     * The ci-secrets-failed reason (repo-null / catch in checking-ci-secrets). The
+     * android tail feeds this into `setCiSecretError` (rendered by the
+     * CiSecretsFailedStep). Forwarded verbatim through `toTailDeps`. No-op when absent.
+     */
+    onCiSecretError?: (message: string) => void;
+    /** Reads the project's package.json scripts map (workflow-builder preload). */
+    getPackageScripts?: () => Record<string, string>;
+    /** Detects the web-framework project type (best-effort; may resolve null). */
+    findProjectType?: (options?: {
+        quiet?: boolean;
+    }) => Promise<string | null>;
+    /** Maps a detected project type to its recommended build script name. */
+    findBuildCommandForProjectType?: (projectType: string) => Promise<string | null>;
+    /**
+     * Workflow-file telemetry hook (e.g. 'workflow-file-written'). The android tail
+     * calls `trackWorkflowEvent`. No-op when absent.
+     */
+    trackWorkflowEvent?: (event: string, options?: {
+        decision?: string;
+    }) => void;
+    /**
+     * DRIVER-HELD transient tail state, threaded back into each post-save tail
+     * effect. The Ink TUI resolves these ONCE (at `saving-credentials`) and keeps
+     * them in React state (`savedCredentials` / `ciSecretEntries` /
+     * `ciSecretExistingKeys`); a headless driver mirrors that by capturing the
+     * matching `AndroidEffectResult.transient` from each effect and passing it
+     * back here on the NEXT effect. The engine NEVER persists these to
+     * progress.json — they are secrets/credentials/entries that must stay in
+     * memory only. When a field is absent (e.g. a crash-recovery resume where the
+     * driver lost its in-memory state) the effect falls back to a SINGLE lossy
+     * re-derivation from progress (rebuildTailCredentials / createCiSecretEntries)
+     * rather than resolving the Capgo API key a second time.
+     */
+    carried?: {
+        /** Full saved credentials map written at saving-credentials (5 fields, no CAPGO_TOKEN). */
+        savedCredentials?: Record<string, string>;
+        /** CI-secret entries resolved ONCE at saving-credentials (creds + Capgo API key → CAPGO_TOKEN). */
+        ciSecretEntries?: CiSecretEntry[];
+        /** Which secret keys already exist on the remote, resolved at checking-ci-secrets. */
+        ciSecretExistingKeys?: string[];
+        /** Whether the workflow file did NOT exist at preview (app.tsx's `previewIsNew`); drives 'Wrote' vs 'Overwrote'. Defaults to NEW when absent. */
+        workflowIsNew?: boolean;
+    };
+    onStatus?: (message: string) => void;
+    onLog?: (message: string, color?: string) => void;
+    /** Internal-only diagnostic line → the support internal log (main PR #2406). Optional; no-op when absent. */
+    onInternalLog?: (line: string) => void;
+    onAuthUrl?: (url: string) => void;
+    signal?: AbortSignal;
+}
+export interface AndroidEffectResult {
+    /** Updated progress after the effect ran (matches what was persisted). */
+    progress: AndroidOnboardingProgress;
+    /** Explicit next step when not derivable from progress alone (★ transitions). */
+    next?: AndroidOnboardingStep;
+    /** Transient runtime data that lives in the driver but is NOT persisted. */
+    transient?: Partial<AndroidStepCtx>;
+}
+export declare function runAndroidEffect(step: AndroidOnboardingStep, progress: AndroidOnboardingProgress, deps: AndroidEffectDeps): Promise<AndroidEffectResult>;

package/dist/src/build/onboarding/android/keystore.d.ts

@@ -20,6 +20,24 @@ export interface KeystoreResult {
     alias: string;
     notAfter: Date;
 }
+/**
+ * Sanitize a keystore alias for use as an on-disk filename component.
+ *
+ * The alias originates from user input (e.g. `keystoreNewAlias`). It is used
+ * verbatim for the keystore crypto and the saved `KEYSTORE_KEY_ALIAS`, but the
+ * value used to build the `<alias>.p12` filename must be sanitized so a value
+ * like `../../evil` or `/etc/x` cannot escape the target directory.
+ *
+ * Rules:
+ * - strip any directory components (keep only the basename),
+ * - allow only `[A-Za-z0-9._-]`, replacing any other char with `_`,
+ * - normalize empty or dot-only results (``, `.`, `..`) to a safe default,
+ * - the return value never contains `/`, `\`, or `..`.
+ *
+ * IMPORTANT: this is ONLY for the filename. Do NOT use it for the crypto alias
+ * or the saved key alias — those must stay exactly what the user chose.
+ */
+export declare function sanitizeKeystoreAlias(alias: string): string;
 /**
  * Generate a URL-safe random password suitable for Android keystore use.
  * 24 bytes → 32-char base64url string. Collision-resistant, never written in logs.

package/dist/src/build/onboarding/android/oauth-google.d.ts

@@ -123,12 +123,43 @@ export interface LoopbackCallbackResult {
      */
     finishResponse: (html: string, statusCode?: number) => void;
 }
+/**
+ * The shape returned by `startOAuthFlow`. The loopback server is already
+ * running and the browser has been opened; the caller awaits `result` at a
+ * later point (fire-and-poll pattern for MCP).
+ */
+export interface PendingOAuthSession {
+    /** Full Google authorization URL that was opened in the browser. */
+    authUrl: string;
+    /** The loopback redirect URI embedded in the authUrl. */
+    redirectUri: string;
+    /**
+     * Resolves with validated tokens once the browser callback lands,
+     * code is exchanged and scopes pass. Rejects on error/timeout/missing-scopes.
+     */
+    result: Promise<GoogleOAuthTokens>;
+    /** Force-close the loopback server (safe after result settles). */
+    close: () => void;
+}
+/**
+ * Non-blocking OAuth starter: opens the browser and starts the loopback
+ * listener, then returns IMMEDIATELY without waiting for the sign-in to
+ * complete. The caller can `await session.result` later to collect tokens.
+ *
+ * This is the foundation for the MCP fire-and-poll sign-in model. The Ink
+ * wizard uses `runOAuthFlow` (which internally calls this and then awaits
+ * `result`) to preserve its blocking behavior.
+ */
+export declare function startOAuthFlow(config: GoogleOAuthConfig, options?: RunOAuthFlowOptions): Promise<PendingOAuthSession>;
 /**
  * Run the full browser-based OAuth flow and return tokens.
  *
  * Side effects:
  *  - Opens a browser window at Google's consent screen.
  *  - Starts (and later stops) a loopback HTTP server on 127.0.0.1.
+ *
+ * Delegates to `startOAuthFlow` and awaits the result — preserving the
+ * original blocking behavior Ink depends on.
  */
 export declare function runOAuthFlow(config: GoogleOAuthConfig, options?: RunOAuthFlowOptions): Promise<GoogleOAuthTokens>;
 export {};

package/dist/src/build/onboarding/android/oauth-scopes.d.ts

@@ -0,0 +1,4 @@
+/** OAuth scopes for Capgo Android onboarding — androidpublisher (Play) plus
+ *  cloud-platform (create GCP projects / service accounts / keys). Shared by the
+ *  Ink wizard and the MCP bridge so the two drivers can never drift. */
+export declare const OAUTH_SCOPES_FOR_ONBOARDING: readonly ["openid", "https://www.googleapis.com/auth/userinfo.email", "https://www.googleapis.com/auth/androidpublisher", "https://www.googleapis.com/auth/cloud-platform"];