@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/main.ts

@@ -0,0 +1,292 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { init, parsePacksFlag, type InitOptions } from "./init.ts";
+import { confirm, isInteractive, select, spinner } from "./prompt.ts";
+import { runSync } from "./sync.ts";
+import { HOOK_NAMES } from "./scripts/hook-command.ts";
+import { COMMANDS, isCommandName, runCommand } from "./commands.ts";
+import { mapCommand } from "./scripts/folder-map.ts";
+
+const PKG_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+const pad = (name: string) => `  ${name.padEnd(18)}`;
+
+const USAGE = `Usage: repo [command]
+
+Default (no command): TTY menu; else init — full setup
+
+Commands:
+${pad("init")}Full setup: write workerstack.config.ts and package.json, bun install (whose postinstall runs repo sync), repo yolo
+${pad("check")}Tsconfig bases, manifests, disable comments, lint.skip entries, generated files current, lint within .repo/lint-baseline.json, knip, actionlint on workflows, and floors, known failures and the baseline against main
+${pad("sync")}Write the committed generated files from workerstack.config.ts (--check: report drift; --postinstall: never fail)
+${pad("map [dir]")}Code-only folder map (git-tracked, no files); dir for depth
+${Object.entries(COMMANDS)
+  .map(([name, entry]) => `${pad(name)}${entry.summary}\n`)
+  .join("")}${pad("hook <name>")}Run a hook: ${HOOK_NAMES.join(", ")}
+${pad("help")}Show this help
+${pad("version")}Print package version
+
+Flags:
+  --skip-globals     Skip repo yolo (otherwise init always runs it)
+  --yes, -y          Non-interactive
+  --non-interactive  Same as --yes
+  --packs <list>     init: skill packs written as agents.skills into a new config: google-workspace,listen,speak,clasp or none
+`;
+
+const MENU_OPTIONS = [
+  { value: "init", label: "init" },
+  { value: "check", label: "check" },
+  { value: "yolo", label: "yolo" },
+  { value: "purge-mcps", label: "purge-mcps" },
+  { value: "doctor", label: "doctor" },
+  { value: "clean", label: "clean" },
+  { value: "setup", label: "setup" },
+  { value: "tasks", label: "tasks" },
+  { value: "help", label: "help" },
+  { value: "quit", label: "quit" },
+];
+
+const YES_FLAGS = new Set(["--yes", "-y", "--non-interactive"]);
+
+function pkgVersion(): string {
+  const pkg: unknown = JSON.parse(readFileSync(path.join(PKG_ROOT, "package.json"), "utf8"));
+  if (typeof pkg !== "object" || pkg === null || !("version" in pkg) || typeof pkg.version !== "string") {
+    throw new Error("package.json has no version");
+  }
+  return pkg.version;
+}
+
+/** The command line, split into the command, its arguments and the flags this CLI knows. */
+export interface Flags {
+  cmd: string | undefined;
+  args: string[];
+  skipGlobals: boolean;
+  packs: string[] | undefined;
+  packsError: boolean;
+}
+
+export function parseArgv(argv: string[]): Flags {
+  let skipGlobals = false;
+  let packs: string[] | undefined;
+  let packsError = false;
+  const positionals: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!; // i < argv.length
+    if (a === "--skip-globals") {
+      skipGlobals = true;
+      continue;
+    }
+    if (YES_FLAGS.has(a)) continue;
+    if (a === "--packs") {
+      const v = argv[i + 1];
+      if (v == null || String(v).startsWith("--")) {
+        packsError = true;
+        continue;
+      }
+      try {
+        packs = parsePacksFlag(v);
+      } catch {
+        packsError = true;
+      }
+      i += 1;
+      continue;
+    }
+    if (typeof a === "string" && a.startsWith("--packs=")) {
+      try {
+        packs = parsePacksFlag(a.slice("--packs=".length));
+      } catch {
+        packsError = true;
+      }
+      continue;
+    }
+    positionals.push(a);
+  }
+  return {
+    cmd: positionals[0],
+    args: positionals.slice(1),
+    skipGlobals,
+    packs,
+    packsError,
+  };
+}
+
+function bindSpinner() {
+  const spin = spinner();
+  return (name: string, action: "start" | "stop") => {
+    if (action === "start") spin.start(name);
+    else spin.stop(name);
+  };
+}
+
+export const APPLY_GLOBALS_CONFIRM = "Apply global prompt optimizations? (recommended)";
+
+function initOpts(base: InitOptions, packs: string[] | undefined): InitOptions {
+  if (packs === undefined) return base;
+  return { ...base, packs };
+}
+
+interface RunInitOptions {
+  skipGlobals: boolean;
+  interactive: boolean;
+  packs: string[] | undefined;
+}
+
+async function runInit(cwd: string, { skipGlobals, interactive, packs }: RunInitOptions) {
+  if (!interactive) {
+    init(cwd, initOpts({ skipGlobals }, packs));
+    return;
+  }
+  const applyGlobals = await confirm({
+    message: APPLY_GLOBALS_CONFIRM,
+    initialValue: !skipGlobals,
+  });
+  init(
+    cwd,
+    initOpts(
+      {
+        skipGlobals: !applyGlobals,
+        onPhase: bindSpinner(),
+      },
+      packs,
+    ),
+  );
+}
+
+const syncIo = () => ({
+  cwd: process.cwd(),
+  stdout: (s: string) => process.stdout.write(s),
+  stderr: (s: string) => process.stderr.write(s),
+});
+
+/** Floors, known failures and the lint baseline held against main, per the config's `coverage` paths. */
+async function ratchetLines(root: string): Promise<string[]> {
+  const { loadConfig } = await import("./config.ts");
+  const { DEFAULT_COVERAGE } = await import("./coverage-config.ts");
+  const { ratchetProblems } = await import("./check-ratchets.ts");
+  const { knownFailures } = await import("./known-failures.ts");
+  const { sourceFiles } = await import("./check-comments.ts");
+  const loaded = await loadConfig(root);
+  const coverage = loaded.ok ? loaded.config.coverage : DEFAULT_COVERAGE;
+  const listed = sourceFiles(root);
+  // Without a git listing there are no test files to read.
+  const files = listed.ok ? listed.files : [];
+  return [...ratchetProblems(root, coverage), ...knownFailures(root, files, coverage.knownFailures)];
+}
+
+async function dispatch(cmd: string | undefined, flags: Flags, interactive: boolean) {
+  if (cmd === "help" || cmd === "--help" || cmd === "-h") {
+    process.stdout.write(USAGE);
+    return;
+  }
+  if (cmd === "version" || cmd === "--version" || cmd === "-v") {
+    process.stdout.write(`${pkgVersion()}\n`);
+    return;
+  }
+  if (!cmd || cmd === "init") {
+    await runInit(process.cwd(), {
+      skipGlobals: flags.skipGlobals,
+      interactive: interactive && (!cmd || cmd === "init"),
+      packs: flags.packs,
+    });
+    return;
+  }
+  if (cmd === "check") {
+    // Loaded here so other commands never load typescript.
+    const { checkTsconfigs } = await import("./check-tsconfig.ts");
+    const { checkEnvModules } = await import("./check-env-modules.ts");
+    const problems = [...checkTsconfigs(process.cwd(), PKG_ROOT), ...checkEnvModules(process.cwd())];
+    for (const line of problems) process.stderr.write(`repo check: ${line}\n`);
+    const synced = await runSync(["--check"], syncIo());
+    const { loadConfig } = await import("./config.ts");
+    const { readWorkspace } = await import("./sync/workspace.ts");
+    const { checkManifests } = await import("./check-manifests.ts");
+    const { checkComments } = await import("./check-comments.ts");
+    const loaded = await loadConfig(process.cwd());
+    const on = loaded.ok && loaded.config.packs.includes("standards");
+    const read = on ? readWorkspace(process.cwd()) : undefined;
+    // An unreadable manifest is already reported by sync --check.
+    const standardsLines = [
+      ...(read?.ok ? checkManifests(read.workspace) : []),
+      ...(on ? checkComments(process.cwd()) : []),
+    ];
+    for (const line of standardsLines) process.stderr.write(`repo check: ${line}\n`);
+    // Computed once: the skip report counts every hit, the baseline only those no skip turns off.
+    const { checkRejectionsAt, checkScriptsAt } = await import("./script-diagnostics.ts");
+    const rejectionLines = (await checkRejectionsAt(process.cwd())).map((line) => `rejections: ${line}`);
+    for (const line of rejectionLines) process.stderr.write(`repo check: ${line}\n`);
+    const scripts = await checkScriptsAt(process.cwd());
+    const { checkLintSkipsAt } = await import("./scripts/lint-skips.ts");
+    const skips = await checkLintSkipsAt(process.cwd(), scripts.all);
+    for (const line of skips.report) process.stdout.write(`repo check: ${line}\n`);
+    const { checkLintBaseline } = await import("./scripts/lint-baseline.ts");
+    const baseline = await checkLintBaseline(process.cwd(), scripts.kept);
+    const lintLines = [...scripts.problems, ...skips.problems, ...baseline];
+    for (const line of lintLines) process.stderr.write(`repo check: ${line}\n`);
+    const { checkNightlyAt } = await import("./check-nightly.ts");
+    const nightlyLines = await checkNightlyAt(process.cwd());
+    for (const line of nightlyLines) process.stderr.write(`repo check: ${line}\n`);
+    const { checkChangelog } = await import("./check-changelog.ts");
+    const changelogLines = checkChangelog(process.cwd());
+    for (const line of changelogLines) process.stderr.write(`repo check: ${line}\n`);
+    const ratchets = await ratchetLines(process.cwd());
+    for (const line of ratchets) process.stderr.write(`repo check: ${line}\n`);
+    const { checkKnipAt } = await import("./knip-check.ts");
+    const knip = await checkKnipAt(process.cwd());
+    for (const line of knip.report) process.stdout.write(`repo check: ${line}\n`);
+    for (const line of knip.problems) process.stderr.write(`repo check: ${line}\n`);
+    const { checkActionlintAt } = await import("./actionlint.ts");
+    const actionlint = await checkActionlintAt(process.cwd());
+    for (const line of actionlint.problems) process.stderr.write(`repo check: ${line}\n`);
+    const found = [
+      ...problems,
+      ...standardsLines,
+      ...rejectionLines,
+      ...lintLines,
+      ...nightlyLines,
+      ...changelogLines,
+      ...ratchets,
+    ];
+    const failing = [...found, ...knip.problems, ...actionlint.problems];
+    const code = failing.length > 0 ? 1 : synced;
+    if (code !== 0) process.exitCode = code;
+    return;
+  }
+  if (cmd === "sync") {
+    process.exitCode = await runSync(flags.args, syncIo());
+    return;
+  }
+  if (isCommandName(cmd)) {
+    process.exitCode = await runCommand(cmd, flags.args);
+    return;
+  }
+  if (cmd === "map") {
+    process.stdout.write(mapCommand(process.cwd(), flags.args[0] || ""));
+    return;
+  }
+  process.stderr.write(`repo: unknown command "${cmd}"; run \`repo --help\`\n`);
+  process.exitCode = 1;
+}
+
+/** Every command but `hook <name>` and the registry commands, which the bin runs through `dispatch` first. */
+export async function start(): Promise<void> {
+  const raw = process.argv.slice(2);
+  const flags = parseArgv(raw);
+  if (flags.packsError) {
+    process.stdout.write(USAGE);
+    process.exitCode = 1;
+    return;
+  }
+  const interactive = isInteractive();
+  let cmd = flags.cmd;
+  if (!cmd && interactive) {
+    const choice = await select({
+      message: "Command",
+      options: MENU_OPTIONS,
+      initialValue: "init",
+    });
+    if (choice === "quit") return;
+    cmd = choice;
+  }
+  await dispatch(cmd, flags, interactive);
+}

