@cruxy/cli 0.9.0 → 0.11.0

package/dist/testing/run-tests-tool.js

@@ -0,0 +1,128 @@
+import { z } from "zod";
+import { ErrorCode } from "../errors/index.js";
+import { detectTestCommand } from "./detect.js";
+import { CommandTestRunner } from "./runner.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 class TestIterationBudget {
+    failedRuns = 0;
+    /** Runs already spent in the current failing streak. */
+    get spent() {
+        return this.failedRuns;
+    }
+    /** True when the next run must be refused; resets the streak as it trips. */
+    trip(maxIterations) {
+        if (this.failedRuns < maxIterations)
+            return false;
+        this.failedRuns = 0;
+        return true;
+    }
+    record(passed) {
+        this.failedRuns = passed ? 0 : this.failedRuns + 1;
+    }
+}
+const parameters = z.object({
+    command: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Override the detected test command (still requires approval). " +
+        "Omit to use the project's configured/detected command."),
+});
+/** The wire shape fed back to the model — structured, bounded, honest. */
+function renderResult(result, command, iteration) {
+    return JSON.stringify({
+        passed: result.passed,
+        exitCode: result.exitCode,
+        durationMs: result.durationMs,
+        command: command.command,
+        ...(result.total !== undefined ? { total: result.total } : {}),
+        failures: result.failures,
+        iteration,
+        output: result.output,
+        outputTruncated: result.outputTruncated,
+    });
+}
+/** Build the `run_tests` tool. One instance = one session's iteration budget. */
+export function makeRunTestsTool(deps = {}) {
+    const runner = deps.runner ?? new CommandTestRunner();
+    const detect = deps.detect ??
+        ((ctx) => detectTestCommand(ctx.cwd, ctx.config));
+    const budget = new TestIterationBudget();
+    return {
+        name: "run_tests",
+        description: "Run the project's test suite and get a structured result: passed (from the exit code), " +
+            "extracted failures with file/line where recognizable, and the output tail. " +
+            "Use it to verify changes: run, read the failures, fix, re-run. The edit→re-run loop is " +
+            "capped — when the iteration limit trips, stop, summarize the remaining failures, and ask the user.",
+        parameters,
+        async execute(input, ctx) {
+            // Resolve the command first: detection failure needs no approval and
+            // must be a coded, actionable error — never an invented command.
+            let resolved;
+            if (input.command !== undefined) {
+                resolved = { command: input.command, source: "override" };
+            }
+            else {
+                const detected = detect(ctx);
+                if (detected === null)
+                    return { ok: false, error: NOT_FOUND };
+                resolved = detected;
+            }
+            // Iteration cap BEFORE the gate and the run: a refused attempt executes
+            // nothing and costs nothing.
+            const max = ctx.config.test.maxIterations;
+            if (budget.trip(max)) {
+                return {
+                    ok: false,
+                    error: `${ErrorCode.TestIterationLimit}: tests are still failing after ${max} run${max === 1 ? "" : "s"}. ` +
+                        "Stop iterating. Summarize the remaining failures and what you tried, then ask the user how to proceed.",
+                };
+            }
+            // U.3 gate (destructive tier, exact-command grant scope). A thrown
+            // CRUXY_E_APPROVAL_REQUIRED (non-interactive) propagates — do not catch.
+            const decision = await ctx.requestApproval({
+                kind: "test",
+                command: resolved.command,
+            });
+            if (!decision.allow) {
+                return {
+                    ok: false,
+                    error: decision.feedback ?? "test run denied by the user",
+                };
+            }
+            const result = await runner.run(resolved.command, {
+                cwd: ctx.cwd,
+                timeoutMs: ctx.config.shell.timeoutMs,
+                captureBytes: ctx.config.test.captureBytes,
+            });
+            budget.record(result.passed);
+            const payload = renderResult(result, resolved, {
+                run: result.passed ? 0 : budget.spent,
+                max,
+            });
+            // Failing tests are an is_error result so the U.4 trail note reads ✗ —
+            // the payload is identical either way; the model reasons over both.
+            return result.passed
+                ? { ok: true, output: payload }
+                : { ok: false, error: payload };
+        },
+    };
+}
+/** The coded not-configured message, actionable for model and user alike. */
+const NOT_FOUND = `${ErrorCode.TestCommandNotFound}: no test command found — package.json has no usable ` +
+    "`scripts.test` and `test.command` is not configured. Ask the user to set `test.command` " +
+    '(e.g. `cruxy config set test.command "pnpm test"`); do not guess a command.';

package/dist/testing/runner.d.ts

