aztrx-cli 0.1.0 → 0.2.0

package/dist/cli.js

@@ -1,21 +1,56 @@
 #!/usr/bin/env node
 import path from "path";
+import * as fs from "fs";
+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 { 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 { promptYesNo } from "./core/prompt.js";
+import { modernizeFile } from "./core/modernize.js";
 function collect(value, prev) {
     prev.push(value);
     return prev;
 }
+/** Auto-size the swarm to the machine's CPU cores, capped so we never oversubscribe. */
+function autoWorkers() {
+    const n = typeof os.availableParallelism === "function" ? os.availableParallelism() : os.cpus().length;
+    return Math.max(1, Math.min(n, 8));
+}
+/** 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
+ * plain-log path when there's a finding worth acting on. */
+function suggestNext(findings, opts) {
+    if (opts.dryRun || opts.crashTest || findings.length === 0)
+        return;
+    const crashOrError = findings.some((f) => f.severity === "crash" || f.severity === "error");
+    const alreadyFixing = opts.heal || opts.fix || opts.magicFix;
+    if (crashOrError && !alreadyFixing) {
+        if (opts.repro) {
+            console.log(pc.dim("Tip: run with --fix to attempt a closed-loop fix"));
+        }
+        else {
+            console.log(pc.dim("Tip: run with --repro to prove these with a runnable spec, or --fix to fix them end-to-end"));
+        }
+        return;
+    }
+    const serverError = findings.some((f) => f.type === "network_5xx");
+    if (serverError && !opts.httpFuzz) {
+        console.log(pc.dim("Tip: run with --http-fuzz to map the server-side attack surface"));
+    }
+}
 program
-    .name("aztrx")
+    .name("aztrx-cli")
     .description("Runtime stress-testing for web apps — detect bugs, prove them with a repro")
     .option("--repo <path>", "project root to inspect/watch (default: cwd)", process.cwd());
 program
@@ -33,7 +68,7 @@ program
     if (res.gitignoreUpdated)
         console.log(pc.green("✓") + " .aztrx/ added to .gitignore");
     console.log("");
-    console.log(pc.dim(`Next:  npx aztrx run ${res.url} --repo .`));
+    console.log(pc.dim(`Next:  npx aztrx-cli run ${res.url} --repo .`));
 });
 program
     .command("studio")
@@ -42,35 +77,90 @@ program
     .action((opts) => {
     startStudio({ repoRoot: path.resolve(program.opts().repo), port: parseInt(opts.port, 10) });
 });
+program
+    .command("modernize")
+    .description("rewrite a legacy JS/TS file into modern idiomatic syntax (LLM)")
+    .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 rel = path.relative(repoRoot, path.resolve(file));
+    const res = await modernizeFile(repoRoot, file);
+    if (!res.ok) {
+        console.error(pc.red("modernize failed:") + ` ${res.error}`);
+        process.exit(1);
+    }
+    for (const c of res.changes)
+        console.log(pc.green("  ✓") + ` ${c}`);
+    const doApply = await promptYesNo(`Apply modernized version to ${rel}? (y/N)`, { yes: opts.yes });
+    if (doApply) {
+        fs.writeFileSync(path.resolve(file), res.modernized, "utf-8");
+        console.log(pc.dim(`  Applied → review with: git diff ${rel}`));
+    }
+    else {
+        console.log(pc.dim("  Not applied."));
+    }
+});
 program
     .command("run", { isDefault: true })
     .description("inspect a running app and prove its bugs with an executable repro")
     .argument("<url>", "dev server to inspect, e.g. http://localhost:3000")
