@capgo/cli 8.0.0-alpha.4 → 8.0.0

package/dist/src/build/onboarding/ui/steps/ios-import.d.ts

@@ -0,0 +1,79 @@
+import type { FC } from 'react';
+export interface SelectOption {
+    label: string;
+    value: string;
+}
+/**
+ * Why the wizard ended up on the no-match recovery menu. Drives the Alert
+ * + hint copy in `ImportNoMatchRecoveryStep` so each route gets accurate
+ * context — previously the screen claimed "no profile linked to this cert"
+ * even when the parent had just logged "Apple linked them to X" (cases 3
+ * and 4 below). Set by the parent right before each setStep call; absent
+ * (undefined) is treated as the legacy `no-profile-on-disk` default for
+ * back-compat with call sites that haven't been audited yet.
+ *
+ *   - 'no-profile-on-disk'        : identity picked, no usable on-disk
+ *                                   profile, and no ASC key to query Apple.
+ *   - 'apple-no-cert-match'       : findCertIdBySha1 returned null — Apple
+ *                                   doesn't recognize this cert.
+ *   - 'apple-no-profiles-linked'  : Apple has the cert but zero profiles
+ *                                   linked to it.
+ *   - 'apple-bundle-mismatch'     : Apple has profiles but none target the
+ *                                   current app's bundle id.
+ *   - 'apple-distribution-mismatch': Apple has profiles for this bundle id
+ *                                   but none in the requested distribution
+ *                                   mode (app_store vs ad_hoc).
+ *   - 'apple-other'               : catch-all when none of the specific
+ *                                   filters above explain the empty result.
+ */
+export type NoMatchReason = 'no-profile-on-disk' | 'apple-no-cert-match' | 'apple-no-profiles-linked' | 'apple-bundle-mismatch' | 'apple-distribution-mismatch' | 'apple-other';
+export declare const ImportScanningStep: FC;
+export interface ImportDistributionModeStepProps {
+    dense?: boolean;
+    onChange: (value: string) => void | Promise<void>;
+}
+export declare const ImportDistributionModeStep: FC<ImportDistributionModeStepProps>;
+export interface ImportPickIdentityStepProps {
+    identityCount: number;
+    options: SelectOption[];
+    dense?: boolean;
+    onChange: (value: string) => void | Promise<void>;
+}
+export declare const ImportPickIdentityStep: FC<ImportPickIdentityStepProps>;
+export interface ImportPickProfileStepProps {
+    matchedCount: number;
+    droppedCount: number;
+    distribution: 'app_store' | 'ad_hoc' | null;
+    options: SelectOption[];
+    dense?: boolean;
+    onChange: (value: string) => void;
+}
+export declare const ImportPickProfileStep: FC<ImportPickProfileStepProps>;
+export interface ImportNoMatchRecoveryStepProps {
+    identityName: string;
+    options: SelectOption[];
+    /**
+     * Why the wizard ended up here. Optional for back-compat — undefined
+     * renders the legacy `no-profile-on-disk` wording.
+     */
+    reason?: NoMatchReason;
+    /** Concrete iOS bundle id; used by the bundle-mismatch + distribution-mismatch alerts. */
+    appId?: string;
+    /** Active distribution mode; used by the distribution-mismatch alert. */
+    importDistribution?: 'app_store' | 'ad_hoc' | null;
+    dense?: boolean;
+    onChange: (value: string) => void;
+}
+export declare const ImportNoMatchRecoveryStep: FC<ImportNoMatchRecoveryStepProps>;
+export declare const ImportCreateProfileOnlyStep: FC;
+export interface ImportExportWarningStepProps {
+    identityName: string;
+    dense?: boolean;
+    onChange: (value: string) => void;
+}
+export declare const ImportExportWarningStep: FC<ImportExportWarningStepProps>;
+export interface ImportCompilingHelperStepProps {
+    dense?: boolean;
+}
+export declare const ImportCompilingHelperStep: FC<ImportCompilingHelperStepProps>;
+export declare const ImportExportingStep: FC;

