@capgo/cli 8.3.1 → 8.4.1

package/dist/src/build/onboarding/mcp/contract.d.ts

@@ -0,0 +1,51 @@
+export type StepKind = 'auto' | 'human_gate' | 'choice' | 'done' | 'error' | 'info';
+export type OnboardingPhase = 'preflight' | 'app' | 'credentials' | 'build' | 'done';
+export type Platform = 'ios' | 'android';
+export interface ChoiceOption {
+    value: string;
+    label?: string;
+    note?: string;
+}
+export interface CollectField {
+    field: string;
+    desc: string;
+}
+export interface NextAction {
+    /** The exact tool to call next. */
+    tool: string;
+    /** Argument hint for the model. */
+    with?: Record<string, unknown>;
+    /** A literal, copy-pasteable example call the model can pattern-match. */
+    call?: string;
+    /** Plain-English directive. */
+    instruction: string;
+}
+export interface NextStepResult {
+    onboarding: 'capgo-builder';
+    phase: OnboardingPhase;
+    /** Granular step name (reuses OnboardingStep vocabulary where applicable). */
+    state: string;
+    platform?: Platform;
+    /** 0–100. */
+    progress: number;
+    kind: StepKind;
+    summary: string;
+    /** Human-facing journey overview; informational, not an execution list. */
+    roadmap?: string[];
+    context?: Record<string, unknown>;
+    /** Present when kind === 'choice'. */
+    options?: ChoiceOption[];
+    /** Present when kind === 'human_gate'. */
+    human?: {
+        instruction: string;
+        resourceUri?: string;
+    };
+    /** Present when kind === 'human_gate': what to bring back. */
+    collect?: CollectField[];
+    next?: NextAction;
+    /** Rules of engagement; included on the first result of a session. */
+    rules?: string[];
+}
+export declare const ONBOARDING_RULES: string[];
+/** Render a result into MCP text content: imperative directive first, structured data last. */
+export declare function renderResult(result: NextStepResult): string;

package/dist/src/build/onboarding/mcp/engine.d.ts

