comber 0.1.0

package/dist/config.js

@@ -0,0 +1,664 @@
+import { config as loadEnv } from "dotenv";
+import { loadNativeEgressProxyEvidenceFromProof } from "./native/proxy-proof.js";
+import { loadDesktopEgressProxyEvidenceFromProof } from "./desktop/proxy-proof.js";
+loadEnv();
+/**
+ * Model IDs are pinned here (authoritative values from the runtime environment,
+ * 2026-06). Change in ONE place if they move. Traversal is deterministic + heuristic
+ * (`orderForExhaustion`); the ONE model call is the post-crawl Opus judge that triages
+ * ambiguous findings. (A Haiku action-picker is a planned enhancement — not wired yet, so
+ * it is deliberately NOT listed here or claimed in the CLI banner.)
+ */
+export const MODELS = {
+    /** Breakage triage / "is this a genuine defect?" judge (non-adversarial quality call). */
+    judge: "claude-opus-4-8",
+    /** ADVERSARIAL "is this ACTION safe?" gate. Fable 5 — best judgment + dual-use safety
+     *  training; this is the one gate a malicious page actively tries to fool, so robustness
+     *  beats cost. PINNED here now; CONSUMED by a later increment that wires the LLM safety-judge
+     *  onto the action-floor's `escalate` verdict (`core/action-gate.ts`). It fires only off the
+     *  hot path, at low/medium effort, and must fail closed on a `refusal` (Comber is
+     *  security-adjacent, so the cyber classifier will occasionally decline → server-side fallback
+     *  to the judge model). See claude-brain PROJECTS/RADLAB-QA-AGENT/HOSTED_THREAT_MODEL.md §3a. */
+    safetyJudge: "claude-fable-5",
+};
+/**
+ * Destructive-action denylist. Any interactive element whose accessible name
+ * matches this is OBSERVED, never clicked — the non-negotiable guard against a
+ * synthetic run nuking data or charging a card. Tune per-app via config.
+ */
+export const DESTRUCTIVE_DENYLIST = /\b(delete|remove|destroy|cancel|unsubscribe|pay|payment|purchase|buy|checkout|charge|refund|transfer|withdraw|wire|send ?money|place ?order|confirm ?order|submit ?payment|archive|deactivate|close account|sign ?out|log ?out)\b/i;
+/** Destructive intent in a link/form target URL — gated even if the name looks benign. */
+export const DESTRUCTIVE_HREF_DENYLIST = /(\/logout|\/signout|\/delete|\/destroy|\/cancel|\/checkout|\/billing|\/pay|\/purchase|\/unsubscribe|\/deactivate)\b/i;
+/**
+ * Network-egress URL denylist — ANY request (XHR/form/nav) to a clearly-destructive or
+ * money endpoint is aborted at the wire regardless of element name. Always on (the real
+ * safety backstop, "an HTTP verb does not lie"). `--block-writes` additionally aborts ALL
+ * mutating methods (POST/PUT/PATCH/DELETE) — the paranoid "only GET/HEAD/OPTIONS" mode —
+ * but that's opt-in because many SPAs legitimately POST for reads (GraphQL) and blocking
+ * those makes the app look broken to the crawler.
+ */
+export const EGRESS_URL_DENYLIST = /(\/checkout|\/billing|\/subscribe|\/logout|\/signout|\/account\/delete|\/api\/.*\/(delete|cancel|charge|refund|transfer)|stripe\.com\/v1|api\.paypal\.com|js\.stripe\.com\/v1\/(tokens|charges|sources))/i;
+const VALUE_FLAGS = new Set([
+    "api-base",
+    "hosted",
+    "app",
+    "app-id",
+    "app-path",
+    "automation-backend",
+    "baseline",
+    "bundle-id",
+    "config",
+    "deeplink",
+    "device",
+    "device-class",
+    "device-model",
+    "egress-proxy-artifact",
+    "egress-proxy-command",
+    "egress-proxy-provider",
+    "egress-proxy-proof",
+    "evidence-accessibility-tree",
+    "evidence-automation-tree",
+    "evidence-crash-log",
+    "evidence-log",
+    "evidence-screenshot",
+    "evidence-video",
+    "graphql",
+    "har",
+    "api-timeout",
+    "app-version",
+    "android-version",
+    "build-fingerprint",
+    "link-concurrency",
+    "link-timeout",
+    "max-actions",
+    "max-external-links",
+    "max-ms",
+    "max-per-state",
+    "max-regotos",
+    "max-states",
+    "max-tokens",
+    "max-visits-per-route",
+    "near-dup",
+    "openapi",
+    "out",
+    "os-version",
+    "platform",
+    "provider",
+    "provider-run-id",
+    "pr-comment",
+    "profile",
+    "process-id",
+    "replay",
+    "replay-out",
+    "seed",
+    "storage",
+    "one-ui",
+    "process-name",
+    "window-title",
+    "launch-command",
+    "verification-command",
+]);
+/** Every boolean (no-value) flag Comber accepts. Kept next to VALUE_FLAGS so the two
+ *  together are the authoritative known-flag set the unknown-flag guard validates against. */
+const BOOLEAN_FLAGS = new Set([
+    "allow-private-target",
+    "allow-writes",
+    "block-writes",
+    "cross-origin",
+    "deterministic",
+    "dry-run",
+    "external-links",
+    "no-external-links",
+    "headed",
+    "llm",
+    "no-llm",
+    "no-screenshots",
+    "samsung",
+    "egress-proxy-verified",
+    "accessibility-permission-verified",
+    "strict-gate", // fail-closed action-floor for untrusted/hosted targets
+    "strict", // consumed in cli.ts, listed here so it is not flagged as unknown
+    "help",
+    "version",
+    "h",
+    "V",
+]);
+/**
+ * Reject an unknown/misspelled `--flag`. Without this a typo like `--max-state 5` (missing
+ * the trailing `s`) is silently ignored: the value becomes a positional, Comber crawls the
+ * literal "5", visits 0 states, and — worst of all — a `--strick` typo silently disables CI
+ * gating while the job stays green. A one-character typo must fail loudly, not fail open.
+ */
+function rejectUnknownFlags(argv) {
+    for (const arg of argv) {
+        if (!arg.startsWith("--") || arg === "--")
+            continue;
+        const name = arg.slice(2).split("=", 1)[0] ?? "";
+        if (name === "")
+            continue;
+        if (!VALUE_FLAGS.has(name) && !BOOLEAN_FLAGS.has(name)) {
+            throw new Error(`unknown flag --${name}. Run \`comber --help\` for the full flag list.`);
+        }
+    }
+}
+function positionalArgs(argv) {
+    const out = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith("--")) {
+            out.push(arg);
+            continue;
+        }
+        const flagName = arg.slice(2).split("=", 1)[0] ?? "";
+        if (!arg.includes("=") && VALUE_FLAGS.has(flagName))
+            i++;
+    }
+    return out;
+}
+function combineRegex(base, additions, name) {
+    if (!additions || additions.length === 0)
+        return base;
+    const sources = [base.source];
+    for (const raw of additions) {
+        try {
+            sources.push(new RegExp(raw, base.flags).source);
+        }
+        catch {
+            throw new Error(`${name} contains an invalid regex: ${raw}`);
+        }
+    }
+    return new RegExp(sources.join("|"), base.flags);
+}
+function originOf(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseDeviceClass(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === "phone" || value === "tablet" || value === "foldable" || value === "emulator" || value === "simulator" || value === "unknown") {
+        return value;
+    }
+    throw new Error(`--device-class must be phone|tablet|foldable|emulator|simulator|unknown (got ${value})`);
+}
+function artifactsForKind(kind, paths) {
+    const out = [];
+    for (const path of paths ?? []) {
+        out.push({ kind, path });
+    }
+    return out;
+}
+function desktopArtifactsForKind(kind, paths) {
+    const out = [];
+    for (const path of paths ?? []) {
+        out.push({ kind, path });
+    }
+    return out;
+}
+function isDesktopAutomationBackend(value) {
+    return value === "accessibility" || value === "xctest" || value === "uia" || value === "unknown";
+}
+/**
+ * Resolve the multi-role auth set (role → token) for the IDOR / broken-auth harness. Merges the
+ * config-file map with the $COMBER_API_AUTH_PROFILES env JSON (env WINS — tokens belong in env,
+ * never a committed config and never a CLI flag). Empty tokens are dropped. Returns undefined
+ * when no profiles are configured (the harness is opt-in).
+ */
+function resolveAuthProfiles(configMap) {
+    const merged = { ...(configMap ?? {}) };
+    const env = process.env.COMBER_API_AUTH_PROFILES;
+    if (env) {
+        let parsed;
+        try {
+            parsed = JSON.parse(env);
+        }
+        catch {
+            throw new Error("COMBER_API_AUTH_PROFILES must be a JSON object of { role: token }");
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error("COMBER_API_AUTH_PROFILES must be a JSON object of { role: token }");
+        }
+        for (const [role, token] of Object.entries(parsed)) {
+            if (typeof token === "string")
+                merged[role] = token;
+        }
+    }
+    const profiles = Object.entries(merged)
+        .filter(([, token]) => typeof token === "string" && token.length > 0)
+        .map(([role, token]) => ({ role, token }));
+    return profiles.length ? profiles : undefined;
+}
+/** Reject `..` traversal in a config-controlled WRITE path (out dir / PR comment).
+ *  A committed comber.config.json must not be able to direct a write outside the
+ *  tree via `../../`. Absolute paths are allowed (explicit operator intent). */
+function rejectTraversal(p, name) {
+    if (p === undefined)
+        return undefined;
+    if (p.replace(/\\/g, "/").split("/").includes("..")) {
+        throw new Error(`${name} must not contain '..' path traversal: ${p}`);
+    }
+    return p;
+}
+export function loadConfig(argv, profile = {}) {
+    rejectUnknownFlags(argv);
+    const positional = positionalArgs(argv);
+    const flag = (name) => {
+        const hit = argv.find((a) => a.startsWith(`--${name}=`));
+        if (hit)
+            return hit.slice(name.length + 3);
+        const idx = argv.indexOf(`--${name}`);
+        if (idx >= 0) {
+            const next = argv[idx + 1];
+            if (next && !next.startsWith("--"))
+                return next;
+        }
+        return undefined;
+    };
+    const has = (name) => argv.includes(`--${name}`);
+    // Validate the RESOLVED value (CLI flag OR the profile-supplied fallback), not
+    // just the CLI raw — otherwise a profile typo like `"maxStates": -3` slips past
+    // and silently yields a 0-state "clean" run. parseProfile only checks finiteness.
+    const intFlag = (name, fallback, min = 1) => {
+        const raw = flag(name);
+        const value = raw === undefined ? fallback : Number(raw);
+        if (!Number.isInteger(value) || value < min) {
+            throw new Error(`--${name} (or its profile value) must be an integer >= ${min} (got ${value})`);
+        }
+        return value;
+    };
+    const numberFlag = (name, fallback, min, max) => {
+        const raw = flag(name);
+        const value = raw === undefined ? fallback : Number(raw);
+        if (!Number.isFinite(value) || value < min || value > max) {
+            throw new Error(`--${name} (or its profile value) must be a number between ${min} and ${max} (got ${value})`);
+        }
+        return value;
+    };
+    const optionalIntFlag = (name, fallback, min = 1) => {
+        const raw = flag(name);
+        const rawValue = raw === undefined ? fallback : raw;
+        if (rawValue === undefined)
+            return undefined;
+        const value = typeof rawValue === "number" ? rawValue : Number(rawValue);
+        if (!Number.isInteger(value) || value < min) {
+            throw new Error(`--${name} (or its profile value) must be an integer >= ${min} (got ${rawValue})`);
+        }
+        return value;
+    };
+    const strFlag = (name, fallback) => flag(name) ?? fallback;
+    /** Collect EVERY occurrence of a repeatable flag (`--deeplink a --deeplink b`). */
+    const multiFlag = (name) => {
+        const out = [];
+        for (let i = 0; i < argv.length; i++) {
+            const a = argv[i];
+            if (a.startsWith(`--${name}=`))
+                out.push(a.slice(name.length + 3));
+            else if (a === `--${name}`) {
+                const next = argv[i + 1];
+                if (next && !next.startsWith("--"))
+                    out.push(next);
+            }
+        }
+        return out;
+    };
+    const repeatableFlag = (name, fallback) => {
+        const values = multiFlag(name);
+        return values.length ? values : fallback ?? [];
+    };
+    // -- driver selection: the composition root picks WebDriver (positional URL, the existing
+    //    behavior) vs ApiDriver (`api` / `--openapi`) vs NativeDriver (`native` / `--app`)
+    //    vs DesktopDriver (`desktop` / `--app-path` or `--process-name`).
+    const desktopMode = positional[0] === "desktop" ||
+        flag("app-path") !== undefined ||
+        flag("process-name") !== undefined ||
+        flag("process-id") !== undefined ||
+        profile.target === "desktop" ||
+        profile.appPath !== undefined ||
+        profile.processName !== undefined ||
+        profile.processId !== undefined;
+    const nativeMode = !desktopMode &&
+        (positional[0] === "native" || flag("app") !== undefined || profile.target === "native" || profile.app !== undefined);
+    const graphqlSel = strFlag("graphql", profile.graphql);
+    const harSel = strFlag("har", profile.har);
+    const apiMode = !desktopMode &&
+        !nativeMode &&
+        (positional[0] === "api" ||
+            flag("openapi") !== undefined ||
+            graphqlSel !== undefined ||
+            harSel !== undefined ||
+            profile.target === "api" ||
+            profile.openapi !== undefined);
+    const target = desktopMode ? "desktop" : nativeMode ? "native" : apiMode ? "api" : "web";
+    let startUrl;
+    let apiSourceKind;
+    let openapiSource;
+    let graphqlUrl;
+    let harPath;
+    let apiBase;
+    let apiSeedDataPath;
+    let apiRoleSeedPath;
+    let apiOwnerScoped;
+    let apiToken;
+    let apiAuthProfiles;
+    let desktopPlatform;
+    let desktopAppId;
+    let desktopAppPath;
+    let desktopProcessName;
+    let desktopProcessId;
+    let desktopWindowTitle;
+    let desktopAppProfile;
+    let nativeApp;
+    let nativePlatform;
+    let nativeDevice;
+    let nativeDeeplinks;
+    let nativeDeviceProfile;
+    if (desktopMode) {
+        const platformRaw = strFlag("platform", profile.platform);
+        const resolvedPlatform = platformRaw ?? "windows";
+        if (resolvedPlatform !== "windows" && resolvedPlatform !== "macos") {
+            throw new Error(`desktop platform must be windows or macos (got ${resolvedPlatform})`);
+        }
+        desktopPlatform = resolvedPlatform;
+        desktopAppId = strFlag("bundle-id", strFlag("app-id", profile.app));
+        desktopAppPath = rejectTraversal(strFlag("app-path", profile.appPath), "--app-path / appPath");
+        desktopProcessName = strFlag("process-name", profile.processName);
+        desktopProcessId = optionalIntFlag("process-id", profile.processId);
+        desktopWindowTitle = strFlag("window-title", profile.windowTitle);
+        if (desktopPlatform !== "windows" && desktopProcessId !== undefined) {
+            throw new Error("desktop --process-id is only supported for the Windows UIA backend");
+        }
+        if (!desktopAppId && !desktopAppPath && !desktopProcessName && desktopProcessId === undefined) {
+            throw new Error("usage: comber desktop --platform windows|macos (--app-path PATH | --process-name NAME | --app-id ID | --process-id PID)");
+        }
+        const backendRaw = strFlag("automation-backend", profile.automationBackend) ?? (desktopPlatform === "windows" ? "uia" : "accessibility");
+        if (!isDesktopAutomationBackend(backendRaw)) {
+            throw new Error(`desktop automation backend must be accessibility, xctest, uia, or unknown (got ${backendRaw})`);
+        }
+        const backend = backendRaw;
+        if (desktopPlatform === "windows" && backend !== "uia") {
+            throw new Error(`desktop Windows automation backend must be uia (got ${backendRaw})`);
+        }
+        if (desktopPlatform === "macos" && backend !== "accessibility" && backend !== "xctest") {
+            throw new Error(`desktop macOS automation backend must be accessibility or xctest (got ${backendRaw})`);
+        }
+        const provider = strFlag("provider", profile.provider);
+        const providerRunId = strFlag("provider-run-id", profile.providerRunId);
+        const launchCommand = strFlag("launch-command", profile.launchCommand) ??
+            (desktopPlatform === "windows"
+                ? desktopAppPath
+                    ? `Start-Process ${desktopAppPath}`
+                    : desktopProcessId !== undefined
+                        ? `Attach-Process ${desktopProcessId}`
+                        : `Attach-Process ${desktopProcessName ?? desktopAppId}`
+                : desktopAppPath
+                    ? `open -n ${desktopAppPath}`
+                    : desktopAppId
+                        ? `open -nb ${desktopAppId}`
+                        : `open -na ${desktopProcessName}`);
+        const verificationCommand = strFlag("verification-command", profile.verificationCommand);
+        const evidenceArtifacts = [
+            ...(profile.desktopEvidenceArtifacts ?? []),
+            ...desktopArtifactsForKind("screenshot", repeatableFlag("evidence-screenshot", profile.evidenceScreenshots)),
+            ...desktopArtifactsForKind("video", repeatableFlag("evidence-video", profile.evidenceVideos)),
+            ...desktopArtifactsForKind("log", repeatableFlag("evidence-log", profile.evidenceLogs)),
+            ...desktopArtifactsForKind("crash-log", repeatableFlag("evidence-crash-log", profile.evidenceCrashLogs)),
+            ...desktopArtifactsForKind("automation-tree", repeatableFlag("evidence-automation-tree", profile.evidenceAutomationTrees)),
+            ...desktopArtifactsForKind("accessibility-tree", repeatableFlag("evidence-accessibility-tree", profile.evidenceAccessibilityTrees)),
+        ];
+        const egressProxyVerified = has("egress-proxy-verified") || profile.egressProxyVerified === true || profile.egressProxy?.verified === true;
+        const egressProxyProofPath = rejectTraversal(strFlag("egress-proxy-proof", profile.egressProxyProof), "--egress-proxy-proof / egressProxyProof");
+        const egressProxyProof = egressProxyProofPath !== undefined ? loadDesktopEgressProxyEvidenceFromProof(egressProxyProofPath) : undefined;
+        const desktopEgressProxyVerified = egressProxyVerified || egressProxyProof?.verified === true;
+        const egressProxyProvider = strFlag("egress-proxy-provider", profile.egressProxyProvider ?? profile.egressProxy?.provider ?? egressProxyProof?.provider);
+        const egressProxyCommand = strFlag("egress-proxy-command", profile.egressProxyCommand ?? profile.egressProxy?.command ?? egressProxyProof?.command);
+        const egressProxyArtifact = strFlag("egress-proxy-artifact", profile.egressProxyArtifact ?? profile.egressProxy?.artifactPath ?? egressProxyProof?.artifactPath);
+        const includeEgressProxy = desktopEgressProxyVerified ||
+            egressProxyProvider !== undefined ||
+            egressProxyCommand !== undefined ||
+            egressProxyArtifact !== undefined ||
+            egressProxyProof !== undefined;
+        const accessibilityPermissionVerified = has("accessibility-permission-verified") || profile.accessibilityPermissionVerified === true;
+        desktopAppProfile = {
+            platform: desktopPlatform,
+            ...(desktopAppId !== undefined ? { appId: desktopAppId } : {}),
+            ...(desktopAppPath !== undefined ? { appPath: desktopAppPath } : {}),
+            ...(desktopProcessName !== undefined ? { processName: desktopProcessName } : {}),
+            ...(desktopProcessId !== undefined ? { processId: desktopProcessId } : {}),
+            ...(desktopWindowTitle !== undefined ? { windowTitle: desktopWindowTitle } : {}),
+            automationBackend: backend,
+            ...(provider !== undefined ? { provider } : {}),
+            ...(providerRunId !== undefined ? { providerRunId } : {}),
+            launchCommand,
+            ...(verificationCommand !== undefined ? { verificationCommand } : {}),
+            ...(evidenceArtifacts.length > 0 ? { evidenceArtifacts } : {}),
+            ...(desktopPlatform === "windows"
+                ? { uiAutomationTreeAvailable: evidenceArtifacts.some((artifact) => artifact.kind === "automation-tree") }
+                : { accessibilityPermissionVerified }),
+            ...(includeEgressProxy
+                ? {
+                    egressProxy: {
+                        verified: desktopEgressProxyVerified,
+                        ...(egressProxyProvider !== undefined ? { provider: egressProxyProvider } : {}),
+                        ...(egressProxyCommand !== undefined ? { command: egressProxyCommand } : {}),
+                        ...(egressProxyArtifact !== undefined ? { artifactPath: egressProxyArtifact } : {}),
+                    },
+                }
+                : {}),
+        };
+        startUrl = desktopAppPath ?? (desktopProcessId !== undefined ? `pid:${desktopProcessId}` : desktopProcessName ?? desktopAppId);
+    }
+    else if (nativeMode) {
+        nativeApp = strFlag("app", profile.app);
+        if (!nativeApp) {
+            throw new Error("usage: comber native --app <appId|apk|path> [--platform android|ios] [--device ID] [--deeplink URI]…");
+        }
+        const platformRaw = strFlag("platform", profile.platform) ?? "android";
+        if (platformRaw !== "android" && platformRaw !== "ios") {
+            throw new Error(`--platform must be "android" or "ios" (got ${platformRaw})`);
+        }
+        nativePlatform = platformRaw;
+        nativeDevice = strFlag("device", profile.device);
+        const cliDeeplinks = multiFlag("deeplink");
+        nativeDeeplinks = cliDeeplinks.length ? cliDeeplinks : profile.deeplinks ?? [];
+        const samsungRequested = has("samsung") || profile.samsung === true;
+        const deviceClass = parseDeviceClass(strFlag("device-class", profile.deviceClass));
+        const deviceModel = strFlag("device-model", profile.deviceModel);
+        const osVersion = strFlag("os-version", profile.osVersion);
+        const androidVersion = strFlag("android-version", profile.androidVersion);
+        const appVersion = strFlag("app-version", profile.appVersion);
+        const provider = strFlag("provider", profile.provider);
+        const providerRunId = strFlag("provider-run-id", profile.providerRunId);
+        const verificationCommand = strFlag("verification-command", profile.verificationCommand);
+        const oneUiVersion = strFlag("one-ui", profile.oneUiVersion);
+        const buildFingerprint = strFlag("build-fingerprint", profile.buildFingerprint);
+        const includeSamsungProfile = samsungRequested || oneUiVersion !== undefined || buildFingerprint !== undefined;
+        const evidenceArtifacts = [
+            ...(profile.evidenceArtifacts ?? []),
+            ...artifactsForKind("screenshot", repeatableFlag("evidence-screenshot", profile.evidenceScreenshots)),
+            ...artifactsForKind("video", repeatableFlag("evidence-video", profile.evidenceVideos)),
+            ...artifactsForKind("log", repeatableFlag("evidence-log", profile.evidenceLogs)),
+            ...artifactsForKind("crash-log", repeatableFlag("evidence-crash-log", profile.evidenceCrashLogs)),
+        ];
+        const egressProxyProofPath = rejectTraversal(strFlag("egress-proxy-proof", profile.egressProxyProof), "--egress-proxy-proof / egressProxyProof");
+        const egressProxyProof = egressProxyProofPath !== undefined ? loadNativeEgressProxyEvidenceFromProof(egressProxyProofPath) : undefined;
+        const egressProxyVerified = has("egress-proxy-verified") ||
+            profile.egressProxyVerified === true ||
+            profile.egressProxy?.verified === true ||
+            egressProxyProof?.verified === true;
+        const egressProxyProvider = strFlag("egress-proxy-provider", profile.egressProxyProvider ?? profile.egressProxy?.provider ?? egressProxyProof?.provider);
+        const egressProxyCommand = strFlag("egress-proxy-command", profile.egressProxyCommand ?? profile.egressProxy?.command ?? egressProxyProof?.command);
+        const egressProxyArtifact = strFlag("egress-proxy-artifact", profile.egressProxyArtifact ?? profile.egressProxy?.artifactPath ?? egressProxyProof?.artifactPath);
+        const includeEgressProxy = egressProxyVerified ||
+            egressProxyProvider !== undefined ||
+            egressProxyCommand !== undefined ||
+            egressProxyArtifact !== undefined ||
+            egressProxyProof !== undefined;
+        nativeDeviceProfile = {
+            platform: nativePlatform,
+            appId: nativeApp,
+            ...(nativeDevice !== undefined ? { deviceId: nativeDevice } : {}),
+            ...(deviceClass !== undefined ? { deviceClass } : {}),
+            ...(deviceModel !== undefined ? { model: deviceModel } : {}),
+            ...(osVersion !== undefined ? { osVersion } : {}),
+            ...(androidVersion !== undefined ? { androidVersion } : {}),
+            ...(appVersion !== undefined ? { appVersion } : {}),
+            ...(provider !== undefined ? { provider } : {}),
+            ...(providerRunId !== undefined ? { providerRunId } : {}),
+            ...(verificationCommand !== undefined ? { verificationCommand } : {}),
+            ...(evidenceArtifacts.length > 0 ? { evidenceArtifacts } : {}),
+            ...(includeEgressProxy
+                ? {
+                    egressProxy: {
+                        verified: egressProxyVerified,
+                        ...(egressProxyProvider !== undefined ? { provider: egressProxyProvider } : {}),
+                        ...(egressProxyCommand !== undefined ? { command: egressProxyCommand } : {}),
+                        ...(egressProxyArtifact !== undefined ? { artifactPath: egressProxyArtifact } : {}),
+                    },
+                }
+                : {}),
+            ...(includeSamsungProfile
+                ? {
+                    samsung: {
+                        requested: samsungRequested,
+                        ...(deviceModel !== undefined ? { model: deviceModel } : {}),
+                        ...(oneUiVersion !== undefined ? { oneUiVersion } : {}),
+                        ...(buildFingerprint !== undefined ? { buildFingerprint } : {}),
+                    },
+                }
+                : {}),
+        };
+        startUrl = nativeApp; // reuse startUrl for redaction/sink/result identity (the app under test)
+    }
+    else if (apiMode) {
+        // Pick the spec source: --graphql <url> | --har <path> | (default) --openapi <path|url>.
+        if (graphqlSel !== undefined) {
+            apiSourceKind = "graphql";
+            graphqlUrl = graphqlSel;
+            startUrl = graphqlUrl; // the endpoint IS the identity (no separate base)
+        }
+        else if (harSel !== undefined) {
+            apiSourceKind = "har";
+            harPath = harSel;
+            // HAR entries carry absolute URLs; --api-base is optional and only an identity hint.
+            startUrl = strFlag("api-base", profile.apiBase) ?? harPath;
+        }
+        else {
+            openapiSource = strFlag("openapi", profile.openapi);
+            apiBase = strFlag("api-base", profile.apiBase);
+            if (!openapiSource) {
+                throw new Error("usage: comber api --openapi <path|url> --api-base <url> [--allow-writes] [--seed PATH]\n" +
+                    "   or: comber api --graphql <url>   |   comber api --har <path>");
+            }
+            if (!apiBase) {
+                throw new Error("api mode requires --api-base <url> (no default base — point Comber at a base you own)");
+            }
+            apiSourceKind = /\.ya?ml$/i.test(openapiSource) ? "openapi-yaml" : "openapi-json";
+            startUrl = apiBase; // reuse startUrl for origin/redaction/sink/result identity
+        }
+        apiSeedDataPath = strFlag("seed", profile.seed);
+        apiRoleSeedPath = profile.roleSeed;
+        apiOwnerScoped = profile.ownerScoped;
+        apiToken = process.env.COMBER_API_TOKEN || undefined;
+        apiAuthProfiles = resolveAuthProfiles(profile.apiAuthProfiles);
+    }
+    else {
+        const url = positional[0] ?? profile.startUrl;
+        if (!url) {
+            throw new Error("usage: comber <url> [--profile NAME] [--config PATH] [--max-states N] [--max-actions N] [--headed] [--llm]\n" +
+                "   or: comber api --openapi <path|url> --api-base <url> [--allow-writes] [--seed PATH]");
+        }
+        startUrl = url;
+    }
+    // Hosted metered inference: --hosted <broker-url> (or $COMBER_HOSTED_URL) points the LLM at our
+    // broker instead of api.anthropic.com. In hosted mode the credential is the Comber LICENSE (the
+    // broker swaps in the funded key); BYO mode uses the Anthropic key directly. Either is sent by the
+    // SDK as x-api-key, so a single `anthropicKey` slot carries whichever applies.
+    const hostedInferenceUrl = strFlag("hosted", process.env.COMBER_HOSTED_URL) || undefined;
+    const anthropicKey = hostedInferenceUrl
+        ? process.env.COMBER_LICENSE || process.env.ANTHROPIC_API_KEY || undefined
+        : process.env.ANTHROPIC_API_KEY || undefined;
+    const cliLlm = has("llm");
+    const noLlm = has("no-llm");
+    if (cliLlm && noLlm) {
+        throw new Error("--llm and --no-llm cannot be used together");
+    }
+    const llmRequested = !noLlm && (cliLlm || profile.llm === true);
+    if (llmRequested && !anthropicKey) {
+        throw new Error(hostedInferenceUrl
+            ? "--llm with --hosted requires COMBER_LICENSE (or ANTHROPIC_API_KEY)"
+            : "--llm requires ANTHROPIC_API_KEY");
+    }
+    const startOrigin = originOf(startUrl);
+    const allowedOrigins = new Set();
+    if (startOrigin)
+        allowedOrigins.add(startOrigin);
+    for (const origin of profile.allowedOrigins ?? []) {
+        allowedOrigins.add(origin);
+    }
+    return {
+        target,
+        startUrl,
+        apiSourceKind,
+        openapiSource,
+        graphqlUrl,
+        harPath,
+        apiBase,
+        apiSeedDataPath,
+        apiRoleSeedPath,
+        apiOwnerScoped,
+        apiToken,
+        apiAuthProfiles,
+        apiAllowPrivateTarget: has("allow-private-target") || profile.allowPrivateTarget === true,
+        apiTimeoutMs: intFlag("api-timeout", profile.apiTimeoutMs ?? 15_000),
+        nativeApp,
+        nativePlatform,
+        nativeDevice,
+        nativeDeeplinks,
+        nativeDeviceProfile,
+        desktopPlatform,
+        desktopAppId,
+        desktopAppPath,
+        desktopProcessName,
+        desktopProcessId,
+        desktopWindowTitle,
+        desktopAppProfile,
+        profileName: profile.name,
+        allowedOrigins: [...allowedOrigins],
+        maxStates: intFlag("max-states", profile.maxStates ?? 40),
+        maxActions: intFlag("max-actions", profile.maxActions ?? 400),
+        maxWallClockMs: intFlag("max-ms", profile.maxWallClockMs ?? 5 * 60_000),
+        maxTokenBudget: intFlag("max-tokens", profile.maxTokenBudget ?? 200_000),
+        maxActionsPerState: intFlag("max-per-state", profile.maxActionsPerState ?? 40),
+        maxRegotosPerState: intFlag("max-regotos", profile.maxRegotosPerState ?? 8, 0),
+        maxVisitsPerRoute: intFlag("max-visits-per-route", profile.maxVisitsPerRoute ?? 3),
+        nearDupThreshold: numberFlag("near-dup", profile.nearDupThreshold ?? 0.92, 0, 1),
+        checkExternalLinks: (has("external-links") || profile.externalLinks === true) && !has("no-external-links"),
+        maxExternalLinks: intFlag("max-external-links", profile.maxExternalLinks ?? 300, 0),
+        linkTimeoutMs: intFlag("link-timeout", profile.linkTimeoutMs ?? 10_000),
+        linkConcurrency: intFlag("link-concurrency", profile.linkConcurrency ?? 8),
+        sameOriginOnly: !(has("cross-origin") || profile.crossOrigin === true),
+        screenshots: !has("no-screenshots") && profile.screenshots !== false,
+        useLLM: llmRequested && Boolean(anthropicKey),
+        deterministic: has("deterministic") || profile.deterministic === true,
+        dryRun: has("dry-run") || profile.dryRun === true,
+        blockWrites: has("block-writes") || (!has("allow-writes") && profile.allowWrites !== true),
+        actionGateMode: has("strict-gate") || profile.strictGate === true ? "strict" : "advisory",
+        egressUrlDenylist: EGRESS_URL_DENYLIST,
+        anthropicKey,
+        hostedInferenceUrl,
+        storageStatePath: process.env.COMBER_STORAGE_STATE || strFlag("storage", profile.storageStatePath),
+        baselinePath: strFlag("baseline", profile.baselinePath),
+        prCommentPath: rejectTraversal(strFlag("pr-comment", profile.prCommentPath), "--pr-comment / prComment"),
+        headless: has("headed") ? false : profile.headless ?? true,
+        outDir: rejectTraversal(strFlag("out", profile.outDir), "--out / outDir") ?? "runs",
+        denylist: combineRegex(DESTRUCTIVE_DENYLIST, profile.denylist, "denylist"),
+        destructiveHrefDenylist: combineRegex(DESTRUCTIVE_HREF_DENYLIST, profile.destructiveHrefDenylist, "destructiveHrefDenylist"),
+        replayPlanPath: strFlag("replay", profile.replay),
+        replayOutPath: rejectTraversal(strFlag("replay-out", profile.replayOut), "--replay-out / replayOut"),
+        connectors: profile.connectors,
+    };
+}