package/dist/src/build/onboarding/ui/steps/ios-shared.d.ts

@@ -0,0 +1,93 @@
+import type { FC } from 'react';
+import type { BuildOnboardingRecoveryAdvice } from '../../recovery.js';
+import type { AiResultKind } from '../components.js';
+export declare const WelcomeStep: FC;
+export interface PlatformSelectStepProps {
+    appId: string;
+    dense?: boolean;
+    onChange: (value: string) => void | Promise<void>;
+}
+export declare const PlatformSelectStep: FC<PlatformSelectStepProps>;
+export interface NoPlatformStepProps {
+    iosDir: string;
+    addIosCommand: string;
+    syncIosCommand: string;
+    dense?: boolean;
+    onChange: (value: string) => void;
+}
+export declare const NoPlatformStep: FC<NoPlatformStepProps>;
+export interface AddingPlatformStepProps {
+    addIosCommand: string;
+    doctorCommand: string;
+    dense?: boolean;
+}
+export declare const AddingPlatformStep: FC<AddingPlatformStepProps>;
+export interface AiAnalysisPromptStepProps {
+    dense?: boolean;
+    onChange: (value: string) => void | Promise<void>;
+}
+export declare const AiAnalysisPromptStep: FC<AiAnalysisPromptStepProps>;
+export declare const AiAnalysisRunningStep: FC<{
+    streamText?: string;
+    terminalRows: number;
+    terminalCols: number;
+}>;
+export interface AiAnalysisResultStepProps {
+    analysisText: string | null;
+    collapsed: boolean;
+    result: {
+        kind: AiResultKind;
+        message: string;
+    } | null;
+    canRetry: boolean;
+    retriesLeft: number;
+    maxRetries: number;
+    dense?: boolean;
+    onChange: (value: string) => void | Promise<void>;
+}
+export declare const AiAnalysisResultStep: FC<AiAnalysisResultStepProps>;
+export interface ErrorStepProps {
+    error: string;
+    recoveryAdvice: BuildOnboardingRecoveryAdvice | null;
+    supportBundlePath: string | null;
+    showRetry: boolean;
+    dense?: boolean;
+    /** When true, the full error + recovery advice was already shown in the
+     *  scrollable viewer (it was taller than the viewport), so render only the
+     *  error headline + the action prompt here — keeping Try again / Restart /
+     *  Exit reachable no matter how long the advice was. */
+    collapsed?: boolean;
+    onChange: (value: string) => void | Promise<void>;
+}
+export declare function formatErrorViewerLines(error: string, recoveryAdvice: BuildOnboardingRecoveryAdvice | null, supportBundlePath: string | null): string[];
+/**
+ * Estimate the rendered row height of the COMFORTABLE ErrorStep body (marginTop
+ * + error line + recovery advice + action prompt), independent of whether the
+ * collapsed or full form actually renders. The parent uses this to decide
+ * whether to route the error through the scroll viewer.
+ *
+ * Why a structural estimate and not `measureElement`: measuring the rendered
+ * body would FEEDBACK-LOOP — a collapsed body measures short → "fits" → render
+ * full → measures tall → collapse → measures short → … This estimate depends
+ * only on the advice shape + width, so the decision is stable at any size.
+ *
+ * Calibrated against the VT harness: the body estimate lands within ~1 row of
+ * the real render across every recovery-advice shape, and the surrounding frame
+ * chrome (boxed header + completed-steps log + padding) is a fixed ~15 rows the
+ * caller reserves on top.
+ */
+export declare function estimateErrorBodyRows(error: string, recoveryAdvice: BuildOnboardingRecoveryAdvice | null, supportBundlePath: string | null, cols: number, showRetry: boolean): number;
+export declare const ErrorStep: FC<ErrorStepProps>;
+export interface BuildCompleteStepProps {
+    buildUrl: string;
+    ciSecretUploadSummary: string | null;
+    buildRequestCommand: string;
+    /** Absolute path of a workflow file written by the GitHub Actions flow. */
+    workflowWrittenPath?: string | null;
+    /** Absolute path of credentials exported to a .env fallback. */
+    envExportPath?: string | null;
+    /** Surfaced when the .env export failed (non-fatal). */
+    envExportError?: string | null;
+    dense?: boolean;
+}
+export declare const BuildCompleteStep: FC<BuildCompleteStepProps>;

