@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/config.ts

@@ -0,0 +1,261 @@
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { z } from "zod";
+import { coverageOf, coverageSchema, type ResolvedCoverage } from "./coverage-config.ts";
+import { knipSchema, type ResolvedKnip } from "./knip-schema.ts";
+import { nightlyOf, nightlySchema, type ResolvedNightly } from "./nightly-config.ts";
+import { lintSchema } from "./lint-schema.ts";
+import type { WorkerstackConfig } from "./workerstack-config.types.ts";
+
+/** Config packs a repo can turn on in workerstack.config.ts. */
+export const PACKS = ["agents", "standards", "docs", "release"] as const;
+export type Pack = (typeof PACKS)[number];
+
+export const CONFIG_FILE = "workerstack.config.ts";
+
+/** The package a config imports `defineConfig` from, and the import error that says nothing provides it. */
+const SELF = "@workerstack/repo";
+const MISSING_SELF = /Cannot find (?:package|module) '@workerstack\/repo'/;
+
+/** Agent hosts repo sync can lay a tree out for. */
+export const HOSTS = ["claude", "codex", "antigravity", "grok", "cursor"] as const;
+export type Host = (typeof HOSTS)[number];
+
+/** Optional skill packs a repo can ship to its agents. */
+export const SKILL_PACKS = ["google-workspace", "listen", "speak", "clasp"] as const;
+export type SkillPack = (typeof SKILL_PACKS)[number];
+
+const listOf = (names: readonly string[]) => `${names.slice(0, -1).join(", ")} or ${names.at(-1)}`;
+
+const packSchema = z.enum(PACKS, {
+  error: (issue) => `${JSON.stringify(issue.input)} is not a pack; use ${listOf(PACKS)}`,
+});
+const hostSchema = z.enum(HOSTS, {
+  error: (issue) => `${JSON.stringify(issue.input)} is not a host; use ${listOf(HOSTS)}`,
+});
+const skillSchema = z.enum(SKILL_PACKS, {
+  error: (issue) => `${JSON.stringify(issue.input)} is not a skill pack; use ${listOf(SKILL_PACKS)}`,
+});
+
+/** A list of unique names; a repeat is reported with its count. */
+function uniqueList<S extends z.ZodType<string>>(item: S, error: string) {
+  return z
+    .array(item, { error })
+    .readonly()
+    .superRefine((names, ctx) => {
+      const counts = new Map<z.output<S>, number>();
+      for (const name of names) counts.set(name, (counts.get(name) ?? 0) + 1);
+      for (const [name, count] of counts) {
+        if (count === 1) continue;
+        const times = count === 2 ? "twice" : `${count} times`;
+        ctx.addIssue({ code: "custom", message: `${JSON.stringify(name)} is listed ${times}` });
+      }
+    });
+}
+
+const agentsSchema = z.strictObject(
+  {
+    hosts: uniqueList(hostSchema, "must be a list of host names")
+      .refine((hosts) => hosts.length > 0, { error: "list at least one host" })
+      .optional(),
+    skills: uniqueList(skillSchema, "must be a list of skill pack names").optional(),
+  },
+  { error: "must be an object like { hosts: [...], skills: [...] }" },
+);
+
+/** How many changed lines a commit may have before its message must say why. */
+export const DEFAULT_MAX_CHANGED_LINES = 1000;
+
+const commitSchema = z.strictObject(
+  {
+    maxChangedLines: z
+      .number({ error: "must be a whole number of lines above 0" })
+      .int({ error: "must be a whole number of lines above 0" })
+      .positive({ error: "must be a whole number of lines above 0" })
+      .optional(),
+  },
+  { error: `must be an object like { maxChangedLines: ${DEFAULT_MAX_CHANGED_LINES} }` },
+);
+
+/** A config section that only means something with its pack on. */
+const needsPack = (key: "agents" | "commit" | "knip" | "lint" | "nightly" | "tdd", pack: Pack) => ({
+  path: [key],
+  error: `set only with the ${pack} pack; add "${pack}" to packs or delete ${key}`,
+});
+
+/** Whether the config turns `pack` on, by its `packs` or the default ones. */
+const hasPack = (config: { packs?: readonly Pack[] | undefined }, pack: Pack) =>
+  (config.packs ?? defaultPacks()).includes(pack);
+
+const configSchema = z
+  .strictObject(
+    {
+      packs: uniqueList(packSchema, "must be a list of pack names").optional(),
+      agents: agentsSchema.optional(),
+      commit: commitSchema.optional(),
+      lint: lintSchema().optional(),
+      knip: knipSchema().optional(),
+      coverage: coverageSchema.optional(),
+      nightly: nightlySchema.optional(),
+      tdd: z.boolean({ error: "must be true or false" }).optional(),
+    },
+    { error: "the default export must be an object; use `export default defineConfig({ ... })`" },
+  )
+  .refine((config) => config.agents === undefined || hasPack(config, "agents"), needsPack("agents", "agents"))
+  .refine((config) => config.commit === undefined || hasPack(config, "standards"), needsPack("commit", "standards"))
+  .refine((config) => config.lint === undefined || hasPack(config, "standards"), needsPack("lint", "standards"))
+  .refine((config) => config.knip === undefined || hasPack(config, "standards"), needsPack("knip", "standards"))
+  .refine((config) => config.nightly === undefined || hasPack(config, "release"), needsPack("nightly", "release"))
+  .refine(
+    (config) => config.tdd === undefined || hasPack(config, "standards"),
+    needsPack("tdd", "standards"),
+  ) satisfies z.ZodType<unknown, WorkerstackConfig>;
+
+export type { WorkerstackConfig };
+export type ResolvedAgents = { readonly hosts: readonly Host[]; readonly skills: readonly SkillPack[] };
+/** What the commit-msg hook checks a commit against. */
+export type ResolvedCommit = { readonly maxChangedLines: number };
+/** One `lint.skip` entry: the rules (oxlint keys) it turns off, for the files its globs match, and why. */
+export type LintSkip = { files: readonly string[]; rules: readonly string[]; reason: string };
+/** What the generated oxlint config and `repo check` read from `lint`. */
+export type ResolvedLint = { readonly skip: readonly LintSkip[] };
+export type ResolvedConfig = {
+  readonly packs: readonly Pack[];
+  readonly agents: ResolvedAgents;
+  readonly commit: ResolvedCommit;
+  readonly lint: ResolvedLint;
+  readonly knip: ResolvedKnip;
+  readonly coverage: ResolvedCoverage;
+  /** The nightly workflow's shard count and secret names. */
+  readonly nightly: ResolvedNightly;
+  /** Whether a feat or fix in a private package must also fail its tests on HEAD's source; public packages always do. */
+  readonly tdd: boolean;
+};
+/** The commit rules a config gets when it omits `commit`. */
+export const DEFAULT_COMMIT: ResolvedCommit = { maxChangedLines: DEFAULT_MAX_CHANGED_LINES };
+export type LoadResult = { ok: true; config: ResolvedConfig } | { ok: false; errors: string[] };
+
+/** Types a workerstack.config.ts default export. */
+export function defineConfig(config: WorkerstackConfig): WorkerstackConfig {
+  return config;
+}
+
+/** The packs a repo gets when its config omits `packs`. */
+export function defaultPacks(): Pack[] {
+  return ["agents", "standards", "docs"];
+}
+
+/** The nearest directory at or above `cwd` that holds workerstack.config.ts, or null. */
+export function findRoot(cwd: string): string | null {
+  let dir = path.resolve(cwd);
+  for (;;) {
+    if (fs.existsSync(path.join(dir, CONFIG_FILE))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Imports and validates `<root>/workerstack.config.ts`, filling omitted packs from `defaultPacks`, omitted agents with
+ * every host and no skills, an omitted commit limit with the default, and omitted lint skips with none.
+ */
+export async function loadConfig(root: string, importModule: ImportConfig = importConfig): Promise<LoadResult> {
+  const fail = (messages: string[]): LoadResult => ({
+    ok: false,
+    errors: messages.map((message) => `${CONFIG_FILE}: ${message}`),
+  });
+
+  let loaded: Record<string, unknown>;
+  try {
+    loaded = await importModule(root);
+  } catch (error) {
+    const message = messageOf(error);
+    // A linked worktree without its own install fails here; the fix is an install, not an edit to the config.
+    if (MISSING_SELF.test(message)) return fail([`${SELF} is not installed in ${root}; run \`bun install\` there`]);
+    return fail([`failed to load: ${message}`]);
+  }
+  if (!("default" in loaded)) return fail(["no default export; add `export default defineConfig({ ... })`"]);
+
+  const parsed = configSchema.safeParse(loaded.default);
+  if (!parsed.success) return fail(parsed.error.issues.flatMap(describeIssue));
+  return { ok: true, config: resolve(parsed.data) };
+}
+
+/** The agent hosts and skills a config turns on; every host and no skills when omitted. */
+function agentsOf(agents: z.output<typeof agentsSchema> | undefined): ResolvedAgents {
+  return { hosts: agents?.hosts ?? HOSTS, skills: agents?.skills ?? [] };
+}
+
+/** A parsed config with every omitted value filled in. */
+function resolve(d: z.output<typeof configSchema>): ResolvedConfig {
+  const agents = agentsOf(d.agents);
+  const commit = { maxChangedLines: d.commit?.maxChangedLines ?? DEFAULT_COMMIT.maxChangedLines };
+  return {
+    packs: d.packs ?? defaultPacks(),
+    agents,
+    commit,
+    lint: { skip: d.lint?.skip ?? [] },
+    knip: { ignore: d.knip?.ignore ?? [] },
+    tdd: d.tdd ?? false,
+    ...coverageOf(d),
+    ...nightlyOf(d),
+  };
+}
+
+/** Imports the config module of `root`; `loadConfig` takes another in tests, whose runner resolves packages its own way. */
+export type ImportConfig = (root: string) => Promise<Record<string, unknown>>;
+
+/** Each config file's last loaded text and module, so a load can tell whether the text on disk changed. */
+const loadedConfigs = new Map<string, { text: string; module: Record<string, unknown> }>();
+
+/**
+ * The config module. A module is cached by path for the life of the process (a query string does not bust that
+ * cache), so a file whose text changed since it was loaded is imported from a temporary copy beside it (same
+ * imports resolve, new path). A first load, or an unchanged file, writes nothing.
+ */
+async function importConfig(root: string): Promise<Record<string, unknown>> {
+  const file = path.join(root, CONFIG_FILE);
+  const text = fs.readFileSync(file, "utf8");
+  const known = loadedConfigs.get(file);
+  if (known?.text === text) return known.module;
+  let module: Record<string, unknown>;
+  if (known === undefined) {
+    module = await import(/* @vite-ignore */ pathToFileURL(file).href);
+  } else {
+    const copy = path.join(root, `.workerstack.config.${randomBytes(6).toString("hex")}.ts`);
+    fs.copyFileSync(file, copy);
+    try {
+      module = await import(/* @vite-ignore */ pathToFileURL(copy).href);
+    } finally {
+      fs.rmSync(copy, { force: true });
+    }
+  }
+  loadedConfigs.set(file, { text, module });
+  return module;
+}
+
+/** The skill packs `agents.skills` enables for the repo at or above `cwd`; none when there is no config or it is invalid. */
+export async function enabledSkills(cwd: string): Promise<readonly SkillPack[]> {
+  const root = findRoot(cwd);
+  if (root === null) return [];
+  const loaded = await loadConfig(root);
+  return loaded.ok ? loaded.config.agents.skills : [];
+}
+
+function describeIssue(issue: z.core.$ZodIssue): string[] {
+  // ["packs", 1] reads packs[1]; a config path always starts at a top-level key.
+  const at = issue.path
+    .map((key) => (typeof key === "number" ? `[${key}]` : `.${String(key)}`))
+    .join("")
+    .replace(/^\./, "");
+  const prefix = at ? `${at}: ` : "";
+  if (issue.code === "unrecognized_keys") return issue.keys.map((key) => `${prefix}unknown key ${JSON.stringify(key)}`);
+  return [`${prefix}${issue.message}`];
+}
+
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/cli/conventional.ts

@@ -0,0 +1,9 @@
+/** A Conventional Commits header: `type(scope)!: subject`. */
+export const HEADER: RegExp = /^(?<type>[^\s():!]+)(?:\((?<scope>[^()]*)\))?(?<bang>!)?: (?<subject>.+)$/;
+
+const FOOTER = /^BREAKING[ -]CHANGE: /;
+
+/** Whether a commit is breaking: its header has `!`, or a line of its body is a `BREAKING CHANGE:` footer. */
+export function isBreaking(header: string, body: readonly string[]): boolean {
+  return HEADER.exec(header)?.groups?.["bang"] === "!" || body.some((line) => FOOTER.test(line));
+}

package/cli/coverage-config.ts

@@ -0,0 +1,62 @@
+/** The `coverage` section of workerstack.config.ts: where the floors and the known-failures list live, what to mutate. */
+import { z } from "zod";
+
+/** Where `repo coverage`, `repo mutate` and `repo check` read and write their ratchet files, relative to the repo root. */
+export type ResolvedCoverage = {
+  readonly floors: string;
+  readonly knownFailures: string;
+  /** The globs of the tracked files `repo mutate` mutates. */
+  readonly mutate: readonly string[];
+  readonly mutationFloors: string;
+};
+
+/** The files a config gets when it omits `coverage` or one of its keys. */
+export const DEFAULT_COVERAGE: ResolvedCoverage = {
+  floors: "coverage-floors.json",
+  knownFailures: "known-failures.json",
+  mutate: ["src/**/*.ts"],
+  mutationFloors: "mutation-floors.json",
+};
+
+const PATH_ERROR = `must be a file path like ${DEFAULT_COVERAGE.floors}`;
+const GLOBS_ERROR = 'must be a non-empty list of globs like ["src/**/*.ts"]';
+
+type FileSchema = z.ZodOptional<z.ZodString>;
+type CoverageSchema = z.ZodObject<
+  {
+    floors: FileSchema;
+    knownFailures: FileSchema;
+    mutate: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    mutationFloors: FileSchema;
+  },
+  z.core.$strict
+>;
+
+function buildSchema(): CoverageSchema {
+  const file = z.string({ error: PATH_ERROR }).min(1, { error: PATH_ERROR }).optional();
+  const globs = z
+    .array(z.string({ error: GLOBS_ERROR }).min(1, { error: GLOBS_ERROR }), { error: GLOBS_ERROR })
+    .min(1, { error: GLOBS_ERROR })
+    .optional();
+  return z.strictObject(
+    { floors: file, knownFailures: file, mutate: globs, mutationFloors: file },
+    { error: `must be an object like { floors: "${DEFAULT_COVERAGE.floors}" }` },
+  );
+}
+
+export const coverageSchema: CoverageSchema = /* @__PURE__ */ buildSchema();
+
+/** The parsed config's `coverage` section with every omitted key filled in. */
+export function coverageOf(parsed: { coverage?: z.output<typeof coverageSchema> | undefined }): {
+  coverage: ResolvedCoverage;
+} {
+  const { floors, knownFailures, mutate, mutationFloors } = parsed.coverage ?? {};
+  return {
+    coverage: {
+      floors: floors ?? DEFAULT_COVERAGE.floors,
+      knownFailures: knownFailures ?? DEFAULT_COVERAGE.knownFailures,
+      mutate: mutate ?? DEFAULT_COVERAGE.mutate,
+      mutationFloors: mutationFloors ?? DEFAULT_COVERAGE.mutationFloors,
+    },
+  };
+}

package/cli/coverage.constants.ts

@@ -0,0 +1,6 @@
+/** The names `repo coverage` reads from the coverage summary. */
+
+/** The summary key holding the totals over every file, which is no file. */
+export const TOTAL_KEY = "total";
+/** The spaces the floors file is indented with. */
+export const JSON_INDENT = 2;

package/cli/coverage.test.ts

@@ -0,0 +1,199 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { main } from "./coverage.ts";
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const RUN_MS = 60_000;
+const FLOORS = "coverage-floors.json";
+const saved = process.cwd();
+const temps: string[] = [];
+
+const SOURCE = `export function sign(n: number): string {
+  if (n < 0) return "neg";
+  return "pos";
+}
+
+export function unused(): number {
+  return 1;
+}
+`;
+const PASSING = `import { expect, it } from "vitest";
+import { sign } from "./a.ts";
+
+it("signs a positive number", () => {
+  expect(sign(1)).toBe("pos");
+});
+`;
+const FAILING = PASSING.replace('"pos"', '"neg"');
+const SECOND_SOURCE = "export const answer = (): number => 42;\n";
+const SECOND_TEST = `import { expect, it } from "vitest";
+import { answer } from "./b.ts";
+
+it("answers", () => {
+  expect(answer()).toBe(42);
+});
+`;
+/** What `SOURCE` measures with `PASSING`: lines are 2 of 3 (66.67), so the floor is 66, not 67. */
+const MEASURED = { statements: 50, branches: 50, functions: 50, lines: 66 };
+
+let out: string[] = [];
+let err: string[] = [];
+
+beforeEach(() => {
+  out = [];
+  err = [];
+  vi.spyOn(process.stdout, "write").mockImplementation((chunk) => out.push(String(chunk)) > 0);
+  vi.spyOn(process.stderr, "write").mockImplementation((chunk) => err.push(String(chunk)) > 0);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  process.chdir(saved);
+  for (const dir of temps.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+/** A tiny vitest project in a temp dir, with the repo's installed packages linked in; `config` is its repo config. */
+function project(config = "export default {};\n"): string {
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "workerstack-coverage-")));
+  temps.push(root);
+  fs.symlinkSync(path.join(REPO_ROOT, "node_modules"), path.join(root, "node_modules"), "junction");
+  const preset = JSON.stringify(path.join(REPO_ROOT, "presets", "vitest.ts"));
+  const vitest = `import { defineConfig } from ${preset};
+export default defineConfig({ test: { include: ["src/**/*.test.ts"], coverage: { include: ["src/**"] } } });
+`;
+  const files = {
+    "workerstack.config.ts": config,
+    "vitest.config.ts": vitest,
+    "src/a.ts": SOURCE,
+    "src/a.test.ts": PASSING,
+  };
+  for (const [name, text] of Object.entries(files)) {
+    fs.mkdirSync(path.dirname(path.join(root, name)), { recursive: true });
+    fs.writeFileSync(path.join(root, name), text);
+  }
+  return root;
+}
+
+function floorsOf(root: string, file = FLOORS): unknown {
+  return JSON.parse(fs.readFileSync(path.join(root, file), "utf8"));
+}
+
+/** Runs `repo coverage` in `root`. */
+function coverage(root: string): Promise<number> {
+  process.chdir(root);
+  return main([]);
+}
+
+it("repo coverage: writes a floor for every measured file on the first run", { timeout: RUN_MS }, async () => {
+  const root = project();
+  expect(await coverage(root)).toBe(0);
+  expect(floorsOf(root)).toEqual({ "src/a.ts": MEASURED });
+  const lines = ["statements new → 50", "branches new → 50", "functions new → 50", "lines new → 66"];
+  expect(out.join("")).toBe(`${lines.map((line) => `src/a.ts ${line}\n`).join("")}wrote ${FLOORS}\n`);
+  expect(fs.readdirSync(os.tmpdir()).filter((name) => name.startsWith("workerstack-cov-run"))).toEqual([]);
+});
+
+it("repo coverage: floors every file the suite measures, sorted by path", { timeout: RUN_MS }, async () => {
+  const root = project();
+  fs.writeFileSync(path.join(root, "src/b.ts"), SECOND_SOURCE);
+  fs.writeFileSync(path.join(root, "src/b.test.ts"), SECOND_TEST);
+  expect(await coverage(root)).toBe(0);
+  const written = floorsOf(root) /* the command wrote an object */ as Record<string, unknown>;
+  expect(Object.keys(written)).toEqual(["src/a.ts", "src/b.ts"]);
+  expect(written["src/b.ts"]).toEqual({ statements: 100, branches: 100, functions: 100, lines: 100 });
+});
+
+it(
+  "repo coverage: prints each raised floor with its old and new value and writes the file",
+  { timeout: RUN_MS },
+  async () => {
+    const root = project();
+    fs.writeFileSync(path.join(root, FLOORS), JSON.stringify({ "src/a.ts": { ...MEASURED, branches: 40, lines: 30 } }));
+    expect(await coverage(root)).toBe(0);
+    expect(out.join("")).toBe(`src/a.ts branches 40 → 50\nsrc/a.ts lines 30 → 66\nwrote ${FLOORS}\n`);
+    expect(floorsOf(root)).toEqual({ "src/a.ts": MEASURED });
+  },
+);
+
+it("repo coverage: prints only the wrote line when nothing rises", { timeout: RUN_MS }, async () => {
+  const root = project();
+  await coverage(root);
+  out = [];
+  expect(await coverage(root)).toBe(0);
+  expect(out.join("")).toBe(`wrote ${FLOORS}\n`);
+});
+
+// A project that links this checkout's packages shares their vitest module cache; a nested run that resets it
+// (its lockfile differs) deletes entries the outer run is still reading.
+it(
+  "repo coverage: leaves the module cache it shares through the linked packages alone",
+  { timeout: RUN_MS },
+  async () => {
+    const cache = path.join(REPO_ROOT, "node_modules", ".vitest-cache");
+    fs.mkdirSync(cache, { recursive: true });
+    const sentinel = path.join(cache, `sentinel-${process.pid}`);
+    fs.writeFileSync(sentinel, "");
+    try {
+      expect(await coverage(project())).toBe(0);
+      expect(fs.existsSync(sentinel)).toBe(true);
+    } finally {
+      fs.rmSync(sentinel, { force: true });
+    }
+  },
+);
+
+it("repo coverage: fails a drop with its line and writes nothing", { timeout: RUN_MS }, async () => {
+  const root = project();
+  const floors = JSON.stringify({ "src/a.ts": { ...MEASURED, branches: 100, lines: 75 } });
+  fs.writeFileSync(path.join(root, FLOORS), floors);
+  expect(await coverage(root)).toBe(1);
+  const keep = "restore the tests or keep the floor";
+  expect(err.join("")).toContain(`coverage: src/a.ts branches would drop 100 → 50; ${keep}\n`);
+  expect(err.join("")).toContain(`coverage: src/a.ts lines would drop 75 → 66; ${keep}\n`);
+  expect(out.join("")).toBe("");
+  expect(fs.readFileSync(path.join(root, FLOORS), "utf8")).toBe(floors);
+});
+
+it(
+  "repo coverage: fails a failing test as a test, not as a drop, and writes nothing",
+  { timeout: RUN_MS },
+  async () => {
+    const root = project();
+    fs.writeFileSync(path.join(root, "src/a.test.ts"), FAILING);
+    expect(await coverage(root)).toBe(1);
+    expect(err.join("")).toContain("coverage: the tests failed; fix them before raising floors");
+    expect(err.join("")).not.toContain("would drop");
+    expect(fs.existsSync(path.join(root, FLOORS))).toBe(false);
+  },
+);
+
+it("repo coverage: writes the file coverage.floors names in the config", { timeout: RUN_MS }, async () => {
+  const root = project('export default { coverage: { floors: "ratchets/floors.json" } };\n');
+  expect(await coverage(root)).toBe(0);
+  expect(floorsOf(root, "ratchets/floors.json")).toEqual({ "src/a.ts": MEASURED });
+  expect(out.join("")).toContain("wrote ratchets/floors.json\n");
+  expect(fs.existsSync(path.join(root, FLOORS))).toBe(false);
+});
+
+it("repo coverage: fails, saying so, when the floors file cannot be formatted", { timeout: RUN_MS }, async () => {
+  const root = project('export default { coverage: { floors: "floors.txt" } };\n');
+  expect(await coverage(root)).toBe(1);
+  expect(err.join("")).toContain("coverage: could not format floors.txt\n");
+  expect(out.join("")).toBe("");
+});
+
+it("repo coverage: fails before running anything when the repo config is invalid", async () => {
+  const root = project("export default { coverage: { floor: 'a.json' } };\n");
+  expect(await coverage(root)).toBe(1);
+  expect(err.join("")).toBe('repo coverage: workerstack.config.ts: coverage: unknown key "floor"\n');
+});
+
+it("repo coverage: names a missing repo config", async () => {
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "workerstack-coverage-")));
+  temps.push(root);
+  expect(await coverage(root)).toBe(1);
+  expect(err.join("")).toContain("repo coverage: no workerstack.config.ts");
+});

