@capgo/cli 8.14.0 → 8.15.0

package/dist/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@capgo/cli",
   "type": "module",
-  "version": "8.14.0",
+  "version": "8.15.0",
   "description": "A CLI to upload to capgo servers",
   "author": "Martin martin@capgo.app",
   "license": "Apache 2.0",
@@ -65,6 +65,7 @@
     "check-posix-paths": "node test/check-posix-paths.js",
     "generate-docs": "node dist/index.js generate-docs README.md",
     "test:bundle": "bun test/test-bundle.mjs",
+    "test:prescan": "bun test test/prescan/",
     "test:functional": "bun test/test-functional.mjs",
     "test:semver": "bun test/test-semver-validation.mjs",
     "test:version-edge-cases": "bun test/test-version-validation.mjs",
@@ -114,6 +115,7 @@
     "test:esm-sdk": "node test/test-sdk-esm.mjs",
     "test:auth-session": "bun test/test-auth-session.mjs",
     "test:mcp": "node test/test-mcp.mjs",
+    "test:mcp-no-key-handshake": "node test/test-mcp-no-key-handshake.mjs",
     "test:version-detection": "node test/test-get-installed-version.mjs",
     "test:version-detection:setup": "./test/fixtures/setup-test-projects.sh",
     "test:platform-paths": "bun test/test-platform-paths.mjs",
@@ -154,7 +156,7 @@
     "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:mcp-instructions && bun run test:mcp-live-update-onboarding && bun run test:mcp-stdout-guard && bun run test:mcp-platform-select && bun run test:mcp-explain-scopes && bun run test:mcp-oauth-reopen && bun run test:mcp-broker-oauth && bun run test:mcp-broker-session && bun run test:mcp-credentials-manage && bun run test:mcp-resume-prompt && bun run test:mcp-build-job && bun run test:mcp-build-tools && 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:init-replay && bun run test:prompt-preferences && bun run test:esm-sdk && bun run test:mcp && bun run test:auth-session && bun run test:version-detection && bun run test:platform-paths && bun run test:project-type-detection && bun run test:payload-split && bun run test:manifest-path-encoding && bun run test:macos-signing && bun run test:asc-key-protocol && bun run test:apple-api-import-helpers && bun run test:apple-api-verify-key && 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:cicd-failure-help && 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": "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:mcp-instructions && bun run test:mcp-live-update-onboarding && bun run test:mcp-stdout-guard && bun run test:mcp-platform-select && bun run test:mcp-explain-scopes && bun run test:mcp-oauth-reopen && bun run test:mcp-broker-oauth && bun run test:mcp-broker-session && bun run test:mcp-credentials-manage && bun run test:mcp-resume-prompt && bun run test:mcp-build-job && bun run test:mcp-build-tools && 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:init-replay && bun run test:prompt-preferences && bun run test:esm-sdk && bun run test:mcp && bun run test:mcp-no-key-handshake && bun run test:auth-session && bun run test:version-detection && bun run test:platform-paths && bun run test:project-type-detection && bun run test:payload-split && bun run test:manifest-path-encoding && bun run test:macos-signing && bun run test:asc-key-protocol && bun run test:apple-api-import-helpers && bun run test:apple-api-verify-key && 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:cicd-failure-help && 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 && bun run test:prescan",
     "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/ai/analyze.d.ts

@@ -1,7 +1,8 @@
-export type AnalyzeBehavior = 'show_menu' | 'ask_then_menu' | 'auto_upload' | 'skip';
+export type AnalyzeBehavior = 'ask_then_menu' | 'auto_upload' | 'skip';
 export interface DecideInput {
     isTTY: boolean;
     aiAnalyticsFlag: boolean;
+    sendLogsFlag: boolean;
 }
 export declare function decideAnalyzeBehavior(input: DecideInput): AnalyzeBehavior;
 export declare const CI_FAILURE_TIP = "Build failed. Tip: re-run with --ai-analytics for an AI-powered diagnosis, or --send-logs to upload the build logs to Capgo support.";

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

