aztrx-cli 0.4.5 → 0.5.2

package/dist/core/heal/llm.d.ts

@@ -0,0 +1,43 @@
+/**
+ * F10 — LLM patch generator. Turns a redacted bug report into a minimal
+ * Search & Replace diff. The transport is Anthropic's Messages API (key from
+ * `ANTHROPIC_API_KEY`, model from `AZTRX_MODEL` or a sensible default); a
+ * `patchFn` can be injected instead, which is how the loop is unit-tested and
+ * how a future provider (local model, proxy) plugs in without touching this
+ * module's callers.
+ */
+import type { HealContext, Patch, SpendBudget } from "./types.js";
+export interface ModelTier {
+    model: string;
+    label: "fast" | "sonnet";
+}
+/**
+ * The Smart Cloud Router's tier plan: fast/cheap first, then the capable model
+ * as the fallback. Collapses to a single tier when the two resolve to the same
+ * model (e.g. `AZTRX_FAST_MODEL=claude-sonnet-5`). Consumers loop over this in
+ * order and stop at the first `healed` result.
+ */
+export declare function modelTiers(fallbackModel?: string, fastFallback?: string): ModelTier[];
+export interface GenerateOptions {
+    model?: string;
+    patchFn?: (ctx: HealContext) => Promise<Patch>;
+    budget?: SpendBudget;
+}
+/** Thrown when the shared session budget has no paid generations left. Heal
+ * maps this to a `budget-exhausted` status rather than a transport error. */
+export declare class BudgetExhaustedError extends Error {
+    constructor();
+}
+/** Parse a model reply into a Patch. Tolerates markdown fences and leading text. */
+export declare function parsePatch(raw: string): Patch;
+/** Sentinel model name for the free, no-key rule-based fixer. */
+export declare const RULE_TIER = "__rule__";
+/**
+ * Rule-based fix for the most common crash — a null/undefined property access.
+ * Adds `?.` (optional chaining) at the failing access. Returns null when the
+ * error isn't a null/undefined deref or the line can't be located. Free and
+ * offline: no LLM, no key, no network — so `--fix` works out of the box for the
+ * most frequent frontend crashes.
+ */
+export declare function generateRulePatch(ctx: HealContext): Patch | null;
+export declare function generatePatch(ctx: HealContext, opts?: GenerateOptions): Promise<Patch>;

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/redact.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Secret redaction layer — F10 gate #1. Before any byte leaves the machine
+ * (sent to an LLM, written to a log, streamed to a dashboard) it passes through
+ * here. Redaction is *reversible*: the caller keeps the placeholder→secret map
+ * so a generated Search & Replace diff (which references placeholders) can be
+ * unredacted back onto the raw source before it is applied.
+ */
+export interface Redaction {
+    text: string;
+    map: Map<string, string>;
+}
+export declare function redact(input: string): Redaction;
+/** Reverse a redaction: swap every placeholder back to its original secret. */
+export declare function unredact(input: string, map: Map<string, string>): string;
+/**
+ * Irreversible secret scrub for anything rendered to a human or written to a
+ * report / PR comment. Runs the same patterns as `redact()` but discards the
+ * map — every secret collapses to a fixed `[REDACTED]` token — then scrubs
+ * emails, which `redact()` deliberately leaves alone (they aren't secrets and
+ * the reversible layer must not mangle non-secret code it may need to patch).
+ */
+export declare function sanitizeSecrets(input: string): string;

package/dist/core/heal/sandbox.d.ts