package/cli/coverage.ts

@@ -0,0 +1,127 @@
+/**
+ * `repo coverage`: runs the suite with coverage and writes each measured file's statements, branches, functions and
+ * lines, floored to integers, to the `coverage.floors` file (`coverage-floors.json`). The preset applies them as
+ * per-file thresholds. A floor only rises: a measurement below one fails and writes nothing.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { CONFIG_FILE, findRoot, loadConfig } from "./config.ts";
+import { JSON_INDENT, TOTAL_KEY } from "./coverage.constants.ts";
+import { childEnv } from "./env.ts";
+import { NESTED_VITEST_FLAGS } from "./nested-vitest-flags.ts";
+import { captureBun, captureTool } from "./scripts/lint.ts";
+
+const METRICS = ["statements", "branches", "functions", "lines"] as const;
+type Metric = (typeof METRICS)[number];
+type Floor = Record<Metric, number>;
+type Floors = Record<string, Floor>;
+type Summary = Record<string, Record<Metric, { pct: number }>>;
+
+const SUMMARY_FILE = "coverage-summary.json";
+const TEMP_PREFIX = "workerstack-cov-run-";
+const FAILED = 1;
+const PASSED = 0;
+
+/** A comparison of the measurement with the old floors: what to write, what rose, what would drop. */
+type Comparison = { next: Floors; raised: string[]; drops: string[] };
+
+type Measured = { ok: true; summary: Summary } | { ok: false };
+
+function write(stream: NodeJS.WriteStream, lines: readonly string[]): void {
+  stream.write(`${lines.join("\n")}\n`);
+}
+
+function readJson<T>(file: string): T | null {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8")) /* the caller names the shape the file holds */ as T;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Runs the suite in `root` with thresholds off, so a floor miss cannot fail the run, and a `json-summary` report in
+ * a temp dir that is removed after. A failing test prints vitest's own output and its own line.
+ */
+function measure(root: string): Measured {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), TEMP_PREFIX));
+  try {
+    const flags = ["--coverage", "--coverage.thresholds=false", "--coverage.reporter=json-summary"];
+    const args = ["--bun", "vitest", "run", ...NESTED_VITEST_FLAGS, ...flags, `--coverage.reportsDirectory=${dir}`];
+    const ran = captureBun(args, root, childEnv());
+    if (ran.code === PASSED) {
+      const summary: unknown = JSON.parse(fs.readFileSync(path.join(dir, SUMMARY_FILE), "utf8"));
+      return { ok: true, summary: summary /* vitest writes the json-summary shape */ as Summary };
+    }
+    process.stderr.write(ran.stdout + ran.stderr);
+    write(process.stderr, ["coverage: the tests failed; fix them before raising floors"]);
+    return { ok: false };
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** Each measured file's floors against `old`: the new floors, the lines for a raise, the lines for a drop. */
+function compare(root: string, summary: Summary, old: Floors): Comparison {
+  const result: Comparison = { next: {}, raised: [], drops: [] };
+  for (const [abs, metrics] of Object.entries(summary)) {
+    if (abs === TOTAL_KEY) continue;
+    const rel = path.relative(root, abs).split(path.sep).join("/");
+    const floor = {} /* filled for every metric below */ as Floor;
+    for (const key of METRICS) {
+      const now = Math.floor(metrics[key].pct);
+      const was = old[rel]?.[key];
+      if (was !== undefined && now < was) {
+        result.drops.push(`coverage: ${rel} ${key} would drop ${was} → ${now}; restore the tests or keep the floor`);
+      } else if (was !== now) {
+        result.raised.push(`${rel} ${key} ${was ?? "new"} → ${now}`);
+      }
+      floor[key] = now;
+    }
+    result.next[rel] = floor;
+  }
+  return result;
+}
+
+/** Writes `floors` sorted to `file`, then formats it with `repo fmt`'s tool; false, after printing why, if that fails. */
+function writeFloors(root: string, file: string, floors: Floors): boolean {
+  const sorted = Object.fromEntries(Object.entries(floors).sort(([a], [b]) => a.localeCompare(b)));
+  const full = path.join(root, file);
+  fs.mkdirSync(path.dirname(full), { recursive: true });
+  fs.writeFileSync(full, `${JSON.stringify(sorted, null, JSON_INDENT)}\n`);
+  const formatted = captureTool("oxfmt", [file], root);
+  if (formatted.code === PASSED) return true;
+  process.stderr.write(formatted.stdout + formatted.stderr);
+  write(process.stderr, [`coverage: could not format ${file}`]);
+  return false;
+}
+
+/** The repo root and its floors path, or the lines that say why there is none. */
+async function locate(cwd: string): Promise<{ root: string; floors: string } | string[]> {
+  const root = findRoot(cwd);
+  if (root === null) return [`repo coverage: no ${CONFIG_FILE} in ${cwd} or any parent; run \`bun repo init\``];
+  const loaded = await loadConfig(root);
+  if (!loaded.ok) return loaded.errors.map((line) => `repo coverage: ${line}`);
+  return { root, floors: loaded.config.coverage.floors };
+}
+
+export async function main(_argv: string[]): Promise<number> {
+  const located = await locate(process.cwd());
+  if (Array.isArray(located)) {
+    write(process.stderr, located);
+    return FAILED;
+  }
+  const { root, floors } = located;
+  const measured = measure(root);
+  if (!measured.ok) return FAILED;
+  const old = readJson<Floors>(path.join(root, floors)) ?? {};
+  const { next, raised, drops } = compare(fs.realpathSync(root), measured.summary, old);
+  if (drops.length > 0) {
+    write(process.stderr, drops);
+    return FAILED;
+  }
+  if (!writeFloors(root, floors, next)) return FAILED;
+  write(process.stdout, [...raised, `wrote ${floors}`]);
+  return PASSED;
+}

package/cli/env.constants.ts

@@ -0,0 +1,10 @@
+/** The names `repo check` and the env-in-config rule compare against. */
+
+/** The one module of a package that reads the process environment. */
+export const ENV_FILE = "env.ts";
+/** The file that marks a folder as a package. */
+export const MANIFEST = "package.json";
+/** The property that carries the environment on `process`, `Bun` and `import.meta`. */
+export const ENV_PROPERTY = "env";
+/** The keyword of `import.meta`. */
+export const IMPORT_KEYWORD = "import";