aztrx-cli 0.4.5 → 0.5.2

package/dist/core/classifier.d.ts

@@ -0,0 +1,41 @@
+import type { Finding, TelemetryErrorPayload } from "./types.js";
+export declare function fingerprintOf(payload: TelemetryErrorPayload): string;
+/**
+ * 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 declare function rootKeyOf(payload: TelemetryErrorPayload): string;
+/**
+ * F3 — Signal classifier. Fingerprints, dedups, assigns severity, and
+ * suppresses a baseline of already-known fingerprints. Returns a Finding on
+ * first sight, `null` on duplicate or suppressed.
+ */
+export declare class SignalClassifier {
+    private seen;
+    private baseline;
+    constructor(baselineFingerprints?: string[]);
+    classify(payload: TelemetryErrorPayload): Finding | null;
+    /** Unique findings, noise suppressed. */
+    findings(): Finding[];
+}
+/**
+ * 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 declare function collapseSignals(findings: Finding[]): Finding[];
+export declare function loadBaseline(repoRoot: string): Promise<string[]>;

package/dist/core/cloud/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * F12 — opt-in cloud sync. Streams a completed run's findings to the Aztrx
+ * ingest API (`POST /api/runs`) for the team dashboard and server-side
+ * deduplication by crash fingerprint. Mirrors the telemetry module's contract:
+ * fire-and-forget, bounded by a short abort, and never affects the exit code.
+ * Everything is sanitized before packaging (secrets, URLs, repo paths).
+ */
+import type { Finding } from "../types.js";
+export interface CloudOptions {
+    repoRoot: string;
+    url: string;
+    /** API key presented as `x-api-key` (falls back to `AZTRX_CLOUD_API_KEY`).
+     *  Deliberately not `AZTRX_API_KEY`: that one is a *model provider*
+     *  credential (`llm.ts:29,35`), and reusing it here would put an OpenRouter or
+     *  Anthropic key on the wire as an auth header to the ingest host. */
+    apiKey?: string;
+    /** Ingest base URL, e.g. `https://api.aztrx.app` (falls back to `AZTRX_CLOUD_URL`). */
+    endpoint?: string;
+    /** Human-readable run mode, shown in the dashboard. */
+    mode: string;
+    counts: Record<string, number>;
+}
+export interface CloudFinding {
+    fingerprint: string;
+    severity: string;
+    type: string;
+    message: string;
+    location?: {
+        file: string;
+        line: number;
+        column: number;
+    };
+    repro?: {
+        verdict: string;
+        rate: number;
+        runs: number;
+        reproductions: number;
+        spec: string | null;
+    };
+    patch?: string | null;
+    model_tier?: string | null;
+}
+export interface RunPayload {
+    schema: "aztrx.run/1";
+    sentAt: string;
+    framework: string;
+    framework_version?: string;
+    target: string;
+    mode: string;
+    counts: Record<string, number>;
+    findings: CloudFinding[];
+}
+/** Fire-and-forget upload. Never rejects; bounded by a short abort. Failures are
+ * reported on stderr rather than discarded — silence here reads as success. */
+export declare function dispatchUpload(payload: RunPayload, endpoint: string, apiKey?: string): Promise<void>;
+/** Build the sanitized payload and detach an upload. A clean run (zero
+ * findings) still uploads — the dashboard tracks green runs too. */
+export declare function submitRun(findings: Finding[], opts: CloudOptions): void;
+/** Await all in-flight uploads (each already bounded). Called right before the
+ * CLI exits so a pending `--upload` isn't killed mid-flight; never affects exit
+ * code. */
+export declare function flushCloud(): Promise<void>;

package/dist/core/cloud/index.js

@@ -6,10 +6,17 @@
  * Everything is sanitized before packaging (secrets, URLs, repo paths).
  */
 import * as fs from "fs";
+import pc from "picocolors";
 import { detectFrameworkMeta } from "../init.js";
 import { createSanitizer } from "../telemetry/sanitize.js";
 const DEFAULT_CLOUD_URL = process.env.AZTRX_CLOUD_URL || "https://api.aztrx.app";
 const UPLOAD_TIMEOUT_MS = 2000;