package/cli/mutate-args.ts

@@ -0,0 +1,79 @@
+/** The command line of `repo mutate`, parsed at the edge into one of three shapes. */
+import {
+  ASSIGN,
+  CHECK_COMMAND,
+  FIRST_SHARD,
+  FLAG_PREFIX,
+  FLAG_WORDS,
+  REPORT_FLAG,
+  SHARD_FLAG,
+  SHARD_PATTERN,
+  WRITE_FLAG,
+} from "./mutate.constants.ts";
+
+/** The `index`th of `total` shards, 1-based. */
+export type Shard = { index: number; total: number };
+
+export type Args =
+  | { kind: "run"; shard: Shard; report: string | undefined }
+  | { kind: "check"; dir: string; write: boolean }
+  | { kind: "error"; line: string };
+
+const fail = (line: string): Args => ({ kind: "error", line });
+const SHARD_USAGE = `${SHARD_FLAG} takes i/n with 1 <= i <= n, such as 2/8`;
+const REPORT_USAGE = `${REPORT_FLAG} takes a file path`;
+const UNKNOWN = `use ${SHARD_FLAG} i/n, ${REPORT_FLAG} <file> or ${CHECK_COMMAND} <dir>`;
+
+/** `i/n` as a shard, or null when it is no shard. */
+function shardOf(text: string): Shard | null {
+  const match = SHARD_PATTERN.exec(text);
+  const [, first, second] = match ?? [];
+  const index = Number(first);
+  const total = Number(second);
+  return match !== null && index >= FIRST_SHARD && index <= total ? { index, total } : null;
+}
+
+/** `--flag=value` as the two words `--flag value`. */
+function expand(argv: string[]): string[] {
+  return argv.flatMap((word) => {
+    const at = word.indexOf(ASSIGN);
+    return word.startsWith(FLAG_PREFIX) && at > 0 ? [word.slice(0, at), word.slice(at + 1)] : [word];
+  });
+}
+
+function parseCheck(rest: string[]): Args {
+  const dir = rest.find((word) => word !== WRITE_FLAG);
+  if (dir === undefined) return fail(`${CHECK_COMMAND} takes the dir of the shard reports`);
+  return { kind: "check", dir, write: rest.includes(WRITE_FLAG) };
+}
+
+type Run = Extract<Args, { kind: "run" }>;
+
+/** Applies one flag and its value to `run`; the line that says what is wrong, or null. */
+function apply(run: Run, flag: string | undefined, value: string | undefined): string | null {
+  if (flag === SHARD_FLAG) {
+    const shard = shardOf(value ?? "");
+    if (shard === null) return SHARD_USAGE;
+    run.shard = shard;
+    return null;
+  }
+  if (flag !== REPORT_FLAG) return `unknown argument "${String(flag)}"; ${UNKNOWN}`;
+  if (value === undefined || value === "" || value.startsWith(FLAG_PREFIX)) return REPORT_USAGE;
+  run.report = value;
+  return null;
+}
+
+function parseRun(words: string[]): Args {
+  const run: Run = { kind: "run", shard: { index: FIRST_SHARD, total: FIRST_SHARD }, report: undefined };
+  for (let at = 0; at < words.length; at += FLAG_WORDS) {
+    const problem = apply(run, words[at], words[at + 1]);
+    if (problem !== null) return fail(problem);
+  }
+  return run;
+}
+
+/** The run `argv` asks for, or the line that says what is wrong with it. */
+export function parseArgs(argv: string[]): Args {
+  const words = expand(argv);
+  return words[0] === CHECK_COMMAND ? parseCheck(words.slice(1)) : parseRun(words);
+}