@@ -0,0 +1,7 @@
+/**
+ * Run an async function with the process working directory temporarily set to `dir`.
+ *
+ * NOTE: `process.chdir()` is global, so this uses a simple in-process queue to avoid
+ * concurrent calls interfering with each other.
+ */
+export declare function withCwd<T>(dir: string, fn: () => Promise<T>): Promise<T>;

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

@@ -34,6 +34,8 @@ 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;
+/** Base64 variant of {@link parseMobileprovisionDetailed} (profiles stored in CAPGO_IOS_PROVISIONING_MAP). */
+export declare function parseMobileprovisionDetailedFromBase64(base64Content: string): MobileprovisionDetail;
 /**
  * Buffer-based variant of {@link parseMobileprovisionDetailed} — parses the raw
  * .mobileprovision bytes directly instead of reading a path. Used by the iOS

package/dist/src/build/onboarding/apple-access.d.ts

@@ -0,0 +1,26 @@
+export interface AssertAscAccessOptions {
+    keyId: string;
+    issuerId: string;
+    /** The decoded .p8 PEM string (forge.util.decode64(APPLE_KEY_CONTENT)). */
+    p8Pem: string;
+    /** Project bundle id; when present we confirm it is reachable by the key. */
+    bundleId?: string;
+    signal?: AbortSignal;
+    /** Per-request timeout. Defaults to 7s (under the engine's 10s race). */
+    timeoutMs?: number;
+    /** Test-only injection point. Defaults to globalThis.fetch. */
+    fetchImpl?: typeof fetch;
+}
+export type AscAccessResult = {
+    ok: true;
+} | {
+    ok: false;
+    kind: 'no-app-access' | 'auth-error' | 'network';
+    message: string;
+};
+/**
+ * Probe App Store Connect for app access. Never throws - every failure shape is
+ * returned as `{ ok: false, kind }` so the prescan check can self-classify the
+ * severity (auth-error -> error, no-app-access -> error, network -> info).
+ */
+export declare function assertAscAccess(opts: AssertAscAccessOptions): Promise<AscAccessResult>;

package/dist/src/build/onboarding/apple-api.d.ts

@@ -8,6 +8,21 @@ export declare class AppleApiHttpError extends Error {
     readonly code?: string;
     constructor(status: number, message: string, code?: string);
 }
+export declare const ASC_AGREEMENTS_MESSAGE: string;
+export declare const ASC_KEY_REJECTED_MESSAGE: string;
+export interface AscAuthClassification {
+    is401or403: boolean;
+    isAgreements: boolean;
+    status?: number;
+    code?: string;
+    message: string;
+}
+/**
+ * Classify a thrown App Store Connect error into the shared 401/403 + agreements
+ * buckets. Returns is401or403=false for anything else (network/5xx/etc) so
+ * callers route those to their own network/info handling.
+ */
+export declare function classifyAscAuthError(err: any): AscAuthClassification;
 /**
  * Verify the API key works and try to detect the team ID from existing certificates.
  * Throws on 401/403 with a user-friendly message.

package/dist/src/build/prescan/checks/android-keystore.d.ts

@@ -0,0 +1,3 @@
+import type { PrescanCheck } from '../types';
+export declare const keystoreOpens: PrescanCheck;
+export declare const keystoreExpiry: PrescanCheck;

package/dist/src/build/prescan/checks/android-manifest.d.ts

@@ -0,0 +1,14 @@
+import type { PrescanCheck } from '../types';
+export declare const manifestWellFormed: PrescanCheck;
+export declare const manifestTagTypo: PrescanCheck;
+export declare const manifestNamespaceUri: PrescanCheck;
+export declare const manifestMissingPrefix: PrescanCheck;
+export declare const manifestExportedMissing: PrescanCheck;
+export declare const manifestMultipleUsesSdk: PrescanCheck;
+export declare const manifestDuplicateComponent: PrescanCheck;
+export declare const manifestUniquePermission: PrescanCheck;
+export declare const manifestHardcodedDebuggable: PrescanCheck;
+export declare const manifestMockLocation: PrescanCheck;
+export declare const manifestExportedUnprotected: PrescanCheck;
+export declare const manifestQueryAllPackages: PrescanCheck;
+export declare const manifestDeeplinkValid: PrescanCheck;

package/dist/src/build/prescan/checks/android-project.d.ts

@@ -0,0 +1,28 @@
+import type { PrescanCheck } from '../types';
+export declare const cordovaVarsPresent: PrescanCheck;
+export declare const gradlePropsHeuristics: PrescanCheck;
+export declare const playSaJson: PrescanCheck;
+/**
+ * Brace-counted extraction of the body of the first `keyword { ... }` block.
+ * A greedy regex would capture to the LAST `}` in the file, swallowing
+ * buildTypes/dependencies/etc. into the flavor list.
+ */
+export declare function extractBraceBlock(source: string, keyword: string): string | null;
+/**
+ * Names of the direct (depth-1) child blocks of a Gradle DSL block body.
+ * Handles Groovy `demo { ... }` and Kotlin DSL `create("demo") { ... }`,
+ * `register("demo") { ... }`, and `val demo by creating { ... }`.
+ */
+export declare function childBlockNames(block: string): string[];
+export declare const flavorExists: PrescanCheck;
+export declare const agp8PackageAttr: PrescanCheck;
+export declare const applicationIdPresent: PrescanCheck;
+export declare const capacitorBuildGradleApplied: PrescanCheck;
+export declare const gradleWrapperPresent: PrescanCheck;
+export declare const flavorDimensions: PrescanCheck;
+export declare const googleServicesFile: PrescanCheck;
+export declare const localPropertiesCommitted: PrescanCheck;
+export declare const sdkFloors: PrescanCheck;
+export declare const targetSdkPlay: PrescanCheck;
+export declare const minSdkCapacitor: PrescanCheck;
+export declare const versionFields: PrescanCheck;

