comber 0.1.0

package/dist/api/request.js

@@ -0,0 +1,141 @@
+import { operationLabel } from "./openapi.js";
+const MAX_DEPTH = 6;
+function firstExampleValue(examples) {
+    if (!examples)
+        return undefined;
+    for (const ex of Object.values(examples))
+        if (ex && "value" in ex)
+            return ex.value;
+    return undefined;
+}
+function sampleString(schema) {
+    switch (schema.format) {
+        case "uuid":
+            return "00000000-0000-0000-0000-000000000000";
+        case "date":
+            return "2020-01-01";
+        case "date-time":
+            return "2020-01-01T00:00:00Z";
+        case "email":
+            return "sample@example.com";
+        case "uri":
+        case "url":
+            return "https://example.com";
+        case "hostname":
+            return "example.com";
+        case "ipv4":
+            return "127.0.0.1";
+        case "byte":
+            return "c2FtcGxl"; // base64("sample")
+        default:
+            return "string";
+    }
+}
+/** A deterministic, minimal value satisfying `schema`. example/default/enum win first. */
+export function sampleValue(schema, resolver, depth = 0) {
+    const s = resolver.deref(schema);
+    if (!s || typeof s !== "object")
+        return "string";
+    if (s.example !== undefined)
+        return s.example;
+    if (s.default !== undefined)
+        return s.default;
+    if (Array.isArray(s.enum) && s.enum.length > 0)
+        return s.enum[0];
+    const type = Array.isArray(s.type) ? s.type[0] : s.type;
+    if (type === "object" || (!type && s.properties)) {
+        if (depth >= MAX_DEPTH)
+            return {};
+        const out = {};
+        for (const [key, prop] of Object.entries(s.properties ?? {}))
+            out[key] = sampleValue(prop, resolver, depth + 1);
+        return out;
+    }
+    switch (type) {
+        case "integer":
+        case "number":
+            return 1;
+        case "boolean":
+            return true;
+        case "array":
+            return depth >= MAX_DEPTH ? [] : [sampleValue(s.items, resolver, depth + 1)];
+        case "string":
+            return sampleString(s);
+        default:
+            return "string";
+    }
+}
+function paramValue(p, resolver) {
+    if (p.example !== undefined)
+        return p.example;
+    const ex = firstExampleValue(p.examples);
+    if (ex !== undefined)
+        return ex;
+    return sampleValue(p.schema, resolver);
+}
+function scalarString(v) {
+    return v !== null && typeof v === "object" ? JSON.stringify(v) : String(v);
+}
+function pickJsonMedia(content) {
+    return (content["application/json"] ??
+        Object.entries(content).find(([mt]) => /\bjson\b/i.test(mt))?.[1] ??
+        Object.values(content)[0]);
+}
+function joinUrl(base, path) {
+    return `${base.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+}
+/** Build the concrete request for an operation (seed → spec example → schema sample). */
+export function buildRequest(base, op, resolver, seed) {
+    const seedEntry = seed?.[operationLabel(op)] ?? {};
+    let path = op.path;
+    for (const p of op.parameters) {
+        if (p.in !== "path")
+            continue;
+        const v = seedEntry.path?.[p.name] ?? paramValue(p, resolver);
+        path = path.replace(`{${p.name}}`, encodeURIComponent(scalarString(v)));
+    }
+    const qs = new URLSearchParams();
+    for (const p of op.parameters) {
+        if (p.in !== "query")
+            continue;
+        const seeded = seedEntry.query?.[p.name];
+        const schema = resolver.deref(p.schema);
+        const hasDefault = schema?.default !== undefined || p.example !== undefined;
+        if (seeded === undefined && !p.required && !hasDefault)
+            continue; // keep the request minimal
+        qs.set(p.name, scalarString(seeded ?? paramValue(p, resolver)));
+    }
+    const headers = {};
+    for (const p of op.parameters) {
+        if (p.in !== "header")
+            continue;
+        const seeded = seedEntry.headers?.[p.name];
+        if (seeded !== undefined)
+            headers[p.name] = String(seeded);
+        else if (p.required)
+            headers[p.name] = scalarString(paramValue(p, resolver));
+    }
+    let body;
+    let bodyContentType;
+    if (op.requestBody) {
+        const media = pickJsonMedia(op.requestBody.content);
+        if (media) {
+            const value = seedEntry.body !== undefined
+                ? seedEntry.body
+                : media.example !== undefined
+                    ? media.example
+                    : (firstExampleValue(media.examples) ?? sampleValue(media.schema, resolver));
+            body = JSON.stringify(value);
+            bodyContentType = "application/json";
+        }
+    }
+    const query = qs.toString();
+    return {
+        method: op.method,
+        url: joinUrl(base, path) + (query ? `?${query}` : ""),
+        pathTemplate: op.path,
+        headers,
+        body,
+        bodyContentType,
+    };
+}

package/dist/api/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../../src/api/request.ts"],"names":[],"mappings":"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"}

package/dist/api/schema.js

@@ -0,0 +1,126 @@
+// Full JSON-Schema response-body validation (ajv) — the "credible" upgrade to the API
+// driver's light required-property check. Given an OpenAPI response schema (which may carry
+// `$ref`s into `components`), we resolve the refs into a self-contained schema, compile it
+// once with ajv (+ ajv-formats), and validate the actual response body against it. Failures
+// become `response-schema-violation` carrying the ajv error PATHS only (never body values),
+// truncated, so the finding is redaction-safe.
+//
+// Leaf module of the api package: imports the new `ajv`/`ajv-formats` libs + the sibling
+// openapi types ONLY (never `core`, never `web`). The dependency arrow stays api → libs.
+import { Ajv } from "ajv";
+import * as ajvFormats from "ajv-formats";
+// ajv-formats ships as CJS with a default export; under NodeNext the resolved value (default,
+// or the module itself depending on interop) is the callable plugin. Pin it once, defensively.
+const addFormats = (ajvFormats.default ?? ajvFormats);
+const MAX_VIOLATIONS = 8;
+const MAX_PATH_LEN = 80;
+const MAX_MSG_LEN = 120;
+const MAX_RESOLVE_DEPTH = 64;
+/**
+ * Deep-resolve every `$ref` in a schema into a self-contained JSON Schema ajv can compile
+ * without knowing OpenAPI pointer semantics. Cyclic schemas (a `Node` whose children are
+ * `Node`s) are broken by replacing a ref already open on the current path with `{}` (accept
+ * anything) — so validation terminates and never over-rejects a legitimately recursive body.
+ * OpenAPI 3.0 `nullable: true` is translated to a JSON-Schema `"null"` type union.
+ */
+export function resolveSchema(schema, resolver) {
+    const walk = (node, active, depth) => {
+        if (depth > MAX_RESOLVE_DEPTH)
+            return {};
+        if (Array.isArray(node))
+            return node.map((n) => walk(n, active, depth + 1));
+        if (!node || typeof node !== "object")
+            return node;
+        const ref = node.$ref;
+        if (typeof ref === "string") {
+            if (active.has(ref))
+                return {}; // cycle → permissive, terminates
+            const target = resolver.deref(node);
+            const next = new Set(active);
+            next.add(ref);
+            return walk(target, next, depth + 1);
+        }
+        const out = {};
+        for (const [k, v] of Object.entries(node)) {
+            out[k] = walk(v, active, depth + 1);
+        }
+        // OpenAPI 3.0 nullable → JSON-Schema null union (3.1 already uses `type: [...]`).
+        if (out.nullable === true && typeof out.type === "string") {
+            out.type = [out.type, "null"];
+        }
+        delete out.nullable;
+        return out;
+    };
+    return walk(schema, new Set(), 0);
+}
+const truncate = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+/** One ajv instance per validator set: tolerant of OpenAPI-isms (unknown keywords/formats are
+ *  ignored, not fatal) so a real-world spec never crashes the checker. */
+function makeAjv() {
+    // `logger: false` keeps ajv silent — a checker that prints unknown-keyword warnings to the
+    // console for every real-world spec would be noisy in CI. `strict: false` tolerates OpenAPI-isms.
+    const ajv = new Ajv({ allErrors: true, strict: false, validateFormats: true, allowUnionTypes: true, logger: false });
+    addFormats(ajv);
+    return ajv;
+}
+/**
+ * Compiles + caches response schemas and validates bodies against them. One instance is held
+ * per driver (per spec) so the ajv compile cost is paid once per distinct schema, keyed by the
+ * ORIGINAL schema object identity (the resolver/doc are stable for a run).
+ */
+export class ResponseValidator {
+    resolver;
+    ajv = makeAjv();
+    cache = new WeakMap();
+    constructor(resolver) {
+        this.resolver = resolver;
+    }
+    /** Compile (once) the self-contained form of `schema`; `null` if it cannot compile. */
+    compile(schema) {
+        if (typeof schema !== "object" || schema === null)
+            return null;
+        const cached = this.cache.get(schema);
+        if (cached !== undefined)
+            return cached;
+        let fn = null;
+        try {
+            fn = this.ajv.compile(resolveSchema(schema, this.resolver));
+        }
+        catch {
+            fn = null; // malformed schema → caller falls back to the light check
+        }
+        this.cache.set(schema, fn);
+        return fn;
+    }
+    /**
+     * Validate a JSON response body against `schema`. Returns `validated:false` (so the caller
+     * falls back) when the schema won't compile OR the body is not JSON — neither is a schema
+     * violation by itself (a non-JSON body is a content-type concern, handled elsewhere).
+     */
+    validate(schema, bodyText) {
+        const fn = this.compile(schema);
+        if (!fn)
+            return { validated: false, ok: false, violations: [] };
+        let body;
+        try {
+            body = JSON.parse(bodyText);
+        }
+        catch {
+            return { validated: false, ok: false, violations: [] };
+        }
+        const ok = fn(body);
+        if (ok)
+            return { validated: true, ok: true, violations: [] };
+        const errs = fn.errors ?? [];
+        const violations = errs.slice(0, MAX_VIOLATIONS).map((e) => ({
+            path: truncate(e.instancePath || "(root)", MAX_PATH_LEN),
+            message: truncate(e.message ?? "is invalid", MAX_MSG_LEN),
+        }));
+        return { validated: true, ok: false, violations };
+    }
+}
+/** A compact, stable, redaction-safe one-liner summarizing the violations for a finding
+ *  message — paths + schema messages only, never the body's values. */
+export function formatViolations(violations) {
+    return violations.map((v) => `${v.path} ${v.message}`).join("; ");
+}

package/dist/api/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/api/schema.ts"],"names":[],"mappings":"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"}

package/dist/cli.js

@@ -0,0 +1,352 @@
+#!/usr/bin/env node
+import { mkdir, writeFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadConfig } from "./config.js";
+import { WebDriver } from "./web/driver.js";
+import { ApiDriver } from "./api/driver.js";
+import { GraphqlDriver } from "./api/graphql-driver.js";
+import { HarDriver } from "./api/har-driver.js";
+import { loadHar, loadOpenApiDocument, loadRoleSeedData, loadSeedData } from "./api/load.js";
+import { NativeDriver } from "./native/driver.js";
+import { buildDefaultRunner } from "./native/load.js";
+import { DesktopDriver } from "./desktop/driver.js";
+import { DefaultMacosAccessibilityRunner } from "./desktop/macos/accessibility-runner.js";
+import { DefaultWindowsUiaRunner } from "./desktop/windows/uia-runner.js";
+import { crawl } from "./core/crawl.js";
+import { replay } from "./core/replay.js";
+import { loadPlan } from "./core/plan.js";
+import { triage } from "./core/triage.js";
+import { writeReport } from "./core/report.js";
+import { MultiSink } from "./sinks/index.js";
+import { ConnectorFanout, builtinManifests } from "./connectors/index.js";
+import { loadProfileFromArgv } from "./profile.js";
+import { compareBaselineFromPath } from "./core/baseline.js";
+import { writePrComment } from "./comment.js";
+import { redactResult, redactUrl } from "./core/redact.js";
+/** Resolve the package version from the shipped package.json (dist/cli.js → ../package.json). */
+function packageVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+const HELP = `🦞 Comber — every-click AI QA agent. Walks every inch of an app and reports what washed up.
+
+USAGE
+  comber <url> [options]                 crawl a web app / site / SaaS surface
+  comber api --openapi <path|url> --api-base <url> [options]
+  comber api --graphql <url> [options]   introspect + exercise a GraphQL endpoint
+  comber api --har <path> [options]      replay a recorded HAR and check for drift
+  comber native --app <id|apk|path> [--platform android|ios] [--device ID] [--deeplink URI]...
+  comber desktop --platform windows|macos (--app-path PATH | --process-name NAME | --app-id ID)
+
+COMMON OPTIONS
+  --profile NAME          use a named profile from comber.config.json
+  --config PATH           path to the config file (default: ./comber.config.json)
+  --strict                exit 1 when any 'fail' finding is present (gate CI)
+  --llm / --no-llm        enable/disable the Opus finding-judge (needs ANTHROPIC_API_KEY)
+  --headed                run the browser headed (web)
+  --allow-writes          exercise mutating controls/methods (DANGER: off by default)
+  --cross-origin          follow links off the start origin (default: same-origin only)
+  --external-links        verify external links (HEAD/GET)
+  --no-screenshots        skip per-state screenshots (raw pixels of the target; sensitive)
+  --baseline PATH         diff findings against a prior baseline
+  --pr-comment PATH       write a Markdown PR-comment summary
+  --replay PATH           deterministic re-run of a recorded plan.json (no discovery, no LLM)
+  --out DIR               output directory (default: runs)
+
+CAPS (runaway-cost backstops)
+  --max-states N          --max-actions N        --max-ms N
+  --max-per-state N       --max-visits-per-route N   --max-tokens N   --near-dup 0..1
+
+API OPTIONS
+  --allow-private-target  target a private/staging base you own (bypass the SSRF egress guard)
+  --api-timeout MS        per-request deadline for API fetches (default 15000)
+
+  Full docs: https://codecomber.io   ·   exit codes: 0 clean · 1 --strict+fails · 2 error`;
+/**
+ * Driver-selection seam (the composition root). The core engine is target-agnostic; a target
+ * is just a Driver. `target: "api"` loads an OpenAPI spec + optional seed and builds the
+ * ApiDriver; `target: "native"` builds the Maestro-backed NativeDriver (default shell-out runner);
+ * everything else keeps the existing WebDriver path (and all of its flags) intact.
+ */
+async function buildDriver(cfg) {
+    if (cfg.target === "api") {
+        const guard = { allowPrivate: cfg.apiAllowPrivateTarget, timeoutMs: cfg.apiTimeoutMs };
+        if (cfg.apiSourceKind === "graphql") {
+            // The GraphqlDriver introspects the endpoint over its (guarded fetch) transport at start().
+            return new GraphqlDriver({
+                endpoint: cfg.graphqlUrl,
+                allowWrites: !cfg.blockWrites,
+                token: cfg.apiToken,
+                allowPrivateTarget: cfg.apiAllowPrivateTarget,
+                timeoutMs: cfg.apiTimeoutMs,
+            });
+        }
+        if (cfg.apiSourceKind === "har") {
+            const har = await loadHar(cfg.harPath);
+            return new HarDriver({
+                har,
+                allowWrites: !cfg.blockWrites,
+                token: cfg.apiToken,
+                allowPrivateTarget: cfg.apiAllowPrivateTarget,
+                timeoutMs: cfg.apiTimeoutMs,
+            });
+        }
+        // OpenAPI (JSON or YAML — the loader content-sniffs). The URL fetch is egress-guarded too.
+        const doc = await loadOpenApiDocument(cfg.openapiSource, guard);
+        const seed = await loadSeedData(cfg.apiSeedDataPath);
+        const roleSeed = await loadRoleSeedData(cfg.apiRoleSeedPath);
+        return new ApiDriver({
+            doc,
+            base: cfg.apiBase,
+            allowWrites: !cfg.blockWrites,
+            token: cfg.apiToken,
+            seed,
+            authProfiles: cfg.apiAuthProfiles,
+            ownerScoped: cfg.apiOwnerScoped ? new Set(cfg.apiOwnerScoped) : undefined,
+            roleSeed,
+            allowPrivateTarget: cfg.apiAllowPrivateTarget,
+            timeoutMs: cfg.apiTimeoutMs,
+        });
+    }
+    if (cfg.target === "native") {
+        const runner = buildDefaultRunner({
+            appId: cfg.nativeApp,
+            platform: cfg.nativePlatform ?? "android",
+            device: cfg.nativeDevice,
+        });
+        return new NativeDriver({
+            appId: cfg.nativeApp,
+            platform: cfg.nativePlatform ?? "android",
+            deeplinks: cfg.nativeDeeplinks,
+            runner,
+            deviceProfile: cfg.nativeDeviceProfile,
+        });
+    }
+    if (cfg.target === "desktop") {
+        if (cfg.desktopPlatform === "macos") {
+            if (cfg.desktopAppProfile?.automationBackend === "xctest") {
+                throw new Error("desktop macOS XCTest backend is not implemented; use --automation-backend accessibility");
+            }
+            const runner = new DefaultMacosAccessibilityRunner({
+                appId: cfg.desktopAppId,
+                appPath: cfg.desktopAppPath,
+                processName: cfg.desktopProcessName,
+            });
+            return new DesktopDriver({
+                platform: "macos",
+                appId: cfg.desktopAppId,
+                appPath: cfg.desktopAppPath,
+                processName: cfg.desktopProcessName,
+                runner,
+                desktopProfile: cfg.desktopAppProfile,
+            });
+        }
+        const runner = new DefaultWindowsUiaRunner({
+            appId: cfg.desktopAppId,
+            appPath: cfg.desktopAppPath,
+            processName: cfg.desktopProcessName,
+            processId: cfg.desktopProcessId,
+            windowTitle: cfg.desktopWindowTitle,
+        });
+        return new DesktopDriver({
+            platform: "windows",
+            appId: cfg.desktopAppId,
+            appPath: cfg.desktopAppPath,
+            processName: cfg.desktopProcessName,
+            processId: cfg.desktopProcessId,
+            windowTitle: cfg.desktopWindowTitle,
+            runner,
+            desktopProfile: cfg.desktopAppProfile,
+        });
+    }
+    return new WebDriver({
+        headless: cfg.headless,
+        storageStatePath: cfg.storageStatePath,
+        blockWrites: cfg.blockWrites,
+        egressUrlDenylist: cfg.egressUrlDenylist,
+        startUrl: cfg.startUrl,
+        sameOriginOnly: cfg.sameOriginOnly,
+        allowedOrigins: cfg.allowedOrigins,
+        denylist: cfg.denylist,
+        destructiveHrefDenylist: cfg.destructiveHrefDenylist,
+        checkExternalLinks: cfg.checkExternalLinks,
+        maxExternalLinks: cfg.maxExternalLinks,
+        linkTimeoutMs: cfg.linkTimeoutMs,
+        linkConcurrency: cfg.linkConcurrency,
+    });
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    // Help/version are the first thing any dev or CI probe tries — they must print and exit 0,
+    // never fall into loadConfig's "usage" throw (which the crash handler re-exits as code 2).
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(HELP);
+        process.exit(0);
+    }
+    if (argv.includes("--version") || argv.includes("-V")) {
+        console.log(packageVersion());
+        process.exit(0);
+    }
+    // `comber connectors` — list the built-in connectors (the marketplace catalog's first-party set).
+    if (argv[0] === "connectors") {
+        console.log("🦞 Comber connectors (built-in):\n");
+        for (const m of builtinManifests()) {
+            const env = m.env?.length ? `  env: ${m.env.join(", ")}` : "";
+            console.log(`  ${m.name.padEnd(10)} ${m.kind.padEnd(13)} ${m.summary}`);
+            if (env)
+                console.log(`  ${" ".repeat(10)} ${env.trim()}`);
+        }
+        console.log(`\nUse in comber.config.json:  "connectors": [{ "use": "slack", "on": "fail" }]\n` +
+            `Install a marketplace connector, then reference its package name in "use".\n` +
+            `Authoring guide: https://codecomber.io/connectors`);
+        process.exit(0);
+    }
+    const loadedProfile = await loadProfileFromArgv(argv);
+    const cfg = loadConfig(argv, loadedProfile.profile);
+    const strict = argv.includes("--strict");
+    const runDir = join(cfg.outDir, `run-${Date.now()}`);
+    await mkdir(runDir, { recursive: true });
+    const mode = cfg.replayPlanPath
+        ? "replaying"
+        : cfg.target === "api"
+            ? "checking API"
+            : cfg.target === "native"
+                ? "checking native app"
+                : cfg.target === "desktop"
+                    ? "checking desktop app"
+                    : "crawling";
+    // Redact the target in the banner too — a start URL with `?token=`/`#access_token=`/a
+    // signed-URL param must not land in stdout/CI logs (PRODUCT.md: "logs never carry secrets").
+    console.log(`🦞 Comber ${mode} ${redactUrl(cfg.startUrl)}`);
+    if (cfg.replayPlanPath)
+        console.log(`   replay: deterministic re-run of ${cfg.replayPlanPath} (no discovery, no LLM)`);
+    console.log(`   mode: ${cfg.useLLM ? "heuristic action-picker + LLM finding-judge (Opus)" : "heuristic (no ANTHROPIC_API_KEY)"}` +
+        `  caps: ${cfg.maxStates} states / ${cfg.maxActions} actions / ${(cfg.maxWallClockMs / 1000) | 0}s`);
+    if (cfg.target === "api") {
+        const src = redactUrl(cfg.graphqlUrl ?? cfg.harPath ?? cfg.openapiSource ?? "");
+        console.log(`   source: ${cfg.apiSourceKind} ${src}  writes: ${cfg.blockWrites ? "read-only" : "ALLOWED (--allow-writes)"}` +
+            (cfg.apiAuthProfiles?.length ? `  roles: ${cfg.apiAuthProfiles.map((p) => p.role).join(", ")}` : ""));
+    }
+    if (cfg.target === "native") {
+        console.log(`   app: ${cfg.nativeApp} (${cfg.nativePlatform ?? "android"})` +
+            `${cfg.nativeDevice ? ` device: ${cfg.nativeDevice}` : ""}` +
+            `  deeplinks: ${cfg.nativeDeeplinks?.length ?? 0}` +
+            `  ⚠️ network-egress safety NOT enforced (no Maestro request interception — see README)`);
+    }
+    if (cfg.target === "desktop") {
+        const backend = cfg.desktopAppProfile?.automationBackend ?? (cfg.desktopPlatform === "macos" ? "accessibility" : "uia");
+        const desktopIdentity = cfg.desktopAppPath ?? cfg.desktopProcessName ?? cfg.desktopAppId ?? `pid:${cfg.desktopProcessId}`;
+        console.log(`   app: ${desktopIdentity} (${cfg.desktopPlatform ?? "windows"} ${backend})` +
+            `  ⚠️ network-egress safety NOT enforced without verified OS-level proxy evidence`);
+    }
+    if (cfg.profileName) {
+        console.log(`   profile: ${cfg.profileName}${loadedProfile.configPath ? ` (${loadedProfile.configPath})` : ""}`);
+    }
+    const driver = await buildDriver(cfg);
+    const result = cfg.replayPlanPath
+        ? await replay(driver, cfg, runDir, await loadPlan(cfg.replayPlanPath))
+        : await crawl(driver, cfg, runDir);
+    const judged = await triage(result.findings, {
+        useLLM: cfg.useLLM,
+        anthropicKey: cfg.anthropicKey,
+        baseURL: cfg.hostedInferenceUrl,
+    });
+    result.findings = judged.findings;
+    result.tokenSpend.input += judged.spend.input;
+    result.tokenSpend.output += judged.spend.output;
+    if (cfg.baselinePath) {
+        result.baseline = await compareBaselineFromPath(result, cfg.baselinePath);
+    }
+    // Redact ONCE before any artifact write. finding.url/message + startUrl +
+    // visited/link URLs routinely carry crawled-app secrets (OAuth #access_token,
+    // ?token= magic links, signed-URL params, path tokens); the report.html and
+    // result.json artifacts are uploaded to CI and the PR comment is posted to a
+    // (possibly public) PR, so none of those surfaces may see raw findings.
+    // (The sink redacts internally, so it still gets the raw result.)
+    const redacted = redactResult(result);
+    const reportPath = await writeReport(redacted, runDir, new Date().toISOString());
+    if (cfg.prCommentPath) {
+        const commentPath = await writePrComment(redacted, reportPath, cfg.prCommentPath);
+        console.log(`   pr-comment: ${commentPath}`);
+    }
+    await writeFile(join(runDir, "result.json"), JSON.stringify(redacted, null, 2)).catch(() => { });
+    const runMeta = {
+        runId: randomUUID(),
+        app: (() => {
+            try {
+                return new URL(cfg.startUrl).hostname;
+            }
+            catch {
+                return undefined;
+            }
+        })(),
+        mode: cfg.useLLM ? "llm" : "heuristic",
+        runDir,
+    };
+    // Persistence — opt-in, no-op when unconfigured, never breaks a run.
+    const sink = MultiSink.fromEnv();
+    if (sink.active.length) {
+        await sink.recordRun(result, runMeta);
+        console.log(`   sinks: ${sink.active.join(", ")}`);
+    }
+    // Connectors — deliver the finished run where developers work (Slack/Discord/GitHub/Linear/
+    // JUnit/webhook/marketplace packages). Declared in comber.config.json; each delivery is gated
+    // by severity + isolated so one connector failure never breaks the run.
+    const connectors = await ConnectorFanout.load(cfg.connectors);
+    if (connectors.active.length) {
+        await connectors.deliver(result, runMeta);
+        console.log(`   connectors: ${connectors.active.join(", ")}`);
+    }
+    const fails = result.findings.filter((f) => f.severity === "fail").length;
+    const warns = result.findings.filter((f) => f.severity === "warn").length;
+    const infos = result.findings.filter((f) => f.severity === "info").length;
+    console.log(`\n${fails ? "❌" : "✅"} ${fails} fail / ${warns} warn / ${infos} info across ${result.visitedStates} states ` +
+        `(${result.actionsTaken} actions, ${(result.durationMs / 1000).toFixed(1)}s, ` +
+        `${result.tokenSpend.output} out-tokens${result.cappedBy ? `, capped by ${result.cappedBy}` : ""})`);
+    if (result.coverage) {
+        const c = result.coverage;
+        const x = (k) => c.extra[k] ?? 0;
+        const followTargets = x("followTargetsDiscovered") || x("linksDiscovered");
+        const denom = Math.max(c.elementsExercised, c.elementsDiscovered - c.elementsSkipped - followTargets);
+        const blockerBlindSpots = c.blindSpots.filter((blindSpot) => blindSpot.severity === "blocker-for-exhaustive").length;
+        const exhaustiveSuffix = c.exhaustiveClaimAllowed
+            ? ""
+            : c.cappedNotExhaustive
+                ? " - not exhaustive (capped)"
+                : " - not exhaustive";
+        console.log(`   coverage: ${c.elementsExercised}/${denom} elements exercised (${c.elementCoveragePct}%) · ` +
+            `${x("controlsExercised")} controls · ${x("modalsOpened")} modals · ` +
+            `links ${x("linksChecked")} checked/${x("linksBroken")} broken/${x("linksDiscovered")} found · ` +
+            `${x("branchesExercised")} branches/${x("branchTargetsDiscovered")} child states, ` +
+            `${c.frameBlindSpots} blind-spots/${blockerBlindSpots} blocker gaps, ` +
+            `${redacted.exhaustivenessLedger.length} ledger rows` +
+            exhaustiveSuffix);
+        const skips = Object.entries(c.skipLedger);
+        if (skips.length)
+            console.log(`   skipped: ${skips.map(([k, v]) => `${k}=${v}`).join(", ")}`);
+    }
+    if (result.baseline) {
+        const b = result.baseline.summary;
+        console.log(`   baseline: ${b.newFail} new fail / ${b.newWarn} new warn / ${b.resolved} resolved / ${b.unchanged} unchanged` +
+            (result.baseline.baselineFound ? "" : " (no prior baseline found)"));
+    }
+    console.log("   covered:");
+    for (const u of redacted.visitedUrls)
+        console.log(`     · ${u}`);
+    console.log(`📄 ${reportPath}`);
+    // Default soft (non-blocking, per the rollout plan); --strict gates CI on fails.
+    process.exit(strict && fails > 0 ? 1 : 0);
+}
+main().catch((err) => {
+    console.error("comber crashed:", err);
+    process.exit(2);
+});