+/** One dim line on stderr. These uploads are fire-and-forget by design, so this
+ * is the only place a failure can surface — and it has to, or an operator who
+ * asked for an upload cannot tell a success from a silent 401. */
+function warn(msg) {
+    process.stderr.write(pc.dim(`aztrx: ${msg}\n`));
+}
 /** In-flight uploads, drained by `flushCloud()` before the CLI exits. */
 const pendingUploads = [];
 function readFileIfExists(p) {
@@ -67,7 +74,8 @@ function buildPayload(findings, opts) {
         findings: cloudFindings,
     };
 }
-/** Fire-and-forget upload. Never rejects; bounded by a short abort. */
+/** Fire-and-forget upload. Never rejects; bounded by a short abort. Failures are
+ * reported on stderr rather than discarded — silence here reads as success. */
 export function dispatchUpload(payload, endpoint, apiKey) {
     const ctrl = new AbortController();
     const timer = setTimeout(() => ctrl.abort(), UPLOAD_TIMEOUT_MS);
@@ -80,15 +88,27 @@ export function dispatchUpload(payload, endpoint, apiKey) {
         body: JSON.stringify(payload),
         signal: ctrl.signal,
     })
-        .then(() => { })
-        .catch(() => { })
+        .then((res) => {
+        // `fetch` resolves on 4xx/5xx too — only the status separates them, so a
+        // bare `.then()` here reports a rejected upload as a clean one.
+        if (!res.ok)
+            warn(`run upload rejected — HTTP ${res.status} from ${endpoint}`);
+    })
+        .catch((e) => {
+        const why = e instanceof Error && e.name === "AbortError"
+            ? `no response within ${UPLOAD_TIMEOUT_MS}ms`
+            : e instanceof Error
+                ? e.message
+                : String(e);
+        warn(`run upload failed — ${why}`);
+    })
         .finally(() => clearTimeout(timer));
 }
 /** Build the sanitized payload and detach an upload. A clean run (zero
  * findings) still uploads — the dashboard tracks green runs too. */
 export function submitRun(findings, opts) {
     const endpoint = opts.endpoint ?? DEFAULT_CLOUD_URL;
-    const apiKey = opts.apiKey ?? process.env.AZTRX_API_KEY;
+    const apiKey = opts.apiKey ?? process.env.AZTRX_CLOUD_API_KEY;
     const payload = buildPayload(findings, opts);
     pendingUploads.push(dispatchUpload(payload, endpoint, apiKey));
 }

