aztrx-cli 0.4.4 → 0.5.1

package/dist/core/orchestrator.js

@@ -72,6 +72,14 @@ export async function run(options) {
         if (!ui)
             console.log(parts.join(" "));
     };
+    // Important hints/warnings (destructive mode, login-wall, wrong --repo) must be
+    // visible in the TUI too — `say` is a no-op there. Emit on the bus always, and
+    // print to stdout only in the linear (non-UI) path so it isn't duplicated.
+    const notice = (message, level = "hint") => {
+        bus.emit("notice", { message, level, ts: Date.now() });
+        if (!ui)
+            console.log(level === "danger" ? pc.red(message) : pc.yellow(message));
+    };
     const emitPhase = (phase, detail) => bus.emit("phase", { phase, detail, ts: Date.now() });
     say(pc.cyan(`\nAztrx AI v${VERSION} — Runtime Detector`));
     say(pc.dim(`Target: ${url}`));
@@ -85,8 +93,7 @@ export async function run(options) {
     if (options.storageState)
         say(pc.dim(`Auth:   ${options.storageState}`));
     if (options.allowDestructive) {
-        say(pc.yellow(pc.bold("⚠ DESTRUCTIVE MODE — delete/pay/logout/checkout controls are ENABLED.")));
-        say(pc.yellow("  This can mutate real data. Run only against a disposable/dev instance you own."));
+        notice("⚠ DESTRUCTIVE MODE — delete/pay/logout/checkout controls are ENABLED. This can mutate real data. Run only against a disposable/dev instance you own.", "danger");
     }
     say("");
     emitPhase("launch", url);
@@ -149,7 +156,7 @@ export async function run(options) {
         say(pc.dim(`\nWalked ${totalActions} action(s).\n`));
     }
     if (sawLoginForm && !options.login) {
-        say(pc.yellow("Hint: this app has a login form — re-run with --login to test the authenticated app."));
+        notice("Hint: this app has a login form — re-run with --login to test the authenticated app.", "hint");
     }
     // F7 → F8 → F9: minimize each finding, compile an executable spec, validate
     // the flake rate. Only crash/error findings with a recorded action history.
@@ -317,10 +324,15 @@ export async function run(options) {
             }
         }
         else if (candidates.length > 0) {
-            // Reproducible crashes, but none mapped to source (wrong --repo?) — tell the
-            // user rather than silently doing nothing. Already-handled fingerprints are
-            // excluded above, so this only fires for genuinely new findings.
-            say(pc.yellow(`Found ${candidates.length} reproducible crash(es) but couldn't map them to source files. Run from your project root (or pass --repo <dir>) so --fix can read the code.`));
+            // Reproducible crashes, but none mapped to a readable source file (wrong
+            // --repo?) — tell the user rather than silently doing nothing. Already-handled
+            // fingerprints are excluded above, so this only fires for genuinely new
+            // findings. Name the files it looked for so the hint is actionable.
+            const missing = candidates
+                .map((f) => f.mappedLocation?.filePath || f.rawMessage.split("\n")[0].slice(0, 40))
+                .filter(Boolean)
+                .slice(0, 3);
+            notice(`Found ${candidates.length} reproducible crash(es) but couldn't read their source (${missing.join(", ")}). Run from your project root (or pass --repo <dir>) so --fix can read the code.`, "warning");
         }
     }
     const reportPath = writeReport(repoRoot, url, findings, options.lang);