package/dist/src/build/prescan/checks/blob-limit.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Local checks parse credential blobs synchronously (node-forge), so the
+ * engine's async timeout cannot bound them: a corrupted or accidentally huge
+ * saved credential would freeze the CLI for minutes with multi-GB memory
+ * amplification. Refuse anything over a sane ceiling before decoding.
+ */
+export declare const MAX_CREDENTIAL_B64_CHARS: number;
+export declare function assertCredentialBlobSize(base64: string, what: 'certificate' | 'keystore'): void;

package/dist/src/build/prescan/checks/credentials.d.ts

@@ -0,0 +1,2 @@
+import type { PrescanCheck } from '../types';
+export declare const credentialsSaved: PrescanCheck;

package/dist/src/build/prescan/checks/ios-certs.d.ts

@@ -0,0 +1,11 @@
+import type { PrescanCheck } from '../types';
+import forge from 'node-forge';
+export interface OpenedP12 {
+    cert: forge.pki.Certificate;
+    sha1: string;
+}
+/** Open the saved P12; throws on wrong password / garbage. Exported for reuse by pairing check. */
+export declare function openP12(base64: string, password: string): OpenedP12;
+export declare const p12Opens: PrescanCheck;
+export declare const p12Expiry: PrescanCheck;
+export declare const ascKeyValid: PrescanCheck;

package/dist/src/build/prescan/checks/ios-plist.d.ts

@@ -0,0 +1,3 @@
+import type { PrescanCheck } from '../types';
+export declare const SCHEME_RE: RegExp;
+export declare const infoplistSanity: PrescanCheck;

package/dist/src/build/prescan/checks/ios-profiles.d.ts

@@ -0,0 +1,21 @@
+import type { PrescanCheck, ScanContext } from '../types';
+/**
+ * One entry of CAPGO_IOS_PROVISIONING_MAP. The serialized shape (produced by
+ * buildProvisioningMap in src/build/credentials-command.ts) is
+ * `{ [bundleId]: { profile: base64, name: string } }` — keyed by the bundle id
+ * the profile is assigned to cover.
+ */
+export interface MappedProfile {
+    /** bundle id this profile is assigned to cover */
+    bundleId: string;
+    /** base64-encoded .mobileprovision content */
+    base64: string;
+    /** profile display name extracted at save time */
+    name?: string;
+}
+export declare function parseProvisioningMap(ctx: ScanContext): MappedProfile[];
+export declare const profileExpiry: PrescanCheck;
+export declare const profileBundleMatch: PrescanCheck;
+export declare const profileTypeVsMode: PrescanCheck;
+export declare const certProfilePairing: PrescanCheck;
+export declare const targetsCovered: PrescanCheck;