@@ -0,0 +1,26 @@
+import type { TestRunner, TestRunOptions, TestRunResult } from "./types.js";
+/**
+ * The shipped {@link TestRunner}: spawn the command via the system shell (the
+ * same detached-group + kill-tree discipline as `run_command`), capture a
+ * TAIL-biased, byte-capped transcript (failures live at the end of test
+ * output), and derive `passed` from the exit code — the only source of truth.
+ * A timeout, a signal kill, or a spawn error is a *failed result*, never a
+ * thrown exception and never a fabricated success.
+ */
+export declare class CommandTestRunner implements TestRunner {
+    run(command: string, opts: TestRunOptions): Promise<TestRunResult>;
+}
+/**
+ * A rolling, tail-biased capture: whole chunks are dropped from the FRONT
+ * once the byte cap is exceeded, so the end of the output — where test
+ * runners print their failure summaries — always survives.
+ */
+export declare class TailCapture {
+    private readonly cap;
+    private chunks;
+    private bytes;
+    truncated: boolean;
+    constructor(cap: number);
+    push(buf: Buffer): void;
+    text(): string;
+}

package/dist/testing/runner.js

@@ -0,0 +1,124 @@
+import { spawn } from "node:child_process";
+import { parseFailures } from "./parse.js";
+/**
+ * The shipped {@link TestRunner}: spawn the command via the system shell (the
+ * same detached-group + kill-tree discipline as `run_command`), capture a
+ * TAIL-biased, byte-capped transcript (failures live at the end of test
+ * output), and derive `passed` from the exit code — the only source of truth.
+ * A timeout, a signal kill, or a spawn error is a *failed result*, never a
+ * thrown exception and never a fabricated success.
+ */
+export class CommandTestRunner {
+    run(command, opts) {
+        const startedAt = Date.now();
+        return new Promise((resolve) => {
+            const capture = new TailCapture(opts.captureBytes);
+            let child;
+            try {
+                child = spawn(command, {
+                    shell: true,
+                    cwd: opts.cwd,
+                    detached: true,
+                });
+            }
+            catch (err) {
+                resolve(failed(null, err.message, startedAt));
+                return;
+            }
+            child.stdout?.on("data", (buf) => capture.push(buf));
+            child.stderr?.on("data", (buf) => capture.push(buf));
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                killTree(child.pid);
+                resolve(failed(null, capture.text() +
+                    `\n… [test run timed out after ${opts.timeoutMs}ms and was killed]`, startedAt, capture.truncated));
+            }, opts.timeoutMs);
+            child.on("error", (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve(failed(null, err.message, startedAt));
+            });
+            child.on("close", (code) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                const output = capture.text();
+                // THE honest-green rule: exit code 0 and nothing else means passed.
+                // `code` is null on a signal kill — a failure, whatever the output says.
+                const passed = code === 0;
+                const parsed = passed ? { failures: [] } : parseFailures(output);
+                resolve({
+                    passed,
+                    exitCode: code,
+                    durationMs: Date.now() - startedAt,
+                    ...(parsed.total !== undefined ? { total: parsed.total } : {}),
+                    failures: parsed.failures,
+                    output,
+                    outputTruncated: capture.truncated,
+                });
+            });
+        });
+    }
+}
+/** Shape a non-execution failure (spawn error, timeout) as a failed result. */
+function failed(exitCode, output, startedAt, truncated = false) {
+    return {
+        passed: false,
+        exitCode,
+        durationMs: Date.now() - startedAt,
+        failures: [],
+        output,
+        outputTruncated: truncated,
+    };
+}
+/**
+ * A rolling, tail-biased capture: whole chunks are dropped from the FRONT
+ * once the byte cap is exceeded, so the end of the output — where test
+ * runners print their failure summaries — always survives.
+ */
+export class TailCapture {
+    cap;
+    chunks = [];
+    bytes = 0;
+    truncated = false;
+    constructor(cap) {
+        this.cap = cap;
+    }
+    push(buf) {
+        this.chunks.push(buf);
+        this.bytes += buf.length;
+        // Drop head chunks while the REMAINDER still meets the cap.
+        while (this.chunks.length > 1 &&
+            this.bytes - this.chunks[0].length >= this.cap) {
+            this.bytes -= this.chunks[0].length;
+            this.chunks.shift();
+            this.truncated = true;
+        }
+    }
+    text() {
+        let all = Buffer.concat(this.chunks);
+        if (all.length > this.cap) {
+            all = all.subarray(all.length - this.cap);
+            this.truncated = true;
+        }
+        const body = all.toString("utf8");
+        return this.truncated ? `… [earlier output truncated]\n${body}` : body;
+    }
+}
+/** Kill the whole process group (POSIX; matches run_command's behavior). */
+function killTree(pid) {
+    if (pid === undefined)
+        return;
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch {
+        // Already exited, or no group — nothing to kill.
+    }
+}