package/cli/mutate-check.test.ts

@@ -0,0 +1,147 @@
+import { expect, it } from "vitest";
+import path from "node:path";
+import { at, fakes, sim, type Fakes } from "./fixtures/mutate-fakes.ts";
+import { runMutate } from "./mutate.ts";
+import type { ShardReport } from "./mutate-report.ts";
+
+const HEAD = "09ed564aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+const OTHER = "1a2b3c4bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";
+const survivor = { line: 1, column: 1, mutator: "m", status: "Survived" } as const;
+
+function shard(index: number, total: number, files: ShardReport["files"]): ShardReport {
+  return { head: HEAD, shard: { index, total }, files };
+}
+
+/** Reports in /repo/reports; shard 1 killed 9 and let 1 live, shard 2 killed 18 and let 2 live: 27 of 30, 90%. */
+const pair = (): ShardReport[] => [
+  shard(1, 2, { "src/a.ts": { killed: 9, survivors: [survivor] } }),
+  shard(2, 2, { "packages/p/b.ts": { killed: 18, survivors: [survivor, survivor] } }),
+];
+
+function planted(reports: ShardReport[], floors?: Record<string, number>): Fakes {
+  const f = fakes(undefined, ["packages/p"]);
+  reports.forEach((report, i) => f.files.set(at("reports", `mutation-${i + 1}.json`), JSON.stringify(report)));
+  if (floors !== undefined) f.files.set(at("mutation-floors.json"), JSON.stringify(floors));
+  return f;
+}
+
+it("merges the shards, scores each package against its floor and passes at or above them", async () => {
+  const f = planted(pair(), { ".": 89, "packages/p": 85 });
+  expect(await runMutate(["check", "reports"], f.deps)).toBe(0);
+  expect(f.out).toEqual(["mutate: 2 shards of 09ed564; . 90.00% (floor 89); packages/p 90.00% (floor 85)\n"]);
+  expect(f.err).toEqual([]);
+});
+
+it("fails a package below its floor and names the report dir", async () => {
+  const f = planted(pair(), { ".": 91 });
+  expect(await runMutate(["check", "reports"], f.deps)).toBe(1);
+  expect(f.err).toEqual([
+    "repo mutate: . scored 90.00%, below its floor of 91 in mutation-floors.json; see the survivors in reports\n",
+  ]);
+  expect(f.files.get(at("mutation-floors.json"))).toBe(JSON.stringify({ ".": 91 }));
+});
+
+it("scores a package with no floor against none", async () => {
+  const f = planted(pair());
+  expect(await runMutate(["check", "reports"], f.deps)).toBe(0);
+  expect(f.out[0]).toBe("mutate: 2 shards of 09ed564; . 90.00% (no floor); packages/p 90.00% (no floor)\n");
+});
+
+it("refuses a missing shard, naming it", async () => {
+  const f = planted([shard(1, 4, {}), shard(4, 4, {})]);
+  expect(await runMutate(["check", "reports"], f.deps)).toBe(1);
+  expect(f.err.join("")).toBe(
+    "repo mutate: reports is missing shards 2, 3 of 4; download every shard's report first\n",
+  );
+  const one = planted([shard(2, 2, {})]);
+  await runMutate(["check", "reports"], one.deps);
+  expect(one.err.join("")).toBe("repo mutate: reports is missing shard 1 of 2; download every shard's report first\n");
+});
+
+it("refuses reports of different heads, different shard counts and a shard twice", async () => {
+  const heads = planted([shard(1, 2, {}), { ...shard(2, 2, {}), head: OTHER }]);
+  await runMutate(["check", "reports"], heads.deps);
+  expect(heads.err.join("")).toBe("repo mutate: reports holds shards of 09ed564 and 1a2b3c4; use one run's reports\n");
+  const totals = planted([shard(1, 2, {}), shard(2, 8, {})]);
+  await runMutate(["check", "reports"], totals.deps);
+  expect(totals.err.join("")).toBe("repo mutate: reports mixes runs of 2 and 8 shards; use one run's reports\n");
+  const twice = planted([shard(1, 2, {}), shard(1, 2, {})]);
+  await runMutate(["check", "reports"], twice.deps);
+  expect(twice.err.join("")).toBe("repo mutate: reports holds shard 1 twice; use one run's reports\n");
+});
+
+it("names a bad file and the reason, and an empty or missing dir", async () => {
+  const bad = planted(pair());
+  bad.files.set(at("reports", "mutation-2.json"), JSON.stringify({ head: 1 }));
+  expect(await runMutate(["check", "reports"], bad.deps)).toBe(1);
+  expect(bad.err.join("")).toMatch(
+    new RegExp(
+      `^repo mutate: ${path.join("reports", "mutation-2.json").replaceAll("\\", "\\\\")} is not a mutation report: head: .+\n$`,
+    ),
+  );
+  const text = planted(pair());
+  text.files.set(at("reports", "mutation-2.json"), "{");
+  await runMutate(["check", "reports"], text.deps);
+  expect(text.err.join("")).toContain(`${path.join("reports", "mutation-2.json")} is not a mutation report: `);
+  const none = planted([]);
+  expect(await runMutate(["check", "reports"], none.deps)).toBe(1);
+  expect(none.err.join("")).toBe(
+    "repo mutate: reports holds no mutation report; run `repo mutate --shard i/n --report reports/mutation-i.json` first\n",
+  );
+});
+
+it("ignores files in the dir that are not JSON", async () => {
+  const f = planted(pair(), { ".": 89 });
+  f.files.set(at("reports", "notes.txt"), "hello");
+  expect(await runMutate(["check", "reports"], f.deps)).toBe(0);
+});
+
+it("raises a floor to the whole score, adds a package, and never lowers one", async () => {
+  const f = planted(pair(), { ".": 85, other: 70 });
+  expect(await runMutate(["check", "reports", "--write"], f.deps)).toBe(0);
+  expect(f.out).toEqual([
+    "mutate: 2 shards of 09ed564; . 90.00% (floor 85 → 90); packages/p 90.00% (floor new → 90); wrote mutation-floors.json\n",
+  ]);
+  expect(JSON.parse(f.files.get(at("mutation-floors.json")) ?? "")).toEqual({
+    ".": 90,
+    other: 70,
+    "packages/p": 90,
+  });
+});
+
+it("floors a fractional score, and writes nothing when no floor changes", async () => {
+  const f = planted([shard(1, 1, { "a.ts": { killed: 5, survivors: [survivor, survivor, survivor] } })], { ".": 62 });
+  expect(await runMutate(["check", "reports", "--write"], f.deps)).toBe(0);
+  expect(f.out[0]).toBe("mutate: 1 shard of 09ed564; . 62.50% (floor 62)\n");
+  expect(f.files.get(at("mutation-floors.json"))).toBe(JSON.stringify({ ".": 62 }));
+});
+
+it("writes nothing and fails when a package is below its floor", async () => {
+  const f = planted(pair(), { ".": 95, "packages/p": 10 });
+  expect(await runMutate(["check", "reports", "--write"], f.deps)).toBe(1);
+  expect(f.files.get(at("mutation-floors.json"))).toBe(JSON.stringify({ ".": 95, "packages/p": 10 }));
+  expect(f.out.join("")).not.toContain("wrote");
+});
+
+it("prints a config's errors and an unreadable floors file instead of scoring", async () => {
+  const config = planted(pair());
+  const state = sim({ config: ["workerstack.config.ts: no default export"] });
+  const broken = fakes(state);
+  expect(await runMutate(["check", "reports"], broken.deps)).toBe(1);
+  expect(broken.err.join("")).toBe("repo mutate: workerstack.config.ts: no default export\n");
+  config.files.set(at("mutation-floors.json"), "[1]");
+  expect(await runMutate(["check", "reports"], config.deps)).toBe(1);
+  expect(config.err.join("")).toMatch(/^repo mutate: mutation-floors.json is not a floors file: .+\n$/);
+});
+
+it("names a report that is no object, and a listed report that cannot be read", async () => {
+  const flat = planted(pair());
+  flat.files.set(at("reports", "mutation-2.json"), "5");
+  await runMutate(["check", "reports"], flat.deps);
+  expect(flat.err.join("")).toMatch(/mutation-2.json is not a mutation report: report: .+\n$/);
+  const gone = planted(pair());
+  const read = gone.deps.fs.read;
+  gone.deps.fs.read = (file) => (file.endsWith("mutation-2.json") ? null : read(file));
+  await runMutate(["check", "reports"], gone.deps);
+  expect(gone.err.join("")).toContain(`${path.join("reports", "mutation-2.json")} is not a mutation report: `);
+});