@@ -0,0 +1,54 @@
+/**
+ * F10 gate #3 — isolated Git worktree sandbox. A patch is never applied to the
+ * user's working tree: it lands in a detached `git worktree`, is verified there,
+ * and the only artifact that escapes is a `.patch` file for a human to review
+ * and apply. Aztrx never commits — humans do.
+ */
+import type { PatchHunk, TestGateResult } from "./types.js";
+export interface Worktree {
+    dir: string;
+    cleanup: () => Promise<void>;
+}
+export interface ApplyResult {
+    ok: boolean;
+    patched: string;
+    applied: number;
+    errors: string[];
+}
+/** Create a detached worktree at HEAD in a temp dir (outside the repo). */
+export declare function createWorktree(repoRoot: string, label: string): Promise<Worktree>;
+/** Apply Search & Replace hunks to an in-memory file. Each `search` must match
+ * exactly once; ambiguous or missing matches fail the whole apply (no partial
+ * writes). Pure — the caller decides where the result lands. */
+export declare function applyHunks(content: string, hunks: PatchHunk[]): ApplyResult;
+/** Write the patched file into the worktree, refusing to escape it. */
+export declare function writeWorktreeFile(worktreeDir: string, repoRelativePath: string, content: string): string | null;
+/** Produce a unified diff of the patched file against HEAD in the worktree. */
+export declare function diffWorktree(worktreeDir: string, repoRelativePath: string): Promise<string>;
+/** Run `tsc --noEmit` against the patched worktree — the full type check that
+ * follows the AST syntax gate. Best-effort: passes (skips) when the repo has no
+ * TypeScript or the worktree has no tsconfig, so non-TS projects aren't blocked.
+ * The worktree has no node_modules; a symlink to the root's is created first and
+ * removed with the worktree on cleanup.
+ *
+ * Unlike every other gate here, this one is whole-project work: `tsc` type-checks
+ * the entire repository, so its cost scales with the repo, and on a very large
+ * one it is minutes. It therefore carries a ceiling — and a timeout is reported
+ * as *skipped*, not failed. "The compiler never reached a verdict" is a different
+ * sentence from "the patch is broken", and conflating them would silently discard
+ * good fixes on exactly the large repos this ceiling exists to protect. */
+export declare function typecheckWorktree(worktreeDir: string, repoRoot: string, opts?: {
+    timeoutMs?: number;
+}): Promise<{
+    ok: boolean;
+    ran: boolean;
+    output: string;
+}>;
+/** Run the repo's own test suite inside the patched worktree. Best-effort: skips
+ * (passes by omission) when there is no `test` script to run, so untested or
+ * non-JS projects are never blocked. `CI=true` is set so watch-mode runners exit
+ * instead of hanging until the timeout. */
+export declare function runTests(worktreeDir: string, repoRoot: string, opts?: {
+    command?: string;
+    timeoutMs?: number;
+}): Promise<TestGateResult>;

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 });
         },
