aztrx-cli 0.5.1 → 0.5.2

package/README.md

@@ -478,7 +478,7 @@ The commands that are not `run`:
 | `--regression-test [dir]` | Copy validated repro specs into the project test dir | first of `e2e/`, `tests/`, `test/`, `__tests__/`; else `.aztrx/regression/` |
 | `--telemetry` | Collect anonymized tuples locally (opt-in) | — |
 | `--share-data` | Also upload the sanitized tuples (opt-in) | — |
-| `--repo <path>` | Root path for sourcemap → source resolution | cwd |
+| `--repo <path>` | Root path for sourcemap → source resolution — must already exist (a path that does not is refused, not created) | 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` | — |

package/dist/cli/repo.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `--repo` is checked, not trusted.
+ *
+ * Commander consumes a `<required>` option argument even when the argument
+ * *looks like a flag*: `aztrx run --repo --fix` sets `repo` to the literal
+ * string `--fix` — measured against commander 12 rather than assumed. From
+ * there `path.resolve` turns it into `<cwd>/--fix`, and the first
+ * `mkdirSync(..., { recursive: true })` on the run path is happy to create it.
+ * So a mistyped invocation does not fail, it *succeeds* — against a project
+ * directory the tool invented — and leaves its `.aztrx/` artifacts inside.
+ *
+ * That is not hypothetical: `C:\Users\dchap\--fix\` existed holding nothing but
+ * `.aztrx/`, which is exactly this. An empty directory nobody can explain is a
+ * worse failure than an error message, because nothing reports it.
+ */
+/** Why `dir` cannot serve as a project root, or null when it can. Pure, so the
+ * wording is testable without spawning a process — the caller prints and exits. */
+export declare function repoPathProblem(dir: string): string | null;
+/** Absolute, existing project root — or exit 1 with the reason. */
+export declare function resolveRepoRoot(raw: string | undefined, cwd?: string): string;

package/dist/cli/repo.js

@@ -0,0 +1,50 @@
+import * as fs from "fs";
+import path from "path";
+import pc from "picocolors";
+/**
+ * `--repo` is checked, not trusted.
+ *
+ * Commander consumes a `<required>` option argument even when the argument
+ * *looks like a flag*: `aztrx run --repo --fix` sets `repo` to the literal
+ * string `--fix` — measured against commander 12 rather than assumed. From
+ * there `path.resolve` turns it into `<cwd>/--fix`, and the first
+ * `mkdirSync(..., { recursive: true })` on the run path is happy to create it.
+ * So a mistyped invocation does not fail, it *succeeds* — against a project
+ * directory the tool invented — and leaves its `.aztrx/` artifacts inside.
+ *
+ * That is not hypothetical: `C:\Users\dchap\--fix\` existed holding nothing but
+ * `.aztrx/`, which is exactly this. An empty directory nobody can explain is a
+ * worse failure than an error message, because nothing reports it.
+ */
+/** Why `dir` cannot serve as a project root, or null when it can. Pure, so the
+ * wording is testable without spawning a process — the caller prints and exits. */
+export function repoPathProblem(dir) {
+    let st;
+    try {
+        st = fs.statSync(dir);
+    }
+    catch {
+        // A path whose last segment is itself a flag is the signature of the option
+        // having eaten one, and saying so beats leaving the user to re-read their
+        // own command line for it.
+        const base = path.basename(dir);
+        if (base.startsWith("-")) {
+            return (`no such directory: ${dir}\n` +
+                `  \`${base}\` looks like a flag, not a path — did it get taken as the value of \`--repo\`?`);
+        }
+        return `no such directory: ${dir}`;
+    }
+    if (!st.isDirectory())
+        return `not a directory: ${dir}`;
+    return null;
+}
+/** Absolute, existing project root — or exit 1 with the reason. */
+export function resolveRepoRoot(raw, cwd = process.cwd()) {
+    const dir = path.resolve(cwd, raw ?? ".");
+    const problem = repoPathProblem(dir);
+    if (problem) {
+        console.error(pc.red("✗ ") + problem);
+        process.exit(1);
+    }
+    return dir;
+}

package/dist/cli.js

