@capgo/cli 8.4.1 → 8.5.1

package/dist/package.json

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

package/dist/src/build/onboarding/asc-key/command.d.ts

@@ -0,0 +1,17 @@
+export interface CreateAppleKeyOptions {
+    apikey?: string;
+    /** When set, the captured key is saved into this app's iOS build credentials. */
+    appId?: string;
+    /** Save into the per-project .capgo-credentials.json instead of the global file. */
+    local?: boolean;
+    /** Print the captured Key ID / Issuer ID / .p8 path as JSON on stdout. */
+    json?: boolean;
+}
+/**
+ * Guided creation of an App Store Connect **team** API key. Launches the native
+ * macOS helper (a precompiled Swift app that walks the user through Apple's web
+ * UI in an embedded browser), streams its stats protocol to PostHog, and
+ * captures the resulting key — issuer id, key id and the one-time .p8 — without
+ * the user ever copy-pasting a credential.
+ */
+export declare function createAppleKeyCommand(options?: CreateAppleKeyOptions): Promise<void>;

package/dist/src/build/onboarding/asc-key/helper.d.ts

@@ -0,0 +1,146 @@
+import type { AscCredentials, AscEventLine, AscLogLine } from './protocol';
+import type { CodesignRunner } from '../macos-signing';
+/**
+ * Where a resolved helper binary came from. `package` is the signed npm bundle —
+ * the ONLY source we spawn-time signature-verify. `override`/`cache`/`local` are
+ * dev/CI paths (unsigned or ad-hoc) that skip verification.
+ */
+export type AscHelperSource = 'override' | 'package' | 'cache' | 'local';
+export interface ResolvedAscHelper {
+    /** Inner executable to spawn. */
+    binary: string;
+    /** Where it came from (drives whether we verify the signature at spawn). */
+    source: AscHelperSource;
+    /**
+     * The enclosing `.app` bundle path — present only for the signed `package`
+     * source, where it is the target of the designated-requirement check.
+     */
+    bundlePath?: string;
+}
+/** Thrown when the helper is requested on a non-macOS host. */
+export declare class NotMacOSError extends Error {
+    constructor();
+}
+export declare function isMacOS(): boolean;
+/**
+ * Locate the precompiled Swift helper, in priority order:
+ *   1. `CAPGO_ASC_KEY_HELPER_PATH` — explicit override (dev / CI / tests). Only
+ *      honored in dev builds (DCE'd from release bundles, like the keychain
+ *      helper's CAPGO_KEYCHAIN_HELPER_PATH); skips signature verification.
+ *   2. The signed `CapgoAscKeyHelper.app` in the arch-matching
+ *      `@capgo/cli-helper-darwin-*` package — verified at spawn time.
+ *   3. `~/.capgo/asc-key-helper/<binary>` — the legacy cached download location.
+ *   4. A local `swift build` of the vendored package (dev, running from src).
+ * Returns `null` (caller shows install / manual guidance) when none exists OR on
+ * macOS < 14 — the packaged SwiftUI/WKWebView app requires macOS 14, so the
+ * guided path must never be offered where it can't launch.
+ *
+ * Synchronous on purpose: it gates the guided path in several call sites that
+ * cannot await. Signature verification of the package source is deferred to
+ * {@link runAscKeyHelper} (just before spawn), which can await.
+ */
+export declare function resolveAscHelper(): ResolvedAscHelper | null;
+/**
+ * Path-only resolver kept for the many synchronous gating call sites. Returns
+ * the inner executable to spawn, or `null`. See {@link resolveAscHelper} for the
+ * source metadata that drives spawn-time signature verification.
+ */
+export declare function resolveHelperBinary(): string | null;
+/** Why the guided helper can't be offered. See {@link probeGuidedHelper}. */
+export type GuidedHelperUnusableReason = 'not-macos' /** Not a Mac — the helper is a macOS app (Linux/Windows). */ | 'unsupported-os' /** macOS < 14 — the SwiftUI/WKWebView app can't launch. */ | 'not-installed' /** No helper resolved (optional package absent, no cache/build). */ | 'untrusted'; /** Helper present but its Developer-ID signature/team didn't verify. */
+export type GuidedHelperProbe = {
+    usable: true;
+    source: AscHelperSource;
+} | {
+    usable: false;
+    reason: GuidedHelperUnusableReason;
+    detail?: string;
+};
+export interface ProbeGuidedHelperOptions {
+    /**
+     * Inject a pre-resolved helper instead of calling {@link resolveAscHelper}
+     * (tests). `null` models "nothing resolved". Omit in production.
+     */
+    resolved?: ResolvedAscHelper | null;
+    /** Forward an injected codesign runner to signature verification (tests). */
+    codesignRunner?: CodesignRunner;
+}
+/**
+ * Decide — once, up front — whether guided ASC-key creation can ACTUALLY run on
+ * this machine, so the onboarding flow never offers the guided path it would
+ * then have to reject. Unlike the sync {@link resolveHelperBinary} existence
+ * check, this also verifies the Developer-ID signature + Capgo team of a
+ * packaged bundle, so a helper that is installed but wrongly signed / wrong-team /
+ * tampered is reported `untrusted` (treated exactly like not-installed: the
+ * guided option is withheld and the user goes straight to manual instructions,
+ * the same as on Linux).
+ *
+ * Async because the signature check spawns `codesign`. Mirrors the spawn-time
+ * verification in {@link runAscKeyHelper} (same bundle id, same verifier), so a
+ * `usable` verdict here means the later spawn won't be refused for trust.
+ */
+export declare function probeGuidedHelper(options?: ProbeGuidedHelperOptions): Promise<GuidedHelperProbe>;
+/**
+ * Dismiss the helper window. The outcome resolves as soon as the helper delivers
+ * its terminal `result` line — BEFORE the process exits — so the helper can keep
+ * its window open (showing a success screen) while the CLI advances. The caller
+ * invokes `close()` once the flow has moved on (e.g. the key verified) to close
+ * the window; until then it stays open. Safe to call more than once / after the
+ * window already closed.
+ */
+export type CloseHelper = () => void;
+export interface AscHelperSuccess {
+    ok: true;
+    credentials: AscCredentials;
+    runId: string;
+    /** Number of stats events the helper emitted during the run. */
+    eventCount: number;
+    /** Number of diagnostic `log` lines routed to the internal support log. */
+    logCount: number;
+    /** Dismiss the still-open helper window. See {@link CloseHelper}. */
+    close: CloseHelper;
+}
+export interface AscHelperFailure {
+    ok: false;
+    errorCode: string;
+    message: string;
+    runId: string;
+    /** Number of diagnostic `log` lines routed to the internal support log. */
+    logCount: number;
+    /** Dismiss the helper window (no-op once it has exited). See {@link CloseHelper}. */
+    close: CloseHelper;
+}
+export type AscHelperOutcome = AscHelperSuccess | AscHelperFailure;
+export interface RunAscKeyHelperOptions {
+    /** Pre-resolved helper binary path (tests inject a fake; prod auto-resolves). */
+    helperPathOverride?: string;
+    /** API key for analytics attribution; falls back to the saved key. */
+    apikey?: string;
+    /** Optional observer for every event line (UI progress / tests). */
+    onEvent?: (event: AscEventLine) => void;
+    /** Optional observer for every diagnostic log line (UI / tests). */
+    onLog?: (line: AscLogLine) => void;
+    /** Forward events to PostHog via trackEvent. Defaults to true. */
+    forwardToAnalytics?: boolean;
+    /**
+     * Append diagnostic `log` lines (and a per-run summary) to the CLI's internal
+     * support log via {@link appendInternalLog}. Defaults to true. The append is
+     * best-effort and no-ops when no internal log has been started for this run.
+     */
+    forwardToInternalLog?: boolean;
+    /**
+     * Abort signal. When it fires — e.g. the onboarding TUI unmounts because the
+     * user quit — the helper child is terminated (SIGTERM, then SIGKILL) so its
+     * stdio pipes stop keeping the CLI process alive. Without this the CLI hangs
+     * after exit while the helper window is still open.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Launch the precompiled helper, stream its NDJSON stats protocol, forward each
+ * `event` line to PostHog, and resolve with the credentials from the terminal
+ * `result` line. The private key is returned to the caller but NEVER forwarded
+ * to analytics. Never rejects on a helper-side failure — returns a structured
+ * failure outcome instead (it throws only for {@link NotMacOSError}).
+ */
+export declare function runAscKeyHelper(options?: RunAscKeyHelperOptions): Promise<AscHelperOutcome>;

package/dist/src/build/onboarding/asc-key/protocol.d.ts

@@ -0,0 +1,97 @@
+/** Protocol version understood by this CLI. Bumped on breaking changes. */
+export declare const ASC_PROTOCOL_VERSION = 1;
+/** Analytics channel every forwarded helper event is sent on. */
+export declare const ASC_KEY_CHANNEL = "app-store-connect-key";
+/** A non-sensitive analytics event emitted by the helper. */
+export interface AscEventLine {
+    capgoAscKey: number;
+    kind: 'event';
+    /** Milliseconds since the helper started. */
+    ts: number;
+    /** Correlates every line of a single helper run. */
+    runId: string;
+    /** snake_case event name, e.g. `step_changed`, `validation_succeeded`. */
+    name: string;
+    /** Non-sensitive properties. NEVER contains the private key. */
+    props: Record<string, unknown>;
+}
+/** Severity levels a helper diagnostic `log` line may carry. */
+export declare const ASC_LOG_LEVELS: readonly ["debug", "info", "warn", "error"];
+export type AscLogLevel = (typeof ASC_LOG_LEVELS)[number];
+/**
+ * A verbose diagnostic line. Unlike an `event` (which feeds PostHog analytics),
+ * a `log` line is routed into the CLI's **internal support log** — the bundle a
+ * user emails to support when a run goes wrong. Use it generously for anything
+ * that helps a human diagnose a stuck/failed run after the fact: a finder that
+ * matched nothing, an unexpected navigation, the detail of a validation error.
+ * It is NOT analytics and, like an event, NEVER carries the private key.
+ */
+export interface AscLogLine {
+    capgoAscKey: number;
+    kind: 'log';
+    /** Milliseconds since the helper started. */
+    ts: number;
+    /** Correlates every line of a single helper run. */
+    runId: string;
+    /** Severity, defaulting to `info` when the helper omits/garbles it. */
+    level: AscLogLevel;
+    /** Human-readable diagnostic message. */
+    message: string;
+    /** Optional structured context. NEVER contains the private key. */
+    props: Record<string, unknown>;
+}
+/** The captured credentials, delivered on the terminal success line. */
+export interface AscCredentials {
+    keyId: string;
+    issuerId: string;
+    privateKey: string;
+}
+/** Terminal line: success carries credentials, failure carries an error. */
+export interface AscResultLine {
+    capgoAscKey: number;
+    kind: 'result';
+    ts: number;
+    runId: string;
+    ok: boolean;
+    keyId?: string;
+    issuerId?: string;
+    privateKey?: string;
+    errorCode?: string;
+    message?: string;
+}
+export type AscProtocolLine = AscEventLine | AscLogLine | AscResultLine;
+/**
+ * Parse a single raw stdout line into a protocol envelope, or `null` when the
+ * line is not part of the protocol (blank line, incidental chatter, wrong
+ * version, or malformed JSON). Never throws — a misbehaving helper must not
+ * crash the CLI.
+ */
+export declare function parseAscProtocolLine(line: string): AscProtocolLine | null;
+/**
+ * Incremental line splitter for a streamed stdout. Push raw chunks as they
+ * arrive; get back the protocol lines completed by that chunk. Partial trailing
+ * data is buffered until its newline arrives. Call {@link flush} at EOF to parse
+ * any final newline-less remainder.
+ */
+export declare class AscProtocolParser {
+    private buffer;
+    push(chunk: string): AscProtocolLine[];
+    flush(): AscProtocolLine[];
+}
+/**
+ * Build the `trackEvent` tags for a forwarded helper event: the helper's
+ * `props` (secret-stripped + scalar-coerced) plus protocol context. Exported
+ * for testing.
+ */
+export declare function buildEventTags(event: AscEventLine): Record<string, string | number | boolean>;
+/**
+ * Map a helper event line to a `trackEvent` input. The `event` field is a
+ * human-readable Title Case rendering of the snake_case name (e.g.
+ * `step_changed` -> "Step Changed"), under the {@link ASC_KEY_CHANNEL} channel.
+ */
+export declare function ascEventToTrack(event: AscEventLine): {
+    channel: string;
+    event: string;
+    icon: string;
+    tags: Record<string, string | number | boolean>;
+};

package/dist/src/build/onboarding/ios/progress.d.ts

@@ -1,2 +1,2 @@
 import type { OnboardingProgress, OnboardingStep } from '../types.js';
-export declare function getIosResumeStep(progress: OnboardingProgress | null): OnboardingStep;
+export declare function getIosResumeStep(progress: OnboardingProgress | null, canAutomate?: boolean): OnboardingStep;

package/dist/src/build/onboarding/macos-signing.d.ts

@@ -122,6 +122,13 @@ export declare function filterProfilesForApp(profiles: readonly DiscoveredProfil
  * exported PKCS#12. 32 bytes of entropy → 64-char hex string.
  */
 export declare function generateP12Passphrase(): string;
+/**
+ * Bundle identifier of the App Store Connect key helper's CapgoAscKeyHelper.app.
+ * Pinned in its designated requirement exactly like the keychain helper above —
+ * same team, same Developer ID, different bundle id. Must match
+ * cli/scripts/package-asc-key-helper-app.sh and publish_cli_helper.yml's sign step.
+ */
+export declare const ASC_KEY_HELPER_BUNDLE_IDENTIFIER = "app.capgo.asc-key-helper";
 /**
  * Map a Node `process.arch` value to the matching helper package name, or
  * null when no precompiled helper exists for that architecture.
@@ -129,14 +136,16 @@ export declare function generateP12Passphrase(): string;
 export declare function helperPackageName(arch: string): string | null;
 /**
  * codesign designated requirement asserting: the exact helper bundle identifier
- * (app.capgo.cli.helper), an Apple-rooted chain, a Developer ID Application leaf
- * cert (OID 1.2.840.113635.100.6.1.13), and the given Apple Team ID as the
- * signing team. The identifier clause is what scopes the requirement to THIS
- * binary — without it, any other binary signed with Capgo's Developer ID cert
- * (a future tool, a leaked artifact) would also satisfy the check.
- */
-export declare function helperSignatureRequirement(teamId?: string): string;
-interface CodesignRunner {
+ * (defaults to the keychain helper's app.capgo.cli.helper), an Apple-rooted
+ * chain, a Developer ID Application leaf cert (OID 1.2.840.113635.100.6.1.13),
+ * and the given Apple Team ID as the signing team. The identifier clause is what
+ * scopes the requirement to THIS binary — without it, any other binary signed
+ * with Capgo's Developer ID cert (a future tool, a leaked artifact) would also
+ * satisfy the check. Pass `bundleIdentifier` to scope it to a different Capgo
+ * helper (e.g. the ASC key helper) signed with the same Developer ID + team.
+ */
+export declare function helperSignatureRequirement(teamId?: string, bundleIdentifier?: string): string;
+export interface CodesignRunner {
     (args: readonly string[]): Promise<SpawnResult>;
 }
 export interface ResolveHelperBinaryOptions {
@@ -158,10 +167,36 @@ export interface ResolveHelperBinaryOptions {
  *
  * Resolution order:
  *   1. CAPGO_KEYCHAIN_HELPER_PATH (dev builds only — see the build-time flag)
- *   2. The arch-matching @capgo/cli-keychain-darwin-* optional dependency
+ *   2. The arch-matching @capgo/cli-helper-darwin-* optional dependency
  *   3. Hard error with install guidance. There is no compile fallback.
  */
 export declare function resolveHelperBinary(options?: ResolveHelperBinaryOptions): Promise<string>;
+export interface VerifyAppBundleSignatureOptions {
+    /**
+     * Bundle identifier to pin in the designated requirement (e.g.
+     * app.capgo.cli.helper for the keychain helper, app.capgo.asc-key-helper for
+     * the ASC key helper). Both are signed with the same Developer ID + team.
+     */
+    bundleIdentifier: string;
+    /** Human-readable name for the helper, used in the thrown error message. */
+    label?: string;
+    /** Extra guidance appended to the error message (e.g. a reinstall hint). */
+    reinstallHint?: string;
+    /** Override the codesign spawn (tests). */
+    codesignRunner?: CodesignRunner;
+}
+/**
+ * Verify an app bundle's (or binary's) code signature against Capgo's designated
+ * requirement (Apple-rooted chain + Developer ID Application leaf + Capgo Team ID
+ * + the given bundle identifier). macOS validates the certificate chain and the
+ * seal, so this also detects post-install tampering. Throws — never returns —
+ * on any failure, so callers can verify-then-spawn safely.
+ *
+ * Shared by the keychain helper and the App Store Connect key helper: both ship
+ * inside the same npm package, signed with the same Developer ID, distinguished
+ * only by their bundle identifiers.
+ */
+export declare function verifyAppBundleSignature(bundlePath: string, options: VerifyAppBundleSignatureOptions): Promise<void>;
 /**
  * Output shape from the Swift helper's stdout — always emitted as one line of
  * JSON regardless of success or failure. See cli-helper/src/helper.swift for
@@ -204,7 +239,7 @@ export interface ExportP12Options {
  * runs against the same identity from the same binary are silent.
  *
  * Internally runs the precompiled, signature-verified `helper keychain-export`
- * subcommand from the arch-matching `@capgo/cli-keychain-darwin-*` package.
+ * subcommand from the arch-matching `@capgo/cli-helper-darwin-*` package.
  *
  * @param targetSha1 SHA1 of the identity to export (from {@link listSigningIdentities})
  * @param options    See {@link ExportP12Options}

package/dist/src/build/onboarding/progress.d.ts

@@ -20,7 +20,7 @@ export declare function deleteProgress(appId: string, baseDir?: string): Promise
  * into the create-new path's `creating-certificate` step (which would trigger
  * the Apple 3-cert-limit error for users at the limit).
  */
-export declare function getResumeStep(progress: OnboardingProgress | null): OnboardingStep;
+export declare function getResumeStep(progress: OnboardingProgress | null, canAutomate?: boolean): OnboardingStep;
 /**
  * Pure routing decision used by the `import-scanning` useEffect to skip
  * questions the user already answered on a previous attempt.

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

@@ -17,7 +17,7 @@ export interface OnboardingResult {
     /** Present only when outcome === 'completed'. */
     summary?: OnboardingCompletionSummary;
 }
-export type OnboardingStep = 'welcome' | 'resume-prompt' | 'platform-select' | 'adding-platform' | 'credentials-exist' | 'backing-up' | 'setup-method-select' | 'import-scanning' | 'import-distribution-mode' | 'import-pick-identity' | 'import-pick-profile' | 'import-validating-all-certs' | 'import-checking-apple-cert' | 'import-no-match-recovery' | 'import-portal-explanation' | 'import-provide-profile-path' | 'import-create-profile-only' | 'import-export-warning' | 'import-exporting' | 'api-key-instructions' | 'p8-method-select' | 'input-p8-path' | 'input-key-id' | 'input-issuer-id' | 'verifying-key' | 'verify-app' | 'creating-certificate' | 'cert-limit-prompt' | 'revoking-certificate' | 'creating-profile' | 'duplicate-profile-prompt' | 'deleting-duplicate-profiles' | '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' | 'ai-analysis-prompt' | 'ai-analysis-running' | 'ai-analysis-result' | 'ai-analysis-result-scroll' | 'build-complete' | 'no-platform' | 'error' | 'support-confirm' | 'support-log-view' | 'support-uploading';
+export type OnboardingStep = 'welcome' | 'resume-prompt' | 'platform-select' | 'adding-platform' | 'credentials-exist' | 'backing-up' | 'setup-method-select' | 'import-scanning' | 'import-distribution-mode' | 'import-pick-identity' | 'import-pick-profile' | 'import-validating-all-certs' | 'import-checking-apple-cert' | 'import-no-match-recovery' | 'import-portal-explanation' | 'import-provide-profile-path' | 'import-create-profile-only' | 'import-export-warning' | 'import-exporting' | 'p8-source-select' | 'asc-key-generating' | 'asc-key-created' | 'api-key-instructions' | 'p8-method-select' | 'input-p8-path' | 'input-key-id' | 'input-issuer-id' | 'verifying-key' | 'verify-app' | 'creating-certificate' | 'cert-limit-prompt' | 'revoking-certificate' | 'creating-profile' | 'duplicate-profile-prompt' | 'deleting-duplicate-profiles' | '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' | 'ai-analysis-prompt' | 'ai-analysis-running' | 'ai-analysis-result' | 'ai-analysis-result-scroll' | 'build-complete' | 'no-platform' | 'error' | 'support-confirm' | 'support-log-view' | 'support-uploading';
 export type OnboardingErrorCategory = 'apple_api_unauthorized' | 'apple_api_rate_limited' | 'cert_limit_reached' | 'profile_creation_failed' | 'p8_invalid' | 'keychain_no_identities' | 'keychain_export_failed' | 'profile_no_match' | 'profile_read_failed' | 'unknown';
 export interface ApiKeyData {
     keyId: string;
@@ -107,6 +107,22 @@ export interface OnboardingProgress extends TailProgress {
      * resume defaults to `create-new` for backward compatibility.
      */
     setupMethod?: 'create-new' | 'import-existing';
+    /**
+     * Records how the user chose to obtain the .p8 in the create-new flow's
+     * source fork (`p8-source-select`):
+     *   - `automated` — picked "No — create one for me": the guided macOS helper
+     *                   creates + captures the key. (Its in-window intro screen
+     *                   still lets the user switch to manual, which re-persists
+     *                   `manual` from the asc-key-generating effect.)
+     *   - `manual`    — the user has a .p8, or chose to create one by hand at App
+     *                   Store Connect, and enters it via `api-key-instructions`.
+     *
+     * Persisted so a quit-and-resume lands the user back where they chose to be:
+     * an `automated` user resumes on the helper (`asc-key-generating`), NOT the
+     * manual .p8 picker. Absent on legacy files and on the import flow.
+     * Only meaningful when `setupMethod === 'create-new'`.
+     */
+    p8CreateMethod?: 'automated' | 'manual';
     /**
      * Records the distribution mode picked at `import-distribution-mode`.
      *

package/dist/src/build/onboarding/ui/app.d.ts

@@ -24,12 +24,23 @@ interface AppProps {
     initialProgress: OnboardingProgress | null;
     /** Resolved iOS directory from capacitor.config (defaults to 'ios') */
     iosDir: string;
+    /**
+     * Whether guided ASC-key creation may be offered: macOS + the signed helper
+     * installed + its Developer-ID signature/team verified (computed once in
+     * command.ts via probeGuidedHelper). Gates every "create one for me" / "do
+     * you already have a .p8?" branch — when false (not installed, wrong
+     * signature, wrong team, or non-macOS) the user goes straight to the manual
+     * .p8 instructions, exactly as before the helper existed and as on Linux.
+     */
+    guidedHelperUsable: boolean;
     /** Optional Capgo API key passed via -a/--apikey flag; takes precedence over saved key */
     apikey?: string;
     supaHost?: string;
-    /** Reports the wizard outcome to the shell when it reaches build-complete, so
+    /**
+     * Reports the wizard outcome to the shell when it reaches build-complete, so
      *  the caller prints an accurate post-exit message + durable summary instead of
-     *  always claiming success. Never fires on cancel/missing-platform exits. */
+     *  always claiming success. Never fires on cancel/missing-platform exits.
+     */
     onResult?: (result: OnboardingResult) => void;
 }
 declare const OnboardingApp: FC<AppProps>;

package/dist/src/build/onboarding/ui/shell.d.ts

@@ -17,6 +17,12 @@ export interface OnboardingShellProps {
     iosBundleIdInitial: string;
     iosDir: string;
     androidDir: string;
+    /**
+     * Whether guided ASC-key creation may be offered (macOS + signed helper
+     * installed + signature/team verified — see the probe in command.ts).
+     * Threaded into the iOS OnboardingApp; the Android app ignores it.
+     */
+    guidedHelperUsable: boolean;
     apikey?: string;
     supaHost?: string;
     /** Pre-resolved platform (--platform flag or the single existing native dir); skips the picker. */

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

@@ -15,10 +15,26 @@ export interface SetupMethodSelectStepProps {
     onChange: (value: string) => void | Promise<void>;
 }
 export declare const SetupMethodSelectStep: FC<SetupMethodSelectStepProps>;
+export interface P8SourceSelectStepProps {
+    dense?: boolean;
+    /** True when the guided macOS helper is available (macOS + binary present). */
+    canAutomate: boolean;
+    onChange: (value: string) => void | Promise<void>;
+}
+export declare const P8SourceSelectStep: FC<P8SourceSelectStepProps>;
+export declare const AscKeyGeneratingStep: FC;
+export interface AscKeyCreatedStepProps {
+    keyId: string;
+    onContinue: () => void;
+}
+export declare const AscKeyCreatedStep: FC<AscKeyCreatedStepProps>;
 export interface ApiKeyInstructionsStepProps {
     canUseFilePicker: boolean;
+    /** macOS + helper available: also offer "✨ Create one for me (guided)" as an
+     *  alternative to providing the .p8 by hand. Defaults to false. */
+    canCreateGuided?: boolean;
     dense?: boolean;
-    onMethodChange: (value: string) => void;
+    onMethodChange: (value: string) => void | Promise<void>;
     onPathSubmit: (value: string) => void | Promise<void>;
 }
 export declare const ApiKeyInstructionsStep: FC<ApiKeyInstructionsStepProps>;

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

@@ -60,6 +60,10 @@ export interface ErrorStepProps {
     /** A captured build log exists for this run (e.g. a build was attempted), so
      *  the help menu may offer the "Ask AI for help" option. Defaults to false. */
     hasBuildLog?: boolean;
+    /** Offer "✨ Create a new key for me (guided)" as the first recovery option —
+     *  set when an App Store Connect key failed to validate on a host where the
+     *  guided macOS helper is available. Defaults to false. */
+    showGuidedKey?: boolean;
     onChange: (value: string) => void | Promise<void>;
 }
 export declare function formatErrorViewerLines(error: string, recoveryAdvice: BuildOnboardingRecoveryAdvice | null, supportBundlePath: string | null): string[];
@@ -79,7 +83,7 @@ export declare function formatErrorViewerLines(error: string, recoveryAdvice: Bu
  * 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, hasBuildLog: boolean): number;
+export declare function estimateErrorBodyRows(error: string, recoveryAdvice: BuildOnboardingRecoveryAdvice | null, supportBundlePath: string | null, cols: number, showRetry: boolean, hasBuildLog: boolean, showGuidedKey?: boolean): number;
 export declare const ErrorStep: FC<ErrorStepProps>;
 export interface BuildCompleteStepProps {
     buildUrl: string;

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

@@ -33,8 +33,8 @@ export declare const onboardingNextStepSchema: z.ZodObject<{
     keystoreKeyPassword: z.ZodOptional<z.ZodString>;
     keystoreNewAlias: z.ZodOptional<z.ZodString>;
     keystorePasswordMethod: z.ZodOptional<z.ZodEnum<{
-        random: "random";
         manual: "manual";
+        random: "random";
     }>>;
     keystoreCommonName: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;