aztrx-cli 0.4.2 → 0.4.4

package/README.md

@@ -22,6 +22,7 @@ npx aztrx-cli run http://localhost:3000 --fix    # fix them — free for common
 ## Why Aztrx AI
 
 - **Sees swallowed errors.** Error Boundaries and `window.onerror` miss the errors your app *catches*. Aztrx reads the real throw-site stack off the `Error` object — a crash you've never seen in your logs becomes a finding you can't ignore.
+- **Explains the crash in one line.** Every crash/error ships with a one-sentence diagnosis — why it happened and what to change (e.g. `the value before `.cart` is undefined — guard with `?.`). Free, no key, right in the terminal and `report.html`.
 - **Proves, not reports.** Every crash ships with an executable `.spec.ts` repro and a flake-rate verdict — `[deterministic 3/3]`, `[flaky 3/5]`, or `[unreliable]`.
 - **Safe by default.** A deny-by-default network guard blocks off-origin calls, a destructive-action deny-list refuses to click "delete", "pay", or "logout", and nothing leaves your machine unless you opt in.
 
@@ -82,6 +83,7 @@ your test suite before you see it. Aztrx never commits. `--pr` opens a merge-rea
 | `--swarm` / `--workers N` | parallel detection workers |
 | `--login` | auto-login to test authenticated pages |
 | `--badge` / `--pr-comment` / `--fail-on` | CI artifacts |
+| `patrol <url>` | autonomous loop — re-scan, fix, open a PR per bug |
 | `modernize <file>` | rewrite legacy JS/TS into modern idiomatic syntax |
 | `studio` | live dashboard on `localhost:7331` |
 
@@ -89,6 +91,35 @@ Full list: `aztrx-cli run --help`, or the [CLI reference](#cli-reference).
 
 ---
 
+## Autonomous patrol
+
+`aztrx patrol` is the looped version of `run --fix`: point it at a running app and it
+re-scans on an interval, fixes anything new, and opens a **PR per bug** — no human in
+the middle. Each PR body carries a **recorded repro**: a short animated GIF that replays
+the crash step-by-step, so a reviewer sees the bug happen before the fix.
+
+```bash
+aztrx-cli patrol http://localhost:3000        # re-scan every 10 min, open a PR per new bug
+aztrx-cli patrol http://localhost:3000 --once # one scan, then exit (great for CI/cron)
+aztrx-cli patrol http://localhost:3000 --batch # group a cycle's fixes into one PR
+```
+
+| Flag | What it does | Default |
+| --- | --- | --- |
+| `--interval <s>` | Seconds between scans | `600` |
+| `--max-fixes <n>` | Max PRs to open per session | `5` |
+| `--max-spend <n>` | Hard cap on paid LLM generations per session | unlimited |
+| `--retry-after <s>` | Cooldown before an unfixable bug is retried | `1800` |
+| `--batch` | Group all of a cycle's fixes into one PR | one PR per bug |
+| `--once` | Run a single scan then exit | loop forever |
+| `--fuzz` / `--workers <n>` | Detection mode / parallelism (pass-through to `run`) | — |
+
+Guardrails keep the loop from running away: it only stages the files a patch touched
+(never `git add -A`), dedups by crash fingerprint (a re-scan won't re-open the same PR),
+backs off from unfixable bugs, and respects a session-wide LLM spend cap.
+
+---
+
 ## Security
 
 - **Local-first.** Nothing leaves your machine unless you opt in.
@@ -114,7 +145,7 @@ jobs:
     permissions: { contents: read, pull-requests: write }
     steps:
       - uses: actions/checkout@v4
-      - uses: Aztrx-AI/aztrx@98dbad0f7b6681c7670f7068d01dc0d54813a55f
+      - uses: Aztrx-AI/aztrx@v0.4.3
         with:
           url: http://localhost:3000
           start-command: npm run dev          # optional — boot the app in the background
@@ -137,9 +168,12 @@ niche tuning knobs).
 | --- | --- | --- |
 | `--fuzz` | Seeded chaos fuzzing instead of the deterministic walk | — |
 | `--http-fuzz` | Server-side mutation fuzzing — hostile requests against the target origin | — |
+| `--http-fuzz-mutations` | With `--http-fuzz`: also send POST/PUT body mutations (default: GET-only) | — |
+| `--allow-destructive` | Opt-in: test destructive controls/endpoints (delete/pay/logout/checkout) — can mutate real data | — |
 | `--repro` | Minimize (ddmin) → emit Playwright spec → validate flake rate | — |
 | `--heal` | Generate + verify a fix (implies `--repro`) | — |
 | `--fix` | Find → explain → heal → apply — the one-command fix (free for null/undefined derefs) | — |
+| `--magic-fix` | Hidden alias for `--fix` (deprecated) | — |
 | `--explain` | Print a human-language summary of the findings | — |
 | `--yes` / `-y` | Auto-apply verified fixes without prompting (with `--fix`) | — |
 | `--pr` | Open a merge-ready PR with the verified fixes (with `--fix`) | — |
@@ -150,10 +184,10 @@ niche tuning knobs).
 | `--max-actions <n>` | Max actions per pass | `100` |
 | `--seed <n>` | PRNG seed for deterministic fuzz | `42` |
 | `--workers <n>` | Number of parallel detection workers | `1` |
-| `--swarm` | Hidden alias for `--workers auto` | — |
+| `--swarm` | Auto-size the swarm to CPU cores (capped at 8) | — |
 | `--repro-runs <n>` | Flake-rate replay iterations | `3` |
 | `--heal-model <model>` | Fallback LLM tier | `claude-sonnet-5` / `$AZTRX_MODEL` |
-| `--heal-fast-model <model>` | Fast/cheap first tier | `claude-haiku-4-5` / `$AZTRX_FAST_MODEL` |
+| `--heal-fast-model <model>` | Fast/cheap first tier | `claude-haiku-4-5-20251001` / `$AZTRX_FAST_MODEL` |
 | `--test-command <cmd>` | Test command run against a healed patch | `npm test` (auto-detected) |
 | `--test-timeout <ms>` | Timeout for the heal test gate | `300000` |
 | `--no-test` | Skip the test gate during healing | — |
@@ -166,7 +200,11 @@ niche tuning knobs).
 | `--repo <path>` | Root path for sourcemap → source resolution | cwd |
 | `--allow-host <host>` | Add a host to the network allow-list (repeatable) | — |
 | `--storage-state <path>` | Playwright storage-state for authenticated pages | — |
+| `--auth <path>` | Hidden alias for `--storage-state` | — |
 | `--login` | Auto-login before the pass (needs `AZTRX_AUTH_EMAIL`/`AZTRX_AUTH_PASSWORD`) | — |
+| `--login-email <email>` | Email for `--login` (default: `$AZTRX_AUTH_EMAIL`) | — |
+| `--login-password <pass>` | Password for `--login` (default: `$AZTRX_AUTH_PASSWORD`) | — |
+| `--login-url <url>` | Explicit login page URL for `--login` (default: current page) | — |
 | `--fail-on` | Exit `1` if any crash/error finding is present | — |
 | `--dry-run` | Log planned actions without executing them | — |
 | `--crash-test` | Throw a deliberate error to verify capture | — |
@@ -182,14 +220,34 @@ Every run writes self-contained artifacts inside `.aztrx/` (gitignored):
 .aztrx/
 ├── report.html                  # interactive triage report
 ├── repro/<id>.spec.ts           # minimal, executable Playwright repro
-├── heal/fix.patch               # gated, compiler-checked fix
+├── heal/<id>.patch              # gated, compiler-checked fix (one per finding)
 ├── events.jsonl                 # run log (streamed by `aztrx-cli studio`)
+├── patrol.json                  # patrol cross-run memory (handled fingerprints)
 ├── pr-comment.md                # GitHub PR markdown (with --pr-comment)
 └── badge.svg                    # status badge (with --badge)
 ```
 
+`aztrx patrol` also writes a `aztrx-media/<fingerprint>.gif` recorded repro next to the
+project root — the animated proof inlined in each patrol PR body.
+
 ---
 
+## Benchmarks
+
+Aztrx is scored against two corpora — a framework-agnostic archetype baseline and a
+corpus of real **Next.js 16 App Router** apps (Turbopack, client components), each with
+one seeded runtime bug:
+
+| corpus | detection | deterministic repro |
+| --- | --- | --- |
+| 13 Next.js 16 apps | **13/13 · 100% recall** | **12/12 · 100%** |
+| 12 vanilla archetypes | **12/12 · 100% recall** | **10/11 · 91%** |
+
+Reproduce it yourself: `npm run bench` (archetypes) and `cd bench/frameworks && npm run bench`
+(Next.js corpus). Per-case results and scope notes live in
+[`bench/frameworks/RESULTS.md`](bench/frameworks/RESULTS.md) and
+[`bench/RESULTS.md`](bench/RESULTS.md).
+
 ## Contributing
 
 ```bash

package/dist/cli.js

@@ -20,6 +20,8 @@ import { applyVerifiedPatches } from "./core/heal/apply.js";
 import { openFixPr } from "./core/fixPr.js";
 import { promptYesNo, promptInput } from "./core/prompt.js";
 import { modernizeFile } from "./core/modernize.js";
+import { renderMarkdown } from "./core/renderMarkdown.js";
+import { patrol } from "./core/patrol/loop.js";
 function collect(value, prev) {
     prev.push(value);
     return prev;
@@ -147,6 +149,7 @@ program
     .addOption(opt("--fuzz", "chaos fuzzing instead of the deterministic walk (F5)", "detect"))
     .addOption(opt("--http-fuzz", "HTTP-layer mutation fuzzing — hostile requests against the target origin (F5-http)", "detect"))
     .addOption(opt("--http-fuzz-mutations", "with --http-fuzz: also send POST/PUT body mutations (default: GET-only)", "advanced"))
+    .addOption(opt("--allow-destructive", "opt-in: test destructive controls/endpoints (delete/pay/logout/checkout) — can mutate real data", "advanced"))
     .addOption(opt("--seed <n>", "RNG seed for fuzz", "advanced").default("42"))
     .addOption(opt("--workers <n>", "number of parallel detection workers (default 1)", "detect"))
     .addOption(opt("--swarm", "auto-size the swarm to the machine's CPU cores (alias: --workers auto)").hideHelp())
@@ -223,6 +226,8 @@ program
         fuzz: opts.fuzz,
         httpFuzz: opts.httpFuzz,
         httpFuzzMutations: opts.httpFuzzMutations,
+        allowDestructive: opts.allowDestructive,
+        lang: opts.lang,
         repro: opts.repro || opts.heal || magicFix,
         seed: parseInt(opts.seed, 10),
         workers,
@@ -297,7 +302,7 @@ program
     // shows the result. Never commits.
     if (magicFix || opts.explain) {
         const summary = await summarizeFindings(findings, { lang: opts.lang });
-        console.log("\n" + summary);
+        console.log("\n" + renderMarkdown(summary));
     }
     if (magicFix) {
         const healed = findings.filter((f) => f.heal?.status === "healed");
@@ -340,4 +345,59 @@ program
     }
     process.exit(0);
 });
+program
+    .command("patrol")
+    .description("autonomously re-scan the app, fix new bugs, and open a PR per bug")
+    .argument("[url]", "app to patrol (auto-detected if omitted), e.g. http://localhost:3000")
+    .configureHelp({ formatHelp })
+    .addOption(opt("--repo <path>", "project root to inspect/watch (default: cwd)", "advanced"))
+    .addOption(opt("--interval <s>", "seconds between scans", "advanced").default("600"))
+    .addOption(opt("--max-fixes <n>", "max PRs to open per session", "advanced").default("5"))
+    .addOption(opt("--max-spend <n>", "hard cap on paid LLM generations per session", "advanced"))
+    .addOption(opt("--retry-after <s>", "cooldown before an unfixed bug is retried", "advanced").default("1800"))
+    .addOption(opt("--batch", "group all fixes of a cycle into one PR", "advanced"))
+    .addOption(opt("--once", "run a single scan then exit (no loop)", "advanced"))
+    .addOption(opt("--max-actions <n>", "max actions per pass", "advanced").default("100"))
+    .addOption(opt("--fuzz", "chaos fuzzing instead of the deterministic walk", "detect"))
+    .addOption(opt("--workers <n>", "number of parallel detection workers", "detect"))
+    .addOption(opt("--lang <en|ru>", "language for the diagnosis", "advanced").default("en"))
+    .addOption(opt("--login", "auto-login before each pass", "auth"))
+    .addOption(opt("--storage-state <path>", "Playwright storage-state JSON for authenticated pages", "auth"))
+    .addOption(opt("--heal-model <model>", "LLM model for healing (default: claude-sonnet-5)", "advanced"))
+    .addOption(opt("--test-command <cmd>", "test command run against a healed patch", "advanced"))
+    .addOption(opt("--no-test", "skip the test gate during healing", "advanced"))
+    .addOption(opt("--start-command <cmd>", "command to boot the app for server healing", "advanced"))
+    .action(async (url, opts) => {
+    const repoRoot = path.resolve(opts.repo ?? program.opts().repo);
+    let targetUrl = url;
+    if (!targetUrl) {
+        targetUrl = await detectUrl(repoRoot);
+        if (!targetUrl) {
+            console.error(pc.red("No URL given and none auto-detected. Pass <url>, or run `aztrx-cli init` first."));
+            process.exit(1);
+        }
+        console.log(pc.dim(`Auto-detected ${targetUrl}`));
+    }
+    await patrol({
+        url: targetUrl,
+        repoRoot,
+        intervalMs: parseInt(opts.interval, 10) * 1000,
+        maxFixes: parseInt(opts.maxFixes, 10),
+        maxSpend: opts.maxSpend ? parseInt(opts.maxSpend, 10) : undefined,
+        retryAfterMs: parseInt(opts.retryAfter, 10) * 1000,
+        batch: Boolean(opts.batch),
+        once: Boolean(opts.once),
+        maxActions: parseInt(opts.maxActions, 10),
+        fuzz: opts.fuzz,
+        workers: opts.workers ? parseInt(opts.workers, 10) : undefined,
+        lang: opts.lang,
+        login: opts.login,
+        storageState: opts.storageState,
+        healModel: opts.healModel,
+        testCommand: opts.testCommand,
+        skipTest: opts.test === false,
+        startCommand: opts.startCommand,
+    });
+    process.exit(0);
+});
 program.parseAsync();

package/dist/core/browser.js

@@ -0,0 +1,47 @@
+/**
+ * Chromium launcher with a first-run safety net. Playwright no longer downloads
+ * its browser builds on `npm install`, so a fresh `npx aztrx-cli run` would
+ * otherwise die on a bare "Executable doesn't exist". This detects that specific
+ * failure, installs the Chromium build that matches the bundled Playwright
+ * version, and retries once — keeping the zero-setup promise.
+ */
+import { spawn } from "child_process";
+import { createRequire } from "module";
+import path from "path";
+import pc from "picocolors";
+import { chromium } from "playwright";
+const require = createRequire(import.meta.url);
+/** True when the driver can't find its browser build (the "run playwright install" case). */
+function isMissingBrowser(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return /Executable doesn't exist|playwright install/i.test(msg);
+}
+/** Install the Chromium build that matches the bundled Playwright version. */
+function installChromium() {
+    const pkgPath = require.resolve("playwright/package.json");
+    const cli = path.join(path.dirname(pkgPath), "cli.js");
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [cli, "install", "chromium"], {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        // Route progress to stderr so it never corrupts the Ink TUI on stdout.
+        child.stdout?.on("data", (d) => process.stderr.write(d));
+        child.stderr?.on("data", (d) => process.stderr.write(d));
+        child.on("error", reject);
+        child.on("close", (code) => code === 0 ? resolve() : reject(new Error(`playwright install exited ${code}`)));
+    });
+}
+/** Launch Chromium headlessly, installing its browser build first when absent. */
+export async function launchChromium(options = {}) {
+    const launch = () => chromium.launch({ headless: true, ...options });
+    try {
+        return await launch();
+    }
+    catch (err) {
+        if (!isMissingBrowser(err))
+            throw err;
+        process.stderr.write(pc.dim("First run: downloading the Chromium browser (~150 MB)…\n"));
+        await installChromium();
+        return await launch();
+    }
+}

package/dist/core/classifier.js

@@ -44,11 +44,14 @@ function normalize(message) {
         .replace(/0x[0-9a-f]+/gi, "<HEX>")
         .replace(/\s+/g, " ");
 }
+// Frame URLs in a V8 stack. `http(s)://` covers normal bundles; `about://React/Server/`
+// is Next.js's client-side render of a Server Action throw site, whose URL encodes
+// the compiled Turbopack chunk. Both carry a trailing `:line:col`.
+const FRAME_URL_RE = /(?:https?:\/\/|about:\/\/React\/Server\/)[^\s)"']+?:\d+:\d+/g;
 function extractFrameUrls(stack) {
     const urls = [];
-    const re = /https?:\/\/[^\s)"']+?:\d+:\d+/g;
     let m;
-    while ((m = re.exec(stack)) !== null)
+    while ((m = FRAME_URL_RE.exec(stack)) !== null)
         urls.push(m[0]);
     return urls;
 }
@@ -70,6 +73,46 @@ export function fingerprintOf(payload) {
     const key = `${payload.type}|${normalize(payload.rawMessage)}|${own.join("|")}`;
     return createHash("sha1").update(key).digest("hex").slice(0, 12);
 }
+/** Pull the resource URL out of a network finding's message ("HTTP 500 <url>"
+ * or "Request failed: <url> (...)"). Fragment is stripped; the URL is the root
+ * cause's identity, not its fragment. */
+function extractUrlFromMessage(msg) {
+    const m = msg.match(/https?:\/\/[^\s)"']+/);
+    return m ? m[0].split("#")[0] : null;
+}
+/**
+ * Cross-signal root-cause key. Distinct capture paths for the SAME fault
+ * collapse onto one key even though their `type` differs:
+ *
+ *   - a thrown JS error surfaces via `pageerror` (`uncaught_exception`) AND the
+ *     forwarded `unhandledrejection` hook (`unhandled_rejection`) → keyed by the
+ *     type-independent fingerprint (normalized message + own frames). The
+ *     leading `Error:` prefix is normalized away, so the two channels match.
+ *   - a failed request surfaces via `response` (`network_5xx`), `requestfailed`
+ *     (`network_timeout`), and the console's "Failed to load resource"
+ *     (`console_error`) → keyed by the resource URL (for `console_error`, the
+ *     URL is `msg.location().url`, the failed resource).
+ *
+ * Falls back to the exact fingerprint when no cross-signal rule applies, so a
+ * finding with no natural group still dedups only against itself.
+ */
+export function rootKeyOf(payload) {
+    if (payload.type === "uncaught_exception" || payload.type === "unhandled_rejection") {
+        const frames = extractFrameUrls(payload.rawStack);
+        const own = frames.filter((f) => !isDepFrame(f)).slice(0, 3).map(stripPos);
+        return `throw:${normalize(payload.rawMessage)}|${own.join("|")}`;
+    }
+    if (payload.type === "network_5xx" || payload.type === "network_timeout") {
+        const url = extractUrlFromMessage(payload.rawMessage);
+        if (url)
+            return `net:${url}`;
+    }
+    else if (payload.type === "console_error" && /Failed to load resource/i.test(payload.rawMessage)) {
+        if (payload.url)
+            return `net:${payload.url.split("#")[0]}`;
+    }
+    return fingerprintOf(payload);
+}
 function classifySeverity(payload, isOwnCode) {
     if (DEV_TOOLING_NOISE.some((n) => payload.rawMessage.includes(n)))
         return "noise";
@@ -113,6 +156,7 @@ export class SignalClassifier {
         const finding = {
             id: fingerprint,
             fingerprint,
+            rootKey: rootKeyOf(payload),
             occurrences: 1,
             severity: classifySeverity(payload, isOwnCode),
             type: payload.type,
@@ -128,6 +172,52 @@ export class SignalClassifier {
         return [...this.seen.values()].filter((f) => f.severity !== "noise");
     }
 }
+const SEVERITY_RANK = { crash: 3, error: 2, warning: 1, noise: 0 };
+/** The richer of two findings: higher severity wins; ties break toward an
+ * own-code source location, then the longer action history. */
+function richer(a, b) {
+    if (SEVERITY_RANK[a.severity] !== SEVERITY_RANK[b.severity]) {
+        return SEVERITY_RANK[a.severity] > SEVERITY_RANK[b.severity] ? a : b;
+    }
+    const aOwn = a.mappedLocation?.isOwnCode === true;
+    const bOwn = b.mappedLocation?.isOwnCode === true;
+    if (aOwn !== bOwn)
+        return aOwn ? a : b;
+    return a.actionHistory.length >= b.actionHistory.length ? a : b;
+}
+/**
+ * Collapse findings that share a root cause across capture paths into a single
+ * finding. Runs after fingerprint dedup + worker merge; groups by `rootKey`,
+ * keeps the richest representative, and sums occurrences. Safe by construction:
+ * the key only groups paths that are the same underlying fault (the same thrown
+ * error, or the same failing URL), never distinct bugs.
+ */
+export function collapseSignals(findings) {
+    const groups = new Map();
+    for (const f of findings) {
+        const key = f.rootKey ?? f.fingerprint;
+        const existing = groups.get(key);
+        if (!existing) {
+            groups.set(key, { ...f, actionHistory: [...f.actionHistory] });
+            continue;
+        }
+        const winner = richer(existing, f);
+        const merged = {
+            ...winner,
+            occurrences: existing.occurrences + f.occurrences,
+            actionHistory: existing.actionHistory.length >= f.actionHistory.length
+                ? existing.actionHistory
+                : f.actionHistory,
+            rawStack: (existing.rawStack?.length ?? 0) >= (f.rawStack?.length ?? 0)
+                ? existing.rawStack
+                : f.rawStack,
+            mappedLocation: existing.mappedLocation ?? f.mappedLocation,
+            serverError: existing.serverError ?? f.serverError,
+        };
+        groups.set(key, merged);
+    }
+    return [...groups.values()];
+}
 export async function loadBaseline(repoRoot) {
     const p = path.join(repoRoot, ".aztrx", "baseline.json");
     try {

package/dist/core/diagnose.js

@@ -0,0 +1,91 @@
+/**
+ * F14 — the per-finding "diagnosis headline": one sentence that says *why* a
+ * crash happened and *what to change*, rendered inline with every crash/error
+ * finding (terminal + report.html) on the free, no-key tier.
+ *
+ * It is deliberately deterministic — keyed on the V8 message shape — so it
+ * needs no network round-trip and can never fail the run. The suggested fix
+ * mirrors what `--fix` actually applies (optional chaining for null/undefined
+ * derefs), so the headline never over-promises a fix it can't deliver.
+ */
+function normalizeLang(lang) {
+    return lang === "ru" ? "ru" : "en";
+}
+const PHRASES = {
+    en: {
+        deref: (n, p) => `the value before \`.${p}\` is ${n} — guard with \`?.\` or a default`,
+        toFixed: `you're calling \`.toFixed()\` on a string, not a number — wrap it in \`Number()\` first`,
+        notAFunction: `a method was called on a value of the wrong type — check it's the object you expect`,
+        notDefined: `a variable is referenced before it's defined — check the name, scope, or import`,
+        notConstructor: `\`new\` was called on a non-constructor — check the export/import`,
+        notIterable: `you're iterating (spread/for..of) over a non-iterable — coerce it to an array first`,
+        jsonParse: `\`JSON.parse\` got malformed input — wrap in try/catch or validate the payload first`,
+        recursion: `unbounded recursion — add a base case or guard the recursive call`,
+        server5xx: `the server returned 5xx on this route — read the server stack and fix the handler`,
+        timeout: `the request hung past the timeout — check for a slow/deadlocked handler or a missing \`await\``,
+        unhandledRejection: `a promise rejected with nothing catching it — add \`.catch()\` or \`await\` inside try/catch`,
+        uncaught: `an uncaught error escaped — wrap in try/catch or guard the input`,
+    },
+    ru: {
+        deref: (n, p) => `значение перед \`.${p}\` равно ${n} — обезопась через \`?.\` или значение по умолчанию`,
+        toFixed: `ты зовёшь \`.toFixed()\` на строке, а не на числе — оберни в \`Number()\` сначала`,
+        notAFunction: `метод вызван на значении неверного типа — проверь, что это тот объект, который ты ждёшь`,
+        notDefined: `переменная используется до определения — проверь имя, область видимости или импорт`,
+        notConstructor: `\`new\` вызван на не-конструкторе — проверь экспорт/импорт`,
+        notIterable: `ты итерируешь (spread/for..of) не-итерируемое — сначала приведи к массиву`,
+        jsonParse: `\`JSON.parse\` получил битый ввод — оберни в try/catch или сначала провалидируй`,
+        recursion: `бесконечная рекурсия — добавь базовый случай или ограничь рекурсивный вызов`,
+        server5xx: `сервер вернул 5xx на этом маршруте — смотри серверный стек и чини обработчик`,
+        timeout: `запрос завис дольше таймаута — проверь на медленный/мёртвый обработчик или пропущенный \`await\``,
+        unhandledRejection: `промис отклонился, а ловить некому — добавь \`.catch()\` или \`await\` в try/catch`,
+        uncaught: `непойманная ошибка вырвалась — оберни в try/catch или проверь входные данные`,
+    },
+};
+/** Match the two V8 null/undefined-deref shapes (modern and legacy) and return
+ * the normalized nullish value + the property being read. */
+function matchDeref(line) {
+    let m = /cannot read properties of (undefined|null) \(reading '([^']*)'\)/i.exec(line);
+    if (m)
+        return { nullish: m[1].toLowerCase(), prop: m[2] };
+    m = /cannot read property '([^']*)' of (undefined|null)/i.exec(line);
+    if (m)
+        return { nullish: m[2].toLowerCase(), prop: m[1] };
+    return null;
+}
+/**
+ * One-line diagnosis for a finding, or "" when there is nothing actionable to
+ * say (noise, or a shape we don't recognize). Crash/error findings only — the
+ * headline is advice, and triaged-away noise deserves none.
+ */
+export function diagnoseFinding(f, lang) {
+    if (f.severity !== "crash" && f.severity !== "error")
+        return "";
+    const p = PHRASES[normalizeLang(lang)];
+    const line = (f.rawMessage || "").split("\n")[0].trim();
+    const deref = matchDeref(line);
+    if (deref)
+        return p.deref(deref.nullish, deref.prop);
+    if (/\.toFixed\s*is not a function/i.test(line))
+        return p.toFixed;
+    if (/\bis not a function\b/i.test(line))
+        return p.notAFunction;
+    if (/\bis not defined\b/i.test(line))
+        return p.notDefined;
+    if (/\bis not a constructor\b/i.test(line))
+        return p.notConstructor;
+    if (/\bis not iterable\b/i.test(line))
+        return p.notIterable;
+    if (/not valid json|unexpected token|unexpected end of json|\bjson\.parse\b/i.test(line))
+        return p.jsonParse;
+    if (/maximum call stack size exceeded/i.test(line))
+        return p.recursion;
+    if (f.type === "network_5xx")
+        return p.server5xx;
+    if (f.type === "network_timeout")
+        return p.timeout;
+    if (f.type === "unhandled_rejection")
+        return p.unhandledRejection;
+    if (f.type === "uncaught_exception")
+        return p.uncaught;
+    return "";
+}

package/dist/core/diff.js

@@ -0,0 +1,137 @@
+/**
+ * Terminal-friendly, word-level diff rendering for healed patches.
+ *
+ * The heal pipeline already computes Search & Replace hunks (`PatchHunk`). This
+ * module turns those hunks into renderable lines — green for added, red for
+ * removed, with the exact changed *words* highlighted — so the terminal can show
+ * "what changed" the way a human reads a diff (Claude-Code-style) instead of a
+ * wall of hunks. Zero dependencies: a small LCS over lines plus a
+ * common-prefix/suffix word split.
+ */
+import pc from "picocolors";
+function splitLines(s) {
+    const r = s.split("\n");
+    // `split` emits a trailing "" when the source ends in "\n"; drop one so a
+    // trailing newline doesn't surface as a phantom blank line.
+    if (r.length > 1 && r[r.length - 1] === "")
+        r.pop();
+    return r;
+}
+/** Common-prefix/suffix word split of two (similar) lines into diff tokens. */
+function wordTokens(oldLine, newLine) {
+    let i = 0;
+    const max = Math.min(oldLine.length, newLine.length);
+    while (i < max && oldLine[i] === newLine[i])
+        i++;
+    let j = 0;
+    const maxJ = Math.min(oldLine.length, newLine.length) - i;
+    while (j < maxJ && oldLine[oldLine.length - 1 - j] === newLine[newLine.length - 1 - j])
+        j++;
+    const prefix = oldLine.slice(0, i);
+    const removed = oldLine.slice(i, oldLine.length - j);
+    const added = newLine.slice(i, newLine.length - j);
+    const suffix = oldLine.slice(oldLine.length - j);
+    const del = [];
+    const add = [];
+    const push = (list, text, kind) => {
+        if (text)
+            list.push({ text, kind });
+    };
+    push(del, prefix, "ctx");
+    push(add, prefix, "ctx");
+    push(del, removed, "del");
+    push(add, added, "add");
+    push(del, suffix, "ctx");
+    push(add, suffix, "ctx");
+    return { del, add };
+}
+/**
+ * Line-level LCS diff between two texts, then word-level refinement inside each
+ * replacement block. Context (unchanged) lines are omitted — the diff shows
+ * only what changed, which is what matters for a fix review.
+ */
+export function diffText(oldText, newText) {
+    const a = splitLines(oldText);
+    const b = splitLines(newText);
+    const n = a.length;
+    const m = b.length;
+    const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+        }
+    }
+    const lines = [];
+    const delBuf = [];
+    const addBuf = [];
+    const flush = () => {
+        const k = Math.max(delBuf.length, addBuf.length);
+        for (let x = 0; x < k; x++) {
+            const delLine = delBuf[x];
+            const addLine = addBuf[x];
+            if (delLine !== undefined && addLine !== undefined) {
+                const pair = wordTokens(delLine, addLine);
+                lines.push({ type: "del", tokens: pair.del });
+                lines.push({ type: "add", tokens: pair.add });
+            }
+            else if (delLine !== undefined) {
+                // Whole line removed — line color, no background.
+                lines.push({ type: "del", tokens: [{ text: delLine, kind: "ctx" }] });
+            }
+            else if (addLine !== undefined) {
+                lines.push({ type: "add", tokens: [{ text: addLine, kind: "ctx" }] });
+            }
+        }
+        delBuf.length = 0;
+        addBuf.length = 0;
+    };
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (a[i] === b[j]) {
+            flush();
+            i++;
+            j++;
+        }
+        else if (dp[i + 1][j] >= dp[i][j + 1]) {
+            delBuf.push(a[i]);
+            i++;
+        }
+        else {
+            addBuf.push(b[j]);
+            j++;
+        }
+    }
+    while (i < n)
+        delBuf.push(a[i++]);
+    while (j < m)
+        addBuf.push(b[j++]);
+    flush();
+    return lines;
+}
+/** One group of diff lines per hunk (renderers space the groups apart). */
+export function diffHunks(hunks) {
+    return hunks.map((h) => diffText(h.search, h.replace));
+}
+/** ANSI-colorized diff for the plain (non-TUI) log path. */
+export function formatDiff(hunks) {
+    return diffHunks(hunks)
+        .map((group) => group
+        .map((l) => {
+        const add = l.type === "add";
+        const lineColor = add ? pc.green : pc.red;
+        const prefix = lineColor(add ? "+" : "-");
+        const body = l.tokens
+            .map((t) => {
+            if (t.kind === "del")
+                return pc.bgRed(pc.white(t.text));
+            if (t.kind === "add")
+                return pc.bgGreen(pc.black(t.text));
+            return lineColor(t.text);
+        })
+            .join("");
+        return "    " + prefix + " " + body;
+    })
+        .join("\n"))
+        .join("\n");
+}

package/dist/core/domWalker.js

@@ -67,7 +67,7 @@ export async function walkDom(page, bus, opts = {}) {
             catch {
                 label = ""; // degraded — no label to filter on
             }
-            if (DESTRUCTIVE.test(label))
+            if (!opts.allowDestructive && DESTRUCTIVE.test(label))
                 continue;
             if (tag === "a") {
                 // Don't click links directly — queue internal ones for the crawl.

package/dist/core/fuzzer.js

@@ -125,7 +125,7 @@ export async function fuzz(page, bus, opts = {}) {
             catch {
                 label = ""; // degraded — no label to filter on
             }
-            if (DESTRUCTIVE.test(label))
+            if (!opts.allowDestructive && DESTRUCTIVE.test(label))
                 continue;
             if (tag === "a") {
                 const href = (await h.getAttribute("href")) ?? "";