aztrx-cli 0.1.0

package/dist/core/heal/verify.js

@@ -0,0 +1,25 @@
+/**
+ * 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 { ReplayEngine } from "../replay.js";
+export async function verifyFix(opts) {
+    const { url: serveUrl, close } = await opts.serve();
+    const engine = new ReplayEngine();
+    try {
+        const runs = opts.runs ?? 3;
+        let reproductions = 0;
+        for (let i = 0; i < runs; i++) {
+            const res = await engine.run(serveUrl, opts.actions, opts.fingerprint);
+            if (res.reproduced)
+                reproductions += 1;
+        }
+        return { runs, reproductions, fixed: reproductions === 0 };
+    }
+    finally {
+        await engine.close();
+        await close().catch(() => { });
+    }
+}

package/dist/core/init.js

@@ -0,0 +1,74 @@
+import * as fs from "fs";
+import * as path from "path";
+// Priority order for detection — first dependency match wins.
+const DETECT_ORDER = [
+    ["next", "Next.js"],
+    ["nuxt", "Nuxt"],
+    ["remix", "Remix"],
+    ["astro", "Astro"],
+    ["sveltekit", "SvelteKit"],
+    ["svelte", "Svelte"],
+    ["vue", "Vue"],
+    ["vite", "Vite"],
+    ["react", "React"],
+];
+/** Detect the framework name plus its installed version range. */
+export function detectFrameworkMeta(repoRoot) {
+    try {
+        const raw = fs.readFileSync(path.join(repoRoot, "package.json"), "utf-8");
+        const pkg = JSON.parse(raw);
+        const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+        for (const [dep, name] of DETECT_ORDER) {
+            if (deps[dep])
+                return { framework: name, version: deps[dep] };
+        }
+    }
+    catch {
+        // no package.json — fall through to "unknown"
+    }
+    return { framework: "unknown" };
+}
+function detectFramework(repoRoot) {
+    return detectFrameworkMeta(repoRoot).framework;
+}
+function defaultPort(framework) {
+    if (["Vite", "Svelte", "SvelteKit", "Vue", "Astro"].includes(framework))
+        return 5173;
+    return 3000;
+}
+function configTemplate(framework, url) {
+    return `// aztrx.config.ts — generated by \`aztrx init\` (framework: ${framework})
+// Docs: https://aztrx.app/docs/config
+
+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.
+  maxActions: 100,
+
+  // Deny-by-default network allow-list for fuzz runs — add your API host here.
+  allowHosts: [],
+};
+`;
+}
+/** `aztrx init` — detect framework + port, scaffold aztrx.config.ts, seed .gitignore. */
+export async function initProject(opts) {
+    const repoRoot = path.resolve(opts.repoRoot);
+    const framework = opts.framework ?? detectFramework(repoRoot);
+    const url = opts.url ?? `http://localhost:${defaultPort(framework)}`;
+    const configPath = path.join(repoRoot, "aztrx.config.ts");
+    fs.writeFileSync(configPath, configTemplate(framework, url), "utf-8");
+    const gitignorePath = path.join(repoRoot, ".gitignore");
+    const existing = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, "utf-8") : "";
+    let gitignoreUpdated = false;
+    if (!/(^|\n)\.aztrx\/\s*\n?/.test(existing)) {
+        const sep = existing === "" || existing.endsWith("\n") ? "" : "\n";
+        fs.appendFileSync(gitignorePath, `${sep}.aztrx/\n`);
+        gitignoreUpdated = true;
+    }
+    return { framework, url, configPath, gitignoreUpdated };
+}

package/dist/core/interceptor.js