package/dist/src/build/onboarding/workflow-generator.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Pure generator for a GitHub Actions workflow file that runs `capgo build
+ * request` against credentials uploaded as repository secrets.
+ *
+ * No I/O — caller decides where to write the resulting file. This keeps the
+ * generator trivially testable: feed it opts, get a `{ path, content }` back.
+ *
+ * v1 deliberately limited: GitHub-only (no GitLab YAML), single `workflow_dispatch`
+ * trigger (no push/pr triggers), one platform per dispatch (no matrix), no
+ * monorepo subdirectory handling. Each of these is a follow-up.
+ */
+export type PackageManager = 'bun' | 'npm' | 'pnpm' | 'yarn';
+export type BuildScriptChoice = {
+    type: 'npm-script';
+    name: string;
+} | {
+    type: 'custom';
+    command: string;
+} | {
+    type: 'skip';
+};
+export interface WorkflowGeneratorOpts {
+    /** The app's bundle ID, e.g. com.example.app */
+    appId: string;
+    /** Default platform when the user dispatches the workflow without overriding the input. */
+    defaultPlatform: 'ios' | 'android';
+    /** Detected via getPMAndCommand(). Drives setup actions and the `npx`/`bunx`/etc runner. */
+    packageManager: PackageManager;
+    /** What runs to produce the web bundle before `capgo build request` fires. */
+    buildScript: BuildScriptChoice;
+    /** Exact secret names that were pushed to GitHub (drives the env: block). */
+    secretKeys: string[];
+}
+export interface GeneratedWorkflow {
+    /** Relative path inside the repo where the file should live. */
+    path: string;
+    /** Full file content, ready to write. */
+    content: string;
+}
+/** Default path inside the repo. */
+export declare const WORKFLOW_PATH = ".github/workflows/capgo-build.yml";
+/**
+ * Build the GitHub Actions workflow YAML.
+ *
+ * The shape is intentionally simple: one job, one platform per dispatch,
+ * `workflow_dispatch` trigger only. Power users can fork it after the fact.
+ */
+export declare function generateWorkflow(opts: WorkflowGeneratorOpts): GeneratedWorkflow;

package/dist/src/build/onboarding/workflow-ui-helpers.d.ts

@@ -0,0 +1,18 @@
+import type { PackageManager } from './workflow-generator.js';
+export interface BuildScriptOption {
+    label: string;
+    value: string;
+}
+/**
+ * `getPMAndCommand()` returns the literal string 'unknown' when no recognizable
+ * lockfile is present. The workflow generator only knows the four real ones —
+ * fall back to 'npm' for the generator template.
+ */
+export declare function normalizePackageManager(pm: string): PackageManager;
+/**
+ * Build the picker options for `pick-build-script`. Shows ALL scripts from
+ * package.json (the user picks; we don't auto-guess), with the project-type
+ * recommendation surfaced at the top, plus escape hatches for custom commands
+ * and "skip build entirely" (raw HTML Capacitor apps).
+ */
+export declare function buildScriptPickerOptions(scripts: Record<string, string>, recommended: string | null): BuildScriptOption[];