package/dist/src/build/prescan/checks/shared-remote.d.ts

@@ -0,0 +1,3 @@
+import type { PrescanCheck } from '../types';
+export declare const apikeyPermission: PrescanCheck;
+export declare const appExists: PrescanCheck;

package/dist/src/build/prescan/checks/shared.d.ts

@@ -0,0 +1,4 @@
+import type { PrescanCheck } from '../types';
+export declare const capSyncStale: PrescanCheck;
+export declare const nodeLinkerLayout: PrescanCheck;
+export declare const bundleIdConsistency: PrescanCheck;

package/dist/src/build/prescan/checks/store-access.d.ts

@@ -0,0 +1,20 @@
+import type { ValidateOptions, ValidationResult } from '../../onboarding/android/service-account-validation.js';
+import type { AscAccessResult, AssertAscAccessOptions } from '../../onboarding/apple-access.js';
+import type { PrescanCheck } from '../types';
+/** Injectable validator type so tests can supply a fake without any network. */
+type PlayValidator = (opts: ValidateOptions) => Promise<ValidationResult>;
+type AscAsserter = (opts: AssertAscAccessOptions) => Promise<AscAccessResult>;
+/**
+ * android/play-sa-access factory. Accepts the (injectable) service-account
+ * validator so the check is fully hermetic under test.
+ */
+export declare function makePlaySaAccess(validator: PlayValidator): PrescanCheck;
+/**
+ * ios/asc-key-access factory. Accepts the (injectable) App Store Connect access
+ * asserter so the check is fully hermetic under test.
+ */
+export declare function makeAscKeyAccess(asserter: AscAsserter): PrescanCheck;
+/** Wired checks (real validators) appended to the registry. */
+export declare const playSaAccess: PrescanCheck;
+export declare const ascKeyAccess: PrescanCheck;
+export {};

package/dist/src/build/prescan/command.d.ts

@@ -0,0 +1,52 @@
+import type { OutcomeOptions, PrescanReport, Severity } from './types';
+export interface PrescanCommandOptions {
+    platform?: string;
+    path?: string;
+    apikey?: string;
+    androidFlavor?: string;
+    iosDist?: 'app_store' | 'ad_hoc';
+    json?: boolean;
+    failOnWarnings?: boolean;
+    ignoreFatal?: boolean;
+    verbose?: boolean;
+    supaHost?: string;
+    supaAnon?: string;
+    /**
+     * pre-merged credentials (CLI flags + env + saved file) when invoked from
+     * build request's gate — the scan must validate the exact set the build
+     * will use, not a fresh saved-file/env merge.
+     */
+    credentials?: Record<string, string>;
+}
+export declare function validateFlags(opts: Pick<PrescanCommandOptions, 'failOnWarnings' | 'ignoreFatal'>): void;
+export declare function exitCodeFor(counts: Record<Severity, number>, opts: OutcomeOptions): number;
+export interface PrescanExecution {
+    report: PrescanReport;
+    /** apikey actually used for the scan (flag or saved key); undefined when remote checks were skipped */
+    apikey?: string;
+}
+/** Shared scan runner used by both the standalone command and build request's gate. */
+export declare function executePrescan(appId: string | undefined, options: PrescanCommandOptions): Promise<PrescanExecution>;
+export declare function prescanCommand(appId: string | undefined, options: PrescanCommandOptions): Promise<void>;
+export interface PrescanGateOptions {
+    enabled: boolean;
+    ignoreFatal?: boolean;
+    failOnWarnings?: boolean;
+    /** test seam; defaults to canPromptInteractively() (via resolveWarningGate) at call time */
+    interactive?: boolean;
+    silent?: boolean;
+    /**
+     * Output sink for the report / crash notice. Callers that own the terminal
+     * (Ink onboarding, SDK, MCP stdio) pass their BuildLogger here; raw clack
+     * writes would corrupt their rendering or the JSON-RPC stdout channel.
+     * Defaults to clack when not silent, and to no output when silent.
+     */
+    print?: (msg: string) => void;
+    warn?: (msg: string) => void;
+}
+/**
+ * Used by build request. Runs the scan via the provided thunk, prints the report,
+ * and resolves to 'proceed' | 'block'. NEVER throws: a crashing scanner proceeds with a notice
+ * (the scanner must never be worse than no scanner).
+ */
+export declare function runPrescanGate(opts: PrescanGateOptions, scan: () => Promise<PrescanReport>): Promise<'proceed' | 'block'>;