@@ -0,0 +1,93 @@
+import { extractFrame } from "./resolver.js";
+// Route unhandled rejections through console.error so a single capture path
+// handles them alongside React Error Boundary logs (both land in console.error).
+const INIT_SCRIPT = `
+  window.addEventListener("unhandledrejection", (event) => {
+    const reason = event.reason instanceof Error ? event.reason : new Error(String(event.reason));
+    console.error("Unhandled Promise Rejection:", reason);
+  });
+`;
+/**
+ * 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 function attachInterceptor(page, bus) {
+    page.on("console", async (msg) => {
+        if (msg.type() !== "error")
+            return;
+        const text = msg.text();
+        // The init script routes `unhandledrejection` through console.error with a
+        // fixed prefix; recover the true signal type so Server Action failures and
+        // other promise rejections classify as "error", not "warning".
+        const type = text.startsWith("Unhandled Promise Rejection:")
+            ? "unhandled_rejection"
+            : "console_error";
+        let source = text;
+        for (const arg of msg.args()) {
+            try {
+                const s = await arg.evaluate((a) => a instanceof Error ? a.stack || String(a) : String(a));
+                if (s.includes("http")) {
+                    source = s;
+                    break;
+                }
+            }
+            catch {
+                // non-serializable arg — keep msg.text()
+            }
+        }
+        const loc = msg.location();
+        const frame = extractFrame(source) ??
+            ({ url: loc.url, line: loc.lineNumber, column: loc.columnNumber, message: text.split("\n")[0].slice(0, 200) });
+        bus.emit("telemetry", {
+            type,
+            rawMessage: frame.message,
+            rawStack: source,
+            url: frame.url,
+            line: frame.line,
+            column: frame.column,
+        });
+    });
+    page.on("crash", () => {
+        bus.emit("telemetry", {
+            type: "uncaught_exception",
+            rawMessage: "Renderer process crashed",
+            rawStack: "",
+        });
+    });
+    page.on("pageerror", (err) => {
+        const frame = extractFrame(err.stack ?? "");
+        bus.emit("telemetry", {
+            type: "uncaught_exception",
+            rawMessage: err.message,
+            rawStack: err.stack ?? err.message,
+            url: frame?.url,
+            line: frame?.line,
+            column: frame?.column,
+        });
+    });
+    page.on("requestfailed", (req) => {
+        const f = req.failure();
+        bus.emit("telemetry", {
+            type: "network_timeout",
+            rawMessage: `Request failed: ${req.url()} (${f?.errorText ?? "unknown"})`,
+            rawStack: "",
+        });
+    });
+    page.on("response", (res) => {
+        if (res.status() >= 500) {
+            bus.emit("telemetry", {
+                type: "network_5xx",
+                rawMessage: `HTTP ${res.status()} ${res.url()}`,
+                rawStack: "",
+            });
+        }
+    });
+    page.addInitScript(INIT_SCRIPT);
+}

package/dist/core/minimizer.js

@@ -0,0 +1,48 @@
+/**
+ * F7 — ddmin (delta debugging). Shrinks the failing action sequence to a
+ * minimal subset that still reproduces `fingerprint`. Best-effort under a
+ * replay budget; a sequence shorter than 2 actions is returned as-is.
+ */
+export async function minimize(engine, actions, opts) {
+    let current = [...actions];
+    if (current.length < 2)
+        return current;
+    let budget = opts.maxReplays ?? 15;
+    const fails = async (subset) => {
+        if (budget <= 0)
+            return false;
+        budget -= 1;
+        const res = await engine.run(opts.url, subset, opts.fingerprint);
+        return res.reproduced;
+    };
+    // Sanity: does the full sequence even reproduce?
+    if (!(await fails(current)))
+        return actions;
+    while (current.length >= 2 && budget > 0) {
+        let n = 2;
+        let reducedThisPass = false;
+        while (n <= current.length && budget > 0) {
+            const chunkSize = Math.ceil(current.length / n);
+            let reduced = false;
+            for (let i = 0; i < current.length; i += chunkSize) {
+                const complement = current.slice(0, i).concat(current.slice(i + chunkSize));
+                if (complement.length === 0 || complement.length === current.length)
+                    continue;
+                if (await fails(complement)) {
+                    current = complement;
+                    reduced = true;
+                    reducedThisPass = true;
+                    break; // restart partitioning from n=2
+                }
+            }
+            if (reduced)
+                break;
+            if (n >= current.length)
+                break;
+            n = Math.min(n * 2, current.length);
+        }
+        if (!reducedThisPass)
+            break;
+    }
+    return current;
+}