@@ -0,0 +1,131 @@
+import type { AndroidOnboardingProgress } from '../android/types.js';
+import type { AndroidEffectDeps } from '../android/flow.js';
+import type { OnboardingProgress } from '../types.js';
+import type { NextStepResult, Platform } from './contract.js';
+import type { BuildOutputRecord } from '../../output-record.js';
+import { androidViewForStep } from '../android/flow.js';
+import { beginOAuthSession, clearOAuthSession, pollOAuthSession } from './oauth-session.js';
+/** Facts gathered during preflight; the pure deciders branch only on these. */
+export interface PreflightFacts {
+    capacitorProject: boolean;
+    appId?: string;
+    platformsDetected: Platform[];
+    authenticated: boolean;
+    appRegistered: boolean;
+    androidProgress: AndroidOnboardingProgress | null;
+    iosProgress: OnboardingProgress | null;
+}
+/** User input carried into the flow via next_step. */
+interface OnboardingInput {
+    platform?: string;
+    serviceAccountJsonPath?: string;
+    runBuild?: boolean;
+    checkBuild?: boolean;
+    keyId?: string;
+    issuerId?: string;
+    p8Path?: string;
+    serviceAccountMethod?: 'generate' | 'existing';
+    playDeveloperId?: string;
+    gcpProjectId?: string;
+    gcpProjectName?: string;
+    androidPackage?: string;
+    saMethodChoice?: 'retry' | 'save-anyway' | 'oauth';
+    credentialsExistChoice?: 'backup' | 'cancel';
+    keystoreMethod?: 'existing' | 'generate';
+    keystorePath?: string;
+    keystoreStorePassword?: string;
+    keystoreAlias?: string;
+    keystoreKeyPassword?: string;
+    keystoreNewAlias?: string;
+    keystorePasswordMethod?: 'random' | 'manual';
+    keystoreCommonName?: string;
+}
+/** Decide the first/again step for a fresh or resumed session. */
+export declare function decideStart(facts: PreflightFacts, progress: OnboardingProgress | null, deps: EngineDeps): Promise<NextStepResult>;
+export declare function decideIos(facts: PreflightFacts): NextStepResult;
+export declare function mapAndroidView(view: ReturnType<typeof androidViewForStep>, facts: PreflightFacts, opts?: {
+    keystorePath?: string;
+    keystorePassword?: string;
+}): NextStepResult;
+export declare function decideAndroid(facts: PreflightFacts, deps: EngineDeps, opts?: {
+    signInProceed?: boolean;
+}): Promise<NextStepResult>;
+export declare function decideAdvance(facts: PreflightFacts, progress: OnboardingProgress | null, input: OnboardingInput | undefined, deps: EngineDeps): Promise<NextStepResult>;
+export interface EngineDeps {
+    cwd: string;
+    hasSavedKey: () => boolean;
+    getAppId: () => Promise<string | undefined>;
+    detectPlatforms: () => Promise<Platform[]>;
+    isAppRegistered: (appId: string) => Promise<boolean>;
+    loadProgress: (appId: string) => Promise<OnboardingProgress | null>;
+    registerApp: (appId: string) => Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        alreadyExists: boolean;
+        error: string;
+    }>;
+    loadAndroidProgress: (appId: string) => Promise<AndroidOnboardingProgress | null>;
+    finalizeAndroidCredentials: (appId: string) => Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    readBuildRecord: (path: string) => Promise<BuildOutputRecord | null>;
+    buildRecordPath: (appId: string, platform: Platform) => string;
+    setIosApiKey: (appId: string, keyId: string, issuerId: string, p8Path: string) => Promise<void>;
+    finalizeIosCredentials: (appId: string) => Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    androidEffectDeps: AndroidEffectDeps;
+    /** Returns true when the current host can launch Terminal.app (macOS). Injectable for tests. */
+    canLaunchTerminal: () => boolean;
+    /** Launch `command` in a new macOS Terminal.app window. Injectable for tests. */
+    launchBuildInTerminal: (command: string) => Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    /**
+     * Optional injectable OAuth session registry for testing. When provided, the
+     * engine uses these instead of the module-level functions in oauth-session.ts.
+     * Production builds omit this and rely on the module-level registry.
+     */
+    oauthSession?: {
+        begin: typeof beginOAuthSession;
+        poll: typeof pollOAuthSession;
+        clear: typeof clearOAuthSession;
+    };
+    /**
+     * Write the generated/loaded Android keystore (.p12) to a file on disk so the
+     * user has a durable copy after onboarding. Called once when the keystore phase
+     * completes. Returns the absolute path of the written file.
+     *
+     * Optional — when omitted the keystore is kept in progress only (no file written).
+     * Omitting does not break the flow; the keystore data is always in _keystoreBase64.
+     */
+    writeKeystoreFile?: (appId: string, base64: string, alias: string) => Promise<string>;
+}
+export declare function gatherFacts(deps: EngineDeps): Promise<PreflightFacts>;
+export declare function runStart(deps: EngineDeps): Promise<NextStepResult>;
+export declare function runAdvance(deps: EngineDeps, input?: OnboardingInput): Promise<NextStepResult>;
+/**
+ * Read-only: determine the onboarding state the user is currently on, WITHOUT
+ * running any side effect. Mirrors the branch selection of decideStart/decideAndroid
+ * (preflight → platform → android resume step) but never calls effects.
+ */
+export declare function resolveCurrentState(facts: PreflightFacts): string;
+/**
+ * Read-only "explain the current step" entry point backing the
+ * capgo_builder_onboarding_explain tool. Gathers facts (read-only) and returns a
+ * plain-language explanation string. Never advances the flow or runs effects.
+ */
+export declare function explainOnboarding(deps: EngineDeps, input?: {
+    state?: string;
+}): Promise<string>;
+export {};

package/dist/src/build/onboarding/mcp/explanations.d.ts

@@ -0,0 +1,4 @@
+/** state → multi-line plain-language explanation (WHAT · WHY · OPTIONS · WHAT TO DO). */
+export declare const EXPLANATIONS: Record<string, string>;
+/** Return the explanation for a state, or a generic fallback for unknown states. */
+export declare function explainForState(state: string | undefined | null): string;

package/dist/src/build/onboarding/mcp/oauth-session.d.ts