package/dist/core/devServer.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Zero-config target resolution — what bare `aztrx` does when no URL is given.
+ *
+ * Every primitive already existed (framework detection in `init.ts`, start-command
+ * detection and process-tree booting in `heal/boot.ts`); what was missing is the
+ * orchestration that turns "I'm standing in a project directory" into a live URL.
+ * The order below is the whole design:
+ *
+ *   1. a dev server already running — declared in `aztrx.config.ts`, named by the
+ *      dev script's `--port`, or sitting on the port this project's framework
+ *      uses — is *attached* to, never killed, because we did not start it
+ *   2. otherwise the project's own dev script is booted and killed on exit
+ *   3. otherwise the caller gets `ok: false` and prints the pass-a-URL error
+ *
+ * Only a project we could not identify at all (no dev script, unknown framework)
+ * falls back to sweeping the usual ports for a stranger — attaching to the wrong
+ * app would report someone else's crashes as yours.
+ *
+ * Booting the user's app is a bigger liberty than attaching to one, which is why
+ * it is opt-out (`--no-boot`) and why the booted child inherits the real
+ * environment: it is their machine and their app, and a stripped env would break
+ * anything reading `DATABASE_URL`.
+ */
+/** A port hardcoded in the dev script (`vite --port 4000`). It beats the
+ * framework default: the script wins over `PORT`, so booting on anything else
+ * would leave us polling a port nothing ever binds. */
+export declare function scriptPort(repoRoot: string): number | undefined;
+/** The `allowHosts` entries from a generated `aztrx.config.ts`.
+ *
+ * `init` scaffolds this key and tells the user to add their API host to it, so
+ * it has to actually do something — otherwise following the tool's own
+ * instructions changes nothing, and a real app's cross-origin API calls stay
+ * refused with no visible reason. Genuinely deny-by-default either way: this
+ * only extends the allow-list, and an unparseable value extends it by nothing. */
+export declare function configAllowHosts(repoRoot: string): string[];
+/** The `maxActions` value from a generated `aztrx.config.ts`, when present. */
+export declare function configMaxActions(repoRoot: string): number | undefined;
+/** Poll until the URL answers with any HTTP response (2xx/4xx/5xx all mean the
+ * listener is up and serving). */
+export declare function waitForHttp(url: string, timeoutMs: number): Promise<boolean>;
+export interface BootPlan {
+    framework: string;
+    startCommand: string;
+    /** Port to *ask* for. `bootServer` honours it only when it is genuinely free. */
+    port: number;
+}
+/** The pure decision at the heart of zero-config: which framework, which command,
+ * which port. Null when the project has no `dev`/`start` script — nothing to boot. */
+export declare function planBoot(repoRoot: string): BootPlan | null;
+/** Find a dev server that is already running, so we can attach instead of booting.
+ *
+ * Declared URLs come first — they are the user's stated intent — then the port
+ * this project's own framework listens on. The port check keys off *a listener
+ * existing* rather than off an HTTP response, because a server that has bound
+ * its port but is still compiling answers nothing yet.
+ *
+ * The generic sweep of common ports runs **only when we could not work out what
+ * this project is** (`plan === null`). That restriction matters: sweeping always
+ * would let a Vite project happily attach to whatever unrelated app happens to
+ * be sitting on 3000 and report a stranger's crashes as its own. A known project
+ * that is not running should be booted, not confused with its neighbour. */
+export declare function findRunning(repoRoot: string, plan: BootPlan | null): Promise<string | null>;
+export type TargetSource = "attached" | "booted";
+export interface ResolvedTarget {
+    url: string;
+    source: TargetSource;
+    /** One line for the user explaining how we got here. */
+    detail: string;
+    /** Idempotent. A no-op when we attached — we never kill a server we didn't start. */
+    close: () => Promise<void>;
+}
+export type TargetResolution = ({
+    ok: true;
+} & ResolvedTarget) | {
+    ok: false;
+    error: string;
+};
+/**
+ * Turn "no URL was given" into a live target: attach to a running server, or
+ * boot one. Never throws — a boot failure comes back as `{ ok: false, error }`
+ * carrying the server's own log tail, which is far more useful than a rejection.
+ */
+export declare function resolveTarget(opts: {
+    repoRoot: string;
+    /** false = attach only, never spawn (`--no-boot`). */
+    allowBoot: boolean;
+    /** Called just before a server is spawned — booting can take up to a minute,
+     * so the user should see why nothing is happening yet. */
+    onBoot?: (plan: BootPlan) => void;
+}): Promise<TargetResolution>;

package/dist/core/devServer.js