package/dist/core/networkGuard.js

@@ -0,0 +1,49 @@
+/**
+ * F6 — deny-by-default network guard (PRD §6.2). Aborts every request whose
+ * host isn't allow-listed, so a fuzz/replay pass can't reach payment, delete,
+ * or analytics endpoints. Loopback is always allowed (this is a local tool).
+ */
+export async function attachNetworkGuard(page, opts) {
+    await page.route("**/*", async (route) => {
+        const url = route.request().url();
+        let host;
+        try {
+            host = new URL(url).hostname.toLowerCase();
+        }
+        catch {
+            await route.abort();
+            return;
+        }
+        if (host === "localhost" || host === "127.0.0.1" || host === "::1") {
+            await route.continue();
+            return;
+        }
+        for (const h of opts.allowHosts) {
+            if (host === h || host.endsWith("." + h)) {
+                await route.continue();
+                return;
+            }
+        }
+        opts.onBlock?.(url);
+        await route.abort();
+    });
+}
+/** Builds the allow-list: target origin + each `--allow-host`. */
+export function allowHostsFrom(url, extra) {
+    const hosts = new Set();
+    try {
+        hosts.add(new URL(url).hostname.toLowerCase());
+    }
+    catch {
+        // ignore malformed target
+    }
+    for (const h of extra) {
+        try {
+            hosts.add(new URL(h.includes("://") ? h : `http://${h}`).hostname.toLowerCase());
+        }
+        catch {
+            // ignore malformed host
+        }
+    }
+    return hosts;
+}

package/dist/core/orchestrator.js