@@ -0,0 +1,29 @@
+import type { GoogleOAuthTokens } from '../android/oauth-google.js';
+import type { PendingOAuthSession } from '../android/oauth-google.js';
+export type { PendingOAuthSession };
+/**
+ * Start a new OAuth session for `appId`, replacing any existing one.
+ *
+ * `start` is a factory that returns a `PendingOAuthSession` (e.g.
+ * `() => startOAuthFlow(config, options)`). Passing a factory rather than the
+ * session directly lets the caller defer construction until after the prior
+ * session has been cleaned up.
+ */
+export declare function beginOAuthSession(appId: string, start: () => Promise<PendingOAuthSession>): Promise<void>;
+/**
+ * Poll the current status for `appId`.
+ *
+ * Returns `{ status: 'absent' }` when no session has been started or the
+ * entry has been cleared. Otherwise returns the entry's current
+ * `status`/`tokens`/`error`.
+ */
+export declare function pollOAuthSession(appId: string): {
+    status: 'pending' | 'done' | 'error' | 'absent';
+    tokens?: GoogleOAuthTokens;
+    error?: Error;
+};
+/**
+ * Close and remove the session entry for `appId`. Safe to call on an absent
+ * appId or after the result has already settled.
+ */
+export declare function clearOAuthSession(appId: string): void;

package/dist/src/build/onboarding/mcp/onboarding-tools.d.ts

@@ -0,0 +1,17 @@
+import type { CapgoSDK } from '../../../sdk.js';
+import type { EngineDeps } from './engine.js';
+/** Minimal shape of the MCP server's tool registrar (matches McpServer.tool). */
+interface McpLike {
+    tool: (name: string, description: string, schema: Record<string, unknown>, handler: (args: any) => Promise<{
+        content: Array<{
+            type: 'text';
+            text: string;
+        }>;
+    }>) => unknown;
+}
+/**
+ * Register the 2-tool onboarding spine onto an MCP server.
+ * `depsOverride` is for tests; production passes only `server` + `sdk`.
+ */
+export declare function registerOnboardingTools(server: McpLike, sdk: CapgoSDK, depsOverride?: EngineDeps): void;
+export {};

package/dist/src/build/onboarding/mcp/step-input.d.ts

@@ -0,0 +1,45 @@
+import type { AndroidOnboardingStep } from '../android/types.js';
+/** state → the set of input fields that legitimately answer it (in order). */
+export declare const STEP_ALLOWED_FIELDS: Partial<Record<AndroidOnboardingStep, string[]>>;
+/** The set of all android input keys we govern (for the extras check). */
+export declare const ANDROID_INPUT_KEYS: string[];
+/**
+ * Validate an incoming next_step input against the step it answers.
+ *
+ * Returns { ok:true } when the input carries EXACTLY ONE of the step's allowed
+ * fields and no other governed android key. Otherwise { ok:false } with the
+ * allowed fields + the offending extra keys for a corrective message.
+ *
+ * Steps with no allowed-field entry (auto/sign-in/no-field) are not governed and
+ * always pass — the strict gate only constrains interactive input steps.
+ *
+ * @param currentStep the resume step the user is currently on
+ * @param input the next_step input object
+ */
+export declare function validateStepInput(currentStep: AndroidOnboardingStep, input: Record<string, unknown>): {
+    ok: boolean;
+    allowedFields?: string[];
+    extras: string[];
+};
+/**
+ * Content validation for the keystore store-password steps, mirroring the ink
+ * TUI onSubmit guards in app.tsx so the stateless MCP path enforces the SAME
+ * rule before a value is persisted (and before it can reach keystore-generating):
+ *
+ *   - keystore-new-store-password  → reject < 6 chars (app.tsx:2575,
+ *     'Password must be at least 6 characters')
+ *   - keystore-existing-store-password → reject empty (app.tsx:2455,
+ *     'Store password cannot be empty')
+ *
+ * Returns { ok:true } when the value passes (or the step is not a store-password
+ * step). On failure returns { ok:false, message } with the exact main wording so
+ * the gate can re-render the current step with a corrective summary and persist
+ * nothing.
+ *
+ * @param currentStep the resume step the user is currently on
+ * @param storePassword the supplied keystoreStorePassword (or undefined/null)
+ */
+export declare function validateStorePassword(currentStep: AndroidOnboardingStep, storePassword: string | undefined | null): {
+    ok: boolean;
+    message?: string;
+};

package/dist/src/build/onboarding/mcp/terminal-launch.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Build the arguments array for invoking osascript to open a Terminal window
+ * running `command`. Escapes backslashes first, then double-quotes, so that
+ * neither character can break out of the AppleScript string literal.
+ */
+export declare function buildOsascriptArgs(command: string): string[];
+/**
+ * Returns true when the current platform is macOS (darwin).
+ * Accepts an explicit platform string for testability.
+ */
+export declare function canLaunchTerminal(platform?: string): boolean;
+/**
+ * Launch `command` in a new macOS Terminal.app window via osascript.
+ * The optional `exec` parameter is injectable so tests never spawn a real
+ * process — pass a fake to avoid side effects.
+ */
+export declare function launchBuildInTerminal(command: string, exec?: (cmd: string, args: string[]) => Promise<unknown>): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+}>;

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