@@ -76,8 +119,15 @@ export async function diffWorktree(worktreeDir, repoRelativePath) {
  * follows the AST syntax gate. Best-effort: passes (skips) when the repo has no
  * TypeScript or the worktree has no tsconfig, so non-TS projects aren't blocked.
  * The worktree has no node_modules; a symlink to the root's is created first and
- * removed with the worktree on cleanup. */
-export async function typecheckWorktree(worktreeDir, repoRoot) {
+ * removed with the worktree on cleanup.
+ *
+ * Unlike every other gate here, this one is whole-project work: `tsc` type-checks
+ * the entire repository, so its cost scales with the repo, and on a very large
+ * one it is minutes. It therefore carries a ceiling — and a timeout is reported
+ * as *skipped*, not failed. "The compiler never reached a verdict" is a different
+ * sentence from "the patch is broken", and conflating them would silently discard
+ * good fixes on exactly the large repos this ceiling exists to protect. */
+export async function typecheckWorktree(worktreeDir, repoRoot, opts = {}) {
     const tscBin = path.join(repoRoot, "node_modules", "typescript", "bin", "tsc");
     const hasTsconfig = fs.existsSync(path.join(worktreeDir, "tsconfig.json"));
     if (!fs.existsSync(tscBin) || !hasTsconfig) {
@@ -93,12 +143,22 @@ export async function typecheckWorktree(worktreeDir, repoRoot) {
             /* symlink failed — tsc reports its own resolution errors below */
         }
     }
+    const timeoutMs = opts.timeoutMs ?? 300000;
     try {
-        const { stdout } = await execFileP(process.execPath, [tscBin, "--noEmit", "-p", worktreeDir], { cwd: worktreeDir, maxBuffer: 10 * 1024 * 1024, env: buildChildEnv() });
+        const { stdout } = await execFileP(process.execPath, [tscBin, "--noEmit", "-p", worktreeDir], { cwd: worktreeDir, timeout: timeoutMs, maxBuffer: 10 * 1024 * 1024, env: buildChildEnv() });
         return { ok: true, ran: true, output: stdout.trim() };
     }
     catch (e) {
         const err = e;
+        // A timeout kills the child; that is not a compile error. Skip the gate and
+        // say why, rather than reporting a verdict the compiler never gave.
+        if (err.killed || err.signal) {
+            return {
+                ok: true,
+                ran: false,
+                output: `tsc did not finish within ${timeoutMs}ms — type check skipped`,
+            };
+        }
         return { ok: false, ran: true, output: ((err.stdout ?? "") + (err.stderr ?? "")).trim() };
     }
 }

package/dist/core/heal/types.d.ts

@@ -0,0 +1,102 @@
+import type { Finding, RecordedAction } from "../types.js";
+export type HealStatus = "healed" | "unfixed" | "rejected" | "compile-failed" | "apply-failed" | "test-failed" | "skipped" | "no-llm" | "budget-exhausted";
+/** One Search & Replace edit. `search` is an exact, unique substring of the
+ * source file; `replace` is its replacement. */
+export interface PatchHunk {
+    search: string;
+    replace: string;
+}
+export interface Patch {
+    explanation: string;
+    hunks: PatchHunk[];
+}
+export interface GateViolation {
+    rule: string;
+    detail: string;
+}
+export interface GateResult {
+    ok: boolean;
+    violations: GateViolation[];
+}
+/** Context handed to the patch generator. `redactedContent` is what may leave
+ * the machine; `fileContent` is the raw bytes used for applying the edit. */
+export interface HealContext {
+    finding: Finding;
+    filePath: string;
+    fileContent: string;
+    redactedContent: string;
+}
+/** Shared, mutable cap on paid LLM generations across a whole patrol session.
+ * `generatePatch` decrements `remaining` each time it pays for a completion; once
+ * it hits 0 generation stops and heal reports `budget-exhausted`. The free
+ * rule-based fixer never touches it. One object is threaded through every
+ * `run()`/`heal()` of a session so the cap spans cycles, not just one run. */
+export interface SpendBudget {
+    remaining: number;
+}
+export interface VerifyResult {
+    runs: number;
+    reproductions: number;
+    /** Of `runs`, how many actually loaded the app. `fixed` requires this to be
+     * non-zero: a run whose page never loaded proves nothing, and counting it as a
+     * non-reproduction is how a patch gets declared verified without being tried. */
+    loaded: number;
+    fixed: boolean;
+}
+export interface TestGateResult {
+    /** False when there was no test script to run — the gate passes by omission. */
+    ran: boolean;
+    ok: boolean;
+    command: string;
+    /** Tail of the test output, already truncated. */
+    output: string;
+}
+export interface HealOptions {
+    repoRoot: string;
+    url: string;
+    /** Minimized repro actions (F7 output). */
+    actions: RecordedAction[];
+    fingerprint: string;
+    allowHosts: string[];
+    /** Fallback model (the last tier tried). Defaults to `claude-sonnet-5`. */
+    model?: string;
+    /** Fast/cheap first tier. Defaults to `claude-haiku-4-5` (`AZTRX_FAST_MODEL`). */
+    fastModel?: string;
+    /** Inject a patch generator for testing/demo (bypasses the network LLM). */
+    patchFn?: (ctx: HealContext) => Promise<Patch>;
+    /** Shared session budget for paid generations (see `SpendBudget`). */
+    budget?: SpendBudget;
+    /** Inject an app server for the patched code. Default: static file server. */
+    serve?: (worktreeDir: string, filePath: string) => Promise<{
+        url: string;
+        close: () => Promise<void>;
+    }>;
+    /** How to boot the patched app for server (network_5xx) findings. Auto-detected
+     * from package.json `scripts.dev` / `scripts.start` when omitted. */
+    startCommand?: string;
+    verifyRuns?: number;
+    /** Override the test command run against a healed patch (default: `npm test`,
+     * auto-detected from package.json). */
+    testCommand?: string;
+    /** Timeout for the test gate, ms (default 300000). */
+    testTimeoutMs?: number;
+    /** Skip the test gate entirely. */
+    skipTest?: boolean;
+}
+export interface HealResult {
+    status: HealStatus;
+    findingId: string;
+    filePath: string;
+    explanation?: string;
+    hunks: PatchHunk[];
+    violations: GateViolation[];
+    verification?: VerifyResult;
+    test?: TestGateResult;
+    /** Path to the saved unified-diff patch artifact (.aztrx/heal/…, gitignored). */
+    patchPath?: string;
+    error?: string;
+    /** Model that produced the returned patch (the winning tier). */
+    model?: string;
+    /** All tiers attempted, in order, for observability in the PR bot. */
+    tiers?: string[];
+}

package/dist/core/heal/verify.d.ts

@@ -0,0 +1,37 @@
+/**
+ * F10 — automated verification. Reuses the repro engine (F9) but inverts the
+ * question: the bug must *stop* reproducing against the patched code. If the
+ * fingerprint is still seen after the fix, the loop rejects the patch rather
+ * than handing the human a lie.
+ */
+import type { ReplayResult } from "../replay.js";
+import type { FindingType, RecordedAction } from "../types.js";
+import type { VerifyResult } from "./types.js";
+/** The slice of the replay engine verification depends on. Production passes a
+ * real browser-backed `ReplayEngine`; tests inject a stub so the pass/fail logic
+ * is exercised without launching Chromium. */
+export interface Verifier {
+    run(url: string, actions: RecordedAction[], targetFingerprint: string, opts?: {
+        targetType?: FindingType;
+    }): Promise<ReplayResult>;
+    close(): Promise<void>;
+}
+export interface VerifyOptions {
+    /** The URL the finding was recorded against. Retained for callers/reporting;
+     * replays run against the served URL, never this origin. */
+    url: string;
+    actions: RecordedAction[];
+    fingerprint: string;
+    runs?: number;
+    /** Start the patched app and return its URL + a close hook. */
+    serve: () => Promise<{
+        url: string;
+        close: () => Promise<void>;
+    }>;
+    /** For network findings: verify by signal type (origin-agnostic) instead of the
+     * exact fingerprint. */
+    targetType?: FindingType;
+    /** Replay engine override — tests only. Defaults to a real browser-backed one. */
+    engine?: Verifier;
+}
+export declare function verifyFix(opts: VerifyOptions): Promise<VerifyResult>;

package/dist/core/heal/verify.js

@@ -23,29 +23,43 @@ function rewriteOrigin(raw, serveUrl) {
 }
 export async function verifyFix(opts) {
     const { url: serveUrl, close } = await opts.serve();
-    const engine = new ReplayEngine();
+    const engine = opts.engine ?? new ReplayEngine();
     try {
-        const runs = opts.runs ?? 3;
+        // Never zero. `fixed` is derived from the reproduction count, so a caller that
+        // asks for 0 runs would otherwise get "fixed: true" out of *no attempts at
+        // all* — a patch declared verified on the strength of never having been run.
+        const runs = Math.max(1, Math.trunc(opts.runs ?? 3));
         let reproductions = 0;
-        const actions = opts.targetType
-            ? opts.actions.map((a) => {
-                if (a.type === "request" && a.request) {
-                    return { ...a, request: { ...a.request, url: rewriteOrigin(a.request.url, serveUrl) } };
-                }
-                if (a.type === "navigate" && a.value) {
-                    return { ...a, value: rewriteOrigin(a.value, serveUrl) };
-                }
-                return a;
-            })
-            : opts.actions;
+        let loaded = 0;
+        // Every recorded URL is rewritten to the served origin — for client findings
+        // too, not just network ones. The repro was recorded against the original
+        // app, so a `navigate` action left as-is would send the replay straight back
+        // to the *unpatched* server, where the bug reproduces no matter what the
+        // patch says. That reads as "unfixed" at best; when the fingerprint happens
+        // to be absent there, it reads as a verified fix that was never exercised.
+        const actions = opts.actions.map((a) => {
+            if (a.type === "request" && a.request) {
+                return { ...a, request: { ...a.request, url: rewriteOrigin(a.request.url, serveUrl) } };
+            }
+            if (a.type === "navigate" && a.value) {
+                return { ...a, value: rewriteOrigin(a.value, serveUrl) };
+            }
+            return a;
+        });
         for (let i = 0; i < runs; i++) {
             const res = opts.targetType
                 ? await engine.run(serveUrl, actions, opts.fingerprint, { targetType: opts.targetType })
                 : await engine.run(serveUrl, actions, opts.fingerprint);
+            if (res.loaded)
+                loaded += 1;
             if (res.reproduced)
                 reproductions += 1;
         }
-        return { runs, reproductions, fixed: reproductions === 0 };
+        // "Did not reproduce" only means "fixed" if the app was actually there to
+        // reproduce against. If no run loaded, this verification proved nothing about
+        // the patch — so it must not report success, or the caller writes an
+        // unverified patch into the user's working tree on the strength of it.
+        return { runs, reproductions, loaded, fixed: loaded > 0 && reproductions === 0 };
     }
     finally {
         await engine.close();

package/dist/core/httpFuzzer.d.ts

@@ -0,0 +1,33 @@
+import type { Page } from "playwright";
+import type { EventBus } from "./eventBus.js";
+export interface HttpFuzzOptions {
+    maxRequests?: number;
+    dryRun?: boolean;
+    /** Hostnames the fuzzer may target — the Node-side self-enforcement of the
+     * deny-by-default policy (the browser `networkGuard` only wraps the `Page`). */
+    allowHosts?: Set<string>;
+    /** Opt-in for POST/PUT body mutations. Default false: the fuzzer sends only
+     * GET requests (query mutations + hostile GET headers), which can't mutate
+     * server state. Set this to also probe JSON-body type-confusion and method
+     * confusion — only on endpoints you own and trust to be non-destructive. */
+    mutations?: boolean;
+    /** Opt-in: also probe endpoints the deny-list skips (delete/pay/logout/…).
+     * Off by default — these can mutate real state. */
+    allowDestructive?: boolean;
+    /** Endpoints observed live during a walk/fuzz pass (e.g. a `fetch()` fired
+     * from a click handler) that `collectEndpoints` can't see on a fresh page.
+     * Each is pushed through the same origin/static/destructive filters. */
+    seedUrls?: string[];
+    /** When false, skip the `page.goto` — the page is already loaded and
+     * positioned by the caller (folded post-walk pass). Default true. */
+    navigate?: boolean;
+}
+/**
+ * F5-http — server-side mutation fuzzer. Harvests the endpoints the app really
+ * uses, then throws seeded hostile requests at them (query overflow, JSON type
+ * confusion, header injection, method confusion). A response `status >= 500`
+ * becomes a `network_5xx` finding — same type and message format the interceptor
+ * emits for in-browser requests — so it flows through the existing
+ * ddmin → spec → validate → heal pipeline unchanged.
+ */
+export declare function httpFuzz(page: Page, targetUrl: string, bus: EventBus, opts?: HttpFuzzOptions): Promise<number>;

package/dist/core/init.d.ts

@@ -0,0 +1,21 @@
+export interface InitOptions {
+    repoRoot: string;
+    url?: string;
+    framework?: string;
+}
+export interface InitResult {
+    framework: string;
+    url: string;
+    configPath: string;
+    gitignoreUpdated: boolean;
+}
+export interface FrameworkMeta {
+    framework: string;
+    version?: string;
+}
+/** Detect the framework name plus its installed version range. */
+export declare function detectFrameworkMeta(repoRoot: string): FrameworkMeta;
+/** The port a framework's dev server listens on by default. */
+export declare function defaultPort(framework: string): number;
+/** `aztrx-cli init` — detect framework + port, scaffold aztrx.config.ts, seed .gitignore. */
+export declare function initProject(opts: InitOptions): Promise<InitResult>;

package/dist/core/init.js

@@ -31,7 +31,8 @@ export function detectFrameworkMeta(repoRoot) {
 function detectFramework(repoRoot) {
     return detectFrameworkMeta(repoRoot).framework;
 }
-function defaultPort(framework) {
+/** The port a framework's dev server listens on by default. */
+export function defaultPort(framework) {
     if (["Vite", "Svelte", "SvelteKit", "Vue", "Astro"].includes(framework))
         return 5173;
     return 3000;
@@ -44,13 +45,11 @@ export default {
   // Dev server Aztrx should attack.
   url: ${JSON.stringify(url)},
 
-  // Repo root for sourcemap → source resolution (defaults to this directory).
-  repo: ".",
-
-  // Max interactions per pass.
+  // Max interactions per pass (default: 100). --max-actions overrides this.
   maxActions: 100,
 
-  // Deny-by-default network allow-list for fuzz runs — add your API host here.
+  // Deny-by-default network allow-list — add your API host here, or every
+  // cross-origin request the app makes is refused. --allow-host adds to this.
   allowHosts: [],
 };
 `;

package/dist/core/interceptor.d.ts

@@ -0,0 +1,21 @@
+import type { Page } from "playwright";
+import type { EventBus } from "./eventBus.js";
+/**
+ * Canonical 5xx finding message. Shared by the interceptor (passive in-browser
+ * capture) and the HTTP mutation fuzzer (active Node-side capture) so the two
+ * produce byte-identical `rawMessage`s — otherwise a finding's fingerprint and
+ * its replay fingerprint would diverge and repro would never match.
+ */
+export declare function network5xxMessage(status: number, url: string): string;
+/**
+ * F1 — CDP interceptor. Attaches capture to a page and emits typed
+ * `telemetry` events on the bus. No framework hooks: works on React
+ * (17/18/19), Next.js, Vite, Svelte, Remix, and Vue alike.
+ *
+ * The subtle part: `console.error` is the ONLY runtime-level way to see
+ * errors a React Error Boundary swallows, because the boundary logs them
+ * there instead of rethrowing — so `window.onerror` / `pageerror` never fire
+ * for them. We pull the real throw-site stack off the Error *object* via
+ * `msg.args()`, not `msg.text()` (which is just the message, no stack).
+ */
+export declare function attachInterceptor(page: Page, bus: EventBus): void;

package/dist/core/llm.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Provider-agnostic LLM client. Two transports behind one `complete()`:
+ *
+ *   - Anthropic Messages API (default) — key from `ANTHROPIC_API_KEY` (or
+ *     `AZTRX_API_KEY`), primary model defaults to `claude-sonnet-5`.
+ *   - Any OpenAI-compatible `/chat/completions` endpoint — selected by setting
+ *     `AZTRX_API_BASE`. That single flag unlocks OpenAI, Grok, DeepSeek, Gemini,
+ *     Kimi, Mistral, OpenRouter, and local models (Ollama / vLLM / LM Studio)
+ *     with their existing keys.
+ *
+ * `AZTRX_MODEL` / `AZTRX_FAST_MODEL` pick the model(s); they default sensibly
+ * for Anthropic and must be set explicitly when a custom base URL is used.
+ */
+export type Provider = "anthropic" | "openai";
+export interface LlmSettings {
+    provider: Provider;
+    apiKey?: string;
+    baseUrl?: string;
+}
+/** Resolve the active provider from the environment. */
+export declare function resolveSettings(): LlmSettings;
+/** Is any provider configured? Used to decide whether to attempt an LLM call. */
+export declare function hasLlmKey(): boolean;
+/** The primary model for the active provider. */
+export declare function primaryModel(): string;
+/** The cheap/fast first tier, or undefined when the provider has none. */
+export declare function fastModel(): string | undefined;
+export interface CompleteOptions {
+    system: string;
+    prompt: string;
+    model?: string;
+    maxTokens?: number;
+    temperature?: number;
+}
+/** Run one completion against the active provider and return the text. */
+export declare function complete(opts: CompleteOptions): Promise<string>;