package/dist/src/build/prescan/context.d.ts

@@ -0,0 +1,15 @@
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { Database } from '../../types/supabase.types';
+import type { Platform, ScanContext } from './types';
+export interface BuildScanContextArgs {
+    appId?: string;
+    platform: Platform;
+    projectDir: string;
+    distributionMode?: 'app_store' | 'ad_hoc';
+    androidFlavor?: string;
+    apikey?: string;
+    supabase?: SupabaseClient<Database>;
+    /** pre-merged credentials when called from build request (avoids double work) */
+    credentials?: Record<string, string>;
+}
+export declare function buildScanContext(args: BuildScanContextArgs): Promise<ScanContext>;

package/dist/src/build/prescan/engine.d.ts

@@ -0,0 +1,7 @@
+import type { OutcomeOptions, PrescanCheck, PrescanOutcome, PrescanReport, ScanContext } from './types';
+interface EngineOptions {
+    checkTimeoutMs?: number;
+}
+export declare function runPrescan(ctx: ScanContext, checks: PrescanCheck[], options?: EngineOptions): Promise<PrescanReport>;
+export declare function decideOutcome(report: Pick<PrescanReport, 'counts'>, options: OutcomeOptions): PrescanOutcome;
+export {};

package/dist/src/build/prescan/gradle.d.ts

@@ -0,0 +1,65 @@
+export declare function readTextIfExists(path: string): string | null;
+/** Parse android/gradle.properties into a key→value map (ignores comments/blank lines). */
+export declare function gradleProperties(projectDir: string): Record<string, string>;
+/** Count `include ':…'` modules in android/capacitor.settings.gradle (proxy for plugin module count). */
+export declare function settingsGradleModuleCount(projectDir: string): number;
+export declare function appBuildGradle(projectDir: string): string | null;
+export declare function gradleApplicationId(projectDir: string): string | null;
+export interface EffectiveApplicationId {
+    /** The resolved package name, or null when the base id is unknown. */
+    packageName: string | null;
+    /**
+     * True when a productFlavors block exists (or a flavor was requested) but the
+     * effective applicationId for that flavor cannot be resolved unambiguously
+     * from static parsing. Callers should NOT emit a blocking error in this case.
+     */
+    ambiguous: boolean;
+}
+/**
+ * Resolve the package name the build will actually upload, accounting for the
+ * active product flavor's `applicationId` override / `applicationIdSuffix` on
+ * top of defaultConfig. A store-access probe must target this final package,
+ * not the unflavored defaultConfig id, or it 404s on a valid flavored upload.
+ *
+ * Returns `ambiguous: true` (and a best-effort packageName) when a flavored
+ * build cannot be statically resolved, so the caller can downgrade rather than
+ * emit a blocking error.
+ */
+export declare function resolveEffectiveApplicationId(projectDir: string, flavor?: string): EffectiveApplicationId;
+declare const SDK_DIMENSIONS: {
+    readonly minSdk: "minSdkVersion";
+    readonly targetSdk: "targetSdkVersion";
+    readonly compileSdk: "compileSdkVersion";
+};
+export type SdkDimension = keyof typeof SDK_DIMENSIONS;
+/**
+ * Remove block and line (`//`) comments from a Gradle source. Required because
+ * gradleApplicationId / resolveSdk must not match commented declarations.
+ * Conservative: line stripping cuts from `//` to end-of-line, so a `//` inside
+ * a string literal trims that line's tail - acceptable for the presence/value
+ * scans these helpers perform.
+ */
+export declare function stripGradleComments(source: string): string;
+/**
+ * Parse android/variables.gradle `ext { name = <int> }` into a key->number map.
+ * The canonical Capacitor template puts SDK literals here and app/build.gradle
+ * only references rootProject.ext.*. Non-integer values are skipped.
+ */
+export declare function variablesGradle(projectDir: string): Record<string, number>;
+/**
+ * Resolve an SDK dimension: literal in comment-stripped app/build.gradle first,
+ * then android/variables.gradle, then the manifest <uses-sdk>. Returns null
+ * (skip the dimension) when unresolved so SDK checks agree on one source of
+ * truth.
+ *
+ * The gradle literal scan excises the `productFlavors` block first. A flavor
+ * routinely pins a per-flavor SDK literal (e.g. a legacy/wear flavor with a
+ * lower minSdk) that the active build does not necessarily apply; reading the
+ * first literal anywhere in the file would let that flavor value drive a false
+ * blocking SDK error (minSdkCapacitor / targetSdkPlay). Excising productFlavors
+ * keeps the android-level `compileSdkVersion` and the defaultConfig
+ * `minSdkVersion`/`targetSdkVersion` (the values the build actually applies)
+ * while ignoring per-flavor overrides.
+ */
+export declare function resolveSdk(projectDir: string, dim: SdkDimension): number | null;
+export {};

