aztrx-cli 0.4.5 → 0.5.2

package/dist/next/index.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Next.js dev-server plugin — `aztrx-cli/next`.
+ *
+ * Next has no `vite.config.ts` to hang a plugin off. What it does have is
+ * `instrumentation.ts`, the hook Next added for exactly this kind of
+ * instrumentation (Sentry, OpenTelemetry) — it runs once in the server process
+ * at startup, in dev and in production alike. So the adapter is a `register()`
+ * call, not a config object:
+ *
+ *     // instrumentation.ts, next to app/ or src/
+ *     export async function register() {
+ *       if (process.env.NEXT_RUNTIME === "nodejs") {
+ *         const { registerAztrx } = await import("aztrx-cli/next");
+ *         registerAztrx();
+ *       }
+ *     }
+ *
+ * Next 15 `register()` may return a promise that Next awaits *before it starts
+ * serving*. That makes the obvious implementation — wait for the server, then
+ * scan — a deadlock: the server cannot serve until `register()` returns, and
+ * `register()` would be waiting on the server. So `registerAztrx` returns
+ * immediately and does its waiting detached. It is deliberately not `async`.
+ *
+ * The scan itself lives in `src/plugins/scan.ts`, shared with the Vite plugin.
+ */
+import type { AztrxResult } from "../plugins/scan.js";
+export type { AztrxResult } from "../plugins/scan.js";
+export { summarize } from "../plugins/scan.js";
+export { resolveCliPath } from "../plugins/scan.js";
+export interface NextPluginOptions {
+    /** Run a scan once the dev server is up. Default `true` — creating
+     * `instrumentation.ts` is already the opt-in. `AZTRX_DEV_SCAN=0` disables it
+     * for a single run without touching the file. */
+    enabled?: boolean;
+    /** The dev server to attack. Almost never needed: the port is derived from
+     * your `next dev` script, falling back to Next's default 3000. Set it (or
+     * `AZTRX_URL`) when Next picked a different port because 3000 was taken. */
+    url?: string;
+    /** Max interactions per pass (the CLI's `--max-actions`). */
+    maxActions?: number;
+    /** Seeded chaos fuzzing instead of the deterministic walk. */
+    fuzz?: boolean;
+    /** Also fuzz the server's HTTP endpoints. Off by default: it mutates. */
+    httpFuzz?: boolean;
+    /** Repo root for sourcemap resolution and `.aztrx/` artifacts. Defaults to
+     * the Next project's working directory. */
+    repoRoot?: string;
+    /** Extra CLI flags, for anything not surfaced above. */
+    args?: string[];
+    /** How long to wait for the dev server to answer before reporting that it
+     * never came up. Raise it for a monorepo whose cold compile outlasts the
+     * default. */
+    readyTimeoutMs?: number;
+    /** Replace the default one-line report — e.g. to wire findings into your own
+     * tooling. */
+    onResult?: (result: AztrxResult) => void;
+    /** Called when the scan itself fails (never throws into the dev server). */
+    onError?: (message: string) => void;
+}
+/** The URL to attack: explicit option → `AZTRX_URL` → the port Next itself is
+ * listening on → the port this project's `next dev` script asks for.
+ *
+ * `process.env.PORT` is the good one: Next sets it in the instrumentation
+ * process to the port it actually bound, *after* resolving collisions. That is
+ * the only source that stays correct when Next auto-increments away from 3000
+ * because something else already holds it. Exported for tests — the rest is I/O. */
+export declare function resolveNextUrl(repoRoot: string, explicit?: string): string;
+/** Wire Aztrx into a Next.js dev server. Call from `instrumentation.ts`.
+ * Returns immediately — see the deadlock note at the top of this file. */
+export declare function registerAztrx(options?: NextPluginOptions): void;

package/dist/next/index.js

@@ -0,0 +1,103 @@
+/**
+ * Next.js dev-server plugin — `aztrx-cli/next`.
+ *
+ * Next has no `vite.config.ts` to hang a plugin off. What it does have is
+ * `instrumentation.ts`, the hook Next added for exactly this kind of
+ * instrumentation (Sentry, OpenTelemetry) — it runs once in the server process
+ * at startup, in dev and in production alike. So the adapter is a `register()`
+ * call, not a config object:
+ *
+ *     // instrumentation.ts, next to app/ or src/
+ *     export async function register() {
+ *       if (process.env.NEXT_RUNTIME === "nodejs") {
+ *         const { registerAztrx } = await import("aztrx-cli/next");
+ *         registerAztrx();
+ *       }
+ *     }
+ *
+ * Next 15 `register()` may return a promise that Next awaits *before it starts
+ * serving*. That makes the obvious implementation — wait for the server, then
+ * scan — a deadlock: the server cannot serve until `register()` returns, and
+ * `register()` would be waiting on the server. So `registerAztrx` returns
+ * immediately and does its waiting detached. It is deliberately not `async`.
+ *
+ * The scan itself lives in `src/plugins/scan.ts`, shared with the Vite plugin.
+ */
+import { planBoot, waitForHttp } from "../core/devServer.js";
+import { resolveRepoRoot, scanDisabled, spawnScan } from "../plugins/scan.js";
+export { summarize } from "../plugins/scan.js";
+// Exposed so a "scan did not produce a result" report can name the path that was
+// actually tried — the one fact needed to tell a resolution bug from a scan bug.
+export { resolveCliPath } from "../plugins/scan.js";
+/** How long to wait for the dev server to answer before giving up. Generous for
+ * the same reason as the CLI's attach timeout: Next binds its port well before
+ * it can serve, and a cold Turbopack compile is not fast. */
+const READY_TIMEOUT_MS = 60_000;
+/** Next may call `register()` more than once (restarts, worker processes); a
+ * second scan of the same server is pure waste. Module-scoped because the
+ * duplicate arrives in the same process. */
+let started = false;
+/** The URL to attack: explicit option → `AZTRX_URL` → the port Next itself is
+ * listening on → the port this project's `next dev` script asks for.
+ *
+ * `process.env.PORT` is the good one: Next sets it in the instrumentation
+ * process to the port it actually bound, *after* resolving collisions. That is
+ * the only source that stays correct when Next auto-increments away from 3000
+ * because something else already holds it. Exported for tests — the rest is I/O. */
+export function resolveNextUrl(repoRoot, explicit) {
+    if (explicit)
+        return explicit;
+    if (process.env.AZTRX_URL)
+        return process.env.AZTRX_URL;
+    if (process.env.PORT)
+        return `http://localhost:${process.env.PORT}`;
+    // planBoot reads the dev script's `--port`/`-p` and otherwise returns Next's
+    // default. It returns null only when there is no dev/start script at all —
+    // not our problem to guess at that point, so fall back to the default.
+    return `http://localhost:${planBoot(repoRoot)?.port ?? 3000}`;
+}
+/** Wire Aztrx into a Next.js dev server. Call from `instrumentation.ts`.
+ * Returns immediately — see the deadlock note at the top of this file. */
+export function registerAztrx(options = {}) {
+    // `next build` and `next start` are production; a scan there would drive a
+    // browser at a real deployment. Dev only, unconditionally.
+    if (process.env.NODE_ENV !== "development")
+        return;
+    // `instrumentation.ts` is also bundled for the edge runtime, which has no
+    // child_process. The caller's `NEXT_RUNTIME` guard is the documented form;
+    // this is the one that holds even when they forget it.
+    if (process.env.NEXT_RUNTIME && process.env.NEXT_RUNTIME !== "nodejs")
+        return;
+    if (scanDisabled(options.enabled))
+        return;
+    if (started)
+        return;
+    started = true;
+    const repoRoot = resolveRepoRoot(options.repoRoot, process.cwd());
+    const url = resolveNextUrl(repoRoot, options.url);
+    /** Killed on the way out, or the browser outlives the server it was driving.
+     * `exit` rather than SIGINT/SIGTERM on purpose: this handler lives inside the
+     * *user's* server process, and installing signal handlers there would fight
+     * whatever Next (and Sentry, and nodemon) already installed. Next's own
+     * Ctrl-C path calls `process.exit()`, which fires this. */
+    let scan;
+    process.once("exit", () => scan?.stop());
+    const timeoutMs = options.readyTimeoutMs ?? READY_TIMEOUT_MS;
+    void (async () => {
+        if (!(await waitForHttp(url, timeoutMs))) {
+            options.onError?.(`no dev server answered at ${url} within ${timeoutMs / 1000}s — ` +
+                "if Next picked a different port, set AZTRX_URL or the `url` option.");
+            return;
+        }
+        scan = spawnScan({
+            url,
+            repoRoot,
+            maxActions: options.maxActions,
+            fuzz: options.fuzz,
+            httpFuzz: options.httpFuzz,
+            args: options.args,
+            onResult: options.onResult,
+            onError: options.onError,
+        });
+    })();
+}

package/dist/plugins/scan.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The scan child that every dev-server plugin (`aztrx-cli/vite`,
+ * `aztrx-cli/next`) runs.
+ *
+ * The scan is a **child process**, not an in-process call. That is the whole
+ * point of the design: a scanner that crashes, hangs, or leaves a browser behind
+ * must never be able to take the user's dev server down with it. The child speaks
+ * `--json` (exactly one document on stdout), so the parent only parses a result.
+ *
+ * The plugins are deliberately quiet — one line when the scan finishes, nothing
+ * while it runs. The dev server owns the terminal; Aztrx is a guest in it.
+ */
+import type { Finding } from "../core/types.js";
+/** The JSON envelope `aztrx-cli --json` prints — see the `if (json)` block in
+ * `src/cli.ts`, which serializes `findings` straight from the run.
+ *
+ * `findings` is the CLI's own `Finding`, not a restatement of it. An earlier
+ * hand-written copy of the shape guessed `mappedLocation.file` where the real
+ * field is `filePath`, and because the tests were written against the same
+ * guess they passed while the plugin printed `first: undefined:18` for every
+ * real crash. Borrowing the type makes that class of drift a compile error. */
+export interface AztrxResult {
+    version: number;
+    url: string;
+    repoRoot: string;
+    counts: {
+        crash: number;
+        error: number;
+        warning: number;
+    };
+    findings: Finding[];
+}
+export interface ScanOptions {
+    /** The dev server to attack. Omitted only with `boot: true`, where the child
+     * works out (and starts) a server itself. */
+    url?: string;
+    /** Repo root for sourcemap resolution and `.aztrx/` artifacts. */
+    repoRoot: string;
+    /** Let the child find a dev server, or start the project's own and stop it
+     * again. Default `false`: the dev-server plugins run *because* a server is
+     * already up, and a second one would be a bug. The git hook passes `true`
+     * because during a push there usually is not one — and the booted server is
+     * then owned by the child, which already tears down correctly on every exit
+     * path including a parent's death. */
+    boot?: boolean;
+    /** Max interactions per pass (the CLI's `--max-actions`). */
+    maxActions?: number;
+    /** Seeded chaos fuzzing instead of the deterministic walk. */
+    fuzz?: boolean;
+    /** Also fuzz the server's HTTP endpoints. Off by default: it mutates. */
+    httpFuzz?: boolean;
+    /** Extra CLI flags, for anything not surfaced above. */
+    args?: string[];
+    /** Replaces the default one-line report — e.g. to wire findings into your own
+     * tooling. */
+    onResult?: (result: AztrxResult) => void;
+    /** Called when the scan itself fails. Never throws into the dev server. */
+    onError?: (message: string) => void;
+}
+export interface ScanHandle {
+    /** Kill the scan and everything below it. Idempotent, synchronous (it is also
+     * called from `process.on("exit")`, where only sync work runs), and it
+     * suppresses the "no result" error — an interrupted scan has nothing to say. */
+    stop: () => void;
+    /** Resolves once the child has exited. Never rejects. */
+    done: Promise<void>;
+}
+/** Every layout the CLI plausibly lives in, most likely first. Exported for
+ * tests — everything below is I/O. */
+export declare function cliCandidates(repoRoot: string): string[];
+/** The first candidate that exists, or undefined. Split from the filesystem so
+ * the ordering is testable without a real install to point at. */
+export declare function pickCliPath(candidates: string[], exists?: (p: string) => boolean): string | undefined;
+/** The first candidate that actually exists on disk. */
+export declare function resolveCliPath(repoRoot: string): string;
+/** One line, no colour games — it has to read well in the middle of the dev
+ * server's own startup output. */
+export declare function summarize(result: AztrxResult): string;
+export declare function spawnScan(opts: ScanOptions): ScanHandle;
+/** Shared by both plugins: adding the plugin to your config is already the
+ * opt-in, and `AZTRX_DEV_SCAN=0` skips a scan for one run without touching it. */
+export declare function scanDisabled(optionsEnabled: boolean | undefined): boolean;
+/** Repo root for sourcemap resolution. The dev server's root is the right
+ * default, but a monorepo package root is often deeper than the repo. */
+export declare function resolveRepoRoot(explicit: string | undefined, fallback: string): string;

package/dist/plugins/scan.js

@@ -0,0 +1,188 @@
+/**
+ * The scan child that every dev-server plugin (`aztrx-cli/vite`,
+ * `aztrx-cli/next`) runs.
+ *
+ * The scan is a **child process**, not an in-process call. That is the whole
+ * point of the design: a scanner that crashes, hangs, or leaves a browser behind
+ * must never be able to take the user's dev server down with it. The child speaks
+ * `--json` (exactly one document on stdout), so the parent only parses a result.
+ *
+ * The plugins are deliberately quiet — one line when the scan finishes, nothing
+ * while it runs. The dev server owns the terminal; Aztrx is a guest in it.
+ */
+import { spawn } from "child_process";
+import * as fs from "fs";
+import { createRequire } from "module";
+import * as path from "path";
+import { fileURLToPath } from "url";
+import { killTreeSync } from "../core/heal/boot.js";
+/** Where the installed package's `cli.js` is, or undefined if we can't find one.
+ * Split out so `resolveCliPath` can try several shapes. */
+function tryResolveCli() {
+    // Anchored on `process.cwd()` — the user's project — and not on
+    // `import.meta.url`. Both halves matter:
+    //
+    //  * cwd, because a bundler will happily pre-evaluate `require.resolve` when
+    //    its base is statically known. Turbopack did exactly that to the
+    //    `import.meta.url` form and inlined a build-time virtual path
+    //    (`…/[project]/node_modules/aztrx-cli/dist/cli.js`) that does not exist on
+    //    disk. A base that is only known at runtime cannot be folded.
+    //  * not `import.meta.url`, because when this module is bundled its URL is the
+    //    *bundle's* — inside `.next/dev/server/` — and anything relative to it
+    //    points at build output rather than the installed package.
+    const fromCwd = createRequire(path.join(process.cwd(), "index.js"));
+    try {
+        // `./package.json` is the one subpath the exports map always exposes.
+        return path.join(path.dirname(fromCwd.resolve("aztrx-cli/package.json")), "dist", "cli.js");
+    }
+    catch {
+        // No `require.resolve` fallback: under a bundler it is the thing that lies.
+        return undefined;
+    }
+}
+/** Every layout the CLI plausibly lives in, most likely first. Exported for
+ * tests — everything below is I/O. */
+export function cliCandidates(repoRoot) {
+    const resolved = tryResolveCli();
+    const candidates = [
+        resolved,
+        // npm's normal shape, read straight off the filesystem. Redundant when
+        // `require.resolve` worked; the whole point when it did not.
+        path.join(repoRoot, "node_modules", "aztrx-cli", "dist", "cli.js"),
+        path.join(process.cwd(), "node_modules", "aztrx-cli", "dist", "cli.js"),
+        // A checkout that was never installed into anyone's node_modules — which is
+        // how this repo's own tests load the plugins.
+        path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "cli.js"),
+    ];
+    return candidates.filter((c) => Boolean(c));
+}
+/** The first candidate that exists, or undefined. Split from the filesystem so
+ * the ordering is testable without a real install to point at. */
+export function pickCliPath(candidates, exists = fs.existsSync) {
+    return candidates.find(exists);
+}
+/** The first candidate that actually exists on disk. */
+export function resolveCliPath(repoRoot) {
+    const candidates = cliCandidates(repoRoot);
+    // Nothing found: hand back the first guess so the spawn error names a real
+    // path the user can look at, rather than a placeholder.
+    return pickCliPath(candidates) ?? candidates[0];
+}
+/** One line, no colour games — it has to read well in the middle of the dev
+ * server's own startup output. */
+export function summarize(result) {
+    const { crash, error, warning } = result.counts;
+    const total = crash + error + warning;
+    if (total === 0)
+        return "[aztrx] clean — no runtime crashes found.";
+    const bits = [
+        crash && `${crash} crash${crash === 1 ? "" : "es"}`,
+        error && `${error} error${error === 1 ? "" : "s"}`,
+        warning && `${warning} warning${warning === 1 ? "" : "s"}`,
+    ].filter(Boolean);
+    const first = result.findings.find((f) => f.severity === "crash" || f.severity === "error");
+    // Forward slashes so the line reads the same on Windows as everywhere else.
+    const where = first?.mappedLocation
+        ? ` — first: ${first.mappedLocation.filePath.replace(/\\/g, "/")}:${first.mappedLocation.line}`
+        : "";
+    return `[aztrx] ${bits.join(" · ")}${where}\n[aztrx] run \`npx aztrx-cli\` for the repro and the fix.`;
+}
+/** What went wrong, in one line, so a failed scan says *why*.
+ *
+ * Not a fixed slice of either end. A Node crash dump opens with
+ * `node:internal/modules/cjs/loader:1451 / throw err; / ^` boilerplate and only
+ * *then* names the failure; the tail is `at node:internal/main/...` noise. Both
+ * a head-slice and a tail-slice report everything except the cause — so find the
+ * line that names it. */
+function stderrTail(stderr) {
+    const lines = stderr
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean);
+    if (!lines.length)
+        return "";
+    const at = lines.findIndex((l) => /(^|\s)\w*Error\b/.test(l));
+    return `: ${(at === -1 ? lines.slice(0, 3) : lines.slice(at, at + 2)).join(" ")}`;
+}
+export function spawnScan(opts) {
+    const args = [
+        resolveCliPath(opts.repoRoot),
+        ...(opts.url ? [opts.url] : []),
+        "--json",
+        // Attach to the running server, never boot another — unless the caller said
+        // there isn't one (`boot`), which is the git hook during a push.
+        ...(opts.boot ? [] : ["--no-boot"]),
+        "--repo",
+        opts.repoRoot,
+        ...(opts.maxActions !== undefined ? ["--max-actions", String(opts.maxActions)] : []),
+        ...(opts.fuzz ? ["--fuzz"] : []),
+        ...(opts.httpFuzz ? ["--http-fuzz"] : []),
+        ...(opts.args ?? []),
+    ];
+    let stopping = false;
+    let child;
+    try {
+        child = spawn(process.execPath, args, {
+            cwd: opts.repoRoot,
+            // Same process-group trick as the boot path: POSIX signals the group
+            // (node + its Playwright browser), Windows uses taskkill /T.
+            detached: process.platform !== "win32",
+            // The IPC slot is not for messages — it is a death signal. The OS closes
+            // the channel when the parent goes away, *including* when it is SIGKILLed,
+            // which no signal handler can catch. See the watcher in `src/cli.ts`.
+            stdio: ["ignore", "pipe", "pipe", "ipc"],
+        });
+    }
+    catch (e) {
+        opts.onError?.(e.message);
+        return { stop: () => { }, done: Promise.resolve() };
+    }
+    const pid = child.pid;
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (d) => (stdout += d.toString()));
+    child.stderr?.on("data", (d) => (stderr += d.toString()));
+    child.on("error", (e) => {
+        if (!stopping)
+            opts.onError?.(e.message);
+    });
+    const done = new Promise((resolve) => {
+        child.on("close", () => {
+            if (stopping)
+                return resolve();
+            let result;
+            try {
+                result = JSON.parse(stdout);
+            }
+            catch {
+                // A failed scan must not look like a clean one — say so instead of
+                // staying silent, which is exactly how a real crash gets missed.
+                opts.onError?.(`scan did not produce a result${stderrTail(stderr)}`);
+                return resolve();
+            }
+            if (opts.onResult)
+                opts.onResult(result);
+            else
+                console.log(summarize(result));
+            resolve();
+        });
+    });
+    return {
+        stop: () => {
+            stopping = true;
+            if (pid)
+                killTreeSync(pid);
+        },
+        done,
+    };
+}
+/** Shared by both plugins: adding the plugin to your config is already the
+ * opt-in, and `AZTRX_DEV_SCAN=0` skips a scan for one run without touching it. */
+export function scanDisabled(optionsEnabled) {
+    return optionsEnabled === false || process.env.AZTRX_DEV_SCAN === "0";
+}
+/** Repo root for sourcemap resolution. The dev server's root is the right
+ * default, but a monorepo package root is often deeper than the repo. */
+export function resolveRepoRoot(explicit, fallback) {
+    return path.resolve(explicit ?? fallback);
+}

package/dist/ui/app.d.ts

@@ -0,0 +1,11 @@
+import type { EventBus } from "../core/eventBus.js";
+import type { Finding } from "../core/types.js";
+export interface AztrxAppProps {
+    bus: EventBus;
+    done: Promise<Finding[]>;
+    targetUrl: string;
+    repoRoot: string;
+    mode: string;
+}
+/** Mount the live terminal panel and resolve once the run (or a failure) ends. */
+export declare function renderTui(props: AztrxAppProps): Promise<void>;

package/dist/vite/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Vite dev-server plugin — `aztrx-cli/vite`.
+ *
+ * Drop it into `vite.config.ts` and the dev server reports its own runtime
+ * crashes while you work, without a second terminal:
+ *
+ *     import { aztrx } from "aztrx-cli/vite";
+ *     export default defineConfig({ plugins: [aztrx()] });
+ *
+ * The scan itself lives in `src/plugins/scan.ts` — a child process every
+ * dev-server plugin shares. This file is only the Vite-shaped adapter: when to
+ * start, and what to do when the server goes away.
+ */
+import type { AztrxResult } from "../plugins/scan.js";
+export type { AztrxResult } from "../plugins/scan.js";
+export { summarize } from "../plugins/scan.js";
+export { resolveCliPath } from "../plugins/scan.js";
+/** The slice of Vite's `DevServer` this plugin actually touches, declared
+ * structurally so the plugin stays usable across Vite majors (4 → 8) without
+ * pinning a peer dependency's types. */
+export interface ViteDevServerLike {
+    config: {
+        root: string;
+    };
+    httpServer: {
+        once(event: string, cb: () => void): unknown;
+        on(event: string, cb: () => void): unknown;
+    } | null;
+    resolvedUrls?: {
+        local?: string[];
+    } | null;
+}
+export interface AztrxPluginOptions {
+    /** Run a scan when the dev server starts. Default `true` — adding the plugin
+     * to your config is already the opt-in. `AZTRX_DEV_SCAN=0` disables it for a
+     * single run without touching the config. */
+    enabled?: boolean;
+    /** Max interactions per pass (the CLI's `--max-actions`). */
+    maxActions?: number;
+    /** Seeded chaos fuzzing instead of the deterministic walk. */
+    fuzz?: boolean;
+    /** Also fuzz the server's HTTP endpoints. Off by default: it mutates. */
+    httpFuzz?: boolean;
+    /** Repo root for sourcemap resolution and `.aztrx/` artifacts. Defaults to
+     * Vite's resolved root. */
+    repoRoot?: string;
+    /** Extra CLI flags, for anything not surfaced above. */
+    args?: string[];
+    /** Replace the default one-line report — e.g. to wire findings into your own
+     * tooling. */
+    onResult?: (result: AztrxResult) => void;
+    /** Called when the scan itself fails (never throws into Vite). */
+    onError?: (message: string) => void;
+}
+export declare function aztrx(options?: AztrxPluginOptions): {
+    name: string;
+    apply: "serve";
+    configureServer(server: ViteDevServerLike): void;
+};
+export default aztrx;

