aztrx-cli 0.4.4 → 0.5.1

package/dist/cli.js

@@ -5,23 +5,27 @@ import * as os from "os";
 import pc from "picocolors";
 import { program } from "commander";
 import { opt, formatHelp } from "./cli/help.js";
-import { run } from "./core/orchestrator.js";
-import { EventBus } from "./core/eventBus.js";
-import { renderTui } from "./ui/app.js";
 import { initProject } from "./core/init.js";
-import { startStudio } from "./core/studio.js";
-import { writePrComment } from "./core/pr.js";
-import { writeBadge } from "./core/badge.js";
-import { writeRegressionSpecs } from "./core/specCompiler.js";
-import { flushTelemetry } from "./core/telemetry/index.js";
-import { flushCloud } from "./core/cloud/index.js";
-import { summarizeFindings } from "./core/summarize.js";
-import { applyVerifiedPatches } from "./core/heal/apply.js";
-import { openFixPr } from "./core/fixPr.js";
-import { promptYesNo, promptInput } from "./core/prompt.js";
-import { modernizeFile } from "./core/modernize.js";
-import { renderMarkdown } from "./core/renderMarkdown.js";
-import { patrol } from "./core/patrol/loop.js";
+import { VERSION } from "./core/version.js";
+import { installHook, runPrePush, uninstallHook } from "./hooks/index.js";
+/**
+ * Everything else is loaded on demand, and that is not tidiness — it is 3.3
+ * seconds off *every* invocation.
+ *
+ * Measured cold, on this repo: `ui/app.js` (ink) costs 1645ms and
+ * `core/orchestrator.js` (Playwright and the whole heal stack) costs 1710ms. As
+ * static imports they are paid before the CLI knows what it was asked to do —
+ * so `--help`, `init`, and a pre-push hook whose scan is *skipped* all pay for a
+ * browser engine they will never use. On the hook that tax was most of the
+ * runtime, which is how a hook gets uninstalled.
+ *
+ * `await import()` caches after the first call, so the commands that do need
+ * these pay exactly what they paid before.
+ */
+async function loadOrchestrator() {
+    const m = await import("./core/orchestrator.js");
+    return m.run;
+}
 function collect(value, prev) {
     prev.push(value);
     return prev;
@@ -31,34 +35,23 @@ function autoWorkers() {
     const n = typeof os.availableParallelism === "function" ? os.availableParallelism() : os.cpus().length;
     return Math.max(1, Math.min(n, 8));
 }
-/** Auto-detect the running dev server URL: `aztrx.config.ts`, the dev script's
- * `--port`, then a probe of common ports. Returns null when nothing responds. */
-async function detectUrl(repoRoot) {
-    const configPath = path.join(repoRoot, "aztrx.config.ts");
-    if (fs.existsSync(configPath)) {
-        const m = fs.readFileSync(configPath, "utf-8").match(/url\s*[=:]\s*["']([^"']+)["']/);
-        if (m)
-            return m[1];
-    }
-    const pkgPath = path.join(repoRoot, "package.json");
-    if (fs.existsSync(pkgPath)) {
-        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
-        const dev = pkg.scripts?.dev || pkg.scripts?.start || "";
-        const pm = dev.match(/(?:--port|-p)\s*[= ]?\s*(\d+)/);
-        if (pm)
-            return `http://localhost:${pm[1]}`;
-    }
-    for (const port of [3000, 5173, 8080, 3001, 4000, 8000]) {
-        try {
-            const res = await fetch(`http://localhost:${port}`, { signal: AbortSignal.timeout(300) });
-            if (res.status < 500)
-                return `http://localhost:${port}`;
-        }
-        catch {
-            // not listening — try the next port
-        }
+/** Resolve the target for a run with no explicit URL: attach to a dev server
+ * that is already up, or boot the project's own one. Prints progress as it goes
+ * (this all happens before the TUI mounts, so plain writes are safe) and exits
+ * with a specific reason when neither is possible. */
+async function resolveTargetOrExit(repoRoot, noBoot, out = (m) => console.log(m)) {
+    const { resolveTarget } = await import("./core/devServer.js");
+    const res = await resolveTarget({
+        repoRoot,
+        allowBoot: !noBoot,
+        onBoot: (plan) => out(pc.dim(`No dev server running — starting \`${plan.startCommand}\` (${plan.framework})…`)),
+    });
+    if (!res.ok) {
+        console.error(pc.red(res.error));
+        process.exit(1);
     }
-    return undefined;
+    out(pc.dim(res.detail));
+    return { url: res.url, close: res.close };
 }
 /** Print one low-key "next flag" hint after a run, so users learn the advanced
  * flags on demand instead of memorizing the whole surface. Fires only in the
@@ -87,6 +80,9 @@ function suggestNext(findings, opts) {
 program
     .name("aztrx-cli")
     .description("Runtime stress-testing for web apps — detect bugs, prove them with a repro")
+    // Read from the installed package.json, so it can never drift from the
+    // published version (see core/version.ts).
+    .version(VERSION, "-V, --version", "print the CLI version")
     .option("--repo <path>", "project root to inspect/watch (default: cwd)", process.cwd());
 program
     .command("init")
@@ -105,11 +101,111 @@ program
     console.log("");
     console.log(pc.dim(`Next:  npx aztrx-cli run ${res.url} --repo .`));
 });
+program
+    .command("hook")
+    .description("install a git hook that scans your app before you push")
+    .argument("<action>", "install | uninstall | run")
+    .argument("[name]", "hook name (default: pre-push)")
+    .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 hookName = name ?? "pre-push";
+    if (hookName !== "pre-push") {
+        console.error(pc.red(`unsupported hook: ${hookName}`) + " (only `pre-push` is wired up)");
+        process.exit(1);
+    }
+    if (action === "install" || action === "uninstall") {
+        const res = action === "install" ? installHook(repoRoot, opts.force) : uninstallHook(repoRoot);
+        if (!res.ok) {
+            console.error(pc.red(`✗ ${res.message}`));
+            process.exit(1);
+        }
+        if (res.action === "absent") {
+            console.log(pc.dim(res.message));
+            return;
+        }
+        console.log(pc.green("✓") + ` pre-push hook ${res.message}`);
+        if (res.hookPath)
+            console.log(pc.dim(`  ${path.relative(repoRoot, res.hookPath).replace(/\\/g, "/")}`));
+        if (action === "install") {
+            console.log(pc.dim("  Every `git push` now scans the app and blocks on a crash."));
+            console.log(pc.dim("  Skip one push with `git push --no-verify`, or a run with AZTRX_HOOK_SKIP=1."));
+        }
+        return;
+    }
+    if (action !== "run") {
+        console.error(pc.red(`unknown action: ${action}`) + " — expected install, uninstall or run");
+        process.exit(1);
+    }
+    // The hook body. Everything is printed at the end rather than streamed: the
+    // scan runs with `--json`, which is silent by contract, so there is nothing
+    // to stream until it has an answer.
+    const res = await runPrePush({
+        repoRoot,
+        always: opts.always,
+        onProgress: (m) => console.log(pc.dim(m)),
+    });
+    for (const line of res.lines)
+        console.log(res.code === 0 ? line : pc.red(line));
+    process.exit(res.code);
+});
+program
+    .command("mcp")
+    .description("serve aztrx to your editor's agent over MCP (stdio), or wire an editor up to it")
+    .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);
+    // 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
+    // printed *in this branch* would land before that guard exists.
+    if (action === undefined) {
+        const { startServer } = await import("./mcp/index.js");
+        await startServer({ repoRoot });
+        return;
+    }
+    if (action !== "install" && action !== "uninstall") {
+        console.error(pc.red(`unknown action: ${action}`) + " — expected install, uninstall, or no action to serve");
+        process.exit(1);
+    }
+    const { installMcp, uninstallMcp } = await import("./mcp/install.js");
+    const { VERSION } = await import("./core/version.js");
+    const res = action === "install" ? installMcp(repoRoot, VERSION, opts.force) : uninstallMcp(repoRoot);
+    let refused = false;
+    for (const o of res.outcomes) {
+        const line = `${pc.bold(o.target.label)} — ${o.message}`;
+        if (o.status === "refused") {
+            refused = true;
+            console.error(pc.red("✗") + ` ${line}`);
+        }
+        else if (o.status === "written") {
+            console.log(pc.green("✓") + ` ${line}`);
+        }
+        else {
+            // skipped and unchanged are both "nothing to do", not failures.
+            console.log(pc.dim(`• ${line}`));
+        }
+    }
+    // A refused config is the one outcome the user must act on — it is the only
+    // reason to fail the command. A project with no editor we recognise is not an
+    // error, it is a project that does not use one.
+    if (refused)
+        process.exit(1);
+    if (action === "install" && !res.nothingDone) {
+        console.log("");
+        console.log(pc.dim("  Restart your editor — or reload its window — to pick the server up."));
+        console.log(pc.dim("  Scanning and proving a crash need no key. Fixing one does:"));
+        console.log(pc.dim("  set ANTHROPIC_API_KEY, or AZTRX_API_BASE + AZTRX_API_KEY + AZTRX_MODEL."));
+    }
+});
 program
     .command("studio")
     .description("start the live studio dashboard on localhost:7331")
     .option("--port <n>", "port to listen on", "7331")
-    .action((opts) => {
+    .action(async (opts) => {
+    const { startStudio } = await import("./core/studio.js");
     startStudio({ repoRoot: path.resolve(program.opts().repo), port: parseInt(opts.port, 10) });
 });
 program
@@ -120,6 +216,10 @@ program
     .action(async (file, opts) => {
     const repoRoot = path.resolve(program.opts().repo);
     const rel = path.relative(repoRoot, path.resolve(file));
+    const [{ modernizeFile }, { promptYesNo }] = await Promise.all([
+        import("./core/modernize.js"),
+        import("./core/prompt.js"),
+    ]);
     const res = await modernizeFile(repoRoot, file);
     if (!res.ok) {
         console.error(pc.red("modernize failed:") + ` ${res.error}`);
@@ -142,9 +242,10 @@ program
     .argument("[url]", "dev server to inspect (auto-detected if omitted), e.g. http://localhost:3000")
     .configureHelp({ formatHelp })
     .addOption(opt("--repo <path>", "project root to inspect/watch (default: cwd)", "advanced"))
-    .addOption(opt("--max-actions <n>", "max actions per pass", "advanced").default("100"))
+    .addOption(opt("--max-actions <n>", "max actions per pass (default: aztrx.config.ts, else 100)", "advanced"))
     .addOption(opt("--dry-run", "report what would be clicked without clicking", "detect"))
     .addOption(opt("--crash-test", "throw a deliberate error to verify capture", "advanced"))
+    .addOption(opt("--no-boot", "never start a dev server — only attach to one already running", "detect"))
     .addOption(opt("--fail-on", "exit 1 if any crash/error finding is present", "ship"))
     .addOption(opt("--fuzz", "chaos fuzzing instead of the deterministic walk (F5)", "detect"))
     .addOption(opt("--http-fuzz", "HTTP-layer mutation fuzzing — hostile requests against the target origin (F5-http)", "detect"))
@@ -170,11 +271,11 @@ program
     .addOption(opt("--lang <en|ru>", "language for the human-language summary", "advanced").default("en"))
     .addOption(opt("--pr-comment [path]", "write a GitHub PR markdown comment (default .aztrx/pr-comment.md)", "ship"))
     .addOption(opt("--badge [path]", "write a self-contained SVG badge (default .aztrx/badge.svg)", "ship"))
-    .addOption(opt("--regression-test [dir]", "copy validated repro specs into the project test dir (default: e2e/ or tests/)", "ship"))
+    .addOption(opt("--regression-test [dir]", "copy validated repro specs into the project test dir (default: first of e2e/, tests/, test/, __tests__/; else .aztrx/regression/)", "ship"))
     .addOption(opt("--telemetry", "opt-in: collect anonymized crash→repro→patch tuples locally (.aztrx/telemetry)", "advanced"))
     .addOption(opt("--share-data", "opt-in: also upload the sanitized tuples to the telemetry endpoint", "advanced"))
     .addOption(opt("--upload", "opt-in: stream run results to the Aztrx AI cloud dashboard (needs --api-key)", "advanced"))
-    .addOption(opt("--api-key <key>", "API key for --upload / --share-data (defaults to $AZTRX_API_KEY)", "advanced"))
+    .addOption(opt("--api-key <key>", "API key for --upload / --share-data (defaults to $AZTRX_CLOUD_API_KEY — a separate key from the model provider's $AZTRX_API_KEY)", "advanced"))
     .addOption(opt("--cloud-url <url>", "override the cloud ingest base URL (default https://api.aztrx.app)", "advanced"))
     .addOption(opt("--allow-host <host>", "add a host to the network allow-list (repeatable)", "advanced").argParser(collect).default([]))
     .addOption(opt("--storage-state <path>", "path to a Playwright storage-state JSON (cookies/localStorage) for authenticated pages", "auth"))
@@ -185,19 +286,45 @@ program
     .addOption(opt("--login-url <url>", "explicit login page URL for --login (default: current page)").hideHelp())
     .addOption(opt("--plain", "disable the live terminal UI, print plain logs (default when piped)", "advanced"))
     .addOption(opt("--ui", "force the live terminal UI even when stdout is not a TTY", "advanced"))
+    .addOption(opt("--json", "machine-readable result on stdout: one JSON document, nothing else", "advanced"))
     .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);
-    // Auto-detect the target when no URL is given — one less thing to type.
+    // 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");
+    // `--json` is a machine contract: one JSON document on stdout, nothing
+    // else. Every human-facing write below is suppressed, and the run itself
+    // gets `ui: true` (which already means "emit nothing, the caller renders").
+    const json = Boolean(opts.json);
+    const out = json ? () => { } : (msg) => console.log(msg);
+    // No URL given: find the app, or start it. `--no-boot` keeps the old
+    // attach-only behaviour for scripts where a surprise child process is
+    // unacceptable.
+    let booted;
     let targetUrl = url;
     if (!targetUrl) {
-        targetUrl = await detectUrl(repoRoot);
-        if (!targetUrl) {
-            console.error(pc.red("No URL given and none auto-detected. Pass <url>, or run `aztrx-cli init` first."));
-            process.exit(1);
-        }
-        console.log(pc.dim(`Auto-detected ${targetUrl}`));
+        const target = await resolveTargetOrExit(repoRoot, opts.boot === false, out);
+        targetUrl = target.url;
+        booted = target.close;
+    }
+    // A booted dev server is a child of this process — releasing it is part of
+    // finishing, so every exit path goes through here. The `process.exit`
+    // calls below would otherwise skip a `finally` block entirely.
+    const finish = async (code) => {
+        await booted?.().catch(() => { });
+        process.exit(code);
+    };
+    // Spawned by a dev-server plugin (`aztrx-cli/vite`, `aztrx-cli/next`)? The
+    // plugins open an IPC channel for exactly this: when the dev server dies,
+    // so must the scan — a browser driving an app nobody owns is worse than no
+    // scan. `disconnect` is the only reliable signal here, because it also
+    // fires when the parent was SIGKILLed, which no signal handler can catch.
+    if (process.connected) {
+        process.once("disconnect", () => {
+            void finish(0);
+        });
     }
     const workers = opts.workers ? parseInt(opts.workers, 10) : opts.swarm ? autoWorkers() : undefined;
     const mode = (workers ?? 1) > 1 || opts.httpFuzz
@@ -214,13 +341,18 @@ program
     let loginEmail = opts.loginEmail ?? process.env.AZTRX_AUTH_EMAIL;
     let loginPassword = opts.loginPassword ?? process.env.AZTRX_AUTH_PASSWORD;
     if (opts.login && !loginEmail && !loginPassword) {
+        const { promptInput } = await import("./core/prompt.js");
         loginEmail = await promptInput("Email:");
         loginPassword = await promptInput("Password:");
     }
     const runOpts = {
         url: targetUrl,
         repoRoot,
-        maxActions: parseInt(opts.maxActions, 10),
+        // Config-file defaults, with the flag winning: `--max-actions` now has no
+        // commander default, so an unset flag is distinguishable from a set one.
+        maxActions: opts.maxActions
+            ? parseInt(opts.maxActions, 10)
+            : (configMaxActions(repoRoot) ?? 100),
         dryRun: opts.dryRun,
         crashTest: opts.crashTest,
         fuzz: opts.fuzz,
@@ -231,7 +363,7 @@ program
         repro: opts.repro || opts.heal || magicFix,
         seed: parseInt(opts.seed, 10),
         workers,
-        allowHosts: opts.allowHost ?? [],
+        allowHosts: [...(opts.allowHost ?? []), ...configAllowHosts(repoRoot)],
         reproRuns: parseInt(opts.reproRuns, 10),
         heal: opts.heal || magicFix,
         healModel: opts.healModel,
@@ -252,9 +384,15 @@ program
         loginUrl: opts.loginUrl,
     };
     const failOn = Boolean(opts.failOn);
-    const useUi = !opts.plain && (process.stdout.isTTY === true || opts.ui === true);
+    const useUi = !json && !opts.plain && (process.stdout.isTTY === true || opts.ui === true);
     let findings = [];
     if (useUi) {
+        // ink (1645ms) and Playwright (1710ms) — together, and only here.
+        const [{ run }, { EventBus }, { renderTui }] = await Promise.all([
+            import("./core/orchestrator.js"),
+            import("./core/eventBus.js"),
+            import("./ui/app.js"),
+        ]);
         const bus = new EventBus();
         const runPromise = run({ ...runOpts, bus, ui: true });
         await renderTui({
@@ -269,31 +407,37 @@ program
         }
         catch (e) {
             console.error(pc.red("Aztrx AI run failed:"), e.message);
-            process.exit(1);
+            await finish(1);
         }
     }
     else {
-        findings = await run(runOpts);
+        // `ui: true` also means "print nothing" — reuse it to silence the
+        // orchestrator's own banner and progress lines under --json.
+        const run = await loadOrchestrator();
+        findings = await run(json ? { ...runOpts, ui: true } : runOpts);
     }
     if (opts.prComment) {
         const prPath = typeof opts.prComment === "string"
             ? opts.prComment
             : path.join(repoRoot, ".aztrx", "pr-comment.md");
+        const { writePrComment } = await import("./core/pr.js");
         writePrComment(repoRoot, targetUrl, findings, prPath);
-        console.log(pc.dim(`PR comment: ${path.relative(repoRoot, prPath)}`));
+        out(pc.dim(`PR comment: ${path.relative(repoRoot, prPath)}`));
     }
     if (opts.badge) {
         const badgePath = typeof opts.badge === "string"
             ? opts.badge
             : path.join(repoRoot, ".aztrx", "badge.svg");
+        const { writeBadge } = await import("./core/badge.js");
         writeBadge(repoRoot, findings, badgePath);
-        console.log(pc.dim(`Badge: ${path.relative(repoRoot, badgePath)}`));
+        out(pc.dim(`Badge: ${path.relative(repoRoot, badgePath)}`));
     }
     if (opts.regressionTest) {
         const regDir = typeof opts.regressionTest === "string" ? opts.regressionTest : undefined;
+        const { writeRegressionSpecs } = await import("./core/specCompiler.js");
         const written = writeRegressionSpecs(repoRoot, findings, regDir);
         for (const w of written) {
-            console.log(pc.green("  ✓ regression test") + ` ${path.relative(repoRoot, w)}`);
+            out(pc.green("  ✓ regression test") + ` ${path.relative(repoRoot, w)}`);
         }
     }
     // F13 — human-language summary + opt-in apply (the "Senior Rescuer" flow).
@@ -301,49 +445,74 @@ program
     // under `--fix`, offers to apply the verified patches so `git diff`
     // shows the result. Never commits.
     if (magicFix || opts.explain) {
+        const [{ summarizeFindings }, { renderMarkdown }] = await Promise.all([
+            import("./core/summarize.js"),
+            import("./core/renderMarkdown.js"),
+        ]);
         const summary = await summarizeFindings(findings, { lang: opts.lang });
-        console.log("\n" + renderMarkdown(summary));
+        out("\n" + renderMarkdown(summary));
     }
     if (magicFix) {
         const healed = findings.filter((f) => f.heal?.status === "healed");
         if (healed.length > 0) {
+            const { promptYesNo } = await import("./core/prompt.js");
             const doApply = await promptYesNo(`Apply ${healed.length} verified fix${healed.length === 1 ? "" : "es"} to the working tree? (y/N)`, { yes: opts.yes });
             if (doApply) {
+                const { applyVerifiedPatches } = await import("./core/heal/apply.js");
                 const result = applyVerifiedPatches(repoRoot, findings);
                 for (const a of result.applied) {
-                    console.log(pc.green("  ✓ applied") + ` ${a.filePath} (${a.hunkCount} edit${a.hunkCount === 1 ? "" : "s"})`);
+                    out(pc.green("  ✓ applied") + ` ${a.filePath} (${a.hunkCount} edit${a.hunkCount === 1 ? "" : "s"})`);
                 }
                 for (const c of result.conflicts) {
-                    console.log(pc.yellow("  ◐ skipped") + ` ${c.filePath}: ${c.error}`);
+                    out(pc.yellow("  ◐ skipped") + ` ${c.filePath}: ${c.error}`);
                 }
-                console.log(pc.dim("  Review with: git diff"));
+                out(pc.dim("  Review with: git diff"));
             }
             else {
-                console.log(pc.dim("  Not applied — review the .patch files under .aztrx/heal/."));
+                out(pc.dim("  Not applied — review the .patch files under .aztrx/heal/."));
             }
         }
     }
     if (opts.pr) {
+        const { openFixPr } = await import("./core/fixPr.js");
         const prRes = await openFixPr(repoRoot, findings, targetUrl);
         if (prRes.ok) {
-            console.log(pc.green("  ✓ PR opened") + ` ${prRes.url}`);
+            out(pc.green("  ✓ PR opened") + ` ${prRes.url}`);
         }
         else {
-            console.log(pc.yellow("  ◐ PR skipped") + `: ${prRes.error}`);
+            out(pc.yellow("  ◐ PR skipped") + `: ${prRes.error}`);
         }
     }
     // Suggest the next flag (e.g. --fix) after the run, in both the live TUI
     // and plain paths. In the TUI this prints after the panel has finished.
-    suggestNext(findings, opts);
+    if (!json)
+        suggestNext(findings, opts);
     // Drain any in-flight telemetry uploads (each bounded) before exit, so a
     // pending `--share-data` dispatch isn't killed mid-flight. Never affects
     // the exit code.
+    const [{ flushTelemetry }, { flushCloud }] = await Promise.all([
+        import("./core/telemetry/index.js"),
+        import("./core/cloud/index.js"),
+    ]);
     await flushTelemetry();
     await flushCloud();
+    if (json) {
+        process.stdout.write(JSON.stringify({
+            version: 1,
+            url: targetUrl,
+            repoRoot,
+            counts: {
+                crash: findings.filter((f) => f.severity === "crash").length,
+                error: findings.filter((f) => f.severity === "error").length,
+                warning: findings.filter((f) => f.severity === "warning").length,
+            },
+            findings,
+        }, null, 2) + "\n");
+    }
     if (failOn && findings.some((f) => f.severity === "crash" || f.severity === "error")) {
-        process.exit(1);
+        await finish(1);
     }
-    process.exit(0);
+    await finish(0);
 });
 program
     .command("patrol")
@@ -357,27 +526,45 @@ program
     .addOption(opt("--retry-after <s>", "cooldown before an unfixed bug is retried", "advanced").default("1800"))
     .addOption(opt("--batch", "group all fixes of a cycle into one PR", "advanced"))
     .addOption(opt("--once", "run a single scan then exit (no loop)", "advanced"))
-    .addOption(opt("--max-actions <n>", "max actions per pass", "advanced").default("100"))
+    .addOption(opt("--max-actions <n>", "max actions per pass (default: aztrx.config.ts, else 100)", "advanced"))
     .addOption(opt("--fuzz", "chaos fuzzing instead of the deterministic walk", "detect"))
     .addOption(opt("--workers <n>", "number of parallel detection workers", "detect"))
     .addOption(opt("--lang <en|ru>", "language for the diagnosis", "advanced").default("en"))
-    .addOption(opt("--login", "auto-login before each pass", "auth"))
+    .addOption(opt("--login", "auto-login before each pass (needs AZTRX_AUTH_EMAIL/AZTRX_AUTH_PASSWORD env)", "auth"))
+    .addOption(opt("--login-email <email>", "email for --login (default: $AZTRX_AUTH_EMAIL)").hideHelp())
+    .addOption(opt("--login-password <pass>", "password for --login (default: $AZTRX_AUTH_PASSWORD)").hideHelp())
+    .addOption(opt("--login-url <url>", "explicit login page URL for --login (default: current page)").hideHelp())
     .addOption(opt("--storage-state <path>", "Playwright storage-state JSON for authenticated pages", "auth"))
     .addOption(opt("--heal-model <model>", "LLM model for healing (default: claude-sonnet-5)", "advanced"))
     .addOption(opt("--test-command <cmd>", "test command run against a healed patch", "advanced"))
     .addOption(opt("--no-test", "skip the test gate during healing", "advanced"))
     .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 { configAllowHosts, configMaxActions } = await import("./core/devServer.js");
+    let booted;
     let targetUrl = url;
     if (!targetUrl) {
-        targetUrl = await detectUrl(repoRoot);
-        if (!targetUrl) {
-            console.error(pc.red("No URL given and none auto-detected. Pass <url>, or run `aztrx-cli init` first."));
-            process.exit(1);
-        }
-        console.log(pc.dim(`Auto-detected ${targetUrl}`));
+        const target = await resolveTargetOrExit(repoRoot, opts.boot === false);
+        targetUrl = target.url;
+        booted = target.close;
+    }
+    // Resolve credentials the same way `run` does — then refuse if they are
+    // incomplete. Patrol is unattended, so it cannot prompt the way `run`
+    // does, and `swarm`'s login block needs all three fields and has no else
+    // branch: without this, `patrol --login` was accepted and silently did
+    // nothing, scanning the logged-out app and opening PRs from those results.
+    const loginEmail = opts.loginEmail ?? process.env.AZTRX_AUTH_EMAIL;
+    const loginPassword = opts.loginPassword ?? process.env.AZTRX_AUTH_PASSWORD;
+    if (opts.login && (!loginEmail || !loginPassword)) {
+        console.error("aztrx: --login needs credentials, but none were found.\n" +
+            "  Set AZTRX_AUTH_EMAIL and AZTRX_AUTH_PASSWORD, or pass --login-email / --login-password.\n" +
+            "  Refusing to run: an unattended patrol that silently scans the logged-out app " +
+            "would open pull requests from the wrong pages.");
+        process.exit(2);
     }
+    const { patrol } = await import("./core/patrol/loop.js");
     await patrol({
         url: targetUrl,
         repoRoot,
@@ -387,17 +574,27 @@ program
         retryAfterMs: parseInt(opts.retryAfter, 10) * 1000,
         batch: Boolean(opts.batch),
         once: Boolean(opts.once),
-        maxActions: parseInt(opts.maxActions, 10),
+        maxActions: opts.maxActions
+            ? parseInt(opts.maxActions, 10)
+            : (configMaxActions(repoRoot) ?? 100),
+        // Patrol exposes no --allow-host, so the config file is the only way to
+        // allow a cross-origin API here. Absent either, the allow-list stays
+        // deny-by-default at the target's own origin.
+        allowHosts: configAllowHosts(repoRoot),
         fuzz: opts.fuzz,
         workers: opts.workers ? parseInt(opts.workers, 10) : undefined,
         lang: opts.lang,
         login: opts.login,
+        loginEmail,
+        loginPassword,
+        loginUrl: opts.loginUrl,
         storageState: opts.storageState,
         healModel: opts.healModel,
         testCommand: opts.testCommand,
         skipTest: opts.test === false,
         startCommand: opts.startCommand,
     });
+    await booted?.().catch(() => { });
     process.exit(0);
 });
 program.parseAsync();

package/dist/core/auth.d.ts

@@ -0,0 +1,33 @@
+/**
+ * F-auth — auto-login. Locates a login form and drives it with the user's
+ * credentials, so the rest of the run (and its repros) exercise the app
+ * *authenticated*. Best-effort by design: a login that can't be found or
+ * doesn't complete is reported, never fatal — the run continues unauth.
+ *
+ * The password input is the reliable signal for a login form; the email/username
+ * field and submit button are resolved within its nearest `<form>` (or the page
+ * body when the app doesn't use a `<form>` element).
+ */
+import type { Locator, Page } from "playwright";
+export interface LoginOptions {
+    email: string;
+    password: string;
+    /** Optional explicit login page URL; otherwise the current page is used. */
+    loginUrl?: string;
+}
+export interface LoginResult {
+    ok: boolean;
+    reason?: string;
+}
+export interface LoginForm {
+    email: Locator;
+    password: Locator;
+    submit: Locator | null;
+}
+/** Locate a login form on the current page, or `null` if none is present. */
+export declare function findLoginForm(page: Page): Promise<LoginForm | null>;
+/**
+ * Drive the login form. Returns whether it appeared to complete: the password
+ * field vanished, or the URL changed. Never throws — every step degrades.
+ */
+export declare function establishLogin(page: Page, opts: LoginOptions): Promise<LoginResult>;

package/dist/core/badge.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Self-contained SVG status badge generated from a real run's findings. Unlike a
+ * static "Protected by …" sticker, this badge is *earned*: it reflects the
+ * crash/error count of the run that produced it, so a stale badge is a
+ * regeneration problem — not a lie baked into the image.
+ */
+import type { Finding } from "./types.js";
+export declare function renderBadge(findings: Finding[], label?: string): string;
+export declare function writeBadge(repoRoot: string, findings: Finding[], filePath?: string): string;

package/dist/core/browser.d.ts

@@ -0,0 +1,3 @@
+import { type Browser, type LaunchOptions } from "playwright";
+/** Launch Chromium headlessly, installing its browser build first when absent. */
+export declare function launchChromium(options?: LaunchOptions): Promise<Browser>;