@@ -0,0 +1,337 @@
+import * as path from "path";
+import { chromium } from "playwright";
+import pc from "picocolors";
+import { EventBus } from "./eventBus.js";
+import { attachInterceptor } from "./interceptor.js";
+import { SignalClassifier, loadBaseline } from "./classifier.js";
+import { ActionRecorder } from "./recorder.js";
+import { walkDom } from "./domWalker.js";
+import { fuzz } from "./fuzzer.js";
+import { attachNetworkGuard, allowHostsFrom } from "./networkGuard.js";
+import { resolveFrame } from "./resolver.js";
+import { ReplayEngine } from "./replay.js";
+import { minimize } from "./minimizer.js";
+import { writeSpec } from "./specCompiler.js";
+import { validate } from "./validator.js";
+import { writeReport } from "./report.js";
+import { RunLog } from "./events.js";
+import { heal } from "./heal/index.js";
+import { submitTelemetry } from "./telemetry/index.js";
+import { submitRun } from "./cloud/index.js";
+const SEVERITY_MARK = {
+    crash: pc.red("● crash "),
+    error: pc.red("● error "),
+    warning: pc.yellow("○ warning "),
+    noise: pc.dim("○ noise "),
+};
+function printFinding(f, write) {
+    write(SEVERITY_MARK[f.severity] + pc.bold(f.rawMessage));
+    if (f.mappedLocation) {
+        write(pc.dim(`   ${f.mappedLocation.filePath}:${f.mappedLocation.line}:${f.mappedLocation.column}`));
+        write(pc.dim(f.mappedLocation.codeContext));
+    }
+    if (f.occurrences > 1)
+        write(pc.dim(`   (×${f.occurrences})`));
+    write("");
+}
+/** Human-readable run mode, surfaced in the cloud dashboard. */
+function runMode(o) {
+    if (o.fuzz)
+        return `fuzz (seed ${o.seed ?? 42})`;
+    if (o.heal)
+        return "repro → heal";
+    if (o.repro)
+        return "repro";
+    return "deterministic walk";
+}
+/**
+ * The run's finite state machine: launch → (guard) → intercept → act (walk or
+ * fuzz) → classify → map → report → repro (minimize/compile/validate). Modules
+ * communicate only through the EventBus; the orchestrator is the single place
+ * that wires them together. In `ui` mode it emits structured events (phase,
+ * action, finding, repro, route, noise) and stays silent on stdout, so a
+ * terminal renderer (Ink) can draw the live panel instead of log lines.
+ */
+export async function run(options) {
+    const { url, repoRoot } = options;
+    const maxActions = options.maxActions ?? 100;
+    const guardOn = Boolean(options.fuzz || options.repro);
+    const allowHosts = allowHostsFrom(url, options.allowHosts ?? []);
+    const ui = options.ui === true;
+    const bus = options.bus ?? new EventBus();
+    const say = (...parts) => {
+        if (!ui)
+            console.log(parts.join(" "));
+    };
+    const emitPhase = (phase, detail) => bus.emit("phase", { phase, detail, ts: Date.now() });
+    say(pc.cyan("\n⚡ Aztrx v0.1.0 — Runtime Detector"));
+    say(pc.dim(`Target: ${url}`));
+    say(pc.dim(`Repo:   ${repoRoot}`));
+    if (options.fuzz)
+        say(pc.dim(`Mode:   fuzz (seed ${options.seed ?? 42})`));
+    if (options.repro)
+        say(pc.dim(`Mode:   repro (${options.reproRuns ?? 3} runs)`));
+    if (guardOn)
+        say(pc.dim(`Net:    deny-by-default → allow ${[...allowHosts].join(", ") || "origin"}`));
+    if (options.storageState)
+        say(pc.dim(`Auth:   ${options.storageState}`));
+    say("");
+    emitPhase("launch", url);
+    const classifier = new SignalClassifier(await loadBaseline(repoRoot));
+    const recorder = new ActionRecorder();
+    const runLog = new RunLog(repoRoot);
+    runLog.reset();
+    runLog.append({ type: "run_start", url, ts: Date.now() });
+    bus.on("action", (a) => recorder.record(a));
+    bus.on("telemetry", async (payload) => {
+        const finding = classifier.classify(payload);
+        if (!finding)
+            return;
+        finding.actionHistory = recorder.snapshot();
+        if (finding.severity === "noise") {
+            bus.emit("noise", { ts: Date.now() });
+            return;
+        }
+        runLog.append({ type: "finding", finding });
+        if (payload.url && payload.line) {
+            const resolved = await resolveFrame({ url: payload.url, line: payload.line, column: payload.column ?? 0, message: payload.rawMessage }, repoRoot);
+            finding.mappedLocation = {
+                filePath: resolved.sourceFile,
+                line: resolved.line,
+                column: resolved.column,
+                codeContext: resolved.codeSnippet,
+                isOwnCode: resolved.resolvedFrom !== "unresolved",
+            };
+        }
+        bus.emit("finding", finding);
+        printFinding(finding, say);
+    });
+    const browser = await chromium.launch({ headless: true });
+    const context = await browser.newContext(options.storageState ? { storageState: options.storageState } : {});
+    const page = await context.newPage();
+    attachInterceptor(page, bus);
+    if (guardOn) {
+        await attachNetworkGuard(page, {
+            allowHosts,
+            onBlock: (u) => say(pc.dim(`  [guard] blocked ${u}`)),
+        });
+    }
+    page.on("framenavigated", (frame) => {
+        if (frame === page.mainFrame())
+            bus.emit("route", { url: frame.url(), ts: Date.now() });
+    });
+    let loaded = true;
+    await page.goto(url, { waitUntil: "load", timeout: 30000 }).catch((e) => {
+        loaded = false;
+        say(pc.red("Failed to load target: ") + pc.dim(e.message));
+    });
+    if (loaded) {
+        // Settle: wait for hydration and mount-time effects (async fetches,
+        // unhandled rejections, React warnings) to fire before we act. A page whose
+        // only bugs are mount-time would otherwise be closed before they happen —
+        // and a page with no interactive elements fuzzes zero actions, so it relies
+        // on this window.
+        await page.waitForTimeout(2000);
+    }
+    if (loaded && options.crashTest) {
+        await page.evaluate(() => {
+            setTimeout(() => {
+                throw new Error("Aztrx test: Cannot read properties of undefined (reading 'token')");
+            }, 300);
+        });
+        await page.waitForTimeout(800);
+    }
+    if (loaded) {
+        emitPhase(options.fuzz ? "fuzz" : "walk");
+        const acted = options.fuzz
+            ? await fuzz(page, bus, { seed: options.seed, maxActions, dryRun: options.dryRun })
+            : await walkDom(page, bus, { maxActions, dryRun: options.dryRun });
+        say(pc.dim(`\n${options.fuzz ? "Fuzzed" : "Walked"} ${acted} action(s).\n`));
+    }
+    await page.waitForTimeout(500);
+    await browser.close();
+    const findings = classifier.findings();
+    // F7 → F8 → F9: minimize each finding, compile an executable spec, validate
+    // the flake rate. Only crash/error findings with a recorded action history.
+    if (options.repro) {
+        const engine = new ReplayEngine({
+            attachGuard: async (p) => attachNetworkGuard(p, { allowHosts }),
+            storageState: options.storageState,
+        });
+        try {
+            const targets = findings.filter((f) => (f.severity === "crash" || f.severity === "error") && f.actionHistory.length > 0);
+            if (targets.length)
+                say(pc.cyan("— Repro pipeline (minimize → compile → validate) —"));
+            emitPhase("repro");
+            for (const f of targets) {
+                try {
+                    const minimal = await minimize(engine, f.actionHistory, { url, fingerprint: f.fingerprint });
+                    const specPath = writeSpec(repoRoot, f, minimal, url);
+                    const v = await validate(engine, url, f, minimal, options.reproRuns ?? 3);
+                    f.repro = {
+                        actions: minimal,
+                        specPath,
+                        verdict: v.verdict,
+                        rate: v.rate,
+                        runs: v.runs,
+                        reproductions: v.reproductions,
+                    };
+                    bus.emit("repro", {
+                        finding: f,
+                        verdict: v.verdict,
+                        runs: v.runs,
+                        reproductions: v.reproductions,
+                        steps: minimal.length,
+                        totalSteps: f.actionHistory.length,
+                        specPath: path.relative(repoRoot, specPath),
+                    });
+                    runLog.append({
+                        type: "repro",
+                        fingerprint: f.fingerprint,
+                        verdict: v.verdict,
+                        runs: v.runs,
+                        reproductions: v.reproductions,
+                        steps: minimal.length,
+                        totalSteps: f.actionHistory.length,
+                        specPath: path.relative(repoRoot, specPath),
+                    });
+                    const mark = v.verdict === "deterministic"
+                        ? pc.green("  ✓ deterministic")
+                        : v.verdict === "flaky"
+                            ? pc.yellow("  ◐ flaky")
+                            : pc.red("  ✗ unreliable");
+                    say(`${mark}  ${pc.bold(f.rawMessage.split("\n")[0].slice(0, 60))}  (${minimal.length}/${f.actionHistory.length} steps, ${v.reproductions}/${v.runs} runs)`);
+                    say(pc.dim(`        spec: ${path.relative(repoRoot, specPath)}`));
+                }
+                catch (e) {
+                    // One finding's repro failing must not abort the whole run — record it
+                    // as unreliable and move on to the next target.
+                    f.repro = { actions: [], specPath: "", verdict: "unreliable", rate: 0, runs: 0, reproductions: 0 };
+                    bus.emit("repro", {
+                        finding: f,
+                        verdict: "unreliable",
+                        runs: 0,
+                        reproductions: 0,
+                        steps: 0,
+                        totalSteps: f.actionHistory.length,
+                        specPath: "",
+                    });
+                    runLog.append({
+                        type: "repro",
+                        fingerprint: f.fingerprint,
+                        verdict: "unreliable",
+                        runs: 0,
+                        reproductions: 0,
+                        steps: 0,
+                        totalSteps: f.actionHistory.length,
+                        specPath: "",
+                    });
+                    say(pc.red(`  ✗ repro failed: ${e.message.split("\n")[0]}`));
+                }
+            }
+        }
+        finally {
+            await engine.close();
+        }
+    }
+    // F10 — closed-loop healing. For each crash/error finding with an own-code
+    // source location and a deterministic repro, generate a patch, gate it, apply
+    // it in a sandboxed worktree, and verify the bug stops reproducing. Opt-in;
+    // the patch is only ever handed to a human for review, never committed.
+    if (options.heal) {
+        const healTargets = findings.filter((f) => (f.severity === "crash" || f.severity === "error") &&
+            f.mappedLocation?.isOwnCode &&
+            f.repro &&
+            f.repro.verdict !== "unreliable");
+        if (healTargets.length) {
+            say(pc.cyan("— Closed-loop healing (redact → generate → gate → sandbox → verify) —"));
+            emitPhase("heal");
+            for (const f of healTargets) {
+                say(pc.dim(`  healing: ${f.rawMessage.split("\n")[0].slice(0, 60)}`));
+                try {
+                    const result = await heal(f, {
+                        repoRoot,
+                        url,
+                        actions: f.repro.actions,
+                        fingerprint: f.fingerprint,
+                        allowHosts: [...allowHosts],
+                        model: options.healModel,
+                        fastModel: options.healFastModel,
+                    });
+                    f.heal = result;
+                    bus.emit("heal", {
+                        finding: f,
+                        status: result.status,
+                        patchPath: result.patchPath,
+                        error: result.error,
+                    });
+                    runLog.append({
+                        type: "heal",
+                        fingerprint: f.fingerprint,
+                        status: result.status,
+                        patchPath: result.patchPath,
+                        error: result.error,
+                    });
+                    const mark = result.status === "healed"
+                        ? pc.green("  ✓ healed")
+                        : result.status === "unfixed"
+                            ? pc.yellow("  ◐ unfixed")
+                            : pc.red(`  ✗ ${result.status}`);
+                    say(`${mark}  ${pc.bold(f.rawMessage.split("\n")[0].slice(0, 60))}`);
+                    if (result.patchPath)
+                        say(pc.dim(`        patch: ${path.relative(repoRoot, result.patchPath)}`));
+                    if (result.error)
+                        say(pc.dim(`        ${result.error}`));
+                }
+                catch (e) {
+                    f.heal = {
+                        status: "skipped",
+                        findingId: f.id,
+                        filePath: f.mappedLocation?.filePath ?? "",
+                        hunks: [],
+                        violations: [],
+                        error: e.message,
+                    };
+                    bus.emit("heal", { finding: f, status: "skipped", error: e.message });
+                    runLog.append({ type: "heal", fingerprint: f.fingerprint, status: "skipped", error: e.message });
+                    say(pc.dim(`  ✗ heal error: ${e.message}`));
+                }
+            }
+        }
+    }
+    const reportPath = writeReport(repoRoot, url, findings);
+    say(pc.dim(`Report: ${path.relative(repoRoot, reportPath)}`));
+    const counts = {};
+    for (const f of findings)
+        counts[f.severity] = (counts[f.severity] ?? 0) + 1;
+    // F11 — opt-in telemetry. Local-only under `--telemetry`; uploads under
+    // `--share-data`. Fire-and-forget, sanitized, and never affects exit codes.
+    if (options.telemetry || options.shareData) {
+        submitTelemetry(findings, {
+            repoRoot,
+            url,
+            telemetry: Boolean(options.telemetry),
+            shareData: Boolean(options.shareData),
+            endpoint: options.telemetryUrl,
+            apiKey: options.apiKey,
+        });
+    }
+    // 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) {
+        submitRun(findings, {
+            repoRoot,
+            url,
+            apiKey: options.apiKey,
+            endpoint: options.cloudUrl,
+            mode: runMode(options),
+            counts,
+        });
+    }
+    runLog.append({ type: "run_end", counts, ts: Date.now() });
+    say(pc.dim("────────────────────────────────────────────"));
+    say(pc.cyan(`${findings.length} unique finding(s)`));
+    say(pc.dim(`crash: ${counts.crash ?? 0}   error: ${counts.error ?? 0}   warning: ${counts.warning ?? 0}`));
+    emitPhase("done");
+    return findings;
+}