package/dist/vite/index.js

@@ -0,0 +1,56 @@
+/**
+ * Vite dev-server plugin — `aztrx-cli/vite`.
+ *
+ * Drop it into `vite.config.ts` and the dev server reports its own runtime
+ * crashes while you work, without a second terminal:
+ *
+ *     import { aztrx } from "aztrx-cli/vite";
+ *     export default defineConfig({ plugins: [aztrx()] });
+ *
+ * The scan itself lives in `src/plugins/scan.ts` — a child process every
+ * dev-server plugin shares. This file is only the Vite-shaped adapter: when to
+ * start, and what to do when the server goes away.
+ */
+import { resolveRepoRoot, scanDisabled, spawnScan } from "../plugins/scan.js";
+export { summarize } from "../plugins/scan.js";
+// Exposed so a "scan did not produce a result" report can name the path that was
+// actually tried — the one fact needed to tell a resolution bug from a scan bug.
+export { resolveCliPath } from "../plugins/scan.js";
+export function aztrx(options = {}) {
+    return {
+        name: "aztrx",
+        // A dev-server sentinel — nothing to scan during a production build.
+        apply: "serve",
+        configureServer(server) {
+            if (scanDisabled(options.enabled))
+                return;
+            if (!server.httpServer)
+                return;
+            let scan;
+            // Vite calls configureServer before listen(), so this fires once the port
+            // is actually bound and `resolvedUrls` is populated — no readiness poll
+            // needed here, unlike the Next.js plugin.
+            server.httpServer.once("listening", () => {
+                const url = server.resolvedUrls?.local?.[0];
+                if (!url) {
+                    options.onError?.("dev server started but Vite reported no local URL");
+                    return;
+                }
+                scan = spawnScan({
+                    url,
+                    repoRoot: resolveRepoRoot(options.repoRoot, server.config.root),
+                    maxActions: options.maxActions,
+                    fuzz: options.fuzz,
+                    httpFuzz: options.httpFuzz,
+                    args: options.args,
+                    onResult: options.onResult,
+                    onError: options.onError,
+                });
+            });
+            // Ctrl-C on the dev server must take the scan down with it, or a browser
+            // is left driving an app that no longer exists.
+            server.httpServer.on("close", () => scan?.stop());
+        },
+    };
+}
+export default aztrx;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aztrx-cli",
-  "version": "0.4.5",
+  "version": "0.5.2",
   "private": false,
   "description": "Aztrx AI — runtime stress-tester for web apps. Detect bugs, then prove them with an executable repro.",
   "license": "Apache-2.0",