@@ -343,7 +355,10 @@ export async function run(options) {
     // F12 — opt-in cloud sync. Streams the sanitized run results to the ingest
     // API for the team dashboard; dedup happens server-side by fingerprint.
     if (options.upload) {
-        if (options.apiKey || process.env.AZTRX_API_KEY) {
+        // `AZTRX_CLOUD_API_KEY`, not `AZTRX_API_KEY`: the latter is a model provider
+        // credential, and treating its presence as consent to upload would put that
+        // key on the wire as the ingest auth header.
+        if (options.apiKey || process.env.AZTRX_CLOUD_API_KEY) {
             submitRun(findings, {
                 repoRoot,
                 url,
@@ -354,7 +369,7 @@ export async function run(options) {
             });
         }
         else {
-            say(pc.yellow("Upload skipped: no API key. Set --api-key or AZTRX_API_KEY to stream findings to the dashboard."));
+            say(pc.yellow("Upload skipped: no API key. Set --api-key or AZTRX_CLOUD_API_KEY to stream findings to the dashboard."));
         }
     }
     runLog.append({ type: "run_end", counts, ts: Date.now() });

package/dist/core/patrol/loop.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `aztrx patrol` — the autonomous bug-patrol loop. It wraps the existing
+ * `run()` detect → repro → heal pipeline in a supervisor loop with memory, so
+ * instead of "run it and read the output" the tool re-scans on an interval,
+ * fixes anything new, and opens a PR per bug — no human in the middle.
+ *
+ * Guardrails that keep an autonomous run from going off the rails:
+ *   - memory (PatrolState) — a handled fingerprint is never re-fixed/re-PR'd;
+ *   - per-session fix cap (`maxFixes`) — bounds LLM spend + PR spam;
+ *   - scoped staging — PRs carry only the files the patch touched;
+ *   - a liveness check — a dead target skips the cycle instead of burning a crawl.
+ */
+export interface PatrolOptions {
+    url: string;
+    repoRoot: string;
+    intervalMs: number;
+    maxFixes?: number;
+    maxActions?: number;
+    /** Hard cap on paid LLM generations across the whole session (0/undefined = unlimited). */
+    maxSpend?: number;
+    /** Cooldown before an `unfixed` fingerprint is retried, ms. Default 30 min. */
+    retryAfterMs?: number;
+    /** Group all of a cycle's fixes into one PR instead of one PR per bug. */
+    batch?: boolean;
+    once?: boolean;
+    fuzz?: boolean;
+    workers?: number;
+    allowHosts?: string[];
+    storageState?: string;
+    login?: boolean;
+    loginEmail?: string;
+    loginPassword?: string;
+    loginUrl?: string;
+    healModel?: string;
+    healFastModel?: string;
+    testCommand?: string;
+    testTimeoutMs?: number;
+    skipTest?: boolean;
+    startCommand?: string;
+    lang?: string;
+    seed?: number;
+    allowDestructive?: boolean;
+    httpFuzz?: boolean;
+    httpFuzzMutations?: boolean;
+}
+export declare function patrol(opts: PatrolOptions): Promise<void>;

package/dist/core/patrol/pr.d.ts

@@ -0,0 +1,42 @@
+/**
+ * PR opener for `aztrx patrol`. Like `fixPr.openFixPr`, but built for an
+ * autonomous loop, so it adds two things a human-driven flow doesn't need:
+ *
+ *   - **Dedup**: a fingerprint-stable branch name (`aztrx/fix-<fp8>`) plus a
+ *     `gh pr list --head` check, so a re-scan never opens a second PR for a bug
+ *     that already has one open.
+ *   - **Scoped staging**: stages only the files the patch touched (`git add --
+ *     <files>`), never `git add -A` — an autonomous run must not sweep up the
+ *     user's unrelated uncommitted work into a PR.
+ *
+ * The caller is responsible for applying patches first (`applyVerifiedPatches`).
+ */
+import type { Finding } from "../types.js";
+export interface PatrolPrResult {
+    ok: boolean;
+    skipped?: boolean;
+    url?: string;
+    branch?: string;
+    error?: string;
+}
+export declare function branchFor(fp: string): string;
+/** Stable branch name for a *set* of fingerprints — the same set always maps to
+ * the same branch, so a re-scan of an unchanged batch doesn't open a duplicate PR. */
+export declare function branchForSet(fps: string[]): string;
+/** A local/loopback/private target is a dev box; only a publicly-routable host is
+ * a deployed app, so a crash there is "live in production" and worth flagging.
+ * Covers loopback, RFC1918 private ranges (10/8, 172.16/12, 192.168/16),
+ * link-local (169.254/16), and mDNS/internal suffixes (.local, .internal). */
+export declare function isLocalUrl(url: string): boolean;
+/**
+ * Pure URL builder: turns a `git remote` origin URL into a raw-content URL for a
+ * repo-relative path, so the PR body can inline an image
+ * (`![…](https://github.com/<owner>/<repo>/raw/<branch>/<path>)`). Handles the
+ * three common remote shapes (`https://`, `git@github.com:`, `ssh://git@…`) and a
+ * trailing `.git`. Returns "" when the remote isn't GitHub.
+ */
+export declare function githubRawUrl(remote: string, branch: string, repoPath: string): string;
+export declare function openPatrolPr(repoRoot: string, finding: Finding, url: string, files: string[], mediaPath?: string | null): Promise<PatrolPrResult>;
+/** One PR carrying a whole batch of fixes. Branch is stable across the *set*, so
+ * an unchanged batch re-scan dedups to the same PR. */
+export declare function openPatrolBatchPr(repoRoot: string, findings: Finding[], url: string, files: string[], mediaPaths?: (string | null)[]): Promise<PatrolPrResult>;

package/dist/core/patrol/pr.js

@@ -144,17 +144,20 @@ async function rawUrlFor(repoRoot, branch, repoPath) {
  * files, commit, open the PR, and return to the original branch. The caller has
  * already done its own dedup + title/body. */
 async function createPr(repoRoot, branch, title, body, files) {
+    // Nothing to stage means no patch landed, so there is no fix to open a PR for.
+    // This used to fall back to `git add -A`, which would have swept the user's
+    // unrelated uncommitted work into an auto-generated commit under a "fix: …"
+    // title and pushed it. Refuse instead — and refuse before touching git, so a
+    // branch is never created for an empty fix set.
+    if (files.length === 0) {
+        return { ok: false, branch, error: "no files to stage — refusing to commit an empty fix set" };
+    }
     const originalBranch = await currentBranch(repoRoot);
     try {
         // `-B` (re)creates the branch at HEAD — idempotent against a stale local
         // branch left over from a previously failed PR attempt.
         await exec("git", ["-C", repoRoot, "checkout", "-B", branch]);
-        if (files.length) {
-            await exec("git", ["-C", repoRoot, "add", "--", ...files]);
-        }
-        else {
-            await exec("git", ["-C", repoRoot, "add", "-A"]);
-        }
+        await exec("git", ["-C", repoRoot, "add", "--", ...files]);
         await exec("git", ["-C", repoRoot, "commit", "-m", title]);
     }
     catch (e) {

package/dist/core/patrol/record.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Recorded repro (Phase 3) — turns a reproducible bug into a shareable
+ * "before/after" proof: an animated GIF and a static crash screenshot, both
+ * destined for the patrol PR body.
+ *
+ * The capture is deliberately OFF the hot path. Verification replays a bug many
+ * times (ddmin + validator), but the recording runs once, only when a PR is about
+ * to open — so it launches its own browser instead of reusing ReplayEngine's.
+ *
+ * GIF encoding is pure-JS (`gifenc` + `pngjs`), no ffmpeg, so it works for every
+ * `npm install aztrx-cli` user rather than only machines with ffmpeg on PATH.
+ */
+import type { Finding, RecordedAction } from "../types.js";
+export interface CaptureOptions {
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /** Settle time after page load, before the first frame. */
+    settleMs?: number;
+    /** Settle time after each replayed action, before its screenshot. */
+    stepMs?: number;
+}
+/**
+ * Captures one PNG screenshot before the replay and one after each action, so
+ * the crash (or its absence) is visible in the sequence. Replays `replayActions`
+ * one action at a time — reusing the exact detection semantics, not a parallel
+ * reimplementation that could drift.
+ */
+export declare function captureReproFrames(url: string, actions: RecordedAction[], opts?: CaptureOptions): Promise<Buffer[]>;
+export interface GifOptions {
+    /** Frame delay in ms (default 400). */
+    delay?: number;
+    /** Quantized palette size, ≤ 256 (default 256). */
+    maxColors?: number;
+}
+/** Encodes a sequence of PNG frames into an animated GIF (pure JS, no ffmpeg). */
+export declare function encodeGif(frames: Buffer[], opts?: GifOptions): Buffer;
+/** The static "crash shot": the final frame, when the crash has fully rendered. */
+export declare function crashFrame(frames: Buffer[]): Buffer;
+/**
+ * Produces the recorded-repro GIF for a finding and writes it to
+ * `aztrx-media/<fp8>.gif`. That dir is deliberate: `media/` is in the npm
+ * `files` allowlist (so demo.gif/logo ship), but patrol GIFs must not publish —
+ * they're per-run artifacts. The path is committed to the PR branch so the PR
+ * body can inline it via a raw URL.
+ *
+ * Returns the repo-relative path, or null when there is nothing to record (no
+ * repro, or capture/encode failed) — the caller opens the PR regardless.
+ */
+export declare function recordFindingGif(repoRoot: string, url: string, finding: Finding): Promise<string | null>;

package/dist/core/patrol/state.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Cross-run memory for `aztrx patrol`. Where `RunLog` is append-only and reset
+ * every run, this is a small index of "have I seen this fingerprint before, and
+ * what happened to it?" — the thing that stops an autonomous loop from re-fixing
+ * the same bug and re-opening the same PR on every cycle.
+ *
+ * Lives at `.aztrx/patrol.json` (already gitignored via `.aztrx/`). A fingerprint
+ * absent from the map is implicitly "new".
+ */
+export type FingerprintStatus = "pr-opened" | "unfixed";
+export interface FingerprintEntry {
+    status: FingerprintStatus;
+    firstSeen: string;
+    lastSeen: string;
+    prUrl?: string;
+    branch?: string;
+    attempts: number;
+}
+export declare class PatrolState {
+    private readonly file;
+    private readonly cooldownMs;
+    private data;
+    constructor(repoRoot: string, url: string, cooldownMs?: number);
+    private read;
+    /**
+     * A fingerprint is "handled" while its PR is open, or while an `unfixed` mark
+     * is still within its cooldown. Once the cooldown lapses, an `unfixed` bug
+     * becomes retry-eligible again — it stops being "handled" and `run()` heals it
+     * afresh rather than skipping it forever.
+     */
+    isHandled(fp: string, now?: number): boolean;
+    /** Every currently-handled fingerprint, so the supervisor can tell `run()` to skip healing them. */
+    handled(now?: number): string[];
+    markPr(fp: string, prUrl: string, branch: string): void;
+    markUnfixed(fp: string): void;
+    private firstSeen;
+    private attempts;
+    save(): void;
+}

package/dist/core/pr.d.ts

@@ -0,0 +1,3 @@
+import type { Finding } from "./types.js";
+export declare function renderPrComment(targetUrl: string, findings: Finding[]): string;
+export declare function writePrComment(repoRoot: string, targetUrl: string, findings: Finding[], filePath?: string): string;

package/dist/core/pr.js

@@ -9,12 +9,6 @@ import { sanitizeSecrets } from "./heal/redact.js";
  * shields.io badges, which GitHub renders natively.
  */
 const SEV_ORDER = ["crash", "error", "warning", "noise"];
-const SEV_BADGE = {
-    crash: "ff5a5f",
-    error: "ff5a5f",
-    warning: "f5a623",
-    noise: "5b6573",
-};
 /** Shields.io badge-path escaping: literal `-` → `--`, `/` → `%2F`, space → `_`. */
 function shield(s) {
     return s.replace(/-/g, "--").replace(/\//g, "%2F").replace(/ /g, "_");
@@ -44,6 +38,17 @@ function inlineCode(s) {
 function cleanInline(s) {
     return sanitizeSecrets(s).replace(/`/g, "").replace(/[\r\n]/g, " ");
 }
+/** Prose that lands in the comment body — a model-written explanation, an error
+ * string. Escaping the HTML keeps it inside the surrounding `<details>`;
+ * defusing the link/image syntax stops a crafted PR from having the bot render
+ * a tracking pixel or a phishing link under the consumer's token. Secrets are
+ * scrubbed for the same reason every other inlined string is: the model read
+ * the app's own source to write this, so it can quote a key back out. */
+function cleanProse(s) {
+    return escapeHtml(sanitizeSecrets(s))
+        .replace(/!\[/g, "!\\[")
+        .replace(/\]\(/g, "\\]\\(");
+}
 /** Hard cap on the server body inlined into a PR comment — a 500 page can be
  * huge, and only the first line or two are ever diagnostic. */
 const SERVER_BODY_CAP = 2000;
@@ -84,13 +89,13 @@ function healBlock(f) {
         body.push(fence(diff, "diff"));
     }
     else if (h.explanation) {
-        body.push(`> ${h.explanation}`);
+        body.push(`> ${cleanProse(h.explanation)}`);
     }
     if (h.test?.ran) {
         body.push(`**tests** ${inlineCode(h.test.command)} — ${h.test.ok ? "passed" : "failed"}`);
     }
     if (h.error)
-        body.push(`\n_${escapeHtml(h.error)}_`);
+        body.push(`\n_${cleanProse(h.error)}_`);
     return `\n<details>\n<summary>${badge("heal", meta.text, meta.color)} proposed patch${via}${tiers}</summary>\n\n${body.join("\n")}\n</details>`;
 }
 function reproBlock(f) {
@@ -122,8 +127,7 @@ function findingBlock(f) {
         : "";
     return `<details open>\n<summary><code>${escapeHtml(sev)}</code> — ${escapeHtml(first)}</summary>\n${loc}${snippet}${serverErr}${reproBlock(f)}${healBlock(f)}\n</details>`;
 }
-export function renderPrComment(targetUrl, findings, opts = {}) {
-    void opts;
+export function renderPrComment(targetUrl, findings) {
     const sorted = [...findings].sort((a, b) => SEV_ORDER.indexOf(a.severity) - SEV_ORDER.indexOf(b.severity));
     const counts = { crash: 0, error: 0, warning: 0, noise: 0 };
     for (const f of sorted)
@@ -160,6 +164,6 @@ ${body}
 export function writePrComment(repoRoot, targetUrl, findings, filePath) {
     const file = filePath ?? path.join(repoRoot, ".aztrx", "pr-comment.md");
     fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, renderPrComment(targetUrl, findings, { repoRoot }), "utf-8");
+    fs.writeFileSync(file, renderPrComment(targetUrl, findings), "utf-8");
     return file;
 }

package/dist/core/prompt.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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".
+ */
+export interface PromptOptions {
+    yes?: boolean;
+}
+export declare function promptYesNo(question: string, opts?: PromptOptions): Promise<boolean>;
+/** A single-line text prompt. Returns "" when stdout isn't a TTY (unattended run). */
+export declare function promptInput(question: string): Promise<string>;

package/dist/core/recorder.d.ts

@@ -0,0 +1,23 @@
+import type { ElementHandle } from "playwright";
+import type { RecordedAction } from "./types.js";
+type AnyElement = SVGElement | HTMLElement;
+/**
+ * F2 — ring buffer of the last 25 actions. The Repro Minimizer (F7) later
+ * shrinks this history; for now it's the action context attached to findings.
+ */
+export declare class ActionRecorder {
+    private buffer;
+    readonly capacity = 25;
+    record(action: RecordedAction): void;
+    snapshot(): RecordedAction[];
+}
+/**
+ * Selector cascade, most-reliable first: data-testid → text → css path.
+ *
+ * Each `evaluate` is wrapped defensively: selector resolution is best-effort
+ * and must never take down a whole run if the page tears the node down
+ * mid-query or the browser rejects a serialized function. A failed probe just
+ * degrades to the next (weaker) selector in the cascade.
+ */
+export declare function selectorCascade(handle: ElementHandle<AnyElement>): Promise<string[]>;
+export {};

package/dist/core/recorder.js

@@ -22,7 +22,7 @@ export class ActionRecorder {
  * mid-query or the browser rejects a serialized function. A failed probe just
  * degrades to the next (weaker) selector in the cascade.
  */
-export async function selectorCascade(page, handle) {
+export async function selectorCascade(handle) {
     const out = [];
     try {
         const testId = await handle.evaluate((el) => {

package/dist/core/renderMarkdown.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Minimal Markdown → ANSI renderer for the `--explain` / `--fix` human-language
+ * summary. Handles the small dialect Aztrx emits: headings, bold/`code` inline,
+ * bullet and numbered lists, and fenced code blocks with a light JS/TS syntax
+ * highlight. Plain prose without markdown passes through unchanged.
+ */
+export declare function renderMarkdown(md: string): string;

package/dist/core/replay.d.ts

@@ -0,0 +1,33 @@
+import type { Page } from "playwright";
+import type { FindingType, RecordedAction } from "./types.js";
+export interface ReplayEngineOptions {
+    attachGuard?: (page: Page) => Promise<void>;
+    /** Playwright storage-state JSON (path or object) for authenticated replays. */
+    storageState?: string;
+}
+export interface ReplayResult {
+    reproduced: boolean;
+    /** Did the target page actually load? A navigation that was refused, timed out,
+     * or answered non-2xx produces no telemetry — which is indistinguishable from
+     * "the bug is gone" unless the caller can tell the two apart. Verification
+     * depends on this: an unreachable page must never count as a passing run. */
+    loaded: boolean;
+}
+/** Replays a recorded action sequence against a page. Best-effort: a selector
+ * that no longer resolves is skipped, not fatal. */
+export declare function replayActions(page: Page, actions: RecordedAction[]): Promise<void>;
+/**
+ * Reuses one browser across replays (ddmin + validator each run many). Each
+ * `run` gets a fresh page; the interceptor collects telemetry fingerprints and
+ * reports whether `targetFingerprint` was seen.
+ */
+export declare class ReplayEngine {
+    private opts;
+    private browser;
+    constructor(opts?: ReplayEngineOptions);
+    private getBrowser;
+    run(url: string, actions: RecordedAction[], targetFingerprint: string, opts?: {
+        targetType?: FindingType;
+    }): Promise<ReplayResult>;
+    close(): Promise<void>;
+}

package/dist/core/replay.js

@@ -111,7 +111,14 @@ export class ReplayEngine {
                 attachInterceptor(page, bus);
                 if (this.opts.attachGuard)
                     await this.opts.attachGuard(page);
-                await page.goto(url, { waitUntil: "load", timeout: 30000 }).catch(() => { });
+                // A rejected navigation (refused connection, DNS failure, timeout) and a
+                // non-2xx answer both leave a page that will never emit the telemetry we
+                // are looking for. Capture that here rather than letting the empty
+                // fingerprint set read as a passing verification.
+                const nav = await page
+                    .goto(url, { waitUntil: "load", timeout: 30000 })
+                    .catch(() => null);
+                const loaded = nav !== null && nav.ok();
                 // Settle for hydration before replaying — the detection pass waits on the
                 // `load` event plus a settle window, and a replay that clicks before React
                 // attaches its handlers won't reproduce the crash (false "unreliable").
@@ -123,7 +130,7 @@ export class ReplayEngine {
                 const reproduced = opts?.targetType
                     ? types.has(opts.targetType)
                     : fingerprints.has(targetFingerprint);
-                return { reproduced };
+                return { reproduced, loaded };
             }
             catch (e) {
                 lastError = e;

package/dist/core/report.d.ts

@@ -0,0 +1,8 @@
+import type { Finding } from "./types.js";
+/**
+ * F-report — standalone offline HTML report. Self-contained (inline CSS, no
+ * CDN), rendered in the shared "crash seismograph" identity: one red spike per
+ * crash, severity chips, and colored repro verdicts.
+ */
+export declare function renderReport(targetUrl: string, findings: Finding[], lang?: string): string;
+export declare function writeReport(repoRoot: string, targetUrl: string, findings: Finding[], lang?: string): string;

package/dist/core/resolver.d.ts

@@ -0,0 +1,44 @@
+import type { ServerFrame } from "./types.js";
+export type ResolvedFrom = "sourcemap" | "direct" | "unresolved";
+export interface MappedError {
+    message: string;
+    /** Repo-relative path to the source file, e.g. `apps/web/src/App.tsx`. */
+    sourceFile: string;
+    line: number;
+    column: number;
+    codeSnippet: string;
+    resolvedFrom: ResolvedFrom;
+}
+export interface RawFrame {
+    url: string;
+    line: number;
+    column: number;
+    message: string;
+}
+/**
+ * Pulls the first *user-code* frame out of a stack string. Iterates every line,
+ * skips framework internals (webpack runtime, node_modules, next/dist), and
+ * returns the first frame in the user's own code — so a Next.js dev stack like
+ * `webpack-internal:///(app-pages-browser)/./app/page.tsx:29:21` resolves to the
+ * user's file, not `intercept-console-error.js`.
+ */
+export declare function extractFrame(text: string): RawFrame | null;
+/**
+ * Pull the first server-side source frame out of a raw server stack (a 500 body,
+ * a Next.js dev error page, etc.). V8 emits one frame per line as
+ * `at <fn> (<path>:<line>:<col>)` or `at <path>:<line>:<col>`; we take the first
+ * frame whose path is not inside node_modules. Best-effort — returns null when
+ * the body carries no stack trace (e.g. an explicit
+ * `NextResponse.json(..., { status: 500 })`).
+ */
+export declare function extractServerFrame(stack: string): ServerFrame | null;
+export declare function resolveFrame(frame: RawFrame, repoRoot: string): Promise<MappedError>;
+/**
+ * Resolve a server-side source frame (a filesystem path) to a repo-relative
+ * source location + snippet. Mirrors `resolveFrame`'s containment rules: a path
+ * outside the repo — via `..` traversal or a symlink pointing out — is never
+ * read. Server frames carry no sourcemap; a directly-readable file maps
+ * `resolvedFrom: "direct"`.
+ */
+export declare function resolveServerFrame(frame: ServerFrame, repoRoot: string): MappedError;
+export declare function extractSnippet(filePath: string, targetLine: number, window?: number): string;

package/dist/core/resolver.js

@@ -1,5 +1,6 @@
 import * as fs from "fs";
 import * as path from "path";
+import { fileURLToPath } from "url";
 import { FlattenMap, originalPositionFor, } from "@jridgewell/trace-mapping";
 /** Framework-internal frames to skip when hunting the throw site. */
 const FRAMEWORK_FRAME = /node_modules|webpack-runtime|\.next[\\/]|next[\\/]dist[\\/]/;
@@ -56,20 +57,40 @@ export function extractServerFrame(stack) {
 function stripQuery(url) {
     return url.split("?")[0];
 }
-/** Normalize a stack-frame URL to a repo-relative source path. Handles the
- * dev-server schemes (`webpack-internal:///(ns)/./src/…`, `webpack://ns/src/…`),
- * `file://`, and plain `https://host/path` bundle URLs. */
+/** Normalize a stack-frame URL to a path to probe: repo-relative for the
+ * dev-server schemes (`webpack-internal:///(ns)/./src/…`, `webpack://ns/src/…`)
+ * and plain `https://host/path` bundle URLs, **absolute** for `file://`.
+ *
+ * The asymmetry is deliberate. `file://` carries a real filesystem path, and on
+ * POSIX the leading slash is the root; the `^\//` strip below exists for URL
+ * paths (`/@fs/src/main.tsx`) and would eat it, turning `/tmp/p/app/actions.ts`
+ * into the relative `tmp/p/app/actions.ts` — a path under the repo that never
+ * exists. Every `file://` frame therefore fell through to "unresolved" on Linux
+ * and macOS. `resolveWithin` accepts absolute segments, so callers are unchanged;
+ * only display has to convert back (see `reportPath`). */
 function normalizeFrameUrl(url) {
-    return stripQuery(url)
+    const raw = stripQuery(url);
+    if (/^file:\/\//i.test(raw)) {
+        try {
+            return fileURLToPath(raw); // handles drive-letter and UNC forms on Windows too
+        }
+        catch {
+            return raw; // malformed URL — let the containment check reject it
+        }
+    }
+    return raw
         .replace(/^webpack-internal:\/\/\/[^/]+\/\.\//, "")
         .replace(/^webpack:\/\/[^/]+\//, "")
         .replace(/^webpack:\/\//, "")
         .replace(/^\/@fs\//, "")
-        .replace(/^file:\/\/\/([A-Za-z]:)/, "$1") // file:///C:/x → C:/x
-        .replace(/^file:\/\//, "")
         .replace(/^https?:\/\/[^/]+\//, "")
         .replace(/^\//, "");
 }
+/** The repo-relative form of a normalized frame path, for anything user-facing.
+ * An absolute `file://` path is reported the same way every other frame is. */
+function reportPath(p, repoRoot) {
+    return path.isAbsolute(p) ? path.relative(repoRoot, p) : p;
+}
 /** True only for a real, readable regular file — directories and unreadable
  * paths return false so readers never hit `EISDIR` / permission errors. */
 function isFile(p) {
@@ -140,14 +161,30 @@ function resolveWithin(root, ...segments) {
 }
 /** Turns a sourcemap `source` value into candidate absolute paths to probe. */
 function sourceCandidates(source, repoRoot) {
-    const cleaned = source
+    const raw = source.split("?")[0];
+    // `file://` is an absolute *filesystem* path, not a URL path, and the two
+    // differ in exactly one place: on POSIX the leading slash is the root. The
+    // web-style stripping below exists for URL paths (`/@fs/src/main.tsx`) and
+    // would eat that slash, turning `/tmp/p/app/actions.ts` into the relative
+    // `tmp/p/app/actions.ts` — a path under the repo that never exists, so every
+    // Turbopack `file:///` source silently resolved to nothing on Linux and macOS.
+    // `fileURLToPath` also handles the drive-letter and UNC forms on Windows.
+    if (/^file:\/\//i.test(raw)) {
+        let abs;
+        try {
+            abs = fileURLToPath(raw);
+        }
+        catch {
+            return []; // malformed URL — nothing to probe
+        }
+        const inside = resolveWithin(repoRoot, abs);
+        return inside === null ? [] : [inside];
+    }
+    const cleaned = raw
         .replace(/^webpack:\/\/[^/]+\//, "") // webpack://namespace/src/...
         .replace(/^webpack:\/\//, "")
         .replace(/^\/@fs\//, "")
-        .replace(/^file:\/\/\/([A-Za-z]:)/, "$1") // file:///C:/x → C:/x
-        .replace(/^file:\/\//, "")
-        .replace(/^\//, "")
-        .split("?")[0];
+        .replace(/^\//, "");
     const prefixes = ["", "apps/web/", "src/", "app/"];
     return prefixes
         .map((p) => resolveWithin(repoRoot, p, cleaned))
@@ -181,12 +218,13 @@ export async function resolveFrame(frame, repoRoot) {
             directPath = withIndex;
     }
     if (!directPath) {
+        const shown = reportPath(relative, repoRoot);
         return {
             message: frame.message,
-            sourceFile: relative,
+            sourceFile: shown,
             line: frame.line,
             column: frame.column,
-            codeSnippet: `<file not accessible locally: ${relative}>`,
+            codeSnippet: `<file not accessible locally: ${shown}>`,
             resolvedFrom: "unresolved",
         };
     }

package/dist/core/rng.d.ts

@@ -0,0 +1,2 @@
+/** Deterministic seeded PRNG (mulberry32) so fuzz runs are reproducible. */
+export declare function mulberry32(seed: number): () => number;