@@ -5,6 +5,7 @@ import * as os from "os";
 import pc from "picocolors";
 import { program } from "commander";
 import { opt, formatHelp } from "./cli/help.js";
+import { resolveRepoRoot } from "./cli/repo.js";
 import { initProject } from "./core/init.js";
 import { VERSION } from "./core/version.js";
 import { installHook, runPrePush, uninstallHook } from "./hooks/index.js";
@@ -91,7 +92,7 @@ program
     .option("--framework <name>", "framework override (auto-detected if omitted)")
     .action(async (opts) => {
     const res = await initProject({
-        repoRoot: path.resolve(program.opts().repo),
+        repoRoot: resolveRepoRoot(program.opts().repo),
         url: opts.url,
         framework: opts.framework,
     });
@@ -109,7 +110,7 @@ program
     .option("--force", "overwrite a pre-push hook that Aztrx did not write")
     .option("--always", "with `run`: scan even when no app code changed")
     .action(async (action, name, opts) => {
-    const repoRoot = path.resolve(program.opts().repo);
+    const repoRoot = resolveRepoRoot(program.opts().repo);
     const hookName = name ?? "pre-push";
     if (hookName !== "pre-push") {
         console.error(pc.red(`unsupported hook: ${hookName}`) + " (only `pre-push` is wired up)");
@@ -156,7 +157,7 @@ program
     .argument("[action]", "install | uninstall — omit to serve on stdio")
     .option("--force", "with `install`: replace a config file that will not parse (a .bak is saved first)")
     .action(async (action, opts) => {
-    const repoRoot = path.resolve(program.opts().repo);
+    const repoRoot = resolveRepoRoot(program.opts().repo);
     // No action means serve, because that is what an editor's config runs and it
     // must be the shortest thing to type. From here stdout is the protocol
     // channel: the server reroutes `console.log` to stderr itself, but anything
@@ -206,7 +207,7 @@ program
     .option("--port <n>", "port to listen on", "7331")
     .action(async (opts) => {
     const { startStudio } = await import("./core/studio.js");
-    startStudio({ repoRoot: path.resolve(program.opts().repo), port: parseInt(opts.port, 10) });
+    startStudio({ repoRoot: resolveRepoRoot(program.opts().repo), port: parseInt(opts.port, 10) });
 });
 program
     .command("modernize")
@@ -214,7 +215,7 @@ program
     .argument("<file>", "path to the file to modernize")
     .option("-y, --yes", "apply without prompting")
     .action(async (file, opts) => {
-    const repoRoot = path.resolve(program.opts().repo);
+    const repoRoot = resolveRepoRoot(program.opts().repo);
     const rel = path.relative(repoRoot, path.resolve(file));
     const [{ modernizeFile }, { promptYesNo }] = await Promise.all([
         import("./core/modernize.js"),
@@ -290,7 +291,7 @@ program
     .action(async (url, opts) => {
     // `--fix` is the memorable verb; `--magic-fix` is a hidden alias.
     const magicFix = opts.magicFix || opts.fix;
-    const repoRoot = path.resolve(opts.repo ?? program.opts().repo);
+    const repoRoot = resolveRepoRoot(opts.repo ?? program.opts().repo);
     // Defaults the scaffolded aztrx.config.ts supplies, read here (lazily, like
     // the target resolver) because only this command knows the repo root.
     const { configAllowHosts, configMaxActions } = await import("./core/devServer.js");
@@ -541,7 +542,7 @@ program
     .addOption(opt("--start-command <cmd>", "command to boot the app for server healing", "advanced"))
     .addOption(opt("--no-boot", "never start a dev server — only attach to one already running", "detect"))
     .action(async (url, opts) => {
-    const repoRoot = path.resolve(opts.repo ?? program.opts().repo);
+    const repoRoot = resolveRepoRoot(opts.repo ?? program.opts().repo);
     const { configAllowHosts, configMaxActions } = await import("./core/devServer.js");
     let booted;
     let targetUrl = url;

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);
         }
@@ -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
+    }
+}

package/dist/core/heal/llm.js

@@ -111,7 +111,21 @@ export function generateRulePatch(ctx) {
         return null;
     // Optional-chain every `.identifier` access on the line (not just the failing
     // one) so a chain like `d.agents.map(…)` becomes `d?.agents?.map(…)`.
-    const replace = src.replace(/\.(?=[a-zA-Z_$])/g, "?.");
+    //
+    // The lookbehind is the whole point, and it is not cosmetic. A bare
+    // `/\.(?=[a-zA-Z_$])/` also matches the dots in a spread and in chaining that
+    // is already optional, so `{ ...s, [id]: result.ok }` became
+    // `{ ..?.s, [id]: result.ok }` and `d?.agents` became `d??.agents`. Both are
+    // syntax errors, which the AST gate then refused — correctly, but the effect
+    // was that the free fixer declined every line containing a spread or an
+    // existing `?.`, which is most React code, and the finding was reported as
+    // `rejected` with no hint that the rule engine was at fault.
+    //
+    // Known limit: this is a regex on a line of source, not a lexer, so a `.name`
+    // *inside a string literal or regex* on the failing line is rewritten too.
+    // That cannot make the file unparseable (the gate above still runs), but it
+    // can change behaviour, and no gate here would catch it.
+    const replace = src.replace(/(?<![.?])\.(?=[a-zA-Z_$])/g, "?.");
     if (replace === src)
         return null;
     return {
@@ -138,7 +152,13 @@ export async function generatePatch(ctx, opts = {}) {
         system: SYSTEM,
         prompt: buildPrompt(ctx),
         model: opts.model,
-        maxTokens: 2048,
+        // A patch is a few hundred tokens, but a reasoning model spends this budget
+        // on its thinking *first* — at 2048 a reasoner like cohere/north-mini-code
+        // hit the cap before emitting any text at all, so healing reported "no
+        // content (finish_reason: length)" and gave up without ever producing a
+        // patch. This is a ceiling, not a charge: cost is per token actually
+        // emitted, so the headroom is free for models that do not reason.
+        maxTokens: 8192,
         temperature: 0,
     });
     if (opts.budget)

package/dist/core/heal/sandbox.js

@@ -12,6 +12,48 @@ import * as path from "path";
 import { buildChildEnv } from "./childEnv.js";
 const execFileP = promisify(execFile);
 const preview = (s) => JSON.stringify(s.length > 60 ? s.slice(0, 57) + "…" : s);
+/**
+ * Remove directory links (POSIX symlinks / Windows junctions) from a worktree root.
+ *
+ * This MUST run before `git worktree remove`. Git's worktree teardown recurses
+ * *through* a junction and deletes its target, so the `node_modules` link that
+ * boot/verify create inside the worktree (below) turns an ordinary cleanup into a
+ * recursive delete of the user's real node_modules. Established by experiment,
+ * not by reading docs: a sentinel file inside the junction target did not survive
+ * `git worktree remove --force`. Node's own recursive `fs.rmSync` handles reparse
+ * points correctly and is safe either way; git's does not.
+ */
+function unlinkDirLinks(dir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const p = path.join(dir, entry.name);
+        try {
+            if (!fs.lstatSync(p).isSymbolicLink())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        // `unlink` covers POSIX dir symlinks; Windows junctions need `rmdir`.
+        try {
+            fs.unlinkSync(p);
+        }
+        catch {
+            try {
+                fs.rmdirSync(p);
+            }
+            catch {
+                /* best effort — a link that survives is still not followed by the rmSync below */
+            }
+        }
+    }
+}
 /** Create a detached worktree at HEAD in a temp dir (outside the repo). */
 export async function createWorktree(repoRoot, label) {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), `aztrx-heal-${label}-`));
@@ -19,6 +61,7 @@ export async function createWorktree(repoRoot, label) {
     return {
         dir,
         cleanup: async () => {
+            unlinkDirLinks(dir);
             await execFileP("git", ["-C", repoRoot, "worktree", "remove", "--force", dir]).catch(() => { });
             fs.rmSync(dir, { recursive: true, force: true });
         },

package/dist/core/llm.js

@@ -73,6 +73,31 @@ export async function complete(opts) {
         ? anthropicComplete(s, model, opts)
         : openaiComplete(s, model, opts);
 }
+/**
+ * Turn an empty completion into a diagnosable error.
+ *
+ * Returning `""` here is what makes a provider-side failure reach the caller as
+ * `Unexpected end of JSON input` — a message that points at *our* parser rather
+ * than at the model, and which the heal path then degrades to a bland "no-llm".
+ * The stop reason is the entire diagnosis, so it is carried into the message.
+ *
+ * Real cases this covers: a free/contended endpoint failing mid-flight
+ * (`finish_reason: "error"` on OpenRouter), a reasoning model spending the whole
+ * budget before emitting any text (`length`), and provider-side filters.
+ */
+function emptyCompletion(provider, model, reason) {
+    const why = reason === "length" || reason === "max_tokens"
+        ? "the token limit was reached before any text was emitted — the model is most likely spending its whole budget on reasoning; pick a different one with --heal-model / AZTRX_MODEL"
+        : reason === "error"
+            ? "the provider failed mid-response"
+            : reason === "content_filter"
+                ? "the provider blocked the response"
+                : reason === "refusal"
+                    ? "the model refused the request"
+                    : "the provider returned no text";
+    const seen = reason ? `finish_reason: ${reason}` : "no finish_reason given";
+    return new Error(`${provider} returned no content (${seen}) — ${why}. Model: ${model}`);
+}
 async function anthropicComplete(s, model, opts) {
     const headers = {
         "content-type": "application/json",
@@ -99,10 +124,13 @@ async function anthropicComplete(s, model, opts) {
         throw new Error(`LLM request failed (${res.status}): ${body.slice(0, 300)}`);
     }
     const data = (await res.json());
-    return (data.content ?? [])
+    const text = (data.content ?? [])
         .filter((c) => c.type === "text")
         .map((c) => c.text ?? "")
         .join("\n");
+    if (!text.trim())
+        throw emptyCompletion("Anthropic", model, data.stop_reason);
+    return text;
 }
 async function openaiComplete(s, model, opts) {
     const res = await fetch(`${s.baseUrl}/chat/completions`, {
@@ -126,14 +154,21 @@ async function openaiComplete(s, model, opts) {
         throw new Error(`LLM request failed (${res.status}): ${body.slice(0, 300)}`);
     }
     const data = (await res.json());
-    const content = data.choices?.[0]?.message?.content;
-    if (typeof content === "string")
+    // OpenRouter reports upstream failures in the body with HTTP 200, so `res.ok`
+    // alone does not mean the model answered.
+    if (data.error)
+        throw new Error(`LLM request failed: ${data.error.message ?? "unknown error"}`);
+    const choice = data.choices?.[0];
+    const content = choice?.message?.content;
+    if (typeof content === "string" && content.trim())
         return content;
     if (Array.isArray(content)) {
-        return content
+        const text = content
             .filter((c) => typeof c === "object" && c !== null && c.type === "text")
             .map((c) => c.text ?? "")
             .join("\n");
+        if (text.trim())
+            return text;
     }
-    return "";
+    throw emptyCompletion("OpenAI-compatible endpoint", model, choice?.finish_reason);
 }

package/dist/core/replay.js

@@ -2,13 +2,39 @@ import { EventBus } from "./eventBus.js";
 import { launchChromium } from "./browser.js";
 import { attachInterceptor } from "./interceptor.js";
 import { fingerprintOf } from "./classifier.js";
+/**
+ * How long to let a freshly-navigated page settle before acting on it.
+ *
+ * The walker waits this long after its own `page.goto` before it touches
+ * anything, so every recorded selector was resolved against a page that had
+ * been given 300ms to render — a replay that clicks the instant the navigation
+ * commits is asking for something the recording never was.
+ *
+ * Measured on a real Next.js app rather than guessed: with no settle, every
+ * action after a `navigate` was skipped — `count()` does not wait, so an
+ * element that is not in the DOM *yet* is indistinguishable from one that is
+ * gone, and the skip is silent — and a bug that fires on every single click
+ * came back `unreliable` 0/3. With 300ms it reproduced 3/3.
+ */
+const NAV_SETTLE_MS = 300;
+/**
+ * How long to keep watching after the last replayed action, for a bug whose
+ * trigger is asynchronous. See the poll in `run` — it exits the moment the
+ * fingerprint appears, so this is a ceiling, not a delay.
+ */
+const POST_REPLAY_WINDOW_MS = 1500;
 /** Replays a recorded action sequence against a page. Best-effort: a selector
  * that no longer resolves is skipped, not fatal. */
 export async function replayActions(page, actions) {
     for (const a of actions) {
         if (a.type === "navigate") {
             if (a.value) {
-                await page.goto(a.value, { waitUntil: "domcontentloaded", timeout: 10000 }).catch(() => { });
+                // Already there: a trace can carry the same URL twice, and re-loading
+                // the page it is already on costs a full load and resets its state.
+                if (page.url() !== a.value) {
+                    await page.goto(a.value, { waitUntil: "domcontentloaded", timeout: 10000 }).catch(() => { });
+                    await page.waitForTimeout(NAV_SETTLE_MS);
+                }
             }
             continue;
         }
@@ -126,11 +152,23 @@ export class ReplayEngine {
                 if (opts?.targetType)
                     collecting = true;
                 await replayActions(page, actions);
-                await page.waitForTimeout(300);
-                const reproduced = opts?.targetType
-                    ? types.has(opts.targetType)
-                    : fingerprints.has(targetFingerprint);
-                return { reproduced, loaded };
+                // An action can start work that throws later — a `fetch` behind a 300ms
+                // mock, a promise chain, a state update that re-renders into the bug —
+                // and the last action is not the last word. Waiting a fixed 300ms for
+                // that measured *exactly* on the boundary of a real app's own 300ms
+                // delay, so the same trace flipped between reproducing and not from one
+                // run to the next.
+                //
+                // Poll instead of sleeping: a bug that fires during the replay returns
+                // on the first check, so the window costs nothing where the verdict is
+                // already decided, and only a trace that is going to be called
+                // `unreliable` pays for the full wait — which is the case that must not
+                // be wrong.
+                const seen = () => opts?.targetType ? types.has(opts.targetType) : fingerprints.has(targetFingerprint);
+                const deadline = Date.now() + POST_REPLAY_WINDOW_MS;
+                while (!seen() && Date.now() < deadline)
+                    await page.waitForTimeout(50);
+                return { reproduced: seen(), loaded };
             }
             catch (e) {
                 lastError = e;

package/dist/core/resolver.d.ts

@@ -42,3 +42,23 @@ export declare function resolveFrame(frame: RawFrame, repoRoot: string): Promise
  */
 export declare function resolveServerFrame(frame: ServerFrame, repoRoot: string): MappedError;
 export declare function extractSnippet(filePath: string, targetLine: number, window?: number): string;
+/**
+ * Re-anchor a position that a transpiled frame reported wrongly.
+ *
+ * `webpack-internal://` frames carry a position in the module webpack
+ * *generated*, not in the `.tsx` on disk. Next dev reported
+ * `app/page.tsx:29:21` for a crash that is on line 15 — and because the URL
+ * path is the real source path, the file is found and a confidently wrong line
+ * is shown. Worse, `generateRulePatch` looks for the property on the mapped
+ * line, finds a `</div>` instead, and declines — so the free no-key fix never
+ * fires on Next.js.
+ *
+ * The error message is the signal. `Cannot read properties of undefined
+ * (reading 'agents')` can only be thrown by a line that reads `.agents`, so a
+ * mapped line that does not read it is provably not the throw site, and the
+ * real one is findable. Ambiguity is left alone rather than guessed at.
+ */
+export declare function reanchorPosition(content: string, line: number, column: number, message: string): {
+    line: number;
+    column: number;
+};

package/dist/core/resolver.js

@@ -228,13 +228,22 @@ export async function resolveFrame(frame, repoRoot) {
             resolvedFrom: "unresolved",
         };
     }
+    // The frame's line is only as good as the code it came from: for a
+    // `webpack-internal://` frame it indexes webpack's *generated* module, not the
+    // source on disk (see reanchorPosition), so re-anchor before showing it — and
+    // before `generateRulePatch` reads it, which is the difference between a free
+    // fix and a paid one.
+    const readable = isFile(directPath) && !isSensitive(directPath);
+    const at = readable
+        ? reanchorPosition(fs.readFileSync(directPath, "utf-8"), frame.line, frame.column, frame.message)
+        : { line: frame.line, column: frame.column };
     return {
         message: frame.message,
         sourceFile: path.relative(repoRoot, directPath),
-        line: frame.line,
-        column: frame.column,
-        codeSnippet: extractSnippet(directPath, frame.line),
-        resolvedFrom: isFile(directPath) && !isSensitive(directPath) ? "direct" : "unresolved",
+        line: at.line,
+        column: at.column,
+        codeSnippet: extractSnippet(directPath, at.line),
+        resolvedFrom: readable ? "direct" : "unresolved",
     };
 }
 /**
@@ -394,3 +403,74 @@ export function extractSnippet(filePath, targetLine, window = 4) {
     })
         .join("\n");
 }
+/** The property a null-deref message was reading:
+ * `Cannot read properties of undefined (reading 'agents')` → `agents`.
+ * Null for every other error, which is what keeps the correction below scoped
+ * to the one message shape that proves where the throw happened. */
+function readProperty(message) {
+    const m = message.match(/reading ['"]([^'"]+)['"]/);
+    return m ? m[1] : null;
+}
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** Drop a trailing `//` comment. The `:` guard keeps `https://` intact. */
+function stripComment(line) {
+    const i = line.indexOf("//");
+    if (i <= 0 || line[i - 1] === ":")
+        return line;
+    return line.slice(0, i);
+}
+/** Does this line read `.prop`? */
+function readsProperty(line, prop) {
+    return new RegExp(`\\.${escapeRe(prop)}\\b`).test(line);
+}
+/** True when every read of `.prop` on this line is optional-chained. A guarded
+ * read cannot throw, so such a line is never the crash site — which is what
+ * separates `d?.agents ?? []` from the `d.agents.map(…)` that actually threw. */
+function allReadsGuarded(line, prop) {
+    const re = new RegExp(`(\\?)?\\.${escapeRe(prop)}\\b`, "g");
+    let seen = false;
+    for (let m = re.exec(line); m; m = re.exec(line)) {
+        seen = true;
+        if (!m[1])
+            return false;
+    }
+    return seen;
+}
+/**
+ * Re-anchor a position that a transpiled frame reported wrongly.
+ *
+ * `webpack-internal://` frames carry a position in the module webpack
+ * *generated*, not in the `.tsx` on disk. Next dev reported
+ * `app/page.tsx:29:21` for a crash that is on line 15 — and because the URL
+ * path is the real source path, the file is found and a confidently wrong line
+ * is shown. Worse, `generateRulePatch` looks for the property on the mapped
+ * line, finds a `</div>` instead, and declines — so the free no-key fix never
+ * fires on Next.js.
+ *
+ * The error message is the signal. `Cannot read properties of undefined
+ * (reading 'agents')` can only be thrown by a line that reads `.agents`, so a
+ * mapped line that does not read it is provably not the throw site, and the
+ * real one is findable. Ambiguity is left alone rather than guessed at.
+ */
+export function reanchorPosition(content, line, column, message) {
+    const prop = readProperty(message);
+    if (!prop)
+        return { line, column };
+    const lines = content.split("\n");
+    const mapped = lines[line - 1];
+    if (mapped && readsProperty(stripComment(mapped), prop))
+        return { line, column };
+    const candidates = [];
+    for (let i = 0; i < lines.length; i++) {
+        const text = stripComment(lines[i]);
+        if (!readsProperty(text, prop) || allReadsGuarded(text, prop))
+            continue;
+        candidates.push(i + 1);
+    }
+    if (candidates.length !== 1)
+        return { line, column }; // ambiguous — don't guess
+    const found = lines[candidates[0] - 1];
+    // Point the column at the property too: the frame's column is as transpiled
+    // as its line was.
+    return { line: candidates[0], column: found.indexOf(`.${prop}`) + 1 };
+}

package/dist/core/summarize.js

@@ -125,12 +125,23 @@ function buildLlmPrompt(findings, lang, hasHealed) {
 const SYSTEM = "You are the plain-spoken explainer for a QA tool called Aztrx AI. You turn raw runtime-finding data into a concise Markdown summary for a developer (headings, bold, bullet lists, short code snippets). Never invent details absent from the data. Respond in the requested language only.";
 async function summarizeFindingsLlm(findings, lang) {
     const hasHealed = findings.some((f) => f.heal?.status === "healed");
-    const text = (await complete({
-        system: SYSTEM,
-        prompt: buildLlmPrompt(findings, lang, hasHealed),
-        maxTokens: 1024,
-        temperature: 0.2,
-    })).trim();
+    // The template is the floor, not a fallback for one case: an explanation is a
+    // nice-to-have, so a provider that errors, truncates or filters must not take
+    // the report down with it. `complete()` throws on an empty completion rather
+    // than returning "", so this catch is what keeps that contract from becoming a
+    // crash — the `||` then covers a reply that was whitespace.
+    let text = "";
+    try {
+        text = (await complete({
+            system: SYSTEM,
+            prompt: buildLlmPrompt(findings, lang, hasHealed),
+            maxTokens: 1024,
+            temperature: 0.2,
+        })).trim();
+    }
+    catch {
+        text = "";
+    }
     return text || summarizeFindingsTemplate(findings, lang);
 }
 /**

package/dist/core/swarm.js

@@ -95,9 +95,32 @@ export async function detectWorker(browser, opts, strategy, forwardBus) {
             onBlock: (u) => opts.log(`[guard] blocked ${u}`),
         });
     }
+    // The last URL this listener recorded as a `navigate`, to drop the duplicate.
+    // Playwright fires `framenavigated` twice for a single `page.goto` — measured
+    // against Chromium, not assumed: one goto to `/agents` produced two events
+    // for the same URL. Recording both would put a redundant full page load in
+    // every trace, and the buffer is only 25 actions deep.
+    let lastNavUrl = "";
     page.on("framenavigated", (frame) => {
-        if (frame === page.mainFrame())
-            workerBus.emit("route", { url: frame.url(), ts: Date.now() });
+        if (frame !== page.mainFrame())
+            return; // an iframe's URL is not the page's
+        const url = frame.url();
+        workerBus.emit("route", { url, ts: Date.now() });
+        // A trace has to say which page it was on, and nothing recorded that. The
+        // walker reaches each crawled route with `page.goto`, which emits no action
+        // at all, so a finding on `/agents` produced a trace of clicks that only
+        // mean anything *there* — replayed from the start URL every one of them
+        // resolved to nothing, the crash was never reached, and a bug that fires
+        // every single time came back `unreliable` (0/3 replays). `navigate` is
+        // already understood by everything that consumes a trace: `replayActions`
+        // and the spec compiler act on it, heal rewrites its origin to the booted
+        // server, and the patrol GIF skips it. Only the producer was missing.
+        if (!/^https?:/i.test(url))
+            return; // about:blank, and the first empty frame
+        if (url === lastNavUrl)
+            return; // the second of the pair described above
+        lastNavUrl = url;
+        workerBus.emit("action", { type: "navigate", selectors: [], value: url, timestamp: Date.now() });
     });
     let loaded = true;
     await page.goto(opts.url, { waitUntil: "load", timeout: 30000 }).catch((e) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aztrx-cli",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "private": false,
   "description": "Aztrx AI — runtime stress-tester for web apps. Detect bugs, then prove them with an executable repro.",
   "license": "Apache-2.0",
@@ -52,7 +52,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/Aztrx-AI/aztrx.git"
+    "url": "git+https://github.com/Aztrx-AI/aztrx.git"
   },
   "scripts": {
     "build": "tsc",
@@ -90,5 +90,13 @@
     "vite": {
       "optional": true
     }
-  }
+  },
+  "directories": {
+    "doc": "docs",
+    "test": "tests"
+  },
+  "bugs": {
+    "url": "https://github.com/Aztrx-AI/aztrx/issues"
+  },
+  "homepage": "https://aztrx.app"
 }