@@ -10,6 +10,26 @@
     "aztrx-cli": "dist/cli.js"
   },
   "main": "dist/core/orchestrator.js",
+  "types": "dist/core/orchestrator.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/core/orchestrator.d.ts",
+      "default": "./dist/core/orchestrator.js"
+    },
+    "./vite": {
+      "types": "./dist/vite/index.d.ts",
+      "default": "./dist/vite/index.js"
+    },
+    "./next": {
+      "types": "./dist/next/index.d.ts",
+      "default": "./dist/next/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/index.d.ts",
+      "default": "./dist/mcp/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
     "dist",
     "README.md",
@@ -17,7 +37,7 @@
     "media"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "keywords": [
     "testing",
@@ -32,13 +52,14 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/Aztrx-AI/aztrx.git"
+    "url": "git+https://github.com/Aztrx-AI/aztrx.git"
   },
   "scripts": {
     "build": "tsc",
     "dev": "node dist/cli.js",
     "bench": "npm run build && tsx bench/run.ts",
-    "test": "tsx --test \"tests/**/*.test.ts\"",
+    "pretest": "npm run build",
+    "test": "node scripts/run-tests.mjs",
     "typecheck": "tsc --noEmit && tsc -p server/tsconfig.json",
     "server": "tsx server/index.ts",
     "server:typecheck": "tsc -p server/tsconfig.json",
@@ -59,6 +80,23 @@
     "@types/node": "^22.10.0",
     "@types/pngjs": "^6.0.5",
     "@types/react": "^18.3.12",
-    "tsx": "^4.19.0"
-  }
+    "tsx": "^4.19.0",
+    "vite": "^8.3.0"
+  },
+  "peerDependencies": {
+    "vite": ">=4"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "directories": {
+    "doc": "docs",
+    "test": "tests"
+  },
+  "bugs": {
+    "url": "https://github.com/Aztrx-AI/aztrx/issues"
+  },
+  "homepage": "https://aztrx.app"
 }