package/dist/src/build/prescan/manifest.d.ts

@@ -0,0 +1,61 @@
+export { SCHEME_RE } from './checks/ios-plist';
+export interface ManifestFile {
+    raw: string;
+    path: string;
+}
+export interface ScannedElement {
+    tag: string;
+    attrs: Record<string, string>;
+    /** byte offset of the element's opening `<` in the source */
+    start: number;
+    /** byte offset just past the element's closing `>` in the source */
+    end: number;
+    /** the raw open tag text, e.g. `<activity android:name=".X">` */
+    rawOpenTag: string;
+}
+/**
+ * Read android/app/src/main/AndroidManifest.xml. Returns null when absent.
+ * Memoized per projectDir (bounded cache) so repeat reads return the same
+ * object.
+ */
+export declare function readAndroidManifest(projectDir: string): ManifestFile | null;
+/**
+ * Remove `<!-- ... -->` comment blocks so typo/duplicate/exported scans don't
+ * trip on commented-out elements. Replaces each comment with an equal-length
+ * run of spaces so byte offsets stay stable for callers that slice the source.
+ */
+export declare function stripXmlComments(raw: string): string;
+/**
+ * The one parse primitive consumed by every manifest check. Matches each
+ * element open tag (self-closing or not) and parses its `name="value"`
+ * attributes into a map. Closing tags (`</application>`) never match.
+ */
+export declare function scanElements(raw: string): ScannedElement[];
+export interface NamespaceFlags {
+    android: boolean;
+    tools: boolean;
+}
+/** Detect the android + tools xmlns declarations anywhere in the source. */
+export declare function hasNamespaceXmlns(raw: string): NamespaceFlags;
+export interface ApplicationBlock {
+    openTag: string;
+    body: string;
+    start: number;
+    end: number;
+}
+/**
+ * Slice the `<application ...>` ... `</application>` block (the XML analogue of
+ * extractBraceBlock). Returns null when there is no application element.
+ */
+export declare function applicationBlock(raw: string): ApplicationBlock | null;
+/**
+ * The 32 Android Lint valid manifest tags. A tag NOT in this set (and not
+ * namespaced/custom) within edit distance 1..3 of one of these is a typo.
+ */
+export declare const MANIFEST_VALID_TAGS: Set<string>;
+/**
+ * Bounded Levenshtein distance capped at `max` (Android Lint uses 3). Returns a
+ * value > max as soon as the distance is provably over the cap so distant
+ * strings never pay the full O(a*b) compute. No npm string-distance package.
+ */
+export declare function editDistance(a: string, b: string, max: number): number;

package/dist/src/build/prescan/prompt.d.ts

@@ -0,0 +1,15 @@
+import type { PrescanOutcome } from './types';
+export interface WarningGateOptions {
+    silent?: boolean;
+    /** test seam; defaults to canPromptInteractively() at call time */
+    interactive?: boolean;
+    /** test seam; defaults to @clack/prompts confirm */
+    confirmImpl?: (opts: {
+        message: string;
+    }) => Promise<boolean | symbol>;
+}
+/**
+ * Resolve an 'ask' outcome: interactive → user decides; non-interactive → proceed (per spec).
+ * Returns the final go/no-go.
+ */
+export declare function resolveWarningGate(outcome: PrescanOutcome, opts?: WarningGateOptions): Promise<'proceed' | 'block'>;