package/cli/mutate-deps.ts

@@ -0,0 +1,42 @@
+import type { Captured } from "./scripts/lint.ts";
+import { FAILED, NEWLINE } from "./mutate.constants.ts";
+
+/** What `repo mutate` reads from workerstack.config.ts: the repo root, the globs to mutate, the floors file. */
+export type MutateConfig = { root: string; mutate: readonly string[]; floors: string };
+
+/** The file system `repo mutate` touches; paths are absolute. */
+export type MutateFs = {
+  /** A new empty dir named `<prefix><random>` under the OS temp dir. */
+  mkdtemp: (prefix: string) => string;
+  rm: (target: string) => void;
+  /** The text of a file, or null when it is missing. */
+  read: (file: string) => string | null;
+  /** Writes `text`, creating the parent dirs. */
+  write: (file: string, text: string) => void;
+  /** The names in a dir, or null when it is missing. */
+  list: (dir: string) => string[] | null;
+};
+
+/** Everything `repo mutate` does outside this process, injected so a test runs none of it. */
+export type MutateDeps = {
+  cwd: string;
+  /** The config of the repo holding `cwd`, or the lines that say why there is none. */
+  config: (cwd: string) => Promise<MutateConfig | string[]>;
+  /** The workspace package dirs of the root, root-relative. */
+  packages: (root: string) => string[];
+  /** `git <args>` in `cwd`, run with no `GIT_*` variable. */
+  git: (cwd: string, args: string[]) => Captured;
+  /** `bun <args>` in `cwd`, run with no `GIT_*` variable. */
+  run: (args: string[], cwd: string) => Captured;
+  fs: MutateFs;
+  /** Absolute path of `stryker-preload.ts`. */
+  preload: string;
+  out: (text: string) => void;
+  err: (text: string) => void;
+};
+
+/** Prints each line as a `repo mutate:` error and answers with the failing exit code. */
+export function fail(deps: MutateDeps, ...lines: string[]): number {
+  for (const line of lines) deps.err(`repo mutate: ${line}${NEWLINE}`);
+  return FAILED;
+}