@cruxy/cli 0.9.0 → 0.11.0

package/dist/config/schema.d.ts

@@ -219,6 +219,27 @@ export declare const CheckpointConfigSchema: z.ZodObject<{
     enabled?: boolean | undefined;
     retention?: number | undefined;
 }>;
+/**
+ * Test-execution loop (C.13): how the agent runs the project's test suite and
+ * iterates on failures. The command is detected from package.json when unset;
+ * cruxy never invents one.
+ */
+export declare const TestConfigSchema: z.ZodObject<{
+    /** Explicit test command (overrides package.json detection). */
+    command: z.ZodOptional<z.ZodString>;
+    /** Consecutive failing runs before the edit→re-run loop trips its cap. */
+    maxIterations: z.ZodDefault<z.ZodNumber>;
+    /** Cap on captured test output bytes (tail-biased — failures come last). */
+    captureBytes: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    maxIterations: number;
+    captureBytes: number;
+    command?: string | undefined;
+}, {
+    maxIterations?: number | undefined;
+    command?: string | undefined;
+    captureBytes?: number | undefined;
+}>;
 /**
  * Subagent orchestration (C.14): scoped child agents the main agent can spawn
  * for bounded subtasks. Every cap here is a hard bound — a subagent can narrow
@@ -514,6 +535,22 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             timeoutMs?: number | undefined;
         } | undefined;
     }>>;
+    test: z.ZodDefault<z.ZodObject<{
+        /** Explicit test command (overrides package.json detection). */
+        command: z.ZodOptional<z.ZodString>;
+        /** Consecutive failing runs before the edit→re-run loop trips its cap. */
+        maxIterations: z.ZodDefault<z.ZodNumber>;
+        /** Cap on captured test output bytes (tail-biased — failures come last). */
+        captureBytes: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        maxIterations: number;
+        captureBytes: number;
+        command?: string | undefined;
+    }, {
+        maxIterations?: number | undefined;
+        command?: string | undefined;
+        captureBytes?: number | undefined;
+    }>>;
     mcpServers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         command: z.ZodOptional<z.ZodString>;
         args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -592,6 +629,11 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             timeoutMs?: number | undefined;
         };
     };
+    test: {
+        maxIterations: number;
+        captureBytes: number;
+        command?: string | undefined;
+    };
     mcpServers: Record<string, {
         command?: string | undefined;
         args?: string[] | undefined;
@@ -662,6 +704,11 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             timeoutMs?: number | undefined;
         } | undefined;
     } | undefined;
+    test?: {
+        maxIterations?: number | undefined;
+        command?: string | undefined;
+        captureBytes?: number | undefined;
+    } | undefined;
     mcpServers?: Record<string, {
         command?: string | undefined;
         args?: string[] | undefined;

package/dist/config/schema.js

@@ -149,6 +149,25 @@ export const CheckpointConfigSchema = z
     retention: z.number().int().positive().default(10),
 })
     .strict();
+/**
+ * Test-execution loop (C.13): how the agent runs the project's test suite and
+ * iterates on failures. The command is detected from package.json when unset;
+ * cruxy never invents one.
+ */
+export const TestConfigSchema = z
+    .object({
+    /** Explicit test command (overrides package.json detection). */
+    command: z.string().min(1).optional(),
+    /** Consecutive failing runs before the edit→re-run loop trips its cap. */
+    maxIterations: z.number().int().positive().default(4),
+    /** Cap on captured test output bytes (tail-biased — failures come last). */
+    captureBytes: z
+        .number()
+        .int()
+        .positive()
+        .default(64 * 1024),
+})
+    .strict();
 /**
  * Subagent orchestration (C.14): scoped child agents the main agent can spawn
  * for bounded subtasks. Every cap here is a hard bound — a subagent can narrow
@@ -196,6 +215,7 @@ export const CruxyConfigSchema = z
     index: IndexConfigSchema.default({}),
     checkpoint: CheckpointConfigSchema.default({}),
     subagent: SubagentConfigSchema.default({}),
+    test: TestConfigSchema.default({}),
     mcpServers: z.record(z.string(), McpServerSchema).default({}),
     logLevel: z.enum(LOG_LEVELS).default("info"),
 })

package/dist/errors/constructors.d.ts

@@ -2,6 +2,13 @@ import { CruxyError } from "./types.js";
 /** Best-effort human message for an arbitrary thrown value. */
 export declare function messageOf(underlying: unknown): string | undefined;
 export declare function usageError(title: string, nextSteps?: string[]): CruxyError;