-    .option("--repo <path>", "project root to inspect/watch (default: cwd)")
-    .option("--max-actions <n>", "max actions per pass", "100")
-    .option("--dry-run", "report what would be clicked without clicking")
-    .option("--crash-test", "throw a deliberate error to verify capture")
-    .option("--fail-on", "exit 1 if any crash/error finding is present")
-    .option("--fuzz", "chaos fuzzing instead of the deterministic walk (F5)")
-    .option("--seed <n>", "RNG seed for fuzz", "42")
-    .option("--repro", "minimize + compile + validate each finding (F7-F9)")
-    .option("--repro-runs <n>", "replay iterations for the flake-rate gate", "3")
-    .option("--heal", "closed-loop healing for crash/error findings (implies --repro)")
-    .option("--heal-model <model>", "LLM model for healing — the fallback tier (default claude-sonnet-5)")
-    .option("--heal-fast-model <model>", "fast/cheap first tier for the smart router (default claude-haiku-4-5)")
-    .option("--pr-comment [path]", "write a GitHub PR markdown comment (default .aztrx/pr-comment.md)")
-    .option("--telemetry", "opt-in: collect anonymized crash→repro→patch tuples locally (.aztrx/telemetry)")
-    .option("--share-data", "opt-in: also upload the sanitized tuples to the telemetry endpoint")
-    .option("--upload", "opt-in: stream run results to the Aztrx cloud dashboard (needs --api-key)")
-    .option("--api-key <key>", "API key for --upload / --share-data (defaults to $AZTRX_API_KEY)")
-    .option("--cloud-url <url>", "override the cloud ingest base URL (default https://api.aztrx.app)")
-    .option("--allow-host <host>", "add a host to the network allow-list (repeatable)", collect, [])
-    .option("--storage-state <path>", "path to a Playwright storage-state JSON (cookies/localStorage) for authenticated pages")
-    .option("--auth <path>", "alias for --storage-state")
-    .option("--plain", "disable the live terminal UI, print plain logs (default when piped)")
-    .option("--ui", "force the live terminal UI even when stdout is not a TTY")
+    .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("--dry-run", "report what would be clicked without clicking", "detect"))
+    .addOption(opt("--crash-test", "throw a deliberate error to verify capture", "advanced"))
+    .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"))
+    .addOption(opt("--http-fuzz-mutations", "with --http-fuzz: also send POST/PUT body mutations (default: GET-only)", "advanced"))
+    .addOption(opt("--seed <n>", "RNG seed for fuzz", "advanced").default("42"))
+    .addOption(opt("--workers <n>", "number of parallel detection workers (default 1)", "detect"))
+    .addOption(opt("--swarm", "auto-size the swarm to the machine's CPU cores (alias: --workers auto)").hideHelp())
+    .addOption(opt("--repro", "minimize + compile + validate each finding (F7-F9)", "prove"))
+    .addOption(opt("--repro-runs <n>", "replay iterations for the flake-rate gate", "advanced").default("3"))
+    .addOption(opt("--fix", "find → explain → heal → apply: one-command fix", "fix"))
+    .addOption(opt("--heal", "closed-loop healing for crash/error findings (implies --repro)", "fix"))
+    .addOption(opt("--magic-fix", "alias for --fix (deprecated)").hideHelp())
+    .addOption(opt("--heal-model <model>", "LLM model for healing — the fallback tier (default claude-sonnet-5)", "advanced"))
+    .addOption(opt("--heal-fast-model <model>", "fast/cheap first tier for the smart router (default claude-haiku-4-5)", "advanced"))
+    .addOption(opt("--test-command <cmd>", "test command run against a healed patch (default: npm test, auto-detected)", "advanced"))
+    .addOption(opt("--test-timeout <ms>", "timeout for the heal test gate, ms", "advanced").default("300000"))
+    .addOption(opt("--no-test", "skip the test gate during healing", "advanced"))
+    .addOption(opt("--start-command <cmd>", "command to boot the app for server healing (default: auto-detect scripts.dev/scripts.start)", "advanced"))
+    .addOption(opt("--explain", "print a human-language summary of the findings (no healing)", "fix"))
+    .addOption(opt("-y, --yes", "auto-apply verified fixes without prompting (with --fix)", "fix"))
+    .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("--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("--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"))
+    .addOption(opt("--auth <path>", "alias for --storage-state").hideHelp())
+    .addOption(opt("--login", "auto-login before the 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("--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"))
     .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 workers = opts.workers ? parseInt(opts.workers, 10) : opts.swarm ? autoWorkers() : undefined;
+    const mode = (workers ?? 1) > 1 || opts.httpFuzz
+        ? `swarm (${workers ?? 1} worker${(workers ?? 1) === 1 ? "" : "s"})`
+        : opts.fuzz
+            ? `fuzz (seed ${opts.seed})`
+            : opts.heal
+                ? "repro → heal"
+                : opts.repro
+                    ? "repro"
+                    : "deterministic walk";
     const runOpts = {
         url,
         repoRoot,
@@ -78,19 +168,30 @@ program
         dryRun: opts.dryRun,
         crashTest: opts.crashTest,
         fuzz: opts.fuzz,
-        repro: opts.repro || opts.heal,
+        httpFuzz: opts.httpFuzz,
+        httpFuzzMutations: opts.httpFuzzMutations,
+        repro: opts.repro || opts.heal || magicFix,
         seed: parseInt(opts.seed, 10),
+        workers,
         allowHosts: opts.allowHost ?? [],
         reproRuns: parseInt(opts.reproRuns, 10),
-        heal: opts.heal,
+        heal: opts.heal || magicFix,
         healModel: opts.healModel,
         healFastModel: opts.healFastModel,
+        testCommand: opts.testCommand,
+        testTimeoutMs: opts.testTimeoutMs ? parseInt(opts.testTimeoutMs, 10) : undefined,
+        skipTest: opts.test === false,
+        startCommand: opts.startCommand,
         telemetry: opts.telemetry,
         shareData: opts.shareData,
         upload: opts.upload,
         apiKey: opts.apiKey,
         cloudUrl: opts.cloudUrl,
         storageState: opts.storageState ?? opts.auth,
+        login: opts.login,
+        loginEmail: opts.loginEmail ?? process.env.AZTRX_AUTH_EMAIL,
+        loginPassword: opts.loginPassword ?? process.env.AZTRX_AUTH_PASSWORD,
+        loginUrl: opts.loginUrl,
     };
     const failOn = Boolean(opts.failOn);
     const useUi = !opts.plain && (process.stdout.isTTY === true || opts.ui === true);
@@ -103,13 +204,13 @@ program
             done: runPromise,
             targetUrl: url,
             repoRoot,
-            mode: opts.fuzz ? `fuzz (seed ${opts.seed})` : opts.heal ? "repro → heal" : opts.repro ? "repro" : "deterministic walk",
+            mode,
         });
         try {
             findings = await runPromise;
         }
         catch (e) {
-            console.error(pc.red("Aztrx run failed:"), e.message);
+            console.error(pc.red("Aztrx AI run failed:"), e.message);
             process.exit(1);
         }
     }