@@ -0,0 +1,253 @@
+/**
+ * Zero-config target resolution — what bare `aztrx` does when no URL is given.
+ *
+ * Every primitive already existed (framework detection in `init.ts`, start-command
+ * detection and process-tree booting in `heal/boot.ts`); what was missing is the
+ * orchestration that turns "I'm standing in a project directory" into a live URL.
+ * The order below is the whole design:
+ *
+ *   1. a dev server already running — declared in `aztrx.config.ts`, named by the
+ *      dev script's `--port`, or sitting on the port this project's framework
+ *      uses — is *attached* to, never killed, because we did not start it
+ *   2. otherwise the project's own dev script is booted and killed on exit
+ *   3. otherwise the caller gets `ok: false` and prints the pass-a-URL error
+ *
+ * Only a project we could not identify at all (no dev script, unknown framework)
+ * falls back to sweeping the usual ports for a stranger — attaching to the wrong
+ * app would report someone else's crashes as yours.
+ *
+ * Booting the user's app is a bigger liberty than attaching to one, which is why
+ * it is opt-out (`--no-boot`) and why the booted child inherits the real
+ * environment: it is their machine and their app, and a stripped env would break
+ * anything reading `DATABASE_URL`.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { defaultPort, detectFrameworkMeta } from "./init.js";
+import { bootServer, detectStartCommand, isPortFree } from "./heal/boot.js";
+/** Ports scanned for an already-running app, most common first. */
+const PROBE_PORTS = [3000, 5173, 8080, 3001, 4000, 8000];
+/** How long to wait for a detected server to answer HTTP. Generous on purpose:
+ * a cold Next.js or Vite server binds its port long before it can serve, and
+ * giving up early would boot a *second* server on top of the user's. */
+const ATTACH_TIMEOUT_MS = 15_000;
+/** Boot can legitimately take a while (dependency scan, cold compile). */
+const BOOT_TIMEOUT_MS = 90_000;
+function readDevScript(repoRoot) {
+    try {
+        const raw = fs.readFileSync(path.join(repoRoot, "package.json"), "utf-8");
+        const s = JSON.parse(raw).scripts;
+        if (!s)
+            return "";
+        if (typeof s.dev === "string")
+            return s.dev;
+        if (typeof s.start === "string")
+            return s.start;
+    }
+    catch {
+        // no package.json, or unparseable — the caller falls through
+    }
+    return "";
+}
+/** A port hardcoded in the dev script (`vite --port 4000`). It beats the
+ * framework default: the script wins over `PORT`, so booting on anything else
+ * would leave us polling a port nothing ever binds. */
+export function scriptPort(repoRoot) {
+    const m = readDevScript(repoRoot).match(/(?:--port|-p)\s*[= ]?\s*(\d+)/);
+    return m ? parseInt(m[1], 10) : undefined;
+}
+/** The raw text of a generated `aztrx.config.ts`, or undefined when there is
+ * none. Read as text rather than imported — the config is an untrusted
+ * TypeScript file, not something to execute just to read a value out of.
+ *
+ * Every reader below goes through this, so the file is read once per question
+ * and they cannot drift into parsing different files. */
+function readConfig(repoRoot) {
+    const configPath = path.join(repoRoot, "aztrx.config.ts");
+    if (!fs.existsSync(configPath))
+        return undefined;
+    try {
+        return fs.readFileSync(configPath, "utf-8");
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The URL a generated `aztrx.config.ts` declares. */
+function configUrl(repoRoot) {
+    const m = readConfig(repoRoot)?.match(/url\s*[=:]\s*["']([^"']+)["']/);
+    return m ? m[1] : undefined;
+}
+/** The `allowHosts` entries from a generated `aztrx.config.ts`.
+ *
+ * `init` scaffolds this key and tells the user to add their API host to it, so
+ * it has to actually do something — otherwise following the tool's own
+ * instructions changes nothing, and a real app's cross-origin API calls stay
+ * refused with no visible reason. Genuinely deny-by-default either way: this
+ * only extends the allow-list, and an unparseable value extends it by nothing. */
+export function configAllowHosts(repoRoot) {
+    const m = readConfig(repoRoot)?.match(/allowHosts\s*[=:]\s*\[([^\]]*)\]/);
+    if (!m)
+        return [];
+    return [...m[1].matchAll(/["'`]([^"'`]+)["'`]/g)].map((x) => x[1]);
+}
+/** The `maxActions` value from a generated `aztrx.config.ts`, when present. */
+export function configMaxActions(repoRoot) {
+    const m = readConfig(repoRoot)?.match(/maxActions\s*[=:]\s*(\d+)/);
+    if (!m)
+        return undefined;
+    const n = parseInt(m[1], 10);
+    return Number.isFinite(n) ? n : undefined;
+}
+/** The port a declared URL points at, or null when the host isn't loopback —
+ * a remote app's liveness can't be checked with a local connect. */
+function loopbackPort(url) {
+    try {
+        const u = new URL(url);
+        if (!["localhost", "127.0.0.1", "::1", "0.0.0.0"].includes(u.hostname))
+            return null;
+        if (u.port)
+            return parseInt(u.port, 10);
+        if (u.protocol === "https:")
+            return 443;
+        if (u.protocol === "http:")
+            return 80;
+    }
+    catch {
+        // not a URL at all — treat it as remote/unprobeable
+    }
+    return null;
+}
+/** Poll until the URL answers with any HTTP response (2xx/4xx/5xx all mean the
+ * listener is up and serving). */
+export async function waitForHttp(url, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            const res = await fetch(url, { signal: AbortSignal.timeout(2000) });
+            await res.arrayBuffer().catch(() => { });
+            return true;
+        }
+        catch {
+            if (Date.now() >= deadline)
+                return false;
+            await new Promise((r) => setTimeout(r, 400));
+        }
+    }
+}
+/** The pure decision at the heart of zero-config: which framework, which command,
+ * which port. Null when the project has no `dev`/`start` script — nothing to boot. */
+export function planBoot(repoRoot) {
+    const startCommand = detectStartCommand(repoRoot);
+    if (!startCommand)
+        return null;
+    const { framework } = detectFrameworkMeta(repoRoot);
+    return {
+        framework,
+        startCommand,
+        port: scriptPort(repoRoot) ?? defaultPort(framework),
+    };
+}
+/** Find a dev server that is already running, so we can attach instead of booting.
+ *
+ * Declared URLs come first — they are the user's stated intent — then the port
+ * this project's own framework listens on. The port check keys off *a listener
+ * existing* rather than off an HTTP response, because a server that has bound
+ * its port but is still compiling answers nothing yet.
+ *
+ * The generic sweep of common ports runs **only when we could not work out what
+ * this project is** (`plan === null`). That restriction matters: sweeping always
+ * would let a Vite project happily attach to whatever unrelated app happens to
+ * be sitting on 3000 and report a stranger's crashes as its own. A known project
+ * that is not running should be booted, not confused with its neighbour. */
+export async function findRunning(repoRoot, plan) {
+    const sp = scriptPort(repoRoot);
+    const declared = [configUrl(repoRoot), sp ? `http://localhost:${sp}` : undefined].filter((u) => Boolean(u));
+    for (const url of declared) {
+        const port = loopbackPort(url);
+        // A declared URL whose port has no listener is simply stale. Don't make the
+        // user sit out the readiness timeout to learn that — go straight to booting.
+        if (port !== null && (await isPortFree(port)))
+            continue;
+        if (await waitForHttp(url, ATTACH_TIMEOUT_MS))
+            return url;
+    }
+    if (plan) {
+        const url = `http://127.0.0.1:${plan.port}`;
+        if (!(await isPortFree(plan.port)) && (await waitForHttp(url, ATTACH_TIMEOUT_MS)))
+            return url;
+        return null; // not up — the caller boots it
+    }
+    for (const port of PROBE_PORTS) {
+        if (await isPortFree(port))
+            continue;
+        const url = `http://localhost:${port}`;
+        if (await waitForHttp(url, ATTACH_TIMEOUT_MS))
+            return url;
+    }
+    return null;
+}
+/** Booting means this process now owns a child dev server, so it also owns
+ * killing it. `close` is idempotent, so a signal racing the normal exit path is
+ * harmless. Only the booted path arms this — an attached server is not ours. */
+function armSignalCleanup(close) {
+    const shutdown = (code) => {
+        void Promise.resolve(close()).finally(() => process.exit(code));
+    };
+    process.once("SIGINT", () => shutdown(130));
+    process.once("SIGTERM", () => shutdown(143));
+}
+/**
+ * Turn "no URL was given" into a live target: attach to a running server, or
+ * boot one. Never throws — a boot failure comes back as `{ ok: false, error }`
+ * carrying the server's own log tail, which is far more useful than a rejection.
+ */
+export async function resolveTarget(opts) {
+    const { repoRoot, allowBoot } = opts;
+    const plan = planBoot(repoRoot);
+    const running = await findRunning(repoRoot, plan);
+    if (running) {
+        return {
+            ok: true,
+            url: running,
+            source: "attached",
+            detail: `Auto-detected ${running} — attaching (nothing started by Aztrx will be stopped).`,
+            close: async () => { },
+        };
+    }
+    if (!allowBoot) {
+        const hint = plan
+            ? `Start it yourself, or drop --no-boot to have Aztrx boot \`${plan.startCommand}\`.`
+            : "Start it yourself, or pass the URL explicitly.";
+        return { ok: false, error: `No dev server is running. ${hint}` };
+    }
+    if (!plan) {
+        return {
+            ok: false,
+            error: "No dev server is running and package.json has no `dev` or `start` script to boot. Pass <url>, or run `aztrx-cli init` first.",
+        };
+    }
+    opts.onBoot?.(plan);
+    try {
+        const server = await bootServer({
+            worktreeDir: repoRoot,
+            repoRoot,
+            startCommand: plan.startCommand,
+            timeoutMs: BOOT_TIMEOUT_MS,
+            port: plan.port,
+            // The user's own app, on the user's own machine — it gets the real env.
+            env: "inherit",
+        });
+        armSignalCleanup(server.close);
+        return {
+            ok: true,
+            url: server.url,
+            source: "booted",
+            detail: `Up at ${server.url} — it stops when Aztrx exits.`,
+            close: server.close,
+        };
+    }
+    catch (e) {
+        return { ok: false, error: `Could not start \`${plan.startCommand}\`: ${e.message}` };
+    }
+}

package/dist/core/diagnose.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+import type { Finding } from "./types.js";
+export type Lang = "en" | "ru";
+/**
+ * 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 declare function diagnoseFinding(f: Finding, lang?: string): string;

package/dist/core/diff.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 type { PatchHunk } from "./heal/types.js";
+/** Render-oriented token kind. `ctx` = no highlight (line color only). */
+export type DiffTokenKind = "ctx" | "del" | "add";
+export interface DiffToken {
+    text: string;
+    kind: DiffTokenKind;
+}
+export interface DiffLine {
+    type: "del" | "add";
+    tokens: DiffToken[];
+}
+/**
+ * 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 declare function diffText(oldText: string, newText: string): DiffLine[];
+/** One group of diff lines per hunk (renderers space the groups apart). */
+export declare function diffHunks(hunks: PatchHunk[]): DiffLine[][];
+/** ANSI-colorized diff for the plain (non-TUI) log path. */
+export declare function formatDiff(hunks: PatchHunk[]): string;

package/dist/core/domWalker.d.ts

@@ -0,0 +1,24 @@
+import type { Page } from "playwright";
+import type { EventBus } from "./eventBus.js";
+export declare const DESTRUCTIVE: RegExp;
+export declare const TEXT_INPUT_TYPES: Set<string>;
+export declare const SELECTOR = "a, button, input, select, textarea, [role=\"button\"], [onclick]";
+export interface WalkOptions {
+    maxActions?: number;
+    dryRun?: boolean;
+    /** Opt-in: include controls the deny-list skips (delete/pay/logout/checkout…).
+     * Off by default — these can mutate real state, so they're refused unless the
+     * caller explicitly accepts the risk. */
+    allowDestructive?: boolean;
+}
+/**
+ * F5-lite — discover interactive elements and act on them, tripping runtime
+ * errors for the interceptor to catch. This is the deterministic "walk every
+ * button" seed of the Chaos Fuzzer; rage-clicks, form fuzzing, and network
+ * jitter come next.
+ */
+export declare function walkDom(page: Page, bus: EventBus, opts?: WalkOptions): Promise<{
+    actions: number;
+    sawLoginForm: boolean;
+}>;
+export declare function originOf(url: string): string;

package/dist/core/domWalker.js

@@ -26,7 +26,7 @@ export async function walkDom(page, bus, opts = {}) {
         if (visited.has(url))
             continue;
         visited.add(url);
-        if (page.url() !== url) {
+        if (!samePage(page.url(), url)) {
             await page.goto(url, { waitUntil: "domcontentloaded" }).catch(() => { });
             await page.waitForTimeout(300);
         }
@@ -92,7 +92,7 @@ export async function walkDom(page, bus, opts = {}) {
                 if (!TEXT_INPUT_TYPES.has(type))
                     continue; // skip password/hidden/submit/checkbox/etc.
             }
-            const selectors = await selectorCascade(page, handle);
+            const selectors = await selectorCascade(handle);
             const signature = selectors.join("|") || `${tag}:${label}`;
             if (seen.has(signature))
                 continue; // already acted on this element
@@ -130,3 +130,19 @@ export async function walkDom(page, bus, opts = {}) {
 export function originOf(url) {
     return url.match(/^https?:\/\/[^/]+/)?.[0] ?? "";
 }
+/**
+ * Are these two strings the same page? Compared as parsed URLs, not as text,
+ * because the browser normalises what the crawler was handed: a run against
+ * `http://localhost:3000` has `page.url() === "http://localhost:3000/"`, so a
+ * raw string compare says "different" and the walk re-loads the start page it
+ * is already sitting on — once per run, re-firing every mount effect for
+ * nothing. `new URL(x).href` puts both sides in the browser's own spelling.
+ */
+function samePage(current, target) {
+    try {
+        return new URL(current).href === new URL(target).href;
+    }
+    catch {
+        return current === target; // about:blank, or an unparseable href
+    }
+}