aztrx-cli 0.1.1 → 0.2.1

package/dist/core/orchestrator.js

@@ -1,15 +1,10 @@
 import * as path from "path";
-import { chromium } from "playwright";
 import pc from "picocolors";
+import { VERSION } from "./version.js";
 import { EventBus } from "./eventBus.js";
-import { attachInterceptor } from "./interceptor.js";
-import { SignalClassifier, loadBaseline } from "./classifier.js";
-import { ActionRecorder } from "./recorder.js";
-import { walkDom } from "./domWalker.js";
-import { fuzz } from "./fuzzer.js";
-import { httpFuzz } from "./httpFuzzer.js";
+import { loadBaseline } from "./classifier.js";
 import { attachNetworkGuard, allowHostsFrom } from "./networkGuard.js";
-import { resolveFrame, resolveServerFrame } from "./resolver.js";
+import { swarmDetect } from "./swarm.js";
 import { ReplayEngine } from "./replay.js";
 import { minimize } from "./minimizer.js";
 import { writeSpec } from "./specCompiler.js";
@@ -40,6 +35,8 @@ function printFinding(f, write) {
 }
 /** Human-readable run mode, surfaced in the cloud dashboard. */
 function runMode(o) {
+    if ((o.workers ?? 1) > 1)
+        return `swarm (${o.workers} workers)`;
     if (o.fuzz)
         return `fuzz (seed ${o.seed ?? 42})`;
     if (o.httpFuzz)
@@ -61,7 +58,7 @@ function runMode(o) {
 export async function run(options) {
     const { url, repoRoot } = options;
     const maxActions = options.maxActions ?? 100;
-    const guardOn = Boolean(options.fuzz || options.repro);
+    const guardOn = Boolean(options.fuzz || options.repro || (options.workers ?? 1) > 1);
     const allowHosts = allowHostsFrom(url, options.allowHosts ?? []);
     const ui = options.ui === true;
     const bus = options.bus ?? new EventBus();
@@ -70,7 +67,7 @@ export async function run(options) {
             console.log(parts.join(" "));
     };
     const emitPhase = (phase, detail) => bus.emit("phase", { phase, detail, ts: Date.now() });
-    say(pc.cyan("\nAztrx AI v0.1.1 — Runtime Detector"));
+    say(pc.cyan(`\nAztrx AI v${VERSION} — Runtime Detector`));
     say(pc.dim(`Target: ${url}`));
     say(pc.dim(`Repo:   ${repoRoot}`));
     if (options.fuzz)
@@ -83,109 +80,64 @@ export async function run(options) {
         say(pc.dim(`Auth:   ${options.storageState}`));
     say("");
     emitPhase("launch", url);
-    const classifier = new SignalClassifier(await loadBaseline(repoRoot));
-    const recorder = new ActionRecorder();
     const runLog = new RunLog(repoRoot);
     runLog.reset();
     runLog.append({ type: "run_start", url, ts: Date.now() });
-    bus.on("action", (a) => recorder.record(a));
-    bus.on("telemetry", async (payload) => {
-        const finding = classifier.classify(payload);
-        if (!finding)
-            return;
-        finding.actionHistory = recorder.snapshot();
-        if (finding.severity === "noise") {
-            bus.emit("noise", { ts: Date.now() });
-            return;
-        }
-        runLog.append({ type: "finding", finding });
-        if (payload.serverError) {
-            finding.serverError = { message: payload.serverError.message, body: payload.serverError.body };
-        }
-        if (payload.url && payload.line) {
-            const resolved = await resolveFrame({ url: payload.url, line: payload.line, column: payload.column ?? 0, message: payload.rawMessage }, repoRoot);
-            finding.mappedLocation = {
-                filePath: resolved.sourceFile,
-                line: resolved.line,
-                column: resolved.column,
-                codeContext: resolved.codeSnippet,
-                isOwnCode: resolved.resolvedFrom !== "unresolved",
-            };
-        }
-        else if (payload.serverError?.frame) {
-            const resolved = resolveServerFrame(payload.serverError.frame, repoRoot);
-            finding.mappedLocation = {
-                filePath: resolved.sourceFile,
-                line: resolved.line,
-                column: resolved.column,
-                codeContext: resolved.codeSnippet,
-                isOwnCode: resolved.resolvedFrom !== "unresolved",
-            };
-        }
-        bus.emit("finding", finding);
-        printFinding(finding, say);
-    });
-    const browser = await chromium.launch({ headless: true });
-    const context = await browser.newContext(options.storageState ? { storageState: options.storageState } : {});
-    const page = await context.newPage();
-    attachInterceptor(page, bus);
-    if (guardOn) {
-        await attachNetworkGuard(page, {
-            allowHosts,
-            onBlock: (u) => say(pc.dim(`  [guard] blocked ${u}`)),
-        });
+    const baseline = await loadBaseline(repoRoot);
+    const workers = options.workers ?? 1;
+    // F-swarm — parallel detection. One worker is the legacy pass; `--http-fuzz`
+    // or `workers > 1` fan out into a swarm. Findings come back merged by
+    // fingerprint, with per-worker action history already attached.
+    if (workers > 1 || options.httpFuzz) {
+        emitPhase("swarm", `${workers} worker(s)`);
     }
-    page.on("framenavigated", (frame) => {
-        if (frame === page.mainFrame())
-            bus.emit("route", { url: frame.url(), ts: Date.now() });
-    });
-    let loaded = true;
-    await page.goto(url, { waitUntil: "load", timeout: 30000 }).catch((e) => {
-        loaded = false;
-        say(pc.red("Failed to load target: ") + pc.dim(e.message));
-    });
-    if (loaded) {
-        // Settle: wait for hydration and mount-time effects (async fetches,
-        // unhandled rejections, React warnings) to fire before we act. A page whose
-        // only bugs are mount-time would otherwise be closed before they happen —
-        // and a page with no interactive elements fuzzes zero actions, so it relies
-        // on this window.
-        await page.waitForTimeout(2000);
+    else if (options.fuzz) {
+        emitPhase("fuzz");
     }
-    if (loaded && options.crashTest) {
-        await page.evaluate(() => {
-            setTimeout(() => {
-                throw new Error("Aztrx test: Cannot read properties of undefined (reading 'token')");
-            }, 300);
-        });
-        await page.waitForTimeout(800);
+    else {
+        emitPhase("walk");
     }
-    if (loaded) {
-        emitPhase(options.fuzz ? "fuzz" : "walk");
-        const acted = options.fuzz
-            ? await fuzz(page, bus, { seed: options.seed, maxActions, dryRun: options.dryRun })
-            : await walkDom(page, bus, { maxActions, dryRun: options.dryRun });
-        say(pc.dim(`\n${options.fuzz ? "Fuzzed" : "Walked"} ${acted} action(s).\n`));
+    const { findings, replayStorageState: swarmAuthState, totalActions, workerCount, } = await swarmDetect({
+        url,
+        repoRoot,
+        maxActions,
+        dryRun: options.dryRun,
+        fuzz: options.fuzz,
+        httpFuzz: options.httpFuzz,
+        httpFuzzMutations: options.httpFuzzMutations,
+        seed: options.seed ?? 42,
+        workers,
+        allowHosts,
+        storageState: options.storageState,
+        login: options.login,
+        loginEmail: options.loginEmail,
+        loginPassword: options.loginPassword,
+        loginUrl: options.loginUrl,
+        crashTest: options.crashTest,
+        baseline,
+        guardOn,
+        log: say,
+    });
+    // Replays reuse the swarm-captured auth state, or the explicit --storage-state.
+    const replayStorageState = swarmAuthState ?? options.storageState;
+    // Surface the merged findings to the live panel, run log, and console.
+    for (const f of findings) {
+        bus.emit("finding", f);
+        runLog.append({ type: "finding", finding: f });
+        printFinding(f, say);
     }
-    if (loaded && options.httpFuzz) {
-        emitPhase("http-fuzz");
-        const sent = await httpFuzz(page, url, bus, {
-            maxRequests: maxActions,
-            dryRun: options.dryRun,
-            allowHosts,
-            mutations: options.httpFuzzMutations,
-        });
-        say(pc.dim(`\nHTTP-fuzzed ${sent} request(s).\n`));
+    if (workerCount > 1) {
+        say(pc.dim(`\nSwarm: ${totalActions} action(s) across ${workerCount} worker(s).\n`));
+    }
+    else {
+        say(pc.dim(`\n${options.fuzz ? "Fuzzed" : "Walked"} ${totalActions} action(s).\n`));
     }
-    await page.waitForTimeout(500);
-    await browser.close();
-    const findings = classifier.findings();
     // F7 → F8 → F9: minimize each finding, compile an executable spec, validate
     // the flake rate. Only crash/error findings with a recorded action history.
     if (options.repro) {
         const engine = new ReplayEngine({
             attachGuard: async (p) => attachNetworkGuard(p, { allowHosts }),
-            storageState: options.storageState,
+            storageState: replayStorageState,
         });
         try {
             const targets = findings.filter((f) => (f.severity === "crash" || f.severity === "error") && f.actionHistory.length > 0);

package/dist/core/prompt.js

@@ -0,0 +1,22 @@
+/**
+ * A single yes/no confirmation for `--fix`. Kept tiny and side-effect free:
+ *
+ *   - `--yes` short-circuits to `true` (scripts/CI).
+ *   - a non-TTY stdout without `--yes` short-circuits to `false` — an unattended
+ *     run never mutates the working tree, it just leaves the `.patch` files.
+ *   - otherwise prompts on stdin, defaulting to "no".
+ */
+import * as readline from "readline";
+export function promptYesNo(question, opts = {}) {
+    if (opts.yes === true)
+        return Promise.resolve(true);
+    if (process.stdout.isTTY !== true)
+        return Promise.resolve(false);
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question + " ", (answer) => {
+            rl.close();
+            resolve(/^y(es)?$/i.test(answer.trim()));
+        });
+    });
+}

package/dist/core/summarize.js

@@ -0,0 +1,173 @@
+/**
+ * F13 — the "X-ray report": a plain-language summary of a run's findings,
+ * instead of a wall of stack traces. Two engines behind one entry point:
+ *
+ *   - LLM (Anthropic Messages API) when `ANTHROPIC_API_KEY` is set — friendly
+ *     prose in the requested language, mirroring the transport in `heal/llm.ts`.
+ *   - deterministic template when there is no key (or the call fails) — a
+ *     readable, structured list that needs no network.
+ *
+ * An empty run short-circuits to the template (no reason to pay for "all clear").
+ * The offer-to-apply line is emitted only when verified fixes are actually ready,
+ * so `--explain` (no healing) never promises a fix it doesn't have.
+ */
+const MODEL = process.env.AZTRX_MODEL || "claude-sonnet-5";
+const API_URL = "https://api.anthropic.com/v1/messages";
+function normalizeLang(lang) {
+    return lang === "ru" ? "ru" : "en";
+}
+/** Russian plural form picker: [one, few, many]. */
+function ruPlural(n, forms) {
+    const mod10 = n % 10;
+    const mod100 = n % 100;
+    if (mod10 === 1 && mod100 !== 11)
+        return forms[0];
+    if (mod10 >= 2 && mod10 <= 4 && (mod100 < 12 || mod100 > 14))
+        return forms[1];
+    return forms[2];
+}
+const PHRASES = {
+    en: {
+        none: "No problems found — the app survived this pass.",
+        found: (n) => `I scanned your code and found ${n} problem${n === 1 ? "" : "s"}:`,
+        offer: (n) => `I've prepared ${n} verified fix${n === 1 ? "" : "es"}.`,
+        severity: { crash: "crash", error: "error", warning: "warning", noise: "noise" },
+        type: {
+            uncaught_exception: "uncaught exception",
+            unhandled_rejection: "unhandled promise rejection",
+            console_error: "console error",
+            network_5xx: "server error (5xx)",
+            network_timeout: "network timeout",
+        },
+        repro: "repro",
+        fix: "fix",
+        healed: "healed",
+    },
+    ru: {
+        none: "Проблем не найдено — приложение пережило этот проход.",
+        found: (n) => `Привет! Я просканировал твой код и нашёл ${n} ${ruPlural(n, ["проблему", "проблемы", "проблем"])}:`,
+        offer: (n) => `Я подготовил ${n} ${ruPlural(n, ["исправление", "исправления", "исправлений"])}, каждое проверено тестами.`,
+        severity: { crash: "краш", error: "ошибка", warning: "предупреждение", noise: "шум" },
+        type: {
+            uncaught_exception: "необработанное исключение",
+            unhandled_rejection: "необработанный reject промиса",
+            console_error: "ошибка в консоли",
+            network_5xx: "ошибка сервера (5xx)",
+            network_timeout: "таймаут сети",
+        },
+        repro: "воспроизведение",
+        fix: "фикс",
+        healed: "вылечено",
+    },
+};
+function location(f) {
+    const m = f.mappedLocation;
+    if (!m || !m.filePath)
+        return "";
+    return `${m.filePath}:${m.line}:${m.column}`;
+}
+function shortMessage(f) {
+    const line = f.rawMessage.split("\n")[0].trim();
+    return line.length > 120 ? line.slice(0, 117) + "…" : line;
+}
+/** One bullet for the template engine: location, kind, and the one-line message. */
+function describeFinding(f, p) {
+    const loc = location(f);
+    const head = loc ? `${loc} — ` : "";
+    const kind = `${p.type[f.type]} (${p.severity[f.severity]})`;
+    const lines = [`${head}${kind}: "${shortMessage(f)}"`];
+    const tail = [];
+    if (f.repro && f.repro.verdict !== "unreliable") {
+        tail.push(`${p.repro}: ${f.repro.verdict} (${f.repro.reproductions}/${f.repro.runs})`);
+    }
+    if (f.heal) {
+        tail.push(`${p.fix}: ${f.heal.status === "healed" ? p.healed : f.heal.status}`);
+    }
+    if (tail.length)
+        lines.push(`  ${tail.join(" · ")}`);
+    return lines.join("\n");
+}
+/** Deterministic, offline summary. Used as the no-key fallback and for empty runs. */
+export function summarizeFindingsTemplate(findings, lang = "en") {
+    const p = PHRASES[lang];
+    if (findings.length === 0)
+        return p.none;
+    const healed = findings.filter((f) => f.heal?.status === "healed");
+    const bullets = findings
+        .map((f, i) => `  ${i + 1}. ${describeFinding(f, p)}`)
+        .join("\n");
+    const lines = [p.found(findings.length), "", bullets];
+    if (healed.length)
+        lines.push("", p.offer(healed.length));
+    return lines.join("\n");
+}
+function buildLlmPrompt(findings, lang, hasHealed) {
+    const rows = findings
+        .map((f) => {
+        const loc = location(f) || "(no source location)";
+        const repro = f.repro ? `${f.repro.verdict} ${f.repro.reproductions}/${f.repro.runs}` : "none";
+        const heal = f.heal
+            ? f.heal.status + (f.heal.explanation ? ` — ${f.heal.explanation}` : "")
+            : "n/a";
+        return `- ${loc} | ${f.type} | severity=${f.severity} | "${shortMessage(f)}" | repro=${repro} | heal=${heal}`;
+    })
+        .join("\n");
+    const fixLine = hasHealed
+        ? "Verified fixes ARE ready to apply — mention that they are prepared."
+        : "No fixes were prepared — do not offer to apply anything.";
+    return [
+        `A QA tool scanned a web app and found the following findings:`,
+        rows,
+        "",
+        `Write a short, friendly, plain-language summary for a developer (${lang}): what was found, what each problem means in simple words, and — per the note below — whether fixes are ready. Do not invent details that are not listed. Keep it to a few short paragraphs or a tight bullet list.`,
+        fixLine,
+    ].join("\n");
+}
+const SYSTEM = "You are the plain-spoken explainer for a QA tool called Aztrx AI. You turn raw runtime-finding data into a concise, human-language summary for a developer. Never invent details absent from the data. Respond in the requested language only.";
+async function summarizeFindingsLlm(findings, lang) {
+    const hasHealed = findings.some((f) => f.heal?.status === "healed");
+    const res = await fetch(API_URL, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            "x-api-key": process.env.ANTHROPIC_API_KEY,
+            "anthropic-version": "2023-06-01",
+        },
+        body: JSON.stringify({
+            model: MODEL,
+            max_tokens: 1024,
+            temperature: 0.2,
+            system: SYSTEM,
+            messages: [{ role: "user", content: buildLlmPrompt(findings, lang, hasHealed) }],
+        }),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`summarize: LLM request failed (${res.status}): ${body.slice(0, 300)}`);
+    }
+    const data = (await res.json());
+    const text = (data.content ?? [])
+        .filter((c) => c.type === "text")
+        .map((c) => c.text ?? "")
+        .join("\n")
+        .trim();
+    return text || summarizeFindingsTemplate(findings, lang);
+}
+/**
+ * Entry point. Empty run → template (no API cost). Otherwise LLM when a key is
+ * present; falls back to the deterministic template on any transport failure, so
+ * the report never crashes the run.
+ */
+export async function summarizeFindings(findings, opts = {}) {
+    const lang = normalizeLang(opts.lang);
+    if (findings.length === 0)
+        return summarizeFindingsTemplate(findings, lang);
+    if (!process.env.ANTHROPIC_API_KEY)
+        return summarizeFindingsTemplate(findings, lang);
+    try {
+        return await summarizeFindingsLlm(findings, lang);
+    }
+    catch {
+        return summarizeFindingsTemplate(findings, lang);
+    }
+}

package/dist/core/swarm.js

@@ -0,0 +1,235 @@
+/**
+ * F-swarm — parallel detection. Runs N workers at once, each with its own
+ * browser context, event bus, action recorder, and classifier, so the action
+ * history attached to a finding belongs to the worker that saw it (never
+ * interleaved). Workers attack different sides: a deterministic walk, several
+ * chaos-fuzz seeds, and — optionally — the server-side HTTP fuzzer.
+ *
+ * Findings are merged by fingerprint at the end (occurrences summed, the richest
+ * action history / source mapping kept); the caller then runs repro/heal on the
+ * merged set as usual.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { chromium } from "playwright";
+import { EventBus } from "./eventBus.js";
+import { attachInterceptor } from "./interceptor.js";
+import { establishLogin } from "./auth.js";
+import { SignalClassifier } from "./classifier.js";
+import { ActionRecorder } from "./recorder.js";
+import { walkDom } from "./domWalker.js";
+import { fuzz } from "./fuzzer.js";
+import { httpFuzz } from "./httpFuzzer.js";
+import { attachNetworkGuard } from "./networkGuard.js";
+import { resolveFrame, resolveServerFrame } from "./resolver.js";
+/**
+ * Run one worker's detection pass and return its findings. All internal events
+ * flow through a local bus (isolation); only `action`/`route`/`noise` are
+ * forwarded to `forwardBus` so a live panel can aggregate, never per-worker
+ * findings (those are merged by the caller first).
+ */
+export async function detectWorker(browser, opts, strategy, forwardBus) {
+    const workerBus = new EventBus();
+    const recorder = new ActionRecorder();
+    const classifier = new SignalClassifier(opts.baseline);
+    workerBus.on("action", (a) => {
+        recorder.record(a);
+        forwardBus?.emit("action", a);
+    });
+    workerBus.on("route", (r) => forwardBus?.emit("route", r));
+    workerBus.on("noise", (n) => forwardBus?.emit("noise", n));
+    // Classify telemetry with THIS worker's recorder, so action history is correct.
+    workerBus.on("telemetry", async (payload) => {
+        const finding = classifier.classify(payload);
+        if (!finding)
+            return;
+        finding.actionHistory = recorder.snapshot();
+        if (finding.severity === "noise") {
+            workerBus.emit("noise", { ts: Date.now() });
+            return;
+        }
+        if (payload.serverError) {
+            finding.serverError = { message: payload.serverError.message, body: payload.serverError.body };
+        }
+        if (payload.url && payload.line) {
+            const resolved = await resolveFrame({ url: payload.url, line: payload.line, column: payload.column ?? 0, message: payload.rawMessage }, opts.repoRoot);
+            finding.mappedLocation = {
+                filePath: resolved.sourceFile,
+                line: resolved.line,
+                column: resolved.column,
+                codeContext: resolved.codeSnippet,
+                isOwnCode: resolved.resolvedFrom !== "unresolved",
+            };
+        }
+        else if (payload.serverError?.frame) {
+            const resolved = resolveServerFrame(payload.serverError.frame, opts.repoRoot);
+            finding.mappedLocation = {
+                filePath: resolved.sourceFile,
+                line: resolved.line,
+                column: resolved.column,
+                codeContext: resolved.codeSnippet,
+                isOwnCode: resolved.resolvedFrom !== "unresolved",
+            };
+        }
+    });
+    const context = await browser.newContext(opts.storageState ? { storageState: opts.storageState } : {});
+    const page = await context.newPage();
+    attachInterceptor(page, workerBus);
+    if (opts.guardOn) {
+        await attachNetworkGuard(page, {
+            allowHosts: opts.allowHosts,
+            onBlock: (u) => opts.log(`[guard] blocked ${u}`),
+        });
+    }
+    page.on("framenavigated", (frame) => {
+        if (frame === page.mainFrame())
+            workerBus.emit("route", { url: frame.url(), ts: Date.now() });
+    });
+    let loaded = true;
+    await page.goto(opts.url, { waitUntil: "load", timeout: 30000 }).catch((e) => {
+        loaded = false;
+        opts.log(`Failed to load target: ${e.message}`);
+    });
+    if (loaded) {
+        // Settle for hydration and mount-time effects before acting.
+        await page.waitForTimeout(2000);
+    }
+    // Auto-login (best-effort). The server-side HTTP fuzzer uses Node-side fetch,
+    // so it doesn't benefit from a browser session — skip it there.
+    let replayStorageState;
+    if (loaded && strategy.kind !== "http-fuzz" && opts.login && opts.loginEmail && opts.loginPassword) {
+        const res = await establishLogin(page, {
+            email: opts.loginEmail,
+            password: opts.loginPassword,
+            loginUrl: opts.loginUrl,
+        });
+        if (res.ok) {
+            if (opts.saveAuthState) {
+                const state = await context.storageState();
+                const authStatePath = path.join(opts.repoRoot, ".aztrx", "auth-state.json");
+                fs.mkdirSync(path.dirname(authStatePath), { recursive: true });
+                fs.writeFileSync(authStatePath, JSON.stringify(state, null, 2), "utf-8");
+                replayStorageState = authStatePath;
+                opts.log(`[auth] logged in → ${path.relative(opts.repoRoot, authStatePath)}`);
+            }
+            else {
+                opts.log("[auth] logged in");
+            }
+            await page.goto(opts.url, { waitUntil: "load", timeout: 30000 }).catch(() => { });
+        }
+        else {
+            opts.log(`[auth] skipped: ${res.reason}`);
+        }
+    }
+    if (loaded && opts.crashTest) {
+        await page.evaluate(() => {
+            setTimeout(() => {
+                throw new Error("Aztrx test: Cannot read properties of undefined (reading 'token')");
+            }, 300);
+        });
+        await page.waitForTimeout(800);
+    }
+    let actions = 0;
+    if (loaded) {
+        if (strategy.kind === "walk") {
+            actions = await walkDom(page, workerBus, { maxActions: opts.maxActions, dryRun: opts.dryRun });
+        }
+        else if (strategy.kind === "fuzz") {
+            actions = await fuzz(page, workerBus, { seed: strategy.seed, maxActions: opts.maxActions, dryRun: opts.dryRun });
+        }
+        else {
+            actions = await httpFuzz(page, opts.url, workerBus, {
+                maxRequests: opts.maxActions,
+                dryRun: opts.dryRun,
+                allowHosts: opts.allowHosts,
+                mutations: opts.httpFuzzMutations,
+            });
+        }
+    }
+    await page.waitForTimeout(500);
+    await context.close();
+    return { findings: classifier.findings(), actions, replayStorageState };
+}
+/** Dedup findings across workers by fingerprint: sum occurrences, keep the richest. */
+export function mergeFindings(arrays) {
+    const byFingerprint = new Map();
+    for (const arr of arrays) {
+        for (const f of arr) {
+            const existing = byFingerprint.get(f.fingerprint);
+            if (!existing) {
+                byFingerprint.set(f.fingerprint, { ...f, actionHistory: [...f.actionHistory] });
+                continue;
+            }
+            existing.occurrences += f.occurrences;
+            if (!existing.mappedLocation && f.mappedLocation)
+                existing.mappedLocation = f.mappedLocation;
+            if (existing.actionHistory.length < f.actionHistory.length)
+                existing.actionHistory = f.actionHistory;
+        }
+    }
+    return [...byFingerprint.values()];
+}
+/** Build the worker roster for a run. `workers = 1` with no http-fuzz is the
+ * legacy single pass; `--http-fuzz` and/or `workers > 1` fan out. */
+function buildStrategies(opts) {
+    const strategies = [];
+    if (opts.httpFuzz)
+        strategies.push({ kind: "http-fuzz" });
+    const w = Math.max(1, opts.workers);
+    if (w === 1) {
+        strategies.push(opts.fuzz ? { kind: "fuzz", seed: opts.seed } : { kind: "walk" });
+        return strategies;
+    }
+    if (opts.fuzz) {
+        for (let i = 0; i < w; i++)
+            strategies.push({ kind: "fuzz", seed: opts.seed + i });
+    }
+    else {
+        strategies.push({ kind: "walk" });
+        for (let i = 1; i < w; i++)
+            strategies.push({ kind: "fuzz", seed: opts.seed + i });
+    }
+    return strategies;
+}
+/** Launch one browser, run the worker roster concurrently, merge findings. */
+export async function swarmDetect(opts) {
+    const strategies = buildStrategies(opts);
+    const browser = await chromium.launch({ headless: true });
+    try {
+        const settled = await Promise.allSettled(strategies.map((strategy, i) => detectWorker(browser, {
+            url: opts.url,
+            repoRoot: opts.repoRoot,
+            allowHosts: opts.allowHosts,
+            maxActions: opts.maxActions,
+            dryRun: opts.dryRun,
+            guardOn: opts.guardOn,
+            storageState: opts.storageState,
+            login: opts.login,
+            loginEmail: opts.loginEmail,
+            loginPassword: opts.loginPassword,
+            loginUrl: opts.loginUrl,
+            crashTest: i === 0 ? opts.crashTest : false,
+            saveAuthState: i === 0,
+            httpFuzzMutations: opts.httpFuzzMutations,
+            baseline: opts.baseline,
+            log: (m) => opts.log(strategies.length > 1 ? `[w${i}] ${m}` : m),
+        }, strategy)));
+        const results = [];
+        settled.forEach((r, i) => {
+            if (r.status === "fulfilled")
+                results.push(r.value);
+            else
+                opts.log(`worker ${i} failed: ${r.reason?.message ?? String(r.reason)}`);
+        });
+        let replayStorageState;
+        for (const r of results)
+            if (r.replayStorageState)
+                replayStorageState = r.replayStorageState;
+        const findings = mergeFindings(results.map((r) => r.findings));
+        const totalActions = results.reduce((sum, r) => sum + r.actions, 0);
+        return { findings, replayStorageState, totalActions, workerCount: strategies.length };
+    }
+    finally {
+        await browser.close();
+    }
+}

package/dist/core/version.js

@@ -0,0 +1,15 @@
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+// Single source of truth for the CLI's self-reported version. Read from the
+// installed package.json so a future `npm version` bump never drifts from the
+// printed banner — a hardcoded "v0.1.1" previously survived the 0.2.0 bump.
+function readVersion() {
+    try {
+        const url = new URL("../../package.json", import.meta.url);
+        return JSON.parse(readFileSync(fileURLToPath(url), "utf-8")).version;
+    }
+    catch {
+        return "0.0.0"; // cosmetic only — package.json not resolvable (raw dist/ checkout)
+    }
+}
+export const VERSION = readVersion();