@@ -123,6 +224,43 @@ program
         writePrComment(repoRoot, url, findings, prPath);
         console.log(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");
+        writeBadge(repoRoot, findings, badgePath);
+        console.log(pc.dim(`Badge: ${path.relative(repoRoot, badgePath)}`));
+    }
+    // F13 — human-language summary + opt-in apply (the "Senior Rescuer" flow).
+    // The run already printed its structured output; this layer explains it and,
+    // under `--fix`, offers to apply the verified patches so `git diff`
+    // shows the result. Never commits.
+    if (magicFix || opts.explain) {
+        const summary = await summarizeFindings(findings, { lang: opts.lang });
+        console.log("\n" + summary);
+    }
+    if (magicFix) {
+        const healed = findings.filter((f) => f.heal?.status === "healed");
+        if (healed.length > 0) {
+            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 result = applyVerifiedPatches(repoRoot, findings);
+                for (const a of result.applied) {
+                    console.log(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}`);
+                }
+                console.log(pc.dim("  Review with: git diff"));
+            }
+            else {
+                console.log(pc.dim("  Not applied — review the .patch files under .aztrx/heal/."));
+            }
+        }
+    }
+    if (!useUi) {
+        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.

package/dist/core/auth.js

@@ -0,0 +1,76 @@
+/**
+ * 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).
+ */
+/** Locate a login form on the current page, or `null` if none is present. */
+export async function findLoginForm(page) {
+    const password = page.locator('input[type="password"]').first();
+    if ((await password.count()) === 0)
+        return null;
+    const form = password.locator("xpath=ancestor::form[1]");
+    const scope = (await form.count()) > 0 ? form : page.locator("body");
+    const emailCandidates = [
+        scope.locator('input[type="email"]'),
+        scope.locator('input[autocomplete="username"]'),
+        scope.locator('input[name*="email" i]'),
+        scope.locator('input[name*="user" i]'),
+        scope.locator('input[name*="login" i]'),
+        scope.locator('input[type="text"]'),
+    ];
+    let email = null;
+    for (const c of emailCandidates) {
+        if ((await c.count()) > 0) {
+            email = c.first();
+            break;
+        }
+    }
+    if (!email)
+        return null;
+    const submitCandidates = [
+        scope.locator('button[type="submit"]'),
+        scope.locator('input[type="submit"]'),
+    ];
+    let submit = null;
+    for (const c of submitCandidates) {
+        if ((await c.count()) > 0) {
+            submit = c.first();
+            break;
+        }
+    }
+    return { email, password, submit };
+}
+/**
+ * Drive the login form. Returns whether it appeared to complete: the password
+ * field vanished, or the URL changed. Never throws — every step degrades.
+ */
+export async function establishLogin(page, opts) {
+    if (opts.loginUrl) {
+        await page.goto(opts.loginUrl, { waitUntil: "load", timeout: 30000 }).catch(() => { });
+        await page.waitForTimeout(1000);
+    }
+    const form = await findLoginForm(page);
+    if (!form)
+        return { ok: false, reason: "no login form detected" };
+    await form.email.fill(opts.email).catch(() => { });
+    await form.password.fill(opts.password).catch(() => { });
+    const urlBefore = page.url();
+    if (form.submit) {
+        await form.submit.click({ timeout: 3000 }).catch(() => { });
+    }
+    else {
+        await form.password.press("Enter").catch(() => { });
+    }
+    await page.waitForLoadState("domcontentloaded").catch(() => { });
+    await page.waitForTimeout(1500);
+    const stillHasPassword = (await page.locator('input[type="password"]').count()) > 0;
+    const urlChanged = page.url() !== urlBefore;
+    if (!stillHasPassword || urlChanged)
+        return { ok: true };
+    return { ok: false, reason: "login did not appear to complete" };
+}

package/dist/core/badge.js

@@ -0,0 +1,50 @@
+/**
+ * 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 * as fs from "fs";
+import * as path from "path";
+const CHAR_W = 7.1; // Verdana 11px approximate advance width
+const PAD_X = 11; // horizontal padding per text block
+const LABEL = "#27272a"; // zinc-800 — brand monochrome
+const GREEN = "#16a34a";
+const RED = "#dc2626";
+function criticalCount(findings) {
+    return findings.filter((f) => f.severity === "crash" || f.severity === "error").length;
+}
+function blockWidth(text) {
+    return Math.round(text.length * CHAR_W + 2 * PAD_X);
+}
+export function renderBadge(findings, label = "aztrx") {
+    const n = criticalCount(findings);
+    const message = n === 0 ? "crash-free" : `${n} finding${n === 1 ? "" : "s"}`;
+    const color = n === 0 ? GREEN : RED;
+    const labelW = blockWidth(label);
+    const msgW = blockWidth(message);
+    const totalW = labelW + msgW;
+    const labelX = labelW / 2;
+    const msgX = labelW + msgW / 2;
+    return [
+        `<svg xmlns="http://www.w3.org/2000/svg" width="${totalW}" height="20" role="img" aria-label="${label}: ${message}">`,
+        `  <linearGradient id="g" x2="0" y2="100%"><stop offset="0" stop-color="#ffffff" stop-opacity="0.14"/><stop offset="1" stop-opacity="0"/></linearGradient>`,
+        `  <clipPath id="r"><rect width="${totalW}" height="20" rx="3" fill="#fff"/></clipPath>`,
+        `  <g clip-path="url(#r)">`,
+        `    <rect width="${labelW}" height="20" fill="${LABEL}"/>`,
+        `    <rect x="${labelW}" width="${msgW}" height="20" fill="${color}"/>`,
+        `    <rect width="${totalW}" height="20" fill="url(#g)"/>`,
+        `  </g>`,
+        `  <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11" font-weight="600">`,
+        `    <text x="${labelX}" y="14">${label}</text>`,
+        `    <text x="${msgX}" y="14">${message}</text>`,
+        `  </g>`,
+        `</svg>`,
+    ].join("\n") + "\n";
+}
+export function writeBadge(repoRoot, findings, filePath) {
+    const file = filePath ?? path.join(repoRoot, ".aztrx", "badge.svg");
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, renderBadge(findings), "utf-8");
+    return file;
+}

package/dist/core/fuzzer.js

@@ -5,7 +5,7 @@ const GARBAGE = [
     "<script>alert(1)</script>",
     "'; DROP TABLE users;--",
     "a".repeat(4096),
-    "😀".repeat(64),
+    "字".repeat(64),
     String.fromCharCode(0) + "null-byte",
     "NaN",
     "-1",

package/dist/core/heal/apply.js

@@ -0,0 +1,52 @@
+/**
+ * F13 — the only place Aztrx writes a verified patch into the user's *working
+ * tree*. Healing itself stays sandboxed (see `index.ts`); this module is the
+ * explicit, opt-in "apply" step behind `--fix`, so the recipe's promised
+ * `git diff` shows real changes.
+ *
+ * Rules that keep this safe:
+ *   - Only findings whose heal result is `healed` (verified: bug gone) are applied.
+ *   - The file is re-read *per finding* (several findings can touch one file),
+ *     and each patch is applied with exact-match hunks. A mismatch is a conflict
+ *     and is skipped — its `.patch` artifact stays for manual review.
+ *   - Paths are confined to `repoRoot`; anything escaping it is refused.
+ *   - Aztrx never commits. This writes working-tree files only.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { applyHunks } from "./sandbox.js";
+export function applyVerifiedPatches(repoRoot, findings) {
+    const applied = [];
+    const conflicts = [];
+    const root = path.resolve(repoRoot);
+    for (const f of findings) {
+        if (f.heal?.status !== "healed")
+            continue;
+        const filePath = f.heal.filePath;
+        if (!filePath) {
+            conflicts.push({ filePath, error: "no source file recorded" });
+            continue;
+        }
+        const abs = path.resolve(root, filePath);
+        if (abs !== root && !abs.startsWith(root + path.sep)) {
+            conflicts.push({ filePath, error: `refusing to write outside repo: ${filePath}` });
+            continue;
+        }
+        let current;
+        try {
+            current = fs.readFileSync(abs, "utf-8");
+        }
+        catch (e) {
+            conflicts.push({ filePath, error: `cannot read: ${e.message}` });
+            continue;
+        }
+        const result = applyHunks(current, f.heal.hunks);
+        if (!result.ok) {
+            conflicts.push({ filePath, error: result.errors.join("; ") });
+            continue;
+        }
+        fs.writeFileSync(abs, result.patched, "utf-8");
+        applied.push({ filePath, hunkCount: result.applied });
+    }
+    return { applied, conflicts };
+}

package/dist/core/heal/boot.js

@@ -0,0 +1,136 @@
+/**
+ * F10 gate #4 — boot the *patched* app for server-side verification. A server
+ * finding (e.g. `HTTP 500 /api/cart`) can't be verified by statically serving
+ * the worktree — the 500 only reappears when the route actually runs. So before
+ * the replay, this boots the patched server inside the worktree on a free port,
+ * waits for an HTTP readiness signal, and returns a `close` hook that tree-kills
+ * the process (and its children) so nothing is left holding the port.
+ */
+import { spawn } from "child_process";
+import * as fs from "fs";
+import * as net from "net";
+import * as path from "path";
+import { buildChildEnv } from "./childEnv.js";
+/** Auto-detect how the app starts, mirroring `runTests`'s `npm test` convention:
+ * prefer `scripts.dev` (no build step), then `scripts.start`. Null when neither
+ * exists — the caller then requires an explicit `--start-command`. */
+export function detectStartCommand(repoRoot) {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf-8"));
+        const s = pkg.scripts;
+        if (s && typeof s.dev === "string")
+            return "npm run dev";
+        if (s && typeof s.start === "string")
+            return "npm run start";
+    }
+    catch {
+        // no package.json, or unparseable — fall through to null
+    }
+    return null;
+}
+/** Allocate a free loopback port. Best-effort: there is a small window between
+ * closing the probe and the app binding, so a collision is surfaced as a boot
+ * timeout rather than silently mis-directed. */
+function freePort() {
+    return new Promise((resolve, reject) => {
+        const srv = net.createServer();
+        srv.once("error", reject);
+        srv.listen(0, "127.0.0.1", () => {
+            const addr = srv.address();
+            srv.close(() => resolve(addr.port));
+        });
+    });
+}
+export async function bootServer(opts) {
+    const { worktreeDir, repoRoot, startCommand } = opts;
+    const timeoutMs = opts.timeoutMs ?? 60_000;
+    // A fresh worktree has no node_modules — symlink the root's so the booted
+    // server resolves its dependencies (the same junction trick sandbox.ts uses).
+    const rootNodeModules = path.join(repoRoot, "node_modules");
+    const wtNodeModules = path.join(worktreeDir, "node_modules");
+    if (!fs.existsSync(wtNodeModules) && fs.existsSync(rootNodeModules)) {
+        try {
+            fs.symlinkSync(rootNodeModules, wtNodeModules, process.platform === "win32" ? "junction" : "dir");
+        }
+        catch {
+            /* resolution errors surface in the readiness timeout below */
+        }
+    }
+    const port = await freePort();
+    // Support scripts that hardcode a port via `-p {port}`; `PORT` is also set in
+    // the environment for the (more common) scripts that read `process.env.PORT`.
+    const command = startCommand.replace(/\{port\}/g, String(port));
+    // Ring buffer of the last ~40 log lines, so a boot timeout can tell the user
+    // *why* the server didn't come up rather than just "timeout".
+    const lines = [];
+    const push = (chunk) => {
+        for (const line of chunk.toString().split(/\r?\n/)) {
+            if (line) {
+                lines.push(line);
+                if (lines.length > 40)
+                    lines.shift();
+            }
+        }
+    };
+    const child = spawn(command, {
+        shell: true,
+        cwd: worktreeDir,
+        // Minimal allow-list — the booted app is patched PR code; it must not see
+        // the caller's ANTHROPIC_API_KEY or other CI secrets.
+        env: buildChildEnv({ PORT: String(port), CI: "true" }),
+        // On POSIX, detach so the server + its children form their own process
+        // group — close() can then signal the whole group. Windows can't do group
+        // signaling; it relies on `taskkill /T` below instead.
+        detached: process.platform !== "win32",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    child.stdout?.on("data", push);
+    child.stderr?.on("data", push);
+    let closed = false;
+    const close = async () => {
+        if (closed || !child.pid)
+            return;
+        closed = true;
+        if (process.platform === "win32") {
+            // `shell: true` spawns cmd.exe which spawns the real server as a child —
+            // a plain child.kill() would orphan that child and leave the port taken.
+            await new Promise((resolve) => {
+                const killer = spawn("taskkill", ["/PID", String(child.pid), "/T", "/F"], {
+                    stdio: "ignore",
+                });
+                killer.on("exit", () => resolve());
+                killer.on("error", () => resolve());
+            });
+        }
+        else {
+            try {
+                process.kill(-child.pid, "SIGTERM");
+            }
+            catch {
+                // already exited
+            }
+        }
+    };
+    // Readiness: poll until the server answers with *any* HTTP response (2xx/4xx/
+    // 5xx all mean "the listener is up"). A still-compiling dev server (Next) may
+    // take a while on its first request — the loop keeps retrying until it's hot.
+    const url = `http://127.0.0.1:${port}`;
+    const deadline = Date.now() + timeoutMs;
+    let ready = false;
+    while (Date.now() < deadline) {
+        try {
+            const res = await fetch(url, { signal: AbortSignal.timeout(1000) });
+            await res.arrayBuffer().catch(() => { });
+            ready = true;
+            break;
+        }
+        catch {
+            await new Promise((r) => setTimeout(r, 400));
+        }
+    }
+    if (!ready) {
+        await close();
+        throw new Error(`server did not become ready in ${timeoutMs}ms: ${startCommand}\n${lines.join("\n").slice(-2000)}`);
+    }
+    return { url, close, logs: () => lines.join("\n") };
+}