package/dist/src/build/onboarding/workflow-writer.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Thin wrapper that turns the pure `generateWorkflow` output into actual files
+ * on disk. Kept separate from `workflow-generator.ts` so the generator stays
+ * trivially unit-testable without mocking fs.
+ *
+ * The wizard's Ink layer owns all prompts (overwrite confirmation, etc.); this
+ * module only handles "does it exist?" and "write it".
+ */
+import type { WorkflowGeneratorOpts } from './workflow-generator.js';
+import { WORKFLOW_PATH } from './workflow-generator.js';
+export { WORKFLOW_PATH };
+export interface WorkflowWriteOptions {
+    /** When true, overwrite an existing file. Default: false. */
+    overwrite?: boolean;
+    /** Optional base dir override. Defaults to cwd(). */
+    baseDir?: string;
+}
+export type WorkflowWriteResult = {
+    kind: 'written';
+    absolutePath: string;
+    content: string;
+} | {
+    kind: 'exists';
+    absolutePath: string;
+    existingContent: string;
+    newContent: string;
+};
+/**
+ * Generate the workflow YAML and write it to `.github/workflows/capgo-build.yml`.
+ * Creates the `.github/workflows/` directory if it doesn't exist.
+ *
+ * If the file already exists and `overwrite` is false, returns `kind: 'exists'`
+ * with both the existing and proposed content so the caller can render a diff
+ * and ask for explicit confirmation before clobbering.
+ */
+export declare function writeWorkflowFile(opts: WorkflowGeneratorOpts, writeOptions?: WorkflowWriteOptions): WorkflowWriteResult;

package/dist/src/build/output-record.d.ts

@@ -0,0 +1,30 @@
+/** Stable shape written to disk; bump schemaVersion if breaking changes are made. */
+export interface BuildOutputRecord {
+    schemaVersion: 1;
+    jobId: string;
+    appId: string;
+    platform: 'ios' | 'android';
+    buildMode: 'debug' | 'release';
+    status: string;
+    outputUrl: string | null;
+    qrCodeAscii: string | null;
+    qrCodePngPath: string | null;
+    finishedAt: string;
+}
+export interface WriteBuildOutputRecordInput {
+    jobId: string;
+    appId: string;
+    platform: 'ios' | 'android';
+    buildMode: 'debug' | 'release';
+    status: string;
+    outputUrl: string | null;
+}
+/**
+ * Write a build-output record to `recordPath` (JSON) and, when a URL is available,
+ * a PNG QR code to `<recordPath>.qr.png`. Returns the parsed record exactly as
+ * written so callers can log a summary without re-reading the file.
+ *
+ * Failures rendering the PNG are non-fatal — the JSON is always written. The
+ * record's `qrCodePngPath` field is null when the PNG could not be produced.
+ */
+export declare function writeBuildOutputRecord(recordPath: string, input: WriteBuildOutputRecordInput, onWarn?: (msg: string) => void): Promise<BuildOutputRecord>;

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

@@ -0,0 +1,48 @@
+export interface PbxTarget {
+    name: string;
+    bundleId: string;
+    productType: string;
+}
+/**
+ * Parse a pbxproj file's content and return all signable native targets
+ * with their resolved bundle identifiers.
+ */
+export declare function findSignableTargets(pbxprojContent: string): PbxTarget[];
+/**
+ * Search for an Xcode project.pbxproj file in standard locations:
+ *   <searchDir>/ios/*.xcodeproj/project.pbxproj
+ *   <searchDir>/*.xcodeproj/project.pbxproj
+ * Returns the first found path, or null.
+ */
+export declare function findXcodeProject(searchDir: string): string | null;
+/**
+ * Convenience: find the Xcode project in projectDir and read its pbxproj content.
+ * Returns null if no project is found.
+ */
+export declare function readPbxproj(projectDir: string): string | null;
+/**
+ * Replace every `PRODUCT_BUNDLE_IDENTIFIER = <fromId>;` assignment in pbxproj
+ * content with `<toId>` (tolerates optional quotes and surrounding whitespace).
+ * Pure — returns the new content and the number of replacements made.
+ *
+ * Matching by exact value (rather than by config block) is deliberate: callers
+ * pass the resolved Release build id as `fromId`, and real Capacitor/RN projects
+ * give extensions a SUFFIXED id (com.app.ext), so only the main target's
+ * assignment(s) match. A Debug config that shares the exact same value is
+ * updated too (keeping Debug == Release); a Debug config with a different value
+ * is left untouched.
+ */
+export declare function replaceBundleIdInPbxproj(content: string, fromId: string, toId: string): {
+    content: string;
+    changed: number;
+};
+/**
+ * Locate the project's pbxproj (same search order as detectIosBundleIds) and
+ * rewrite its `PRODUCT_BUNDLE_IDENTIFIER = <fromId>;` assignments to `<toId>`,
+ * writing the file back only when something changed. Returns the number of
+ * replacements (0 when no project or no matching assignment was found). Throws
+ * only on a filesystem read/write error.
+ */
+export declare function writeReleaseBundleId(cwd: string, iosDir: string, fromId: string, toId: string): {
+    changed: number;
+};

package/dist/src/build/platform-paths.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Platform Path Helpers
+ *
+ * Used by cloud build packaging to resolve custom Capacitor native project paths
+ * (e.g. android.path / ios.path) in monorepos.
+ */
+/**
+ * Normalize a user-configured relative path:
+ * - Converts Windows separators to forward slashes
+ * - Strips a leading "./"
+ * - Strips trailing slashes
+ * - Returns "" for "." / "./" / empty
+ */
+export declare function normalizeRelPath(input: string): string;
+/**
+ * Get the platform directory to use inside the project zip based on Capacitor config.
+ * Falls back to the default platform directory ("ios" or "android") when not configured
+ * or when configured as ".".
+ */
+export declare function getPlatformDirFromCapacitorConfig(capConfig: any, platform: 'ios' | 'android'): string;

package/dist/src/build/qr.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Handle a custom_msg from the websocket stream.
+ * Known kinds get rich rendering; unknown kinds get a warning + raw dump.
+ */
+export declare function handleCustomMsg(kind: string, data: Record<string, unknown>, log: (line: string) => void, warn: (line: string) => void): Promise<void>;

package/dist/src/build/request.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Native Build Request Module
+ *
+ * This module handles native iOS and Android build requests through Capgo's cloud build service.
+ *
+ * CREDENTIAL SECURITY GUARANTEE:
+ * ═══════════════════════════════════════════════════════════════════════════
+ * Your build credentials (certificates, keystores, passwords, API keys) are:
+ *
+ * ✓ NEVER stored permanently on Capgo servers
+ * ✓ Used ONLY during the active build process
+ * ✓ Automatically deleted from Capgo servers after build completion
+ * ✓ Retained for a MAXIMUM of 24 hours (even if build fails)
+ * ✓ Builds sent DIRECTLY to app stores (Apple/Google)
+ * ✓ Build outputs may optionally be uploaded for time-limited download links
+ *
+ * Credentials are transmitted securely over HTTPS and used only in ephemeral
+ * build environments that are destroyed after each build completes.
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * BEFORE BUILDING:
+ * You must save your credentials first using:
+ * - `npx @capgo/cli build credentials save --platform ios` (for iOS)
+ * - `npx @capgo/cli build credentials save --platform android` (for Android)
+ * - Credentials stored in ~/.capgo/credentials.json (local machine only)
+ * - Use `build credentials clear` to remove saved credentials
+ */
+import type { BuildOptionsPayload, BuildRequestOptions, BuildRequestResult } from '../schemas/build';
+/**
+ * Callback interface for build logging.
+ * Allows callers (like the onboarding UI) to capture log output
+ * without stdout/stderr interception hacks.
+ */
+export interface BuildLogger {
+    info: (msg: string) => void;
+    error: (msg: string) => void;
+    warn: (msg: string) => void;
+    success: (msg: string) => void;
+    /** Called with build log lines streamed from the builder */
+    buildLog: (msg: string) => void;
+    /** Called with upload progress percentage (0-100) */
+    uploadProgress: (percent: number) => void;
+    /** Called with custom messages from the builder (QR codes, etc.) */
+    customMsg: (kind: string, data: Record<string, unknown>) => void | Promise<void>;
+}
+type BuildPlatform = 'ios' | 'android';
+interface ResolveBuildPlatformOptions {
+    silent?: boolean;
+    interactive?: boolean;
+    promptPlatform?: () => Promise<unknown>;
+}
+export declare function resolveBuildPlatform(platform: string | undefined, { silent, interactive, promptPlatform, }?: ResolveBuildPlatformOptions): Promise<BuildPlatform>;
+export type { BuildCredentials, BuildRequestOptions, BuildRequestResult } from '../schemas/build';
+/**
+ * Extract native node_modules roots that contain platform folders.
+ */
+interface NativeDependencies {
+    packages: Set<string>;
+    cordovaPackages: Set<string>;
+    usesSPM: boolean;
+    usesCocoaPods: boolean;
+}
+interface ZipDirectoryOptions {
+    nodeModules?: string;
+}
+/**
+ * Check if a file path should be included in the zip
+ */
+export declare function shouldIncludeFile(filePath: string, platform: 'ios' | 'android', nativeDeps: NativeDependencies, platformDir: string): boolean;
+/**
+ * Zip directory for native build, including only necessary files:
+ * - ios/ OR android/ folder (based on platform)
+ * - node_modules with native code (from Podfile/settings.gradle)
+ * - capacitor.config.*, package.json, package-lock.json
+ * Zip contents are the user's responsibility, not Capgo's; Capgo packages the user-provided files as-is.
+ */
+export declare function zipDirectory(projectDir: string, outputPath: string, platform: 'ios' | 'android', capConfig: any, options?: ZipDirectoryOptions): Promise<void>;
+/**
+ * Request a native build from Capgo's cloud build service
+ *
+ * @param appId - The app ID (e.g., com.example.app)
+ * @param options - Build request options including platform and credentials
+ * @param silent - Suppress console output
+ *
+ * @returns Build request result with job ID and status
+ *
+ * SECURITY NOTE:
+ * Credentials provided to this function are:
+ * - Transmitted securely over HTTPS to Capgo's build servers
+ * - Used ONLY during the active build process
+ * - Automatically deleted after build completion
+ * - NEVER stored permanently on Capgo servers
+ * - Build outputs may optionally be uploaded for time-limited download links
+ */
+/** Keys that are non-secret build options and should NOT be sent in the credentials blob. */
+export declare const NON_CREDENTIAL_KEYS: Set<string>;
+/**
+ * Split merged credentials into a build options payload and a credentials-only payload.
+ * Non-secret configuration keys (schemes, directories, output control) go into buildOptions.
+ * Only actual secrets (certificates, passwords, API keys) remain in buildCredentials.
+ */
+export declare function splitPayload(mergedCredentials: Record<string, string | undefined>, platform: 'ios' | 'android', buildMode: string, cliVersion: string): {
+    buildOptions: BuildOptionsPayload;
+    buildCredentials: Record<string, string>;
+};
+export declare function requestBuildInternal(appId: string, options: BuildRequestOptions, silent?: boolean, logger?: BuildLogger): Promise<BuildRequestResult>;
+export declare function requestBuildCommand(appId: string, options: BuildRequestOptions): Promise<void>;

package/dist/src/build/telemetry.d.ts

@@ -0,0 +1,17 @@
+export type BuilderUploadFailureCategory = 'network_error' | 'unauthorized' | 'payload_too_large' | 'storage_failure' | 'unknown';
+type BuilderUploadPhase = 'started' | 'succeeded' | 'failed';
+export interface TrackBuilderUploadInput {
+    apikey: string;
+    appId: string;
+    orgId: string;
+    platform: 'ios' | 'android';
+    buildMode: string;
+    jobId: string;
+    sizeBytes: number;
+    phase: BuilderUploadPhase;
+    durationSeconds?: number;
+    error?: unknown;
+}
+export declare function mapBuilderUploadError(error: unknown): BuilderUploadFailureCategory;
+export declare function trackBuilderUpload(input: TrackBuilderUploadInput): Promise<void>;
+export {};

package/dist/src/bundle/builder-cta.d.ts

@@ -0,0 +1,67 @@
+export type BuilderCtaSurface = 'skip' | 'ci-ad' | 'prompt-onboarding' | 'prompt-build';
+export type BuilderCtaAction = 'continue' | 'abort' | 'launch-onboarding' | 'launch-build';
+export interface BuilderCtaContext {
+    incompatible: boolean;
+    interactive: boolean;
+    hasCredentials: boolean;
+}
+/**
+ * Pure decision: which Builder CTA surface (if any) to show for this upload.
+ * - `skip`: do nothing (compatible bundle).
+ * - `ci-ad`: non-interactive — print a one-off ad, never prompt.
+ * - `prompt-onboarding` / `prompt-build`: interactive prompt, branched on
+ *   whether the app already has build credentials.
+ */
+export declare function decideBuilderCtaSurface(ctx: BuilderCtaContext): BuilderCtaSurface;
+export interface ShouldBlockIncompatibleUploadContext {
+    incompatible: boolean;
+    failOnIncompatible: boolean;
+    interactive: boolean;
+    /** The resolved Builder CTA action (`continue` in CI / when declined). */
+    builderAction: BuilderCtaAction;
+}
+/**
+ * Pure decision: should an incompatible upload be blocked (abort + exit non-zero)
+ * instead of uploaded, given `--fail-on-incompatible`?
+ *
+ * - Only confirmed-incompatible bundles with the flag set are candidates.
+ * - Non-interactive (CI): block immediately.
+ * - Interactive: block only when the user declined the Capgo Builder native-build
+ *   escape hatch (`builderAction === 'continue'`). Accepting a native build
+ *   (`launch-build` / `launch-onboarding`) supersedes the OTA upload, so do not block.
+ */
+export declare function shouldBlockIncompatibleUpload(ctx: ShouldBlockIncompatibleUploadContext): boolean;
+export declare function printBuilderCiAd(hasCredentials: boolean): void;
+export type BuilderCtaChoice = 'yes' | 'no' | 'learn';
+interface BuilderSelectOption {
+    value: BuilderCtaChoice;
+    label: string;
+}
+interface BuilderSelectOptions {
+    message: string;
+    options: BuilderSelectOption[];
+    initialValue?: BuilderCtaChoice;
+}
+/** Select-prompt seam (`@clack/prompts` `select` satisfies it); injectable for tests. */
+export type BuilderSelect = (opts: BuilderSelectOptions) => Promise<BuilderCtaChoice | symbol>;
+export interface MaybePromptBuilderCtaParams {
+    incompatible: boolean;
+    interactive: boolean;
+    /** Whether the app already has saved build credentials (resolved by the caller). */
+    hasCredentials: boolean;
+    appId: string;
+    orgId: string;
+    apikey: string;
+    incompatibleCount: number;
+    /** Injectable for tests; defaults to the `@clack/prompts` select prompt. */
+    select?: BuilderSelect;
+    /** Injectable for tests; defaults to opening the learn page in the browser. */
+    openUrl?: (url: string) => Promise<unknown>;
+}
+/**
+ * Surface the Capgo Builder CTA for an incompatible upload and return the action
+ * the caller should take. Never throws; telemetry and prompt failures degrade to
+ * `continue` so the upload is never blocked by the CTA.
+ */
+export declare function maybePromptBuilderCta(params: MaybePromptBuilderCtaParams): Promise<BuilderCtaAction>;
+export {};

package/dist/src/bundle/check.d.ts

@@ -1,3 +1,2 @@
 export declare function searchInDirectory(dirPath: string, searchString: string): boolean;
 export declare function checkIndexPosition(dirPath: string): boolean;
-//# sourceMappingURL=check.d.ts.map

package/dist/src/bundle/cleanup.d.ts

@@ -1,18 +1,9 @@
-import type { OptionsBase } from '../utils';
-interface Options extends OptionsBase {
-    version: string;
-    bundle: string;
-    keep: number;
-    force: boolean;
-    ignoreChannel: boolean;
-}
-export declare function cleanupBundleInternal(appId: string, options: Options, silent?: boolean): Promise<{
+import type { BundleCleanupOptions } from '../schemas/bundle';
+export declare function cleanupBundleInternal(appId: string, options: BundleCleanupOptions, silent?: boolean): Promise<{
     removed: number;
     kept: number;
 }>;
-export declare function cleanupBundle(appId: string, options: Options): Promise<{
+export declare function cleanupBundle(appId: string, options: BundleCleanupOptions): Promise<{
     removed: number;
     kept: number;
 }>;
-export {};
-//# sourceMappingURL=cleanup.d.ts.map

package/dist/src/bundle/compatibility.d.ts

@@ -1,15 +1,26 @@
-import type { OptionsBase } from '../utils';
-import { checkCompatibilityCloud } from '../utils';
-interface Options extends OptionsBase {
-    channel?: string;
-    text?: boolean;
-    packageJson?: string;
-    nodeModules?: string;
-}
+import type { BundleCompatibilityOptions } from '../schemas/bundle';
+import type { Compatibility } from '../utils';
 interface CompatibilityResult {
-    finalCompatibility: Awaited<ReturnType<typeof checkCompatibilityCloud>>['finalCompatibility'];
+    finalCompatibility: Compatibility[];
+    hasIncompatible: boolean;
+    resolvedAppId: string;
+    channel: string;
+}
+export declare function checkCompatibilityInternal(appId: string, options: BundleCompatibilityOptions, silent?: boolean): Promise<CompatibilityResult>;
+export declare function checkCompatibility(appId: string, options: BundleCompatibilityOptions): Promise<void>;
+export type UploadCompatibilityResult = 'compatible' | 'incompatible' | 'skipped';
+export interface UploadCompatibilitySummary {
+    result: UploadCompatibilityResult;
+    incompatibleCount: number;
+    reasons: string[];
 }
-export declare function checkCompatibilityInternal(appId: string, options: Options, silent?: boolean): Promise<CompatibilityResult>;
-export declare function checkCompatibility(appId: string, options: Options): Promise<void>;
+/**
+ * Summarize an upload's compatibility outcome for analytics.
+ *
+ * `finalCompatibility` is `undefined` when the comparison did not run (new
+ * channel / no remote native metadata / `--ignore-metadata-check`), which is
+ * reported as `skipped` so the funnel never silently counts a skip as
+ * `compatible`.
+ */
+export declare function summarizeUploadCompatibility(finalCompatibility: Compatibility[] | undefined): UploadCompatibilitySummary;
 export {};
-//# sourceMappingURL=compatibility.d.ts.map

package/dist/src/bundle/decrypt.d.ts

@@ -0,0 +1,4 @@
+import type { BundleDecryptOptions, DecryptResult } from '../schemas/bundle';
+export type { DecryptResult } from '../schemas/bundle';
+export declare function decryptZipInternal(zipPath: string, ivsessionKey: string, options: BundleDecryptOptions, silent?: boolean): Promise<DecryptResult>;
+export declare function decryptZip(zipPath: string, ivsessionKey: string, options: BundleDecryptOptions): Promise<void>;