package/dist/src/build/prescan/registry.d.ts

@@ -0,0 +1,2 @@
+import type { PrescanCheck } from './types';
+export declare const ALL_CHECKS: PrescanCheck[];

package/dist/src/build/prescan/report.d.ts

@@ -0,0 +1,6 @@
+import type { PrescanReport } from './types';
+export declare function renderTerminalReport(report: PrescanReport, opts?: {
+    verbose?: boolean;
+    color?: boolean;
+}): string;
+export declare function renderJsonReport(report: PrescanReport): string;

package/dist/src/build/prescan/types.d.ts

@@ -0,0 +1,50 @@
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { Database } from '../../types/supabase.types';
+import type { CapacitorConfig } from '../../schemas/config';
+export type Severity = 'error' | 'warning' | 'info';
+export type Platform = 'ios' | 'android';
+export interface Finding {
+    id: string;
+    severity: Severity;
+    /**
+     * detail/fix/title are printed to the terminal and serialized into --json reports
+     * (routinely captured in CI logs): they must NEVER contain credential material
+     * (passwords, key/cert contents, raw credential field values).
+     */
+    title: string;
+    detail?: string;
+    fix?: string;
+    docsUrl?: string;
+}
+export interface ScanContext {
+    appId: string;
+    platform: Platform;
+    projectDir: string;
+    config?: CapacitorConfig;
+    /** merged credentials, env-var style keys (BUILD_CERTIFICATE_BASE64, ANDROID_KEYSTORE_FILE, ...) */
+    credentials?: Record<string, string>;
+    distributionMode?: 'app_store' | 'ad_hoc';
+    androidFlavor?: string;
+    apikey?: string;
+    supabase?: SupabaseClient<Database>;
+}
+export interface PrescanCheck {
+    id: string;
+    platforms: Platform[];
+    /** requires ctx.supabase; skipped (with notice) when absent */
+    remote?: boolean;
+    appliesTo?: (ctx: ScanContext) => boolean;
+    run: (ctx: ScanContext) => Promise<Finding[]>;
+}
+export interface PrescanReport {
+    findings: Finding[];
+    counts: Record<Severity, number>;
+    skippedRemote: number;
+    durationMs: number;
+    checksRun: number;
+}
+export type PrescanOutcome = 'proceed' | 'ask' | 'block';
+export interface OutcomeOptions {
+    failOnWarnings?: boolean;
+    ignoreFatal?: boolean;
+}

package/dist/src/build/prescan/upload-intent.d.ts

@@ -0,0 +1,3 @@
+import type { ScanContext } from './types';
+export declare function willUploadToPlay(ctx: ScanContext): boolean;
+export declare function willUploadToAppStore(ctx: ScanContext): boolean;

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

@@ -71,6 +71,9 @@ export declare const buildRequestOptionsSchema: z.ZodObject<{
         "auto-prompt": "auto-prompt";
         "caller-handled": "caller-handled";
     }>>;
+    prescan: z.ZodOptional<z.ZodBoolean>;
+    prescanIgnoreFatal: z.ZodOptional<z.ZodBoolean>;
+    failOnWarnings: z.ZodOptional<z.ZodBoolean>;
     builderJourneyId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type BuildRequestOptions = z.infer<typeof buildRequestOptionsSchema>;

package/dist/src/schemas/sdk.d.ts

@@ -278,6 +278,8 @@ export declare const requestBuildOptionsSchema: z.ZodObject<{
     apikey: z.ZodOptional<z.ZodString>;
     supaHost: z.ZodOptional<z.ZodString>;
     supaAnon: z.ZodOptional<z.ZodString>;
+    prescan: z.ZodOptional<z.ZodBoolean>;
+    prescanIgnoreFatal: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type RequestBuildOptions = z.infer<typeof requestBuildOptionsSchema>;
 export declare const currentBundleOptionsSchema: z.ZodObject<{