package/dist/testing/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Types for the test-execution loop (C.13): run the project's test suite,
+ * parse what's honestly parseable, and let the agent iterate on failures
+ * under a hard cap. The cardinal rule lives in `runner.ts`: **passed is
+ * derived from the exit code and nothing else.**
+ */
+/** A resolved test command and where it came from — shown, never guessed. */
+export interface TestCommand {
+    command: string;
+    source: "config" | "package-json";
+}
+/** One extracted failure. Every field beyond `name`/`message` is best-effort. */
+export interface TestFailure {
+    name: string;
+    message: string;
+    file?: string;
+    line?: number;
+}
+/** The structured outcome of one test-suite execution. */
+export interface TestRunResult {
+    /** `exitCode === 0`, full stop — never inferred from output text. */
+    passed: boolean;
+    /** The command's exit code; `null` when killed by signal or never spawned. */
+    exitCode: number | null;
+    /** Measured wall time of the execution. */
+    durationMs: number;
+    /** Total tests, only when a parser confidently extracted it. */
+    total?: number;
+    /** Best-effort extracted failures; may be empty even when `passed` is false. */
+    failures: TestFailure[];
+    /** Tail-biased captured stdout+stderr, capped at `test.captureBytes`. */
+    output: string;
+    /** Whether the head of the output was dropped to honor the byte cap. */
+    outputTruncated: boolean;
+}
+/** Execution bounds handed to a runner per run. */
+export interface TestRunOptions {
+    cwd: string;
+    /** Kill the run (and its process tree) after this many ms. */
+    timeoutMs: number;
+    /** Cap on captured output bytes (tail-biased). */
+    captureBytes: number;
+}
+/**
+ * The swappable execution seam (same discipline as VectorStore/ForgeProvider):
+ * the shipped {@link CommandTestRunner} spawns the command via the system
+ * shell; tests inject fakes, and a future framework-native runner (e.g. a
+ * vitest API runner) slots in without touching the tool.
+ */
+export interface TestRunner {
+    run(command: string, opts: TestRunOptions): Promise<TestRunResult>;
+}
+/**
+ * A pluggable best-effort failure extractor: given the captured output,
+ * return whatever structure it can positively recognize — and nothing it
+ * can't. Parsers never touch `passed` and never fabricate counts.
+ */
+export type FailureParser = (output: string) => {
+    failures: TestFailure[];
+    total?: number;
+};

package/dist/testing/types.js

@@ -0,0 +1,7 @@
+/**
+ * Types for the test-execution loop (C.13): run the project's test suite,
+ * parse what's honestly parseable, and let the agent iterate on failures
+ * under a hard cap. The cardinal rule lives in `runner.ts`: **passed is
+ * derived from the exit code and nothing else.**
+ */
+export {};

package/dist/tools/registry.js

@@ -3,6 +3,7 @@ import { listFilesTool } from "./list-files.js";
 import { gitStatusTool } from "./git-status.js";
 import { readFileTool, writeFileTool, editFileTool, applyPatchTool, globTool, grepFilesTool, } from "./file/index.js";
 import { runCommandTool } from "./shell/index.js";
+import { makeRunTestsTool } from "../testing/run-tests-tool.js";
 import { searchCodebaseTool } from "./search-codebase.js";
 import { listSkillsTool } from "./list-skills.js";
 import { loadSkillTool } from "./load-skill.js";
@@ -63,6 +64,8 @@ export function buildDefaultRegistry() {
     registry.register(grepFilesTool);
     registry.register(gitStatusTool);
     registry.register(runCommandTool);
+    // A fresh tool per registry — its iteration budget (C.13) is session-scoped.
+    registry.register(makeRunTestsTool());
     registry.register(searchCodebaseTool);
     registry.register(listSkillsTool);
     registry.register(loadSkillTool);

package/dist/tools/types.d.ts

@@ -101,10 +101,10 @@ export type ActionPreview =
  */
 export interface ApproveAction {
     /** The category of side effect being requested. */
-    kind: "write" | "edit" | "shell" | "patch" | "vcs" | "rollback";
+    kind: "write" | "edit" | "shell" | "patch" | "vcs" | "rollback" | "test";
     /** Absolute resolved path the action targets (write/edit). */
     path?: string;
-    /** The command to run (shell). */
+    /** The command to run (shell / test). */
     command?: string;
     /** Exact-change preview rendered above the prompt (write/edit/patch/vcs/rollback). */
     preview?: ActionPreview;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {