probatio 0.3.0 → 0.5.0

package/dist/cli.js

@@ -1,721 +0,0 @@
-#!/usr/bin/env node
-import path from "node:path";
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { SCHEMA_VERSION, render } from "./contract.js";
-import { bool, int, parseArgs, requireText, text, texts } from "./flags.js";
-import { asTable, checkGolden, goldenShape, readGolden, writeGolden } from "./golden/check.js";
-import { compareGoldens, recordGoldens } from "./golden/record.js";
-import { buildLedger } from "./ledger/build.js";
-import { checkLedger } from "./ledger/check.js";
-import { readKills, reportMatrix } from "./matrix/report.js";
-import { appendFinding, chooseSealed, fixGap, guardAllows, lineHash, loadState, parseGuard, readSourceLine, revertGap, saveState, sealIds, statusEnvelope, } from "./memory/state.js";
-import { git } from "./mutate/patch.js";
-import { generateMutants } from "./mutate/generate.js";
-import { runMutants } from "./mutate/run.js";
-import { fixEditedKillers, LABEL_LEAK_SUMMARY, labelLeaked, readSealedLabel, sealedTreeLeaked } from "./mutate/sealed.js";
-import { generateNext } from "./mutate/suite-decision.js";
-import { discoverSuite } from "./mutate/suites.js";
-import { tallyRun } from "./mutate/tally.js";
-import { checkKill } from "./swarm/check-kill.js";
-import { claimItem, reapClaims, seedQueue } from "./swarm/queue.js";
-import { verifyChange } from "./verify/change.js";
-import { nodeTooOld } from "./node-version.js";
-const tooOld = nodeTooOld(process.versions.node);
-if (tooOld) {
-    process.stdout.write(`${JSON.stringify({
-        schemaVersion: SCHEMA_VERSION,
-        ok: false,
-        command: "mutate.help",
-        summary: tooOld,
-        next: "Install Node 22.6 or newer and run the command again.",
-        nextCall: null,
-    })}\n`);
-    process.exit(1);
-}
-const parsed = parseArgs(process.argv.slice(2));
-const [group, action] = parsed.command;
-if (group === "mcp" && !action) {
-    await import("./mcp.js");
-}
-else
-    try {
-        if (group === "mutate" && action === "generate")
-            finish(await generateCommand(parsed.flags), parsed.human);
-        if (group === "mutate" && action === "run")
-            finish(await runCommand(parsed.flags), parsed.human);
-        if (group === "mutate" && action === "sealed")
-            finish(await sealedCommand(parsed.flags), parsed.human);
-        if (group === "mutate" && action === "tally")
-            finish(tallyCommand(parsed.flags), parsed.human);
-        if (group === "ledger" && action === "build")
-            finish(await ledgerCommand(parsed.flags), parsed.human);
-        if (group === "ledger" && action === "check")
-            finish(await ledgerCheckCommand(parsed.flags), parsed.human);
-        if (group === "matrix" && action === "report")
-            finish(matrixCommand(parsed.flags), parsed.human);
-        if (group === "golden" && action === "check")
-            finish(goldenCommand(parsed.flags), parsed.human);
-        if (group === "golden" && action === "record")
-            finish(await goldenRecordCommand(parsed.flags), parsed.human);
-        if (group === "golden" && action === "compare")
-            finish(await goldenCompareCommand(parsed.flags), parsed.human);
-        if (group === "gap" && action === "fix")
-            finish(gapFixCommand(parsed.flags), parsed.human);
-        if (group === "gap" && action === "revert")
-            finish(gapRevertCommand(parsed.flags), parsed.human);
-        if (group === "guard" && action === "check")
-            finish(guardCommand(parsed.flags), parsed.human);
-        if (group === "findings" && action === "add")
-            finish(findingsCommand(parsed.flags), parsed.human);
-        if (group === "status")
-            finish(statusCommand(parsed.flags), parsed.human);
-        if (group === "seal")
-            finish(sealCommand(parsed.flags), parsed.human);
-        if (group === "queue" && action === "seed")
-            finish(queueSeedCommand(parsed.flags), parsed.human);
-        if (group === "queue" && action === "claim")
-            finish(queueClaimCommand(parsed.flags), parsed.human);
-        if (group === "queue" && action === "reap")
-            finish(queueReapCommand(parsed.flags), parsed.human);
-        if (group === "check-kill")
-            finish(await checkKillCommand(parsed.flags, action), parsed.human);
-        if (group === "verify-change")
-            finish(await verifyCommand(parsed.flags), parsed.human);
-        if (group === "schema")
-            finish(schemaCommand(action), parsed.human);
-        finish(usage(false, "Use mutate, ledger, matrix, golden, gap, guard, findings, status, queue, check-kill, verify-change, or schema."), parsed.human);
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        finish({
-            schemaVersion: SCHEMA_VERSION,
-            ok: false,
-            command: `${group ?? "mutate"}.${action ?? "help"}`,
-            summary: message,
-            next: "Fix the command and run it again.",
-            nextCall: null,
-        }, parsed.human);
-    }
-function usage(ok, summary) {
-    return {
-        schemaVersion: SCHEMA_VERSION,
-        ok,
-        command: "mutate.help",
-        summary,
-        next: "probatio mutate generate writes operator mutants. probatio mutate run confirms each kill twice. probatio mutate sealed runs one forward bug and keeps the label file out of the report. probatio mutate tally reads a finished run and does not delete a test. probatio ledger build reverts fix commits. probatio matrix report reads a recorded score table.",
-        nextCall: null,
-    };
-}
-async function generateCommand(flags) {
-    const packageDir = path.resolve(requireText(flags, "package"));
-    const outDir = path.resolve(requireText(flags, "out"));
-    const perFile = int(flags, "per-file");
-    const result = generateMutants({
-        packageDir,
-        srcDir: text(flags, "src") ?? "src",
-        outDir,
-        perFile: perFile === undefined ? null : perFile,
-        skip: int(flags, "skip") ?? 0,
-        seed: int(flags, "seed") ?? 20261003,
-        maxMutants: int(flags, "max-mutants") ?? null,
-        maxMinutes: int(flags, "max-minutes") ?? null,
-        skipFiles: texts(flags, "skip-file"),
-        commit: text(flags, "commit") ?? "HEAD",
-        workingTree: bool(flags, "working-tree", false),
-        operators: operatorSet(flags),
-    });
-    if (result.error) {
-        return {
-            schemaVersion: SCHEMA_VERSION,
-            ok: false,
-            command: "mutate.generate",
-            summary: result.error,
-            next: "Commit the file, or pass --working-tree to mutate the checkout on disk. mutate run scores the commit.",
-            nextCall: null,
-        };
-    }
-    if (result.violations.length > 0) {
-        const first = result.violations[0];
-        return {
-            schemaVersion: SCHEMA_VERSION,
-            ok: false,
-            command: "mutate.generate",
-            summary: `Refusing to write mutants: ${first.file}:${first.line} sits inside a string or a comment.`,
-            next: "That is a generator bug. Do not use the batch.",
-            nextCall: null,
-            stringLiteralMutants: result.violations.length,
-        };
-    }
-    const shown = result.mutants.slice(0, 10).map(({ id, file, line, op }) => ({ id, file, line, op }));
-    const patches = path.join(outDir, "mutants");
-    const stopped = result.budgetHit;
-    const suite = discoverSuite(packageDir, text(flags, "tests-dir") ?? "tests");
-    return {
-        schemaVersion: SCHEMA_VERSION,
-        ok: true,
-        command: "mutate.generate",
-        summary: stopped
-            ? `Stopped by the time budget after ${result.filesVisited} files. ${result.mutants.length} mutants written.`
-            : `${result.mutants.length} mutants in ${result.filesVisited} files. No string-literal mutant.`,
-        next: [
-            stopped
-                ? "Narrow --src or raise --max-minutes, then run the same command."
-                : generateNext(result.mutants.length, suite ? { kind: suite.kind, command: suite.command } : null),
-            result.source === "working-tree"
-                ? "These patches match the working tree. mutate run scores the commit, so commit the files before mutate run."
-                : "",
-        ].filter((line) => line.length > 0).join(" "),
-        nextCall: result.mutants.length === 0
-            ? null
-            : { argv: ["mutate", "run", "--package", packageDir, "--patches", patches, "--out", path.join(outDir, "runs")] },
-        mutantCount: result.mutants.length,
-        operators: operatorSet(flags),
-        stringLiteralMutants: 0,
-        filesVisited: result.filesVisited,
-        budgetHit: result.budgetHit,
-        mutants: shown,
-        rest: Math.max(result.mutants.length - shown.length, 0),
-        full: path.join(patches, "mutants.json"),
-    };
-}
-async function runCommand(flags, hide = null) {
-    const hidden = hide ?? texts(flags, "hide");
-    const escaped = hidden.find((rel) => rel.split(/[\\/]/).includes(".."));
-    if (escaped) {
-        return {
-            schemaVersion: SCHEMA_VERSION,
-            ok: false,
-            command: "mutate.run",
-            summary: `--hide stays inside the package. Refused ${escaped}.`,
-            next: "Pass a relative path with no .. segment.",
-            nextCall: null,
-            killed: 0,
-        };
-    }
-    const onlyNames = texts(flags, "only-test");
-    if (onlyNames.some((id) => id === "::command" || id.endsWith("::command"))) {
-        return {
-            schemaVersion: SCHEMA_VERSION,
-            ok: false,
-            command: "mutate.run",
-            summary: "::command is not a test id.",
-            next: "Pass a test name the suite can collect.",
-            nextCall: null,
-            killed: 0,
-        };
-    }
-    if (onlyNames.length > 0 && text(flags, "suite-command")) {
-        return {
-            schemaVersion: SCHEMA_VERSION,
-            ok: false,
-            command: "mutate.run",
-            summary: "--only-test cannot be combined with --suite-command.",
-            next: "Drop --suite-command and pass the keep ids with --only-test.",
-            nextCall: null,
-            killed: 0,
-        };
-    }
-    const packageDir = path.resolve(requireText(flags, "package"));
-    const patchDirs = texts(flags, "patches").map((dir) => path.resolve(dir));
-    if (patchDirs.length === 0)
-        throw new Error("--patches is required");
-    const outDir = path.resolve(requireText(flags, "out"));
-    const repoDir = path.resolve(text(flags, "repo") ?? gitRoot(packageDir));
-    const workers = int(flags, "workers") ?? 1;
-    if (workers < 1)
-        throw new Error("--workers must be at least 1");
-    const direction = text(flags, "direction") ?? "auto";
-    if (direction !== "auto" && direction !== "forward" && direction !== "reverse") {
-        throw new Error("--direction must be auto, forward, or reverse");
-    }
-    const build = buildCommand(flags);
-    const report = await runMutants({
-        packageDir,
-        repoDir,
-        commit: text(flags, "commit") ?? "HEAD",
-        patchDirs,
-        outDir,
-        direction,
-        workers,
-        concurrency: int(flags, "concurrency") ?? 3,
-        maxMinutes: int(flags, "max-minutes") ?? null,
-        maxMutants: int(flags, "max-mutants") ?? null,
-        build,
-        testsDir: text(flags, "tests-dir") ?? "tests",
-        unset: texts(flags, "unset"),
-        suiteTimeoutMs: int(flags, "suite-timeout-ms") ?? 600_000,
-        testTimeoutMs: int(flags, "test-timeout-ms") ?? 60_000,
-        confirm: bool(flags, "confirm", true),
-        affected: bool(flags, "affected", false),
-        agent: text(flags, "agent") ?? null,
-        suiteCommand: text(flags, "suite-command") ?? null,
-        onlyNames: onlyNames.length > 0 ? onlyNames : null,
-        historyPath: text(flags, "history") ? path.resolve(text(flags, "history")) : null,
-        timeoutMultiple: int(flags, "timeout-multiple") ?? 5,
-        timeoutFloorMs: int(flags, "timeout-floor-ms") ?? 20_000,
-        budgetMs: int(flags, "budget-ms") ?? null,
-        hide,
-        onProgress: (line) => process.stderr.write(`${line}\n`),
-    });
-    const resume = report.budgetHit
-        ? { argv: ["mutate", "run", "--package", packageDir, "--repo", repoDir, "--out", outDir, ...patchDirs.flatMap((dir) => ["--patches", dir])] }
-        : null;
-    return {
-        schemaVersion: SCHEMA_VERSION,
-        ok: report.ok,
-        command: "mutate.run",
-        summary: report.summary,
-        next: report.next,
-        nextCall: report.ok ? resume : null,
-        killed: report.killed,
-        unviable: report.unviable,
-        unviableIds: report.unviableIds,
-        survived: report.survived,
-        flaky: report.flaky,
-        timeouts: report.timeouts,
-        errors: report.errors,
-        noCoverage: report.noCoverage,
-        notStarted: report.notStarted,
-        suiteCommand: report.suiteCommand,
-        baselineMs: report.baselineMs,
-        commands: report.commands,
-        gaps: report.gaps,
-        rest: report.rest,
-        flakyIds: report.flakyIds,
-        budgetHit: report.budgetHit,
-        commit: report.commit,
-        runId: report.runId,
-        kills: report.kills,
-        full: report.full,
-    };
-}
-function tallyCommand(flags) {
-    return tallyRun(path.resolve(requireText(flags, "out")));
-}
-async function sealedCommand(flags) {
-    const label = readSealedLabel(path.resolve(requireText(flags, "label")));
-    const hide = texts(flags, "hide");
-    const outDir = path.resolve(requireText(flags, "out"));
-    const report = await runCommand(flags, hide);
-    const packageDir = path.resolve(requireText(flags, "package"));
-    const repoDir = path.resolve(text(flags, "repo") ?? gitRoot(packageDir));
-    const kills = Array.isArray(report.kills) ? report.kills : [];
-    // The fix commit is the scored commit unless --fix names an earlier one (new tests landed on top of it).
-    const scored = typeof report.commit === "string" ? report.commit : "";
-    const fixRef = text(flags, "fix");
-    const fixSha = fixRef ? git(repoDir, ["rev-parse", "--verify", `${fixRef}^{commit}`]) : null;
-    if (fixSha && fixSha.status !== 0)
-        throw new Error(`--fix ${fixRef} does not resolve`);
-    const commit = fixSha ? fixSha.stdout.trim() : scored;
-    const edited = report.ok && commit ? fixEditedKillers(repoDir, packageDir, commit, hide, kills) : { files: [], olderTestCatch: false };
-    const fromFix = kills.length > 0 && !edited.olderTestCatch;
-    const judged = {
-        ...report,
-        ...(fromFix
-            ? {
-                summary: `${report.summary} Every kill came from a test edited by the fix commit (${edited.files.join(", ")}). That is the fix's own test, so no older test caught the bug.`,
-                next: "Record this as a miss. Do not restore the hidden test.",
-            }
-            : {}),
-        fixEdited: edited.files,
-        olderTestCatch: edited.olderTestCatch,
-    };
-    const body = JSON.stringify(judged);
-    if (!labelLeaked(body, label) && !sealedTreeLeaked(outDir, label))
-        return judged;
-    return {
-        schemaVersion: SCHEMA_VERSION,
-        ok: false,
-        command: "mutate.sealed",
-        summary: LABEL_LEAK_SUMMARY,
-        next: "Keep the label in its own file. Run the same command again.",
-        nextCall: null,
-    };
-}
-async function ledgerCommand(flags) {
-    const packageDir = path.resolve(requireText(flags, "package"));
-    const outDir = path.resolve(requireText(flags, "out"));
-    const repoDir = path.resolve(text(flags, "repo") ?? gitRoot(packageDir));
-    const report = buildLedger({
-        packageDir,
-        repoDir,
-        commit: text(flags, "commit") ?? "HEAD",
-        outDir,
-        srcDir: text(flags, "src") ?? "src",
-        testsDir: text(flags, "tests-dir") ?? "tests",
-        maxLines: int(flags, "max-lines") ?? 300,
-        maxCommits: int(flags, "max-commits") ?? null,
-    });
-    return {
-        schemaVersion: SCHEMA_VERSION,
-        ok: report.ok,
-        command: "ledger.build",
-        summary: report.summary,
-        next: report.next,
-        nextCall: report.ok ? report.nextCall : null,
-        clean: report.clean,
-        hand: report.hand,
-        handmade: report.handmade,
-        skipped: report.skipped,
-        handNeeded: report.handNeeded,
-        rest: report.rest,
-        commit: report.commit,
-        full: report.full,
-        historyBudgetHit: report.historyBudgetHit,
-        commitsScanned: report.commitsScanned,
-    };
-}
-function matrixCommand(flags) {
-    const scoresPath = requireText(flags, "scores");
-    const directPath = requireText(flags, "direct");
-    const outDir = path.resolve(requireText(flags, "out"));
-    const killsPath = text(flags, "kills");
-    return reportMatrix({
-        scores: readFileSync(scoresPath, "utf8"),
-        direct: readFileSync(directPath, "utf8"),
-        patchDirs: texts(flags, "patches").map((dir) => path.resolve(dir)),
-        outDir,
-        kills: killsPath ? readKills(killsPath) : new Map(),
-    });
-}
-function goldenCommand(flags) {
-    const recordedPath = requireText(flags, "recorded");
-    const recordedText = readFileSync(recordedPath, "utf8");
-    const updateRaw = text(flags, "update");
-    if (updateRaw && updateRaw !== "wording" && updateRaw !== "all")
-        throw new Error("--update must be wording or all");
-    const result = checkGolden({
-        recorded: asTable(recordedText),
-        actual: readGolden(requireText(flags, "actual")),
-        update: updateRaw === "wording" || updateRaw === "all" ? updateRaw : null,
-        message: text(flags, "message") ?? "",
-        roots: texts(flags, "root").map((dir) => path.resolve(dir)),
-    });
-    if (result.write)
-        writeGolden(recordedPath, result.table, goldenShape(recordedText));
-    return result.envelope;
-}
-function gapFixCommand(flags) {
-    const dir = path.resolve(requireText(flags, "state"));
-    const line = int(flags, "line");
-    if (line === undefined || line < 1)
-        throw new Error("--line must be a positive integer");
-    const state = fixGap(loadState(dir), {
-        id: requireText(flags, "id"),
-        file: requireText(flags, "file"),
-        line,
-        guard: requireText(flags, "guard"),
-        commit: requireText(flags, "commit"),
-        root: path.resolve(text(flags, "root") ?? dir),
-    });
-    saveState(dir, state);
-    const gap = state.gaps.find((item) => item.id === requireText(flags, "id"));
-    return {
-        schemaVersion: SCHEMA_VERSION,
-        ok: true,
-        command: "gap.fix",
-        summary: `${gap?.id} is fixed, guarded by ${gap?.guard}.`,
-        next: "Run status.",
-        nextCall: { argv: ["status", "--state", dir] },
-    };
-}
-function gapRevertCommand(flags) {
-    const dir = path.resolve(requireText(flags, "state"));
-    const reverted = revertGap(loadState(dir), requireText(flags, "id"));
-    saveState(dir, reverted.state);
-    return {
-        schemaVersion: SCHEMA_VERSION,
-        ok: true,
-        command: "gap.revert",
-        summary: reverted.text,
-        next: reverted.text,
-        nextCall: null,
-    };
-}
-function guardCommand(flags) {
-    const dir = path.resolve(requireText(flags, "state"));
-    const guard = requireText(flags, "guard");
-    parseGuard(guard);
-    const result = guardAllows(loadState(dir), guard, text(flags, "message") ?? "", path.resolve(text(flags, "root") ?? dir));
-    return {
-        schemaVersion: SCHEMA_VERSION,
-        ok: result.ok,
-        command: "guard.check",
-        summary: result.summary,
-        next: result.ok ? "The guard check passed." : "Add a Guard-Change trailer naming the guard, or restore it.",
-        nextCall: null,
-    };
-}
-function findingsCommand(flags) {
-    const dir = path.resolve(requireText(flags, "state"));
-    const status = text(flags, "status");
-    if (status !== "open" && status !== "fixed" && status !== "equivalent" && status !== "wont-fix") {
-        throw new Error("--status must be open, fixed, equivalent, or wont-fix");
-    }
-    const id = requireText(flags, "id");
-    const reason = requireText(flags, "reason");
-    const finding = {
-        id,
-        status,
-        reason,
-    };
-    const agent = text(flags, "agent");
-    if (agent)
-        finding.agent = agent;
-    const file = text(flags, "file");
-    const line = int(flags, "line");
-    if (file && line !== undefined) {
-        const source = readSourceLine(path.resolve(text(flags, "root") ?? dir, file), line);
-        if (source === null)
-            throw new Error("decision line does not exist");
-        finding.file = file;
-        finding.line = line;
-        finding.hash = lineHash(source);
-        const state = loadState(dir);
-        const decisions = state.decisions.filter((item) => item.id !== id);
-        decisions.push({ id, file, line, hash: finding.hash, status, reason });
-        saveState(dir, { ...state, decisions });
-    }
-    appendFinding(dir, finding);
-    return {
-        schemaVersion: SCHEMA_VERSION,
-        ok: true,
-        command: "findings.add",
-        summary: `Recorded ${id} as ${status}.`,
-        next: "Run status.",
-        nextCall: null,
-    };
-}
-function statusCommand(flags) {
-    const dir = path.resolve(requireText(flags, "state"));
-    const root = path.resolve(text(flags, "root") ?? dir);
-    const pagePath = path.resolve(text(flags, "page") ?? "PROBATIO.md");
-    const scoresPath = text(flags, "scores");
-    const score = scoresPath ? JSON.parse(readFileSync(scoresPath, "utf8")) : null;
-    const view = statusEnvelope(dir, root, score, text(flags, "agent") ?? null);
-    mkdirSync(path.dirname(pagePath), { recursive: true });
-    writeFileSync(pagePath, view.page);
-    return view.envelope;
-}
-function sealCommand(flags) {
-    const dir = path.resolve(requireText(flags, "state"));
-    const from = text(flags, "from");
-    let ids = texts(flags, "id");
-    if (from) {
-        const parsed = JSON.parse(readFileSync(from, "utf8"));
-        const list = Array.isArray(parsed) ? parsed : parsed.ids ?? [];
-        const fraction = Number(text(flags, "fraction") ?? "0.2");
-        if (!Number.isFinite(fraction) || fraction < 0 || fraction > 1)
-            throw new Error("--fraction must be between 0 and 1");
-        ids = chooseSealed(list, fraction, int(flags, "seed") ?? 20261004);
-    }
-    sealIds(dir, ids);
-    return {
-        schemaVersion: SCHEMA_VERSION,
-        ok: true,
-        command: "seal",
-        summary: `Sealed ${ids.length} ids.`,
-        next: "status, PROBATIO.md, and the queue omit them.",
-        nextCall: null,
-        sealedCount: ids.length,
-    };
-}
-function queueSeedCommand(flags) {
-    const dir = path.resolve(requireText(flags, "state"));
-    const written = seedQueue(dir, texts(flags, "id"));
-    return {
-        schemaVersion: SCHEMA_VERSION,
-        ok: true,
-        command: "queue.seed",
-        summary: `Seeded ${written.length} queue items.`,
-        next: "Claim one.",
-        nextCall: null,
-        seeded: written,
-    };
-}
-function queueClaimCommand(flags) {
-    const dir = path.resolve(requireText(flags, "state"));
-    const now = int(flags, "now") ?? Date.now();
-    const lease = int(flags, "lease-ms") ?? 600_000;
-    const result = claimItem(dir, requireText(flags, "id"), requireText(flags, "agent"), now, lease);
-    return {
-        schemaVersion: SCHEMA_VERSION,
-        ok: result.ok,
-        command: "queue.claim",
-        summary: result.summary,
-        next: result.ok ? "Work the claim, then check-kill it." : "Pick another item.",
-        nextCall: null,
-    };
-}
-function queueReapCommand(flags) {
-    const dir = path.resolve(requireText(flags, "state"));
-    const now = int(flags, "now") ?? Date.now();
-    const returned = reapClaims(dir, now);
-    return {
-        schemaVersion: SCHEMA_VERSION,
-        ok: true,
-        command: "queue.reap",
-        summary: `Returned ${returned.length} expired claims.`,
-        next: returned.length === 0 ? "Nothing expired." : "The expired claims are back in the queue.",
-        nextCall: null,
-        returned,
-    };
-}
-async function checkKillCommand(flags, id) {
-    if (!id)
-        throw new Error("check-kill needs a mutant id");
-    const packageDir = path.resolve(requireText(flags, "package"));
-    const patchDirs = texts(flags, "patches").map((dir) => path.resolve(dir));
-    if (patchDirs.length === 0)
-        throw new Error("--patches is required");
-    const build = buildCommand(flags);
-    return checkKill(id, {
-        packageDir,
-        repoDir: path.resolve(text(flags, "repo") ?? gitRoot(packageDir)),
-        commit: text(flags, "commit") ?? "HEAD",
-        patchDirs,
-        outDir: path.resolve(requireText(flags, "out")),
-        direction: "forward",
-        workers: 1,
-        concurrency: 1,
-        maxMinutes: int(flags, "max-minutes") ?? 3,
-        maxMutants: null,
-        build,
-        testsDir: text(flags, "tests-dir") ?? "tests",
-        unset: ["SOLARI_API_KEY", "AUSPEX_LIVE"],
-        suiteTimeoutMs: int(flags, "suite-timeout-ms") ?? 60_000,
-        testTimeoutMs: int(flags, "test-timeout-ms") ?? 30_000,
-        confirm: bool(flags, "confirm", true),
-        affected: false,
-        agent: text(flags, "agent") ?? null,
-        onProgress: (line) => process.stderr.write(`${line}\n`),
-    });
-}
-async function ledgerCheckCommand(flags) {
-    const packageDir = path.resolve(requireText(flags, "package"));
-    return checkLedger({
-        packageDir,
-        repoDir: path.resolve(text(flags, "repo") ?? gitRoot(packageDir)),
-        commit: text(flags, "commit") ?? "HEAD",
-        ledgerDir: path.resolve(packageDir, text(flags, "ledger") ?? "ledger"),
-        outDir: path.resolve(requireText(flags, "out")),
-        update: bool(flags, "update", false),
-        message: text(flags, "message") ?? "",
-        concurrency: int(flags, "concurrency") ?? 3,
-        suiteTimeoutMs: int(flags, "suite-timeout-ms") ?? 600_000,
-        testTimeoutMs: int(flags, "test-timeout-ms") ?? 60_000,
-        onProgress: (line) => process.stderr.write(`${line}\n`),
-    });
-}
-async function goldenRecordCommand(flags) {
-    const packageDir = path.resolve(requireText(flags, "package"));
-    return recordGoldens({
-        packageDir,
-        repoDir: path.resolve(text(flags, "repo") ?? gitRoot(packageDir)),
-        commit: text(flags, "commit") ?? "HEAD",
-        modules: texts(flags, "module"),
-        tests: texts(flags, "tests"),
-        outDir: text(flags, "dir") ?? "tests/golden",
-        timeoutMs: int(flags, "suite-timeout-ms") ?? 600_000,
-    });
-}
-async function goldenCompareCommand(flags) {
-    const packageDir = path.resolve(requireText(flags, "package"));
-    return compareGoldens({
-        packageDir,
-        repoDir: path.resolve(text(flags, "repo") ?? gitRoot(packageDir)),
-        commit: text(flags, "commit") ?? "HEAD",
-        modules: texts(flags, "module"),
-        tests: texts(flags, "tests"),
-        golden: texts(flags, "golden"),
-        outDir: path.resolve(requireText(flags, "out")),
-        operators: operatorSet(flags),
-        timeoutMs: int(flags, "suite-timeout-ms") ?? 600_000,
-        onProgress: (line) => process.stderr.write(`${line}\n`),
-    });
-}
-async function verifyCommand(flags) {
-    const packageDir = path.resolve(requireText(flags, "package"));
-    const operators = operatorSet(flags);
-    const envelope = await verifyChange({
-        packageDir,
-        repoDir: path.resolve(text(flags, "repo") ?? gitRoot(packageDir)),
-        outDir: path.resolve(requireText(flags, "out")),
-        base: text(flags, "base") ?? "HEAD",
-        commit: text(flags, "commit") ?? "HEAD",
-        maxMutants: int(flags, "max-mutants") ?? 4,
-        maxMinutes: int(flags, "max-minutes") ?? 3,
-        maxTests: int(flags, "max-tests") ?? null,
-        operators,
-        onProgress: (line) => process.stderr.write(`${line}\n`),
-    });
-    return { ...envelope, operators };
-}
-/** `--operators core` (default) or `--operators wide`. Anything else is a usage error, not a silent default. */
-function operatorSet(flags) {
-    const value = text(flags, "operators") ?? "core";
-    if (value !== "core" && value !== "wide")
-        throw new Error("--operators must be core or wide");
-    return value;
-}
-/** The published JSON Schema of one command's output. MCP-only agents read the contract this way. */
-function schemaCommand(name) {
-    const dir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "schemas");
-    const commands = existsSync(dir)
-        ? readdirSync(dir).filter((file) => file.endsWith(".schema.json")).map((file) => file.slice(0, -".schema.json".length)).sort()
-        : [];
-    if (!name) {
-        return {
-            schemaVersion: SCHEMA_VERSION,
-            ok: commands.length > 0,
-            command: "schema",
-            summary: `${commands.length} commands have a published schema.`,
-            next: "Pass one name, for example: probatio schema mutate.run",
-            nextCall: null,
-            commands,
-        };
-    }
-    if (!commands.includes(name)) {
-        return {
-            schemaVersion: SCHEMA_VERSION,
-            ok: false,
-            command: "schema",
-            summary: `No schema named ${name}.`,
-            next: `Use one of: ${commands.join(", ")}.`,
-            nextCall: null,
-            commands,
-        };
-    }
-    return {
-        schemaVersion: SCHEMA_VERSION,
-        ok: true,
-        command: "schema",
-        summary: `JSON Schema for ${name}, schemaVersion ${SCHEMA_VERSION}.`,
-        next: "Validate a command's stdout against it. A new field does not change schemaVersion. A renamed or removed one does.",
-        nextCall: null,
-        commands,
-        schema: JSON.parse(readFileSync(path.join(dir, `${name}.schema.json`), "utf8")),
-    };
-}
-function gitRoot(cwd) {
-    const result = git(cwd, ["rev-parse", "--show-toplevel"]);
-    if (result.status !== 0)
-        throw new Error("package is not inside a git repository. Pass --repo.");
-    return result.stdout.trim();
-}
-function finish(envelope, human) {
-    process.stdout.write(render(envelope, human));
-    process.exit(envelope.ok ? 0 : 1);
-}
-/** Omitted `--build` and `--no-build` both mean no build. `--build <cmd>` opts in. */
-function buildCommand(flags) {
-    const values = flags.get("build");
-    if (!values || values.length === 0)
-        return null;
-    const last = values[values.length - 1];
-    if (typeof last !== "string")
-        return null;
-    const parts = last.split(" ").filter(Boolean);
-    return parts.length > 0 ? parts : null;
-}