+/**
+ * An interactive component (picker, fuzzy finder) was needed but stdin is not
+ * an interactive terminal and the caller supplied no default (U.7). Never
+ * silently picks an option, never blocks on a pipe — same discipline as the
+ * approval/onboarding layers.
+ */
+export declare function interactiveRequired(what: string, alternatives?: string[]): CruxyError;
 export declare function configKeyUnknown(key: string): CruxyError;
 export declare function providerUnsupported(provider: string): CruxyError;
 export declare function configParse(path: string, underlying?: unknown): CruxyError;
@@ -78,6 +85,11 @@ export declare function subagentDepthExceeded(depth: number, maxDepth: number):
  * reasons over; thrown only when the orchestrator itself cannot proceed.
  */
 export declare function subagentFailed(underlying?: unknown): CruxyError;
+/**
+ * No test command could be detected and none is configured (C.13). cruxy never
+ * invents a test command — the fix is always to declare one.
+ */
+export declare function testCommandNotFound(): CruxyError;
 export declare function internal(underlying?: unknown): CruxyError;
 /**
  * Map a known provider/transport error (from `@cruxy/sdk`) to a typed

package/dist/errors/constructors.js

@@ -23,6 +23,21 @@ export function usageError(title, nextSteps) {
         nextSteps: nextSteps ?? ["run `cruxy --help` for usage"],
     });
 }
+/**
+ * An interactive component (picker, fuzzy finder) was needed but stdin is not
+ * an interactive terminal and the caller supplied no default (U.7). Never
+ * silently picks an option, never blocks on a pipe — same discipline as the
+ * approval/onboarding layers.
+ */
+export function interactiveRequired(what, alternatives = []) {
+    return new CruxyError({
+        code: ErrorCode.InteractiveRequired,
+        title: `${what} needs an interactive terminal`,
+        cause: "stdin is not a TTY (or the terminal cannot render an interactive picker)",
+        nextSteps: ["run cruxy in an interactive terminal", ...alternatives],
+        meta: { what },
+    });
+}
 export function configKeyUnknown(key) {
     return new CruxyError({
         code: ErrorCode.ConfigKeyUnknown,
@@ -421,6 +436,22 @@ export function subagentFailed(underlying) {
         underlying,
     });
 }
+// ── testing (exit 2) ──────────────────────────────────────────────────────────
+/**
+ * No test command could be detected and none is configured (C.13). cruxy never
+ * invents a test command — the fix is always to declare one.
+ */
+export function testCommandNotFound() {
+    return new CruxyError({
+        code: ErrorCode.TestCommandNotFound,
+        title: "no test command found for this project",
+        cause: "package.json has no usable `scripts.test` and `test.command` is not configured",
+        nextSteps: [
+            'set `test.command` in your cruxy config (e.g. `cruxy config set test.command "pnpm test"`)',
+            "or add a `test` script to package.json",
+        ],
+    });
+}
 // ── internal (exit 1) ─────────────────────────────────────────────────────────
 export function internal(underlying) {
     return new CruxyError({

package/dist/errors/types.d.ts

@@ -14,6 +14,7 @@
 export declare const ErrorCode: {
     readonly Internal: "CRUXY_E_INTERNAL";
     readonly Usage: "CRUXY_E_USAGE";
+    readonly InteractiveRequired: "CRUXY_E_INTERACTIVE_REQUIRED";
     readonly ConfigKeyUnknown: "CRUXY_E_CONFIG_KEY_UNKNOWN";
     readonly ProviderUnsupported: "CRUXY_E_PROVIDER_UNSUPPORTED";
     readonly GitProtectedBranch: "CRUXY_E_GIT_PROTECTED_BRANCH";
@@ -48,6 +49,9 @@ export declare const ErrorCode: {
     /** Carried inside a SubagentResult (informational) — never fatal by itself. */
     readonly SubagentBudget: "CRUXY_E_SUBAGENT_BUDGET";
     readonly SubagentFailed: "CRUXY_E_SUBAGENT_FAILED";
+    readonly TestCommandNotFound: "CRUXY_E_TEST_COMMAND_NOT_FOUND";
+    /** Carried inside a run_tests result (informational) — never fatal by itself. */
+    readonly TestIterationLimit: "CRUXY_E_TEST_ITERATION_LIMIT";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 /** The process exit code for an error code (defaults to 1 for safety). */

package/dist/errors/types.js

@@ -16,6 +16,7 @@ export const ErrorCode = {
     Internal: "CRUXY_E_INTERNAL",
     // usage (exit 2)
     Usage: "CRUXY_E_USAGE",
+    InteractiveRequired: "CRUXY_E_INTERACTIVE_REQUIRED",
     ConfigKeyUnknown: "CRUXY_E_CONFIG_KEY_UNKNOWN",
     ProviderUnsupported: "CRUXY_E_PROVIDER_UNSUPPORTED",
     GitProtectedBranch: "CRUXY_E_GIT_PROTECTED_BRANCH",
@@ -59,6 +60,10 @@ export const ErrorCode = {
     /** Carried inside a SubagentResult (informational) — never fatal by itself. */
     SubagentBudget: "CRUXY_E_SUBAGENT_BUDGET",
     SubagentFailed: "CRUXY_E_SUBAGENT_FAILED",
+    // testing (exit 2 / 11)
+    TestCommandNotFound: "CRUXY_E_TEST_COMMAND_NOT_FOUND",
+    /** Carried inside a run_tests result (informational) — never fatal by itself. */
+    TestIterationLimit: "CRUXY_E_TEST_ITERATION_LIMIT",
 };
 /**
  * Category exit codes. Distinct per category so a caller (CI, a script) can
@@ -67,6 +72,7 @@ export const ErrorCode = {
 const EXIT_CODES = {
     [ErrorCode.Internal]: 1,
     [ErrorCode.Usage]: 2,
+    [ErrorCode.InteractiveRequired]: 2,
     [ErrorCode.ConfigKeyUnknown]: 2,
     [ErrorCode.ProviderUnsupported]: 2,
     [ErrorCode.GitProtectedBranch]: 2,
@@ -102,6 +108,10 @@ const EXIT_CODES = {
     [ErrorCode.SubagentDepthExceeded]: 2,
     [ErrorCode.SubagentBudget]: 11,
     [ErrorCode.SubagentFailed]: 11,
+    // No test command is a configuration gap (usage); the iteration limit
+    // surfaces inside a run_tests result and is never fatal by itself.
+    [ErrorCode.TestCommandNotFound]: 2,
+    [ErrorCode.TestIterationLimit]: 11,
 };
 /** The process exit code for an error code (defaults to 1 for safety). */
 export function exitCodeFor(code) {

package/dist/onboarding/io.d.ts

@@ -2,7 +2,8 @@ import type { OnboardingIO } from "./types.js";
 /**
  * The real stdin/stderr-backed {@link OnboardingIO}. Prompts go to stderr (stdout
  * stays clean for piping); the secret reader echoes `*` per keystroke and never
- * the real character. All readers restore cooked mode on the way out, even on
- * Ctrl-C / EOF — the terminal is never left in raw mode.
+ * the real character. Raw-mode key handling is the shared U.7 reader
+ * (`components/input.ts`) — the single owner of `setRawMode` — so cooked mode
+ * is restored on every exit path, Ctrl-C / EOF included.
  */
 export declare function defaultOnboardingIO(color?: boolean): OnboardingIO;

package/dist/onboarding/io.js

@@ -1,54 +1,21 @@
+import { createKeyReader, readSingleKey } from "../components/input.js";
 import { shouldUseColor } from "../errors/index.js";
 /**
  * The real stdin/stderr-backed {@link OnboardingIO}. Prompts go to stderr (stdout
  * stays clean for piping); the secret reader echoes `*` per keystroke and never
- * the real character. All readers restore cooked mode on the way out, even on
- * Ctrl-C / EOF — the terminal is never left in raw mode.
+ * the real character. Raw-mode key handling is the shared U.7 reader
+ * (`components/input.ts`) — the single owner of `setRawMode` — so cooked mode
+ * is restored on every exit path, Ctrl-C / EOF included.
  */
 export function defaultOnboardingIO(color = shouldUseColor()) {
     return {
         write: (text) => void process.stderr.write(text),
         readLine: readLineFromStdin,
-        readKey: readKeyFromStdin,
+        readKey: () => readSingleKey(),
         readSecret: readSecretFromStdin,
         color,
     };
 }
-const CTRL_C = 0x03;
-const CTRL_D = 0x04;
-const BACKSPACE = 0x08;
-const DELETE = 0x7f;
-const LF = 0x0a;
-const CR = 0x0d;
-/** Read one keypress in raw mode; "" on EOF / Ctrl-C / Ctrl-D. Restores cooked mode. */
-function readKeyFromStdin() {
-    const stdin = process.stdin;
-    return new Promise((resolve) => {
-        const cleanup = () => {
-            stdin.removeListener("data", onData);
-            stdin.removeListener("end", onEnd);
-            if (stdin.isTTY)
-                stdin.setRawMode(false);
-            stdin.pause();
-        };
-        const onData = (buf) => {
-            cleanup();
-            const code = buf[0];
-            resolve(code === CTRL_C || code === CTRL_D
-                ? ""
-                : buf.toString("utf8").slice(0, 1));
-        };
-        const onEnd = () => {
-            cleanup();
-            resolve("");
-        };
-        if (stdin.isTTY)
-            stdin.setRawMode(true);
-        stdin.resume();
-        stdin.once("data", onData);
-        stdin.once("end", onEnd);
-    });
-}
 /** Read one line in cooked mode; "" on EOF. */
 function readLineFromStdin() {
     const stdin = process.stdin;
@@ -80,54 +47,41 @@ function readLineFromStdin() {
 }
 /**
  * Read a secret with no echo: each printable keystroke shows a `*`, backspace
- * erases one, Enter submits, Ctrl-C / Ctrl-D / EOF resolve "" (abort). The real
- * characters are never written anywhere.
+ * erases one, Enter submits, Ctrl-C / Ctrl-D / EOF resolve "" (abort). The
+ * real characters are never written anywhere. Built on the shared key reader,
+ * which also keeps arrow/escape sequences from leaking into the secret.
  */
-function readSecretFromStdin() {
-    const stdin = process.stdin;
+async function readSecretFromStdin() {
     const out = process.stderr;
-    return new Promise((resolve) => {
-        let buf = "";
-        let done = false;
-        const cleanup = () => {
-            stdin.removeListener("data", onData);
-            stdin.removeListener("end", onEnd);
-            if (stdin.isTTY)
-                stdin.setRawMode(false);
-            stdin.pause();
-        };
-        const finish = (value) => {
-            if (done)
-                return;
-            done = true;
-            cleanup();
-            out.write("\n");
-            resolve(value);
-        };
-        const onData = (chunk) => {
-            for (const byte of chunk) {
-                if (byte === CR || byte === LF)
-                    return finish(buf); // Enter → submit
-                if (byte === CTRL_C || byte === CTRL_D)
-                    return finish(""); // abort
-                if (byte === DELETE || byte === BACKSPACE) {
+    const keys = createKeyReader(process.stdin);
+    keys.begin();
+    let buf = "";
+    try {
+        for (;;) {
+            const key = await keys.read();
+            switch (key.kind) {
+                case "enter":
+                    return buf;
+                case "ctrl-c":
+                case "eof":
+                    return "";
+                case "backspace":
                     if (buf.length > 0) {
                         buf = buf.slice(0, -1);
                         out.write("\b \b"); // erase one star
                     }
-                    continue;
-                }
-                if (byte < 0x20)
-                    continue; // ignore other control chars
-                buf += String.fromCharCode(byte);
-                out.write("*");
+                    break;
+                case "char":
+                    buf += key.char;
+                    out.write("*");
+                    break;
+                default:
+                    break; // arrows / tab / escape: ignored, never echoed
             }
-        };
-        const onEnd = () => finish("");
-        if (stdin.isTTY)
-            stdin.setRawMode(true);
-        stdin.resume();
-        stdin.on("data", onData);
-        stdin.once("end", onEnd);
-    });
+        }
+    }
+    finally {
+        keys.restore();
+        out.write("\n");
+    }
 }

package/dist/testing/detect.d.ts

@@ -0,0 +1,3 @@
+import type { CruxyConfig } from "../config/index.js";
+import type { TestCommand } from "./types.js";
+export declare function detectTestCommand(cwd: string, config: CruxyConfig): TestCommand | null;

package/dist/testing/detect.js

@@ -0,0 +1,44 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+/**
+ * Resolve the project's test command (C.13). Order: explicit `test.command`
+ * config, then package.json `scripts.test`. Returns `null` when neither
+ * yields one — cruxy NEVER invents a test command; the caller surfaces the
+ * coded not-configured error instead.
+ */
+/** npm's scaffold placeholder is an error message, not a test suite. */
+const NPM_PLACEHOLDER = /no test specified/i;
+export function detectTestCommand(cwd, config) {
+    if (config.test.command) {
+        return { command: config.test.command, source: "config" };
+    }
+    const script = readTestScript(cwd);
+    if (script === null)
+        return null;
+    return { command: `${packageManager(cwd)} test`, source: "package-json" };
+}
+/** The package.json `scripts.test` value, or null if absent/placeholder/unreadable. */
+function readTestScript(cwd) {
+    try {
+        const raw = readFileSync(path.join(cwd, "package.json"), "utf8");
+        const pkg = JSON.parse(raw);
+        const script = pkg.scripts?.test;
+        if (typeof script !== "string" || script.trim() === "")
+            return null;
+        if (NPM_PLACEHOLDER.test(script))
+            return null;
+        return script;
+    }
+    catch {
+        // No package.json / unparseable → not detected (never a crash).
+        return null;
+    }
+}
+/** Pick the package manager by lockfile; npm when nothing identifies one. */
+function packageManager(cwd) {
+    if (existsSync(path.join(cwd, "pnpm-lock.yaml")))
+        return "pnpm";
+    if (existsSync(path.join(cwd, "yarn.lock")))
+        return "yarn";
+    return "npm";
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./detect.js";
+export * from "./runner.js";
+export * from "./parse.js";
+export * from "./run-tests-tool.js";

package/dist/testing/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./detect.js";
+export * from "./runner.js";
+export * from "./parse.js";
+export * from "./run-tests-tool.js";

package/dist/testing/parse.d.ts

@@ -0,0 +1,33 @@
+import type { FailureParser, TestFailure } from "./types.js";
+/**
+ * Best-effort failure extraction (C.13). Two conservative parsers ship —
+ * vitest-style and jest-style — behind the pluggable {@link FailureParser}
+ * seam. The contract: extract only what a pattern positively recognizes;
+ * when nothing matches, return NOTHING (the caller falls back to the raw
+ * tail). Parsers never decide pass/fail and never invent counts — `message`
+ * fields are verbatim runner output, not summaries we authored.
+ */
+/**
+ * Vitest: per-test failure lines (`FAIL src/x.test.ts > suite > name`, also
+ * `×`/`✗` markers) and the `Tests  2 failed | 570 passed (572)` summary.
+ * Plain file-level `FAIL <file>` lines are deliberately left to the jest
+ * parser, which owns the file+bullet association.
+ */
+export declare const parseVitest: FailureParser;
+/**
+ * Jest: `FAIL <file>` headers with `● <name>` bullets underneath (the bullet's
+ * following indented lines are its message, verbatim), and the
+ * `Tests: …, N total` summary. A FAIL header with no bullets (e.g. a suite
+ * that failed to load) becomes one file-level failure.
+ */
+export declare const parseJest: FailureParser;
+/** Parser order: most-specific first. The pluggable seam for new frameworks. */
+export declare const defaultParsers: readonly FailureParser[];
+/**
+ * Run the parser chain; the first parser that recognizes anything wins.
+ * Nothing recognized → empty failures, no total — the raw tail is the result.
+ */
+export declare function parseFailures(output: string): {
+    failures: TestFailure[];
+    total?: number;
+};

package/dist/testing/parse.js

@@ -0,0 +1,137 @@
+/**
+ * Best-effort failure extraction (C.13). Two conservative parsers ship —
+ * vitest-style and jest-style — behind the pluggable {@link FailureParser}
+ * seam. The contract: extract only what a pattern positively recognizes;
+ * when nothing matches, return NOTHING (the caller falls back to the raw
+ * tail). Parsers never decide pass/fail and never invent counts — `message`
+ * fields are verbatim runner output, not summaries we authored.
+ */
+/**
+ * Vitest: per-test failure lines (`FAIL src/x.test.ts > suite > name`, also
+ * `×`/`✗` markers) and the `Tests  2 failed | 570 passed (572)` summary.
+ * Plain file-level `FAIL <file>` lines are deliberately left to the jest
+ * parser, which owns the file+bullet association.
+ */
+export const parseVitest = (output) => {
+    const failures = [];
+    for (const line of output.split("\n")) {
+        const match = /^\s*(?:FAIL|✗|×)\s+(\S+)\s+>\s+(.+?)\s*$/.exec(line);
+        if (match) {
+            failures.push({
+                name: match[2],
+                message: line.trim(),
+                file: match[1],
+            });
+        }
+    }
+    attachLines(failures, output);
+    const total = /^\s*Tests\s+.*\((\d+)\)\s*$/m.exec(output);
+    return {
+        failures,
+        ...(total ? { total: Number(total[1]) } : {}),
+    };
+};
+/**
+ * Jest: `FAIL <file>` headers with `● <name>` bullets underneath (the bullet's
+ * following indented lines are its message, verbatim), and the
+ * `Tests: …, N total` summary. A FAIL header with no bullets (e.g. a suite
+ * that failed to load) becomes one file-level failure.
+ */
+export const parseJest = (output) => {
+    const failures = [];
+    const lines = output.split("\n");
+    let currentFile;
+    const filesWithBullets = new Set();
+    const bareFiles = [];
+    for (let i = 0; i < lines.length; i++) {
+        const fail = /^\s*FAIL\s+(\S+)\s*$/.exec(lines[i]);
+        if (fail) {
+            currentFile = fail[1];
+            bareFiles.push(fail[1]);
+            continue;
+        }
+        const bullet = /^\s*●\s+(.+?)\s*$/.exec(lines[i]);
+        if (bullet) {
+            failures.push({
+                name: bullet[1],
+                message: bulletMessage(lines, i),
+                ...(currentFile ? { file: currentFile } : {}),
+            });
+            if (currentFile)
+                filesWithBullets.add(currentFile);
+        }
+    }
+    // A failed suite with no per-test bullets is still one honest failure.
+    for (const file of bareFiles) {
+        if (!filesWithBullets.has(file)) {
+            failures.push({ name: file, message: `FAIL ${file}`, file });
+        }
+    }
+    attachLines(failures, output);
+    const total = /^Tests:.*?(\d+)\s+total\s*$/m.exec(output);
+    return {
+        failures,
+        ...(total ? { total: Number(total[1]) } : {}),
+    };
+};
+/**
+ * Up to three non-blank lines under a jest bullet — its verbatim message.
+ * Jest separates the bullet from its detail with a blank line, so leading
+ * blanks are skipped; collection stops at the next blank, the next bullet,
+ * or the cap.
+ */
+function bulletMessage(lines, bulletIndex) {
+    const body = [];
+    for (let j = bulletIndex + 1; j < lines.length && body.length < 3; j++) {
+        const text = lines[j].trim();
+        if (text === "") {
+            if (body.length === 0)
+                continue; // the separator blank under the bullet
+            break;
+        }
+        if (/^\s*●\s+/.test(lines[j]))
+            break;
+        body.push(text);
+    }
+    return body.length > 0 ? body.join("\n") : lines[bulletIndex].trim();
+}
+/**
+ * Attach `line` to failures whose file appears in a `file:line:col` stack
+ * reference anywhere in the output (vitest `❯ file:39:5`, jest
+ * `at … (file:12:15)`). First reference per file wins; no reference → no line.
+ */
+function attachLines(failures, output) {
+    if (failures.length === 0)
+        return;
+    const firstLineFor = new Map();
+    for (const match of output.matchAll(/([^\s():]+):(\d+):\d+/g)) {
+        if (!firstLineFor.has(match[1])) {
+            firstLineFor.set(match[1], Number(match[2]));
+        }
+    }
+    for (const failure of failures) {
+        if (failure.file === undefined || failure.line !== undefined)
+            continue;
+        const line = firstLineFor.get(failure.file);
+        if (line !== undefined)
+            failure.line = line;
+    }
+}
+/** Parser order: most-specific first. The pluggable seam for new frameworks. */
+export const defaultParsers = [
+    parseVitest,
+    parseJest,
+];
+/**
+ * Run the parser chain; the first parser that recognizes anything wins.
+ * Nothing recognized → empty failures, no total — the raw tail is the result.
+ */
+export function parseFailures(output) {
+    for (const parser of defaultParsers) {
+        const result = parser(output);
+        if (result.failures.length > 0 || result.total !== undefined) {
+            return result;
+        }
+    }
+    return { failures: [] };
+}

package/dist/testing/run-tests-tool.d.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import type { Tool, ToolContext } from "../tools/types.js";
+import type { TestCommand, TestRunner } from "./types.js";
+/**
+ * The `run_tests` tool (C.13): execute the project's test suite and return a
+ * structured result the model can iterate on (edit → re-run → repeat). The
+ * iteration loop itself is the ordinary agent loop; this module contributes
+ * the two guarantees that make it trustworthy — honest green (exit-code-only)
+ * and a hard cap on consecutive failing runs.
+ */
+/**
+ * Counts consecutive FAILING test executions; a green run resets it. When the
+ * count reaches the cap, the next attempt is refused with the coded
+ * CRUXY_E_TEST_ITERATION_LIMIT result (nothing executes), and the counter
+ * resets — so the episode ends loudly, but a deliberate later attempt (a new
+ * user instruction) starts fresh rather than finding a permanently dead tool.
+ * Per-turn work stays bounded regardless via `agent.maxIterations`.
+ */
+export declare class TestIterationBudget {
+    private failedRuns;
+    /** Runs already spent in the current failing streak. */
+    get spent(): number;
+    /** True when the next run must be refused; resets the streak as it trips. */
+    trip(maxIterations: number): boolean;
+    record(passed: boolean): void;
+}
+declare const parameters: z.ZodObject<{
+    command: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    command?: string | undefined;
+}, {
+    command?: string | undefined;
+}>;
+export interface RunTestsToolDeps {
+    /** Execution seam (tests inject a fake; default spawns the real command). */
+    runner?: TestRunner;
+    /** Detection seam (defaults to config + package.json detection). */
+    detect?: (ctx: ToolContext) => TestCommand | null;
+}
+/** Build the `run_tests` tool. One instance = one session's iteration budget. */
+export declare function makeRunTestsTool(deps?: RunTestsToolDeps): Tool<typeof parameters>;
+export {};