@@ -0,0 +1,283 @@
+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';
+export type TailStep = 'saving-credentials' | 'detecting-ci-secrets' | 'ci-secrets-setup' | 'ci-secrets-target-select' | 'ask-ci-secrets' | 'checking-ci-secrets' | 'confirm-ci-secret-overwrite' | 'uploading-ci-secrets' | 'ci-secrets-failed' | 'ask-github-actions-setup' | 'confirm-secrets-push' | 'ask-export-env' | 'exporting-env' | 'confirm-env-export-overwrite' | 'overwrite-and-export-env' | 'pick-package-manager' | 'pick-build-script' | 'pick-build-script-custom' | 'preview-workflow-file' | 'view-workflow-diff' | 'writing-workflow-file' | 'ask-build' | 'requesting-build' | 'build-complete';
+export type TailStepKind = 'auto' | 'input' | 'choice' | 'done' | 'error';
+export interface TailStepOption {
+    value: string;
+    label?: string;
+    note?: string;
+}
+export interface TailStepView {
+    step: string;
+    kind: TailStepKind;
+    title?: string;
+    prompt?: string;
+    collect?: string[];
+    options?: TailStepOption[];
+    message?: string;
+}
+/**
+ * Runtime context for the tail views — the OPTIONAL transient data a driver
+ * surfaces from a prior effect. Mirrors the tail subset of `AndroidStepCtx` so
+ * the android engine can pass its ctx straight through.
+ */
+export interface TailStepCtx {
+    ciSecretEntries?: CiSecretEntry[];
+    ciSecretTargets?: CiSecretTarget[];
+    ciSecretSetupAdvice?: CiSecretSetupAdvice[];
+    ciSecretRepoLabel?: string | null;
+    detectedPackageManager?: string;
+    availableScripts?: Record<string, string>;
+    recommendedScript?: string | null;
+    defaultEnvExportPath?: string;
+}
+export interface TailEffectProgress {
+    appId: string;
+    setupMode?: 'undecided' | 'with-workflow' | 'secrets-only' | 'declined';
+    ciSecretTarget?: CiSecretTarget | null;
+    selectedPackageManager?: PackageManager | null;
+    buildScriptChoice?: BuildScriptChoice | null;
+    envExportTargetPath?: string;
+    /**
+     * Android-only marker that gates the random-password backup hint at
+     * saving-credentials. DRIVER REQUIREMENT: the driver MUST set this on `progress`
+     * when its keystore step auto-generated the store password (the bespoke android
+     * tail only held this in React `randomPasswordGenerated` state, never persisted);
+     * the engine reads it from `progress` and has no other source. Never set on iOS.
+     */
+    keystorePasswordGenerated?: boolean;
+}
+export interface TailEffectDeps<P extends TailEffectProgress = TailEffectProgress> {
+    /** Tags the saved-cred store, env-export filename and build/workflow platform. */
+    platform: 'ios' | 'android';
+    /**
+     * Build the platform credential SHAPE written at `saving-credentials` (e.g.
+     * ANDROID_KEYSTORE_FILE… on android). Throws on missing inputs — same guards
+     * the android engine used inline.
+     */
+    buildSavedCredentials: (progress: P) => Record<string, string> | Promise<Record<string, string>>;
+    /**
+     * Lossy fallback used when the driver did not thread the saved-credential map
+     * through `carried` (crash-recovery resume). Returns {} when not rebuildable.
+     */
+    rebuildTailCredentials: (progress: P) => Record<string, string>;
+    /**
+     * The platform's resume resolver — used by the `saving-credentials` self-heal
+     * guard to detect a progress that should resume elsewhere.
+     */
+    resumeStep: (progress: P) => string;
+    updateSavedCredentials: (appId: string, platform: 'ios' | 'android', credentials: Record<string, string>) => Promise<void>;
+    loadProgress: (appId: string) => Promise<P | null>;
+    /**
+     * Persist progress. NOTE: the POST-SAVE tail never calls this — saving-credentials
+     * deletes progress.json and every later tail step runs purely from transient/
+     * carried (the bespoke android tail is in-memory-only), so persisting would
+     * re-create the deleted file. Kept on the surface so drivers can still supply it
+     * (and for symmetry with the pre-save engine), but unused by runTailEffect.
+     */
+    saveProgress: (appId: string, progress: P) => Promise<void>;
+    deleteProgress: (appId: string) => Promise<void>;
+    createCiSecretEntries?: (credentials: Partial<BuildCredentials>, apiKey?: string) => CiSecretEntry[];
+    detectCiSecretTargets?: (runner?: CommandRunner) => CiSecretDiscovery;
+    getCiSecretRepoLabelAsync?: (target: CiSecretTarget, runner?: AsyncCommandRunner) => Promise<string | null>;
+    listExistingCiSecretKeysAsync?: (target: CiSecretTarget, keys: string[], runner?: AsyncCommandRunner) => Promise<string[]>;
+    uploadCiSecretsAsync?: (target: CiSecretTarget, entries: CiSecretEntry[], existingKeys?: string[], runner?: AsyncCommandRunner, onProgress?: (current: number, total: number, keyName: string) => void) => Promise<void>;
+    exportCredentialsToEnv?: (opts: EnvExportOpts) => EnvExportResult;
+    defaultExportPath?: (appId: string, platform: 'ios' | 'android') => string;
+    generateWorkflow?: (opts: WorkflowGeneratorOpts) => GeneratedWorkflow;
+    writeWorkflowFile?: (opts: WorkflowGeneratorOpts, writeOptions?: WorkflowWriteOptions) => WorkflowWriteResult;
+    requestBuildInternal?: (appId: string, options: BuildRequestOptions, silent?: boolean, logger?: BuildLogger) => Promise<BuildRequestResult>;
+    /**
+     * The streaming BuildLogger the TUI threads into requestBuildInternal (the 4th
+     * arg). On android it streams every line into `setBuildOutput`; the engine just
+     * forwards it. When absent, requestBuildInternal is called without a logger.
+     */
+    logger?: BuildLogger;
+    /**
+     * The build VIEWER sink — DISTINCT from `onLog` (the side-log). The bespoke
+     * android tail (app.tsx ~L1654-1740) writes the build header / blank+queued /
+     * ⚠ failure / no-key UX / catch lines via `setBuildOutput` (a dedicated build
+     * output pane), NOT via the side-log `addLog`. The shared engine forwards
+     * those build-viewer lines here so the driver can route them to the right
+     * sink. OPTIONAL — absent on iOS (and legacy callers), where the lines are
+     * simply dropped and routing is unaffected.
+     */
+    onBuildOutput?: (line: string) => void;
+    /**
+     * Resolves the Capgo API key the build request should use, mirroring the
+     * android tail's CLI-flag-over-saved precedence (`apikey ?? findSavedKeySilent()`).
+     * Returns undefined when no key is resolvable — in which case requesting-build
+     * skips the build attempt and finishes at build-complete (the android no-key UX).
+     * When this dep is ABSENT the engine falls back to the legacy empty-string apikey
+     * so existing callers/tests that never resolved a key keep working.
+     */
+    resolveApikey?: () => string | undefined;
+    /**
+     * Per-key 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 ('Resolving GitHub repository…'
+     * then 'Checking existing env vars in <repo>…'). The android tail feeds this into
+     * `setCiSecretCheckPhase`. This is the ONLY sink for the check phases — they are
+     * intentionally NOT surfaced via `onStatus`, which the driver routes to the
+     * oauth/gcp panes (sending the check phases there would corrupt those). 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`, which the CiSecretsFailedStep
+     * renders. Also surfaced via `transient.ciSecretError`. OPTIONAL — no-op when
+     * absent (the failed-step view falls back to its generic message).
+     */
+    onCiSecretError?: (message: string) => void;
+    /** Reads the project's package.json scripts map. */
+    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 effect. The TUI
+     * resolves these ONCE (at `saving-credentials`) and keeps them in React state;
+     * a headless driver mirrors that by capturing `TailEffectResult.transient` and
+     * passing it back here on the NEXT effect. NEVER persisted to progress.json.
+     */
+    carried?: {
+        savedCredentials?: Record<string, string>;
+        ciSecretEntries?: CiSecretEntry[];
+        ciSecretExistingKeys?: string[];
+        /**
+         * Whether the workflow file did NOT exist when previewed (app.tsx's
+         * `previewIsNew`, resolved at `preview-workflow-file` via existsSync — driver
+         * state, never persisted). `writing-workflow-file` logs '✔ Wrote' vs
+         * '✔ Overwrote' from it. Absent/undefined defaults to NEW ('Wrote'), matching
+         * the bespoke React `useState(true)` default.
+         */
+        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;
+    signal?: AbortSignal;
+}
+export interface TailEffectResult<P extends TailEffectProgress = TailEffectProgress> {
+    /** Updated progress after the effect ran (matches what was persisted). */
+    progress: P;
+    /** Explicit next step (a platform step id — string so each platform widens it). */
+    next?: string;
+    /** Transient runtime data that lives in the driver but is NOT persisted. */
+    transient?: TailTransient;
+}
+/** The tail subset of a platform's transient ctx. Every field is optional. */
+export interface TailTransient {
+    ciSecretEntries?: CiSecretEntry[];
+    savedCredentials?: Record<string, string>;
+    ciSecretTargets?: CiSecretTarget[];
+    ciSecretSetupAdvice?: CiSecretSetupAdvice[];
+    ciSecretRepoLabel?: string | null;
+    ciSecretExistingKeys?: string[];
+    ciSecretUploadSummary?: string;
+    envExportPath?: string;
+    workflowFilePath?: string;
+    buildUrl?: string;
+    buildOutput?: string[];
+    aiJobId?: string;
+    /** Workflow-builder script preload (resolved at uploading-ci-secrets, with-workflow). */
+    availableScripts?: Record<string, string>;
+    recommendedScript?: string | null;
+    /** Set when env-export found nothing to write or threw — routed to build-complete, never thrown. */
+    envExportError?: string;
+    /** Set when requesting-build THREW — routed to build-complete, never thrown (app.tsx ~L1733). */
+    error?: string;
+    /** Set on the ci-secrets-failed routes (repo-null / catch) so the failed-step view can render the reason. */
+    ciSecretError?: string;
+}
+export type TailInput = {
+    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' | 'no';
+} | {
+    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';
+};
+/**
+ * Pure: a UI-framework-neutral description of a tail step. Mirrors the matching
+ * <Select>/prompt the TUI renders. Moved verbatim from `androidViewForStep`'s
+ * tail cases — the android engine adapts the returned view to `AndroidStepView`.
+ */
+export declare function tailViewForStep(step: TailStep, progress: TailEffectProgress | null, ctx: TailStepCtx): TailStepView;
+/**
+ * Pure state write for each tail choice/input step — returns a NEW progress
+ * object (spread — never mutate). Navigation-only / spinner-gate inputs return
+ * progress unchanged. Moved verbatim from `applyAndroidInput`'s tail reducers.
+ */
+export declare function applyTailInput<P extends TailEffectProgress>(step: TailStep, progress: P, input: TailInput): P;
+/**
+ * Dispatches to the right tail effect handler. Moved verbatim from
+ * `runAndroidEffect`'s tail cases. Platform-specific calls are parameterised via
+ * `deps.platform` / `deps.buildSavedCredentials` / `deps.rebuildTailCredentials`
+ * / `deps.resumeStep`; everything else is unchanged.
+ */
+export declare function runTailEffect<P extends TailEffectProgress>(step: TailStep, progress: P, deps: TailEffectDeps<P>): Promise<TailEffectResult<P>>;

package/dist/src/build/onboarding/tail-types.d.ts

@@ -0,0 +1,29 @@
+import type { CiSecretTarget } from './ci-secrets.js';
+import type { BuildScriptChoice, PackageManager } from './workflow-generator.js';
+export interface TailProgress {
+    /**
+     * The 3-way GitHub Actions setup choice made at `ask-github-actions-setup`.
+     * Mirrors `const [setupMode] = useState<…>('undecided')` in both app.tsx.
+     */
+    setupMode?: 'undecided' | 'with-workflow' | 'secrets-only' | 'declined';
+    /**
+     * The CI-secrets destination picked at `ci-secrets-target-select`.
+     * Mirrors `const [ciSecretTarget] = useState<CiSecretTarget | null>(null)`.
+     */
+    ciSecretTarget?: CiSecretTarget | null;
+    /**
+     * The package manager chosen at `pick-package-manager`.
+     * Mirrors `const [selectedPackageManager] = useState<PackageManager | null>(null)`.
+     */
+    selectedPackageManager?: PackageManager | null;
+    /**
+     * The build-script choice made at `pick-build-script`.
+     * Mirrors `const [buildScriptChoice] = useState<BuildScriptChoice | null>(null)`.
+     */
+    buildScriptChoice?: BuildScriptChoice | null;
+    /**
+     * The user-supplied `.env` export path entered at `ask-export-env`.
+     * Mirrors `const [envExportTargetPath] = useState<string>('')`.
+     */
+    envExportTargetPath?: string;
+}