@bensandee/tooling 0.55.2 → 0.57.0

package/README.md

@@ -162,6 +162,80 @@ Convention and overrides coexist — a repo can use both.
 
 Works for both `changesets` and `simple` release strategies, on Forgejo (via API upload) and GitHub (via `gh release upload --clobber`). The asset step in the workflow is gated on the release itself having published/pushed, so failed releases never upload stale artifacts.
 
+### Coverage tracking
+
+| Command                    | Description                                                                                   |
+| -------------------------- | --------------------------------------------------------------------------------------------- |
+| `tooling coverage:summary` | Print a labeled per-package summary of the latest run. `--json` for machine-readable form.    |
+| `tooling coverage:check`   | Compare the latest run against `coverage-baseline.json`; exit non-zero on regression.         |
+| `tooling coverage:record`  | Append the latest run to a `bst/coverage-metrics` orphan branch (CI: push to default branch). |
+| `tooling coverage:status`  | Show recent coverage trend. Read-only — fetches the orphan branch, no checkout.               |
+
+The feature has two halves: a **CI history** that captures one record per commit on the default branch (visible to anyone with the repo), and a **local ratchet** that the agent (or developer) consults before declaring a task complete.
+
+#### How it works
+
+`repo:sync` enables coverage tracking automatically when a `vitest.config.ts` is present. The generated `vitest.config.ts` includes the `json-summary` reporter so each `pnpm test:coverage` writes `coverage/coverage-summary.json` alongside the human-readable HTML report. A generated `coverage.yml` workflow runs on push to the default branch and pipes:
+
+```text
+pnpm test:coverage  →  coverage:summary  →  coverage:record  →  coverage:status
+```
+
+so every CI log ends with the trend table for the last 10 records.
+
+The history file (`coverage-history.jsonl`) lives on a dedicated `bst/coverage-metrics` orphan branch — never on `main`. This sidesteps branch protection (no privileged token needed beyond `contents: write`) and keeps `git log main` clean. `coverage:record` uses pure git plumbing (`hash-object` → `mktree` → `commit-tree` → `push --force-with-lease`) so the working tree is never touched, and concurrent CI runs are handled safely via compare-and-swap with retry.
+
+#### The local ratchet
+
+A tracked `coverage-baseline.json` at the repo root captures the four overall totals (lines/statements/branches/functions) plus per-package numbers. `coverage:check` compares the latest run against it and exits non-zero if any total drops more than the configured `tolerancePp` (default 0.1). When all four are flat-or-up, `--update-baseline` rewrites the file so it can be staged with the change.
+
+`repo:sync` also inserts a `<!-- @tooling:coverage-rule -->` managed block into `CLAUDE.md` describing the workflow:
+
+> Before declaring a task complete that touched files under `packages/*/src/`, run `pnpm test:coverage` then `pnpm exec bst coverage:check`. If any total dropped, add tests until parity is restored — or, if a touched file is genuinely not worth covering, exclude it via `coverage.exclude` in `vitest.config.ts` and explain why in the commit message. If all four are flat-or-up, run `pnpm exec bst coverage:check --update-baseline` and stage `coverage-baseline.json`.
+
+Skip the rule for docs-only, config-only, dependency-bump, or test-only changes.
+
+#### Bootstrap
+
+On a clean default branch, generate the initial baseline:
+
+```bash
+pnpm test:coverage
+pnpm exec bst coverage:check --update-baseline --no-fail-on-missing-baseline
+git add coverage-baseline.json
+```
+
+The first CI run on the default branch creates the orphan `bst/coverage-metrics` branch automatically. From any clone, inspect the trend with:
+
+```bash
+pnpm exec bst coverage:status --limit 20
+```
+
+#### Opt-out
+
+Disable the feature entirely:
+
+```json
+{ "coverage": false }
+```
+
+Or keep the local ratchet but skip the CI history append:
+
+```json
+{ "coverage": { "history": "none" } }
+```
+
+| Override field       | Default                  | Description                                                            |
+| -------------------- | ------------------------ | ---------------------------------------------------------------------- |
+| `history`            | `"orphan-branch"`        | `"none"` disables CI history; the local ratchet still works            |
+| `historyBranch`      | `"bst/coverage-metrics"` | Override the orphan branch name                                        |
+| `tolerancePp`        | `0.1`                    | Tolerance in percentage points before `coverage:check` flags a drop    |
+| `gateOnPullRequests` | `false`                  | Run coverage on PR builds too (deferred follow-up — currently a no-op) |
+
+#### Per-package re-sum
+
+The trimmed record's `packages` map is computed by aggregating files whose path starts with `packages/<name>/`, so monorepo packages get their own line/branch percentages without per-package vitest configs. Single-package repos collapse to one entry keyed by the directory basename. Per-package numbers are recorded but **not gated** — only the four overall totals control the ratchet.
+
 ### Docker
 
 | Command                  | Description                                                         |

package/dist/bin.mjs

@@ -595,6 +595,12 @@ const DockerCheckConfigSchema = z.object({
 	timeoutMs: z.number().int().positive().optional().meta({ description: "Overall timeout in milliseconds" }),
 	pollIntervalMs: z.number().int().positive().optional().meta({ description: "Poll interval in milliseconds" })
 });
+const CoverageConfigSchema = z.strictObject({
+	history: z.enum(["orphan-branch", "none"]).optional().meta({ description: "How coverage history is persisted. 'orphan-branch' (default) appends to a dedicated branch; 'none' disables CI history but keeps the local ratchet." }),
+	historyBranch: z.string().optional().meta({ description: "Orphan branch name for coverage history (default: 'bst/coverage-metrics')" }),
+	tolerancePp: z.number().nonnegative().optional().meta({ description: "Tolerance in percentage points for baseline comparison (default: 0.1)" }),
+	gateOnPullRequests: z.boolean().optional().meta({ description: "Run coverage on PR builds too (default: false; deferred follow-up)" })
+});
 const ReleaseAssetSchema = z.strictObject({
 	command: z.array(z.string()).nonempty().optional().meta({ description: "argv passed directly to the child process (no shell interpolation), e.g. [\"pnpm\",\"build\"]" }),
 	file: z.string().meta({ description: "Path to the asset file to upload, relative to the project root" }),
@@ -637,7 +643,8 @@ const ToolingConfigSchema = z.strictObject({
 	registryNamespace: z.string().optional().meta({ description: "Docker registry namespace (e.g. ghcr.io/myorg, code.example.com/myorg)" }),
 	releaseAssets: z.array(ReleaseAssetSchema).optional().meta({ description: "Custom assets to build and upload to the release" }),
 	postReleaseHook: z.string().optional().meta({ description: "Override the post-release hook command (default: POST to POST_RELEASE_HOOK_URL with HMAC-SHA256 auth)" }),
-	postReleaseHookSecrets: z.array(z.string()).optional().meta({ description: "Additional secret names to inject as env vars in the post-release hook step (e.g. ['WEBHOOK_SECRET'])" })
+	postReleaseHookSecrets: z.array(z.string()).optional().meta({ description: "Additional secret names to inject as env vars in the post-release hook step (e.g. ['WEBHOOK_SECRET'])" }),
+	coverage: z.union([z.literal(false), CoverageConfigSchema]).optional().meta({ description: "Coverage tracking configuration. Set to false to disable; omit for default-on (when a vitest config is present)." })
 });
 /** Format a Zod issue as a human-readable bullet: location + plain-English explanation. */
 function formatIssue(issue) {
@@ -1522,6 +1529,7 @@ const STANDARD_SCRIPTS_SINGLE = {
 	dev: "tsdown --watch",
 	typecheck: "tsc --noEmit",
 	test: "vitest run",
+	"test:coverage": "vitest run --coverage",
 	lint: "oxlint",
 	knip: "knip",
 	check: "bst checks:run",
@@ -1532,6 +1540,7 @@ const STANDARD_SCRIPTS_SINGLE = {
 const STANDARD_SCRIPTS_MONOREPO = {
 	build: "pnpm -r build",
 	test: "pnpm -r test",
+	"test:coverage": "vitest run --coverage",
 	typecheck: "pnpm -r --parallel run typecheck",
 	lint: "oxlint",
 	knip: "knip",
@@ -1791,7 +1800,7 @@ async function generatePackageJson(ctx) {
 	const devDeps = { ...ROOT_DEV_DEPS };
 	if (!isMonorepo) Object.assign(devDeps, PER_PACKAGE_DEV_DEPS);
 	devDeps["@bensandee/config"] = isWorkspacePackage(ctx, "@bensandee/config") ? "workspace:*" : "0.10.2";
-	devDeps["@bensandee/tooling"] = isWorkspacePackage(ctx, "@bensandee/tooling") ? "workspace:*" : "0.55.2";
+	devDeps["@bensandee/tooling"] = isWorkspacePackage(ctx, "@bensandee/tooling") ? "workspace:*" : "0.57.0";
 	if (ctx.config.useEslintPlugin) devDeps["@bensandee/eslint-plugin"] = isWorkspacePackage(ctx, "@bensandee/eslint-plugin") ? "workspace:*" : "0.12.0";
 	if (ctx.config.formatter === "oxfmt") devDeps["oxfmt"] = {
 		"@changesets/cli": "2.31.0",
@@ -2095,12 +2104,342 @@ function generateMonorepoPackageTsconfigs(ctx) {
 	return results;
 }
 //#endregion
+//#region src/coverage-tracking/compare.ts
+const TOTAL_KEYS = [
+	"lines",
+	"statements",
+	"branches",
+	"functions"
+];
+const DEFAULT_TOLERANCE_PP = .1;
+/** Round to 2 decimal places to keep diff output stable across runs. */
+function round2$1(n) {
+	return Math.round(n * 100) / 100;
+}
+/**
+* Compare a current run against a baseline across the four overall totals.
+* A total passes when current >= baseline OR (baseline - current) <= tolerancePp.
+*/
+function compareTotals(baseline, current, tolerancePp = DEFAULT_TOLERANCE_PP) {
+	const totals = TOTAL_KEYS.map((key) => {
+		const b = baseline[key];
+		const c = current[key];
+		return {
+			key,
+			baseline: b,
+			current: c,
+			delta: round2$1(c - b),
+			pass: c >= b || b - c <= tolerancePp
+		};
+	});
+	return {
+		pass: totals.every((t) => t.pass),
+		tolerancePp,
+		totals
+	};
+}
+/** True iff every total is flat-or-up (delta >= 0). Used to gate baseline updates. */
+function isFlatOrUp(baseline, current) {
+	return TOTAL_KEYS.every((key) => current[key] >= baseline[key]);
+}
+//#endregion
+//#region src/coverage-tracking/parse.ts
+const TotalEntrySchema = z.object({
+	total: z.number(),
+	covered: z.number(),
+	skipped: z.number().optional(),
+	pct: z.number()
+});
+const FileEntrySchema = z.object({
+	lines: TotalEntrySchema,
+	statements: TotalEntrySchema,
+	branches: TotalEntrySchema,
+	functions: TotalEntrySchema
+});
+/**
+* Schema for v8 / istanbul `coverage/coverage-summary.json`. The "total" key
+* holds the grand totals; every other key is a per-file path → entry mapping.
+*/
+const V8CoverageSummarySchema = z.object({ total: FileEntrySchema }).catchall(FileEntrySchema);
+const TotalsSchema = z.object({
+	lines: z.number(),
+	statements: z.number(),
+	branches: z.number(),
+	functions: z.number()
+});
+const PackageEntrySchema = z.object({
+	lines: z.number(),
+	branches: z.number()
+});
+/** Coverage record without identity fields — body shape for `coverage-baseline.json`. */
+const CoverageBaselineSchema = z.object({
+	totals: TotalsSchema,
+	packages: z.record(z.string(), PackageEntrySchema)
+});
+/** Full trimmed record — appended to `coverage-history.jsonl` and emitted by `coverage:summary`. */
+const CoverageRecordSchema = CoverageBaselineSchema.extend({
+	sha: z.string(),
+	timestamp: z.string()
+});
+/** Parse a v8 `coverage-summary.json` blob; throws FatalError on malformed input. */
+function parseV8Summary(raw) {
+	let json;
+	try {
+		json = JSON.parse(raw);
+	} catch (error) {
+		throw new FatalError(`coverage-summary.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	const result = V8CoverageSummarySchema.safeParse(json);
+	if (!result.success) throw new FatalError(`coverage-summary.json shape doesn't match v8 / istanbul output: ${result.error.message}`);
+	return result.data;
+}
+/** Parse a `coverage-baseline.json` blob; throws FatalError on malformed input. */
+function parseBaseline(raw) {
+	let json;
+	try {
+		json = JSON.parse(raw);
+	} catch (error) {
+		throw new FatalError(`coverage-baseline.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	const result = CoverageBaselineSchema.safeParse(json);
+	if (!result.success) throw new FatalError(`coverage-baseline.json has unexpected shape: ${result.error.message}`);
+	return result.data;
+}
+/** Parse a single line of `coverage-history.jsonl`; returns undefined for malformed lines. */
+function parseHistoryLine(line) {
+	let json;
+	try {
+		json = JSON.parse(line);
+	} catch (_error) {
+		return;
+	}
+	const result = CoverageRecordSchema.safeParse(json);
+	return result.success ? result.data : void 0;
+}
+//#endregion
+//#region src/coverage-tracking/history.ts
+const DEFAULT_HISTORY_BRANCH = "bst/coverage-metrics";
+const HISTORY_FILE = "coverage-history.jsonl";
+const MAX_PUSH_ATTEMPTS = 5;
+function remoteRef(config) {
+	return `refs/remotes/${config.remote ?? "origin"}/${config.historyBranch}`;
+}
+function fetchBranch(executor, config) {
+	const remote = config.remote ?? "origin";
+	if (executor.exec("git", [
+		"fetch",
+		remote,
+		`${config.historyBranch}:${remoteRef(config)}`
+	], { cwd: config.cwd }).exitCode !== 0) return { exists: false };
+	const revParse = executor.exec("git", [
+		"rev-parse",
+		"--quiet",
+		"--verify",
+		remoteRef(config)
+	], { cwd: config.cwd });
+	if (revParse.exitCode !== 0) return { exists: false };
+	return {
+		exists: true,
+		parentSha: revParse.stdout.trim()
+	};
+}
+function readRemoteHistory(executor, config) {
+	const showResult = executor.exec("git", ["show", `${remoteRef(config)}:${HISTORY_FILE}`], { cwd: config.cwd });
+	if (showResult.exitCode !== 0) return "";
+	return showResult.stdout;
+}
+function makeBlob(executor, cwd, content) {
+	const result = executor.exec("git", [
+		"hash-object",
+		"-w",
+		"--stdin"
+	], {
+		cwd,
+		input: content
+	});
+	if (result.exitCode !== 0) throw new FatalError(`git hash-object failed: ${result.stderr.trim() || "unknown error"}`);
+	return result.stdout.trim();
+}
+function makeTree(executor, cwd, blobSha) {
+	const treeInput = `100644 blob ${blobSha}\t${HISTORY_FILE}\n`;
+	const result = executor.exec("git", ["mktree"], {
+		cwd,
+		input: treeInput
+	});
+	if (result.exitCode !== 0) throw new FatalError(`git mktree failed: ${result.stderr.trim() || "unknown error"}`);
+	return result.stdout.trim();
+}
+function makeCommit(executor, config, treeSha, parentSha, message) {
+	const env = {};
+	if (config.authorName) {
+		env["GIT_AUTHOR_NAME"] = config.authorName;
+		env["GIT_COMMITTER_NAME"] = config.authorName;
+	}
+	if (config.authorEmail) {
+		env["GIT_AUTHOR_EMAIL"] = config.authorEmail;
+		env["GIT_COMMITTER_EMAIL"] = config.authorEmail;
+	}
+	const args = parentSha ? [
+		"commit-tree",
+		"-p",
+		parentSha,
+		"-m",
+		message,
+		treeSha
+	] : [
+		"commit-tree",
+		"-m",
+		message,
+		treeSha
+	];
+	const result = executor.exec("git", args, {
+		cwd: config.cwd,
+		env
+	});
+	if (result.exitCode !== 0) throw new FatalError(`git commit-tree failed: ${result.stderr.trim() || "unknown error"}`);
+	return result.stdout.trim();
+}
+function pushCommit(executor, config, commitSha, parentSha) {
+	const remote = config.remote ?? "origin";
+	const refSpec = `${commitSha}:refs/heads/${config.historyBranch}`;
+	if (parentSha === void 0) return executor.exec("git", [
+		"push",
+		remote,
+		refSpec
+	], { cwd: config.cwd });
+	const lease = `--force-with-lease=refs/heads/${config.historyBranch}:${parentSha}`;
+	return executor.exec("git", [
+		"push",
+		lease,
+		remote,
+		refSpec
+	], { cwd: config.cwd });
+}
+function shortSha(sha) {
+	return sha.slice(0, 7);
+}
+/**
+* Append a coverage record to the orphan branch. Bootstraps the branch on first run.
+* Uses pure git plumbing (no worktree / no checkout) so the working tree stays untouched.
+* On push conflict (concurrent record), refetches and rebuilds the commit (up to MAX_PUSH_ATTEMPTS).
+*/
+function appendRecord(executor, config, record) {
+	const line = JSON.stringify(record) + "\n";
+	let lastError = "";
+	for (let attempt = 1; attempt <= MAX_PUSH_ATTEMPTS; attempt++) {
+		const fetched = fetchBranch(executor, config);
+		const newContent = (fetched.exists ? readRemoteHistory(executor, config) : "") + line;
+		const blobSha = makeBlob(executor, config.cwd, newContent);
+		const treeSha = makeTree(executor, config.cwd, blobSha);
+		const message = `chore(coverage): record ${shortSha(record.sha)} [skip ci]`;
+		const commitSha = makeCommit(executor, config, treeSha, fetched.parentSha, message);
+		const pushResult = pushCommit(executor, config, commitSha, fetched.parentSha);
+		if (pushResult.exitCode === 0) return {
+			commitSha,
+			bootstrapped: !fetched.exists,
+			attempts: attempt
+		};
+		lastError = pushResult.stderr.trim() || pushResult.stdout.trim() || "unknown push error";
+	}
+	throw new FatalError(`Failed to push to ${config.historyBranch} after ${MAX_PUSH_ATTEMPTS} attempts: ${lastError}`);
+}
+/**
+* Read all records from the orphan branch (read-only). Performs a shallow fetch and
+* reads via `git show` — no working-tree disruption, no local branch creation.
+* Returns an empty array if the branch doesn't exist yet.
+*/
+function readRecords(executor, config) {
+	if (!fetchBranch(executor, config).exists) return [];
+	const raw = readRemoteHistory(executor, config);
+	const records = [];
+	for (const line of raw.split("\n")) {
+		if (line.trim() === "") continue;
+		const parsed = parseHistoryLine(line);
+		if (parsed) records.push(parsed);
+	}
+	return records;
+}
+//#endregion
+//#region src/coverage-tracking/config.ts
+/** Resolve the effective coverage configuration from explicit inputs (testable). */
+function resolveFromInputs(inputs) {
+	if (inputs.coverage === false) return {
+		enabled: false,
+		historyEnabled: false,
+		historyBranch: DEFAULT_HISTORY_BRANCH,
+		tolerancePp: DEFAULT_TOLERANCE_PP,
+		gateOnPullRequests: false
+	};
+	const enabled = inputs.hasVitestConfig || inputs.setupVitest;
+	const overrides = inputs.coverage ?? {};
+	return {
+		enabled,
+		historyEnabled: enabled && overrides.history !== "none",
+		historyBranch: overrides.historyBranch ?? "bst/coverage-metrics",
+		tolerancePp: overrides.tolerancePp ?? .1,
+		gateOnPullRequests: overrides.gateOnPullRequests ?? false
+	};
+}
+/**
+* Resolve from the real filesystem (used by CLI commands).
+* Default-on when a vitest config is detected and `.tooling.json#coverage` is not `false`.
+*/
+function resolveCoverageConfig(targetDir) {
+	const tooling = safeLoadToolingConfig(targetDir);
+	return resolveFromInputs({
+		hasVitestConfig: existsSync(path.join(targetDir, "vitest.config.ts")) || existsSync(path.join(targetDir, "vitest.config.mts")),
+		setupVitest: tooling?.setupVitest === true,
+		coverage: tooling?.coverage
+	});
+}
+const CoverageOverridesShape = z.object({
+	history: z.enum(["orphan-branch", "none"]).optional(),
+	historyBranch: z.string().optional(),
+	tolerancePp: z.number().nonnegative().optional(),
+	gateOnPullRequests: z.boolean().optional()
+});
+const CoverageFieldSchema = z.union([z.literal(false), CoverageOverridesShape]);
+const ToolingShallowSchema = z.object({
+	setupVitest: z.boolean().optional(),
+	coverage: CoverageFieldSchema.optional()
+});
+/** Resolve from a generator context (used by generators for mock-friendly testing). */
+function resolveCoverageConfigFromContext(reader, fallbackSetupVitest) {
+	const toolingRaw = reader.read(".tooling.json");
+	let setupVitest = fallbackSetupVitest;
+	let coverage;
+	if (toolingRaw) try {
+		const result = ToolingShallowSchema.safeParse(JSON.parse(toolingRaw));
+		if (result.success) {
+			if (typeof result.data.setupVitest === "boolean") setupVitest = result.data.setupVitest;
+			coverage = result.data.coverage;
+		}
+	} catch (_error) {}
+	return resolveFromInputs({
+		hasVitestConfig: reader.exists("vitest.config.ts") || reader.exists("vitest.config.mts"),
+		setupVitest,
+		coverage
+	});
+}
+/** Like loadToolingConfig but returns undefined on any error so commands can degrade gracefully. */
+function safeLoadToolingConfig(targetDir) {
+	try {
+		return loadToolingConfig(targetDir);
+	} catch (_error) {
+		return;
+	}
+}
+//#endregion
 //#region src/generators/vitest.ts
 const VITEST_CONFIG = `import { defineConfig } from "vitest/config";
 
 export default defineConfig({
   test: {
     include: ["test/**/*.test.ts"],
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "html", "lcov", "json-summary"],
+    },
   },
 });
 `;
@@ -2112,18 +2451,50 @@ describe("example", () => {
   });
 });
 `;
+const ROOT_CONFIG_PATHS = ["vitest.config.ts", "vitest.config.mts"];
+function findJsonSummaryIssue(content) {
+	if (!/\bcoverage\s*:\s*\{/.test(content)) return "missing-coverage";
+	const reporterMatch = /\breporter\s*:\s*\[([\s\S]*?)\]/.exec(content);
+	if (!reporterMatch) return "missing-reporter";
+	if (!reporterMatch[1]?.includes("json-summary")) return "missing-json-summary";
+}
+function describeIssue(issue) {
+	switch (issue) {
+		case "missing-coverage": return "no `coverage` block found";
+		case "missing-reporter": return "no `reporter` array inside `coverage` block";
+		case "missing-json-summary": return "`coverage.reporter` does not include \"json-summary\"";
+	}
+}
+function warnIfMissingJsonSummary(ctx) {
+	if (!resolveCoverageConfigFromContext(ctx, ctx.config.setupVitest).enabled) return;
+	for (const rel of ROOT_CONFIG_PATHS) {
+		if (!ctx.exists(rel)) continue;
+		const content = ctx.read(rel);
+		if (content === void 0) continue;
+		const issue = findJsonSummaryIssue(content);
+		if (issue === void 0) return;
+		log.warn(`${rel}: ${describeIssue(issue)} — coverage tracking (bst coverage:summary / coverage:check) requires the "json-summary" reporter to read coverage/coverage-summary.json.`);
+		return;
+	}
+}
 async function generateVitest(ctx) {
 	const results = [];
-	if (!ctx.config.setupVitest) return [{
-		filePath: "vitest.config.ts",
-		action: "skipped",
-		description: "Vitest setup not requested"
-	}];
-	if (ctx.config.structure === "monorepo") return [{
-		filePath: "vitest.config.ts",
-		action: "skipped",
-		description: "Monorepo: vitest config belongs in individual packages"
-	}];
+	if (!ctx.config.setupVitest) {
+		warnIfMissingJsonSummary(ctx);
+		return [{
+			filePath: "vitest.config.ts",
+			action: "skipped",
+			description: "Vitest setup not requested"
+		}];
+	}
+	if (ctx.config.structure === "monorepo") {
+		warnIfMissingJsonSummary(ctx);
+		return [{
+			filePath: "vitest.config.ts",
+			action: "skipped",
+			description: "Monorepo: vitest config belongs in individual packages"
+		}];
+	}
 	const configPath = "vitest.config.ts";
 	if (ctx.exists(configPath)) if (ctx.read(configPath) === VITEST_CONFIG) results.push({
 		filePath: configPath,
@@ -2160,6 +2531,7 @@ async function generateVitest(ctx) {
 			description: "Generated starter test file"
 		});
 	}
+	warnIfMissingJsonSummary(ctx);
 	return results;
 }
 //#endregion
@@ -2902,7 +3274,8 @@ const REQUIRED_ENTRIES = [
 const OPTIONAL_ENTRIES = [
 	".tooling-migrate.md",
 	".tooling-archived/",
-	".claude/hooks/bst-hook.audit.local.jsonl*"
+	".claude/hooks/bst-hook.audit.local.jsonl*",
+	"coverage/"
 ];
 /**
 * Optional entries added only when a feature is actually configured.
@@ -4039,6 +4412,201 @@ async function generateVscodeSettings(ctx) {
 	return results;
 }
 //#endregion
+//#region src/generators/coverage-ci.ts
+function coverageSteps(nodeVersionYaml) {
+	return [
+		{ step: {
+			uses: "actions/checkout@v6",
+			with: { "fetch-depth": 0 }
+		} },
+		{ step: { uses: "pnpm/action-setup@v5" } },
+		{ step: {
+			uses: "actions/setup-node@v6",
+			with: {
+				...nodeVersionYaml.startsWith("node-version-file") ? { "node-version-file": "package.json" } : { "node-version": "24" },
+				cache: "pnpm"
+			}
+		} },
+		{ step: { run: "pnpm install --frozen-lockfile" } },
+		{ step: {
+			name: "Build",
+			run: "pnpm build"
+		} },
+		{ step: {
+			name: "Run tests with coverage",
+			run: "pnpm test:coverage"
+		} },
+		{ step: {
+			name: "Print coverage summary",
+			run: "pnpm exec bst coverage:summary"
+		} },
+		{ step: {
+			name: "Append record to bst/coverage-metrics branch",
+			run: "pnpm exec bst coverage:record"
+		} },
+		{ step: {
+			name: "Show recent coverage trend",
+			run: "pnpm exec bst coverage:status --limit 10"
+		} }
+	];
+}
+async function generateCoverageCi(ctx) {
+	const filePath = "coverage-ci";
+	if (ctx.config.ci === "none") return {
+		filePath,
+		action: "skipped",
+		description: "CI workflow not requested"
+	};
+	const config = resolveCoverageConfigFromContext(ctx, ctx.config.setupVitest);
+	if (!config.enabled || !config.historyEnabled) return {
+		filePath,
+		action: "skipped",
+		description: "Coverage tracking disabled"
+	};
+	const isGitHub = ctx.config.ci === "github";
+	const isForgejo = !isGitHub;
+	const workflowPath = isGitHub ? ".github/workflows/coverage.yml" : ".forgejo/workflows/coverage.yml";
+	const nodeVersionYaml = computeNodeVersionYaml(ctx);
+	const content = buildWorkflowYaml({
+		ci: ctx.config.ci,
+		name: "Coverage",
+		on: { push: {
+			branches: ["main"],
+			"tags-ignore": ["**"]
+		} },
+		permissions: { contents: "write" },
+		enableEmailNotifications: isForgejo,
+		jobName: "coverage",
+		steps: coverageSteps(nodeVersionYaml)
+	});
+	const alreadyExists = ctx.exists(workflowPath);
+	const existing = alreadyExists ? ctx.read(workflowPath) : void 0;
+	if (existing) {
+		if (isToolingIgnored(existing)) return {
+			filePath: workflowPath,
+			action: "skipped",
+			description: "Coverage workflow has ignore comment"
+		};
+		if (normalizeWorkflow(existing) === normalizeWorkflow(content)) return {
+			filePath: workflowPath,
+			action: "skipped",
+			description: "Coverage workflow already up to date"
+		};
+	}
+	const withPinnedActions = preservePinnedActions(preserveDevBinaryPath(content, existing), existing);
+	const final = existing ? insertCustomBlocks(withPinnedActions, extractCustomBlocks(existing)) : withPinnedActions;
+	ctx.write(workflowPath, final);
+	return {
+		filePath: workflowPath,
+		action: alreadyExists ? "updated" : "created",
+		description: `Generated ${isGitHub ? "GitHub" : "Forgejo"} Actions coverage workflow`
+	};
+}
+//#endregion
+//#region src/generators/claude-md.ts
+const FILE = "CLAUDE.md";
+const START_MARKER = "<!-- @tooling:coverage-rule -->";
+const END_MARKER = "<!-- @tooling:endcoverage-rule -->";
+/**
+* The coverage-baseline rule that the agent must consult before declaring a
+* task complete. Kept terse — the linked plan and `--help` carry the long form.
+*/
+const RULE_BODY = [
+	"### Coverage baseline",
+	"",
+	"Before declaring a task complete that touched files under `packages/*/src/` (or `src/` for single-package repos), run `pnpm test:coverage` then `pnpm exec bst coverage:check`. If any of the four overall totals (lines/statements/branches/functions) dropped by more than the configured tolerance, add tests until parity is restored — or, if a touched file is genuinely not worth covering, exclude it via `coverage.exclude` in `vitest.config.ts` and explain why in the commit message. If all four are flat-or-up, run `pnpm exec bst coverage:check --update-baseline` and stage `coverage-baseline.json` with the change. Skip this gate for docs-only, config-only, dependency-bump, or test-only changes."
+].join("\n");
+/** Build the full managed block including markers. */
+function buildBlock() {
+	return `${START_MARKER}\n\n${RULE_BODY}\n\n${END_MARKER}\n`;
+}
+function findBlock(existing) {
+	const lines = existing.split("\n");
+	let startLine = -1;
+	for (let i = 0; i < lines.length; i++) if (lines[i]?.trim() === START_MARKER) {
+		startLine = i;
+		break;
+	}
+	if (startLine === -1) return void 0;
+	for (let i = startLine + 1; i < lines.length; i++) if (lines[i]?.trim() === END_MARKER) return {
+		startLine,
+		endLine: i
+	};
+}
+/**
+* Replace any existing `<!-- @tooling:coverage-rule -->...<!-- @tooling:endcoverage-rule -->`
+* block in `existing` with `block`, or append it at the end if no block is found.
+*/
+function upsertBlock(existing, block) {
+	const found = findBlock(existing);
+	if (!found) return `${existing.replace(/\n+$/, "")}\n\n${block}`;
+	const lines = existing.split("\n");
+	const beforeLines = lines.slice(0, found.startLine);
+	const afterLines = lines.slice(found.endLine + 1);
+	const before = beforeLines.join("\n").replace(/\n+$/, "");
+	const after = afterLines.join("\n").replace(/^\n+/, "");
+	const tail = after.length > 0 ? `\n\n${after}` : "\n";
+	return `${before}\n\n${block.replace(/\n+$/, "")}${tail}`;
+}
+/** Strip a coverage-rule managed block (markers + body) from CLAUDE.md content. */
+function removeBlock(existing) {
+	const found = findBlock(existing);
+	if (!found) return existing;
+	const lines = existing.split("\n");
+	const beforeLines = lines.slice(0, found.startLine);
+	const afterLines = lines.slice(found.endLine + 1);
+	const before = beforeLines.join("\n").replace(/\n+$/, "");
+	const after = afterLines.join("\n").replace(/^\n+/, "");
+	if (after.length === 0) return `${before}\n`;
+	return `${before}\n\n${after}`;
+}
+const STARTER_CLAUDE_MD = "# CLAUDE.md\n\nProject guidance for Claude Code.\n";
+async function generateClaudeMd(ctx) {
+	const config = resolveCoverageConfigFromContext(ctx, ctx.config.setupVitest);
+	const existing = ctx.read(FILE);
+	if (!config.enabled) {
+		if (!existing) return {
+			filePath: FILE,
+			action: "skipped",
+			description: "Coverage disabled; no CLAUDE.md to manage"
+		};
+		if (!existing.includes(START_MARKER)) return {
+			filePath: FILE,
+			action: "skipped",
+			description: "Coverage disabled; no managed block to remove"
+		};
+		const updated = removeBlock(existing);
+		ctx.write(FILE, updated);
+		return {
+			filePath: FILE,
+			action: "updated",
+			description: "Removed coverage-rule managed block"
+		};
+	}
+	const block = buildBlock();
+	if (!existing) {
+		const content = upsertBlock(STARTER_CLAUDE_MD, block);
+		ctx.write(FILE, content);
+		return {
+			filePath: FILE,
+			action: "created",
+			description: "Generated CLAUDE.md with coverage-rule block"
+		};
+	}
+	const updated = upsertBlock(existing, block);
+	if (updated === existing) return {
+		filePath: FILE,
+		action: "skipped",
+		description: "Coverage-rule block already up to date"
+	};
+	ctx.write(FILE, updated);
+	return {
+		filePath: FILE,
+		action: "updated",
+		description: "Updated coverage-rule managed block"
+	};
+}
+//#endregion
 //#region src/generators/versionrc.ts
 function buildConfig() {
 	return {
@@ -4127,6 +4695,8 @@ async function runGenerators(ctx) {
 	results.push(await generateChangesets(ctx));
 	results.push(await generateReleaseCi(ctx));
 	results.push(await generateDeployCi(ctx));
+	results.push(await generateCoverageCi(ctx));
+	results.push(await generateClaudeMd(ctx));
 	results.push(...await generateVitest(ctx));
 	results.push(...await generateVscodeSettings(ctx));
 	results.push(saveToolingConfig(ctx, ctx.config));
@@ -4141,7 +4711,7 @@ async function runGenerators(ctx) {
 function generateMigratePrompt(results, config, detected) {
 	const sections = [];
 	const timestamp = (/* @__PURE__ */ new Date()).toISOString();
-	sections.push(`# Migration Prompt\n\n_Generated by \`@bensandee/tooling@0.55.2 repo:sync\` on ${timestamp}_\n`);
+	sections.push(`# Migration Prompt\n\n_Generated by \`@bensandee/tooling@0.57.0 repo:sync\` on ${timestamp}_\n`);
 	const changed = results.filter((r) => r.action === "created" || r.action === "updated" || r.action === "archived");
 	if (changed.length > 0) {
 		const items = changed.map((r) => {
@@ -7111,11 +7681,451 @@ async function sendWebhookWithLogging(url, secret, payload) {
 	else log.warn(`Post-release hook failed: ${result.error ?? "unknown error"} (${context})`);
 }
 //#endregion
+//#region src/commands/webhook-send.ts
+const webhookSendCommand = defineCommand({
+	meta: {
+		name: "webhook:send",
+		description: "Send a POST request to a webhook URL with GitHub-style HMAC-SHA256 authentication"
+	},
+	args: {
+		url: {
+			type: "positional",
+			description: "Webhook URL to POST to. If empty or missing, the command exits successfully (no-op)."
+		},
+		tag: {
+			type: "string",
+			description: "Release tag name (e.g. v1.2.3). Falls back to GITHUB_REF env var."
+		},
+		repository: {
+			type: "string",
+			description: "Repository in owner/repo format. Falls back to GITHUB_REPOSITORY env var."
+		},
+		"server-url": {
+			type: "string",
+			description: "Server URL (e.g. https://github.com). Falls back to GITHUB_SERVER_URL env var."
+		},
+		actor: {
+			type: "string",
+			description: "User or bot that triggered the release. Falls back to GITHUB_ACTOR env var."
+		},
+		prerelease: {
+			type: "boolean",
+			description: "Mark the release as a prerelease"
+		}
+	},
+	async run({ args }) {
+		if (!args.url) {
+			log.info("No webhook URL configured — skipping post-release hook");
+			return;
+		}
+		const secret = process.env["WEBHOOK_SECRET"];
+		const payload = args.tag || args.repository ? buildSimplePayload({
+			tag: args.tag ?? "",
+			repository: args.repository ?? process.env["GITHUB_REPOSITORY"] ?? "",
+			serverUrl: args["server-url"] ?? process.env["GITHUB_SERVER_URL"] ?? "https://github.com",
+			actor: args.actor ?? process.env["GITHUB_ACTOR"] ?? "github-actions[bot]",
+			prerelease: args.prerelease ?? false
+		}) : buildPayloadFromEnv();
+		await sendWebhookWithLogging(args.url, secret || void 0, payload);
+	}
+});
+//#endregion
+//#region src/coverage-tracking/derive.ts
+function emptySums() {
+	return {
+		linesTotal: 0,
+		linesCovered: 0,
+		branchesTotal: 0,
+		branchesCovered: 0
+	};
+}
+function addEntry(sums, entry) {
+	sums.linesTotal += entry.lines.total;
+	sums.linesCovered += entry.lines.covered;
+	sums.branchesTotal += entry.branches.total;
+	sums.branchesCovered += entry.branches.covered;
+}
+function pct(covered, total) {
+	if (total === 0) return 0;
+	return Math.round(covered / total * 1e3) / 10;
+}
+function toPackageEntry(sums) {
+	return {
+		lines: pct(sums.linesCovered, sums.linesTotal),
+		branches: pct(sums.branchesCovered, sums.branchesTotal)
+	};
+}
+function totalsFrom(entry) {
+	return {
+		lines: entry.lines.pct,
+		statements: entry.statements.pct,
+		branches: entry.branches.pct,
+		functions: entry.functions.pct
+	};
+}
+/** Match `<rootDir>/packages/<name>/...` and capture `<name>`. Posix-style; tolerates `\` on win32. */
+function packageNameFromPath(filePath, rootDir) {
+	const normalized = filePath.split(path.sep).join("/");
+	const rootNormalized = rootDir.split(path.sep).join("/").replace(/\/+$/, "");
+	const rel = normalized.startsWith(`${rootNormalized}/`) ? normalized.slice(rootNormalized.length + 1) : normalized;
+	return /^packages\/([^/]+)\//.exec(rel)?.[1];
+}
+/** Build a trimmed coverage record (or baseline body) from a parsed v8 summary. */
+function deriveBaseline(summary, options) {
+	const totals = totalsFrom(summary.total);
+	const perPackage = /* @__PURE__ */ new Map();
+	const fallbackName = options.singlePackageName ?? path.basename(options.rootDir);
+	const fallbackSums = emptySums();
+	let sawAnyMonorepoPath = false;
+	for (const [filePath, entry] of Object.entries(summary)) {
+		if (filePath === "total") continue;
+		const pkgName = packageNameFromPath(filePath, options.rootDir);
+		if (pkgName) {
+			sawAnyMonorepoPath = true;
+			const sums = perPackage.get(pkgName) ?? emptySums();
+			addEntry(sums, entry);
+			perPackage.set(pkgName, sums);
+		} else addEntry(fallbackSums, entry);
+	}
+	const packages = {};
+	if (sawAnyMonorepoPath) for (const [name, sums] of perPackage) packages[name] = toPackageEntry(sums);
+	else if (fallbackSums.linesTotal > 0 || fallbackSums.branchesTotal > 0) packages[fallbackName] = toPackageEntry(fallbackSums);
+	return {
+		totals,
+		packages
+	};
+}
+/** Build a full record (with identity) from a parsed v8 summary. */
+function deriveRecord(summary, options) {
+	const baseline = deriveBaseline(summary, options);
+	return {
+		sha: options.identity.sha,
+		timestamp: options.identity.timestamp,
+		...baseline
+	};
+}
+//#endregion
+//#region src/coverage-tracking/executor.ts
+/** Real implementation of CoverageExecutor that shells out to git. */
+function createRealCoverageExecutor() {
+	return { exec(file, args, options) {
+		try {
+			return {
+				stdout: execFileSync(file, args, {
+					cwd: options?.cwd,
+					env: options?.env ? {
+						...process.env,
+						...options.env
+					} : void 0,
+					input: options?.input,
+					encoding: "utf-8",
+					stdio: [
+						"pipe",
+						"pipe",
+						"pipe"
+					]
+				}),
+				stderr: "",
+				exitCode: 0
+			};
+		} catch (err) {
+			if (isExecSyncError(err)) return {
+				stdout: err.stdout,
+				stderr: err.stderr,
+				exitCode: err.status
+			};
+			return {
+				stdout: "",
+				stderr: "",
+				exitCode: 1
+			};
+		}
+	} };
+}
+//#endregion
+//#region src/coverage-tracking/render.ts
+const PCT_WIDTH = 7;
+function pad(value, width) {
+	if (value.length >= width) return value;
+	return value + " ".repeat(width - value.length);
+}
+function padLeft(value, width) {
+	if (value.length >= width) return value;
+	return " ".repeat(width - value.length) + value;
+}
+function formatPct(n) {
+	return `${n.toFixed(1)}%`;
+}
+function formatDelta(n) {
+	if (n === 0) return "  0.00";
+	return `${n > 0 ? "+" : ""}${n.toFixed(2)}`;
+}
+/** Format a single record (or baseline) as a labeled, aligned block for `coverage:summary`. */
+function formatRecordSummary(body) {
+	const t = body.totals;
+	const totalsLine = `lines ${formatPct(t.lines)} | statements ${formatPct(t.statements)} | branches ${formatPct(t.branches)} | functions ${formatPct(t.functions)}`;
+	const lines = [body.sha ? `coverage @ ${body.sha.slice(0, 7)}` : "coverage", totalsLine];
+	const pkgs = Object.entries(body.packages);
+	if (pkgs.length > 0) {
+		const longest = Math.max(...pkgs.map(([name]) => name.length));
+		lines.push("by package:");
+		for (const [name, entry] of pkgs.toSorted(([a], [b]) => a.localeCompare(b))) lines.push(`  ${pad(name, longest)}  lines ${padLeft(formatPct(entry.lines), PCT_WIDTH)}  branches ${padLeft(formatPct(entry.branches), PCT_WIDTH)}`);
+	}
+	return lines.join("\n");
+}
+/** Format a CompareResult diff table for `coverage:check` failure output. */
+function formatCompareDiff(result) {
+	const lines = [];
+	lines.push(`coverage check ${result.pass ? "PASS" : "FAIL"} (tolerance ${result.tolerancePp.toFixed(2)}pp)`);
+	const longestKey = Math.max(...TOTAL_KEYS.map((k) => k.length));
+	for (const total of result.totals) {
+		const status = total.pass ? "✓" : "✗";
+		lines.push(`  ${status} ${pad(total.key, longestKey)}  baseline ${padLeft(formatPct(total.baseline), PCT_WIDTH)}  current ${padLeft(formatPct(total.current), PCT_WIDTH)}  Δ ${padLeft(formatDelta(total.delta), 7)}`);
+	}
+	return lines.join("\n");
+}
+/** Format a trend table for `coverage:status`. */
+function formatTrendTable(records) {
+	if (records.length === 0) return "no coverage history recorded yet";
+	const rows = records.map((r) => ({
+		sha: r.sha.slice(0, 7),
+		when: formatTimestamp(r.timestamp),
+		totals: r.totals
+	}));
+	const header = [
+		"sha",
+		"when",
+		"lines",
+		"statements",
+		"branches",
+		"functions",
+		"Δlines"
+	];
+	const widths = [
+		Math.max(header[0].length, ...rows.map((r) => r.sha.length)),
+		Math.max(header[1].length, ...rows.map((r) => r.when.length)),
+		PCT_WIDTH,
+		PCT_WIDTH,
+		PCT_WIDTH,
+		PCT_WIDTH,
+		7
+	];
+	const lines = [];
+	lines.push(joinRow(header, widths));
+	lines.push(joinRow(widths.map((w) => "-".repeat(w)), widths));
+	let prevLines;
+	for (const row of rows) {
+		const deltaLines = prevLines === void 0 ? "" : formatDelta(round2(row.totals.lines - prevLines));
+		lines.push(joinRow([
+			row.sha,
+			row.when,
+			formatPct(row.totals.lines),
+			formatPct(row.totals.statements),
+			formatPct(row.totals.branches),
+			formatPct(row.totals.functions),
+			deltaLines
+		], widths));
+		prevLines = row.totals.lines;
+	}
+	if (records.length >= 2) {
+		const first = records[0];
+		const last = records[records.length - 1];
+		if (first && last) {
+			const overall = round2(last.totals.lines - first.totals.lines);
+			lines.push("");
+			lines.push(`lines ${formatPct(last.totals.lines)} (${formatDelta(overall)} over last ${String(records.length)} records)`);
+		}
+	}
+	return lines.join("\n");
+}
+function round2(n) {
+	return Math.round(n * 100) / 100;
+}
+function joinRow(cells, widths) {
+	return cells.map((cell, i) => padLeft(cell, widths[i] ?? cell.length)).join("  ");
+}
+function formatTimestamp(iso) {
+	const date = new Date(iso);
+	if (Number.isNaN(date.getTime())) return iso;
+	return `${String(date.getUTCFullYear())}-${String(date.getUTCMonth() + 1).padStart(2, "0")}-${String(date.getUTCDate()).padStart(2, "0")}`;
+}
+//#endregion
+//#region src/commands/coverage-summary.ts
+const COVERAGE_SUMMARY_FILE$2 = "coverage/coverage-summary.json";
+const out$3 = (msg) => console.log(msg);
+function readSummary(targetDir) {
+	const summaryPath = path.join(targetDir, COVERAGE_SUMMARY_FILE$2);
+	if (!existsSync(summaryPath)) throw new FatalError(`${COVERAGE_SUMMARY_FILE$2} not found. Run \`pnpm test:coverage\` first, or add "json-summary" to your vitest reporters.`);
+	return readFileSync(summaryPath, "utf-8");
+}
+function getHeadSha(targetDir) {
+	const result = createRealCoverageExecutor().exec("git", ["rev-parse", "HEAD"], { cwd: targetDir });
+	if (result.exitCode !== 0) return "unknown";
+	return result.stdout.trim();
+}
+const coverageSummaryCommand = defineCommand({
+	meta: {
+		name: "coverage:summary",
+		description: "Print a human-readable summary of the latest coverage run"
+	},
+	args: {
+		dir: {
+			type: "positional",
+			description: "Project directory (default: current directory)",
+			required: false
+		},
+		json: {
+			type: "boolean",
+			description: "Emit the trimmed record as JSON on stdout (for downstream tooling)"
+		}
+	},
+	run({ args }) {
+		const targetDir = path.resolve(args.dir ?? ".");
+		const summary = parseV8Summary(readSummary(targetDir));
+		if (args.json === true) {
+			const record = deriveRecord(summary, {
+				rootDir: targetDir,
+				identity: {
+					sha: getHeadSha(targetDir),
+					timestamp: (/* @__PURE__ */ new Date()).toISOString()
+				}
+			});
+			out$3(JSON.stringify(record));
+			return;
+		}
+		out$3(formatRecordSummary({
+			...deriveBaseline(summary, { rootDir: targetDir }),
+			sha: getHeadSha(targetDir)
+		}));
+	}
+});
+//#endregion
+//#region src/coverage-tracking/baseline.ts
+/** Serialize a baseline to its JSON form (with trailing newline). Single source of truth for layout. */
+function serializeBaseline(baseline) {
+	return JSON.stringify(baseline, null, 2) + "\n";
+}
+//#endregion
+//#region src/commands/coverage-check.ts
+const COVERAGE_SUMMARY_FILE$1 = "coverage/coverage-summary.json";
+const BASELINE_FILE = "coverage-baseline.json";
+const out$2 = (msg) => console.log(msg);
+const coverageCheckCommand = defineCommand({
+	meta: {
+		name: "coverage:check",
+		description: "Compare the latest coverage run against coverage-baseline.json"
+	},
+	args: {
+		dir: {
+			type: "positional",
+			description: "Project directory (default: current directory)",
+			required: false
+		},
+		"update-baseline": {
+			type: "boolean",
+			description: "If all four totals are flat-or-up, rewrite coverage-baseline.json"
+		},
+		"no-fail-on-missing-baseline": {
+			type: "boolean",
+			description: "Treat absent baseline as a soft notice (used during bootstrap)"
+		},
+		json: {
+			type: "boolean",
+			description: "Emit machine-readable diff on stdout instead of the table"
+		}
+	},
+	run({ args }) {
+		const targetDir = path.resolve(args.dir ?? ".");
+		const summaryPath = path.join(targetDir, COVERAGE_SUMMARY_FILE$1);
+		const baselinePath = path.join(targetDir, BASELINE_FILE);
+		if (!existsSync(summaryPath)) throw new FatalError(`${COVERAGE_SUMMARY_FILE$1} not found. Run \`pnpm test:coverage\` first, or add "json-summary" to your vitest reporters.`);
+		const current = deriveBaseline(parseV8Summary(readFileSync(summaryPath, "utf-8")), { rootDir: targetDir });
+		if (!existsSync(baselinePath)) {
+			if (args["update-baseline"] === true) {
+				writeFileSync(baselinePath, serializeBaseline(current));
+				out$2(`Created ${BASELINE_FILE} (no prior baseline).`);
+				return;
+			}
+			const message = `${BASELINE_FILE} not found. Run with --update-baseline to create one from the current run.`;
+			if (args["no-fail-on-missing-baseline"] === true) {
+				out$2(message);
+				return;
+			}
+			throw new FatalError(message);
+		}
+		const baseline = parseBaseline(readFileSync(baselinePath, "utf-8"));
+		const config = resolveCoverageConfig(targetDir);
+		const result = compareTotals(baseline.totals, current.totals, config.tolerancePp);
+		if (args.json === true) out$2(JSON.stringify(result));
+		else out$2(formatCompareDiff(result));
+		if (args["update-baseline"] === true) if (isFlatOrUp(baseline.totals, current.totals)) {
+			writeFileSync(baselinePath, serializeBaseline(current));
+			out$2(`Updated ${BASELINE_FILE} (all four totals flat-or-up).`);
+		} else out$2(`Skipped baseline update: at least one total dropped below baseline. Add tests or adjust coverage.exclude before updating.`);
+		if (!result.pass) process.exitCode = 1;
+	}
+});
+//#endregion
+//#region src/commands/coverage-record.ts
+const COVERAGE_SUMMARY_FILE = "coverage/coverage-summary.json";
+const out$1 = (msg) => console.log(msg);
+const coverageRecordCommand = defineCommand({
+	meta: {
+		name: "coverage:record",
+		description: "Append the current coverage run to the orphan-branch history"
+	},
+	args: {
+		dir: {
+			type: "positional",
+			description: "Project directory (default: current directory)",
+			required: false
+		},
+		branch: {
+			type: "string",
+			description: "Override the orphan branch name (default: from .tooling.json or 'bst/coverage-metrics')"
+		}
+	},
+	run({ args }) {
+		const targetDir = path.resolve(args.dir ?? ".");
+		const config = resolveCoverageConfig(targetDir);
+		if (!config.historyEnabled) {
+			out$1("coverage history disabled (.tooling.json: coverage.history === 'none' or coverage === false). Skipping record.");
+			return;
+		}
+		const summaryPath = path.join(targetDir, COVERAGE_SUMMARY_FILE);
+		if (!existsSync(summaryPath)) throw new FatalError(`${COVERAGE_SUMMARY_FILE} not found. Run \`pnpm test:coverage\` before \`coverage:record\`.`);
+		const summary = parseV8Summary(readFileSync(summaryPath, "utf-8"));
+		const executor = createRealCoverageExecutor();
+		const headResult = executor.exec("git", ["rev-parse", "HEAD"], { cwd: targetDir });
+		if (headResult.exitCode !== 0) throw new FatalError(`Failed to resolve HEAD sha: ${headResult.stderr.trim()}`);
+		const sha = headResult.stdout.trim();
+		const record = deriveRecord(summary, {
+			rootDir: targetDir,
+			identity: {
+				sha,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			}
+		});
+		const branch = args.branch ?? config.historyBranch;
+		out$1(`Appending coverage record for ${sha.slice(0, 7)} to ${branch}...`);
+		const result = appendRecord(executor, {
+			cwd: targetDir,
+			historyBranch: branch,
+			authorName: "coverage-bot",
+			authorEmail: "coverage-bot@noreply.localhost"
+		}, record);
+		out$1(`${result.bootstrapped ? "Bootstrapped" : "Appended to"} ${branch}: commit ${result.commitSha.slice(0, 7)}${result.attempts > 1 ? ` (after ${String(result.attempts)} attempts)` : ""}.`);
+	}
+});
+//#endregion
+//#region src/commands/coverage-status.ts
+const out = (msg) => console.log(msg);
+//#endregion
 //#region src/bin.ts
 const main = defineCommand({
 	meta: {
 		name: "bst",
-		version: "0.55.2",
+		version: "0.57.0",
 		description: "Bootstrap and maintain standardized TypeScript project tooling"
 	},
 	subCommands: {
@@ -7135,56 +8145,59 @@ const main = defineCommand({
 		"setup:secrets": setupSecretsCommand,
 		"forgejo:secrets": forgejoSecretsCommand,
 		"forgejo:webhooks": forgejoWebhooksCommand,
-		"webhook:send": defineCommand({
+		"webhook:send": webhookSendCommand,
+		"coverage:summary": coverageSummaryCommand,
+		"coverage:check": coverageCheckCommand,
+		"coverage:record": coverageRecordCommand,
+		"coverage:status": defineCommand({
 			meta: {
-				name: "webhook:send",
-				description: "Send a POST request to a webhook URL with GitHub-style HMAC-SHA256 authentication"
+				name: "coverage:status",
+				description: "Show recent coverage history (read-only; fetches from the orphan branch)"
 			},
 			args: {
-				url: {
+				dir: {
 					type: "positional",
-					description: "Webhook URL to POST to. If empty or missing, the command exits successfully (no-op)."
-				},
-				tag: {
-					type: "string",
-					description: "Release tag name (e.g. v1.2.3). Falls back to GITHUB_REF env var."
-				},
-				repository: {
-					type: "string",
-					description: "Repository in owner/repo format. Falls back to GITHUB_REPOSITORY env var."
+					description: "Project directory (default: current directory)",
+					required: false
 				},
-				"server-url": {
+				limit: {
 					type: "string",
-					description: "Server URL (e.g. https://github.com). Falls back to GITHUB_SERVER_URL env var."
+					description: "Number of trailing records to render (default: 10)"
 				},
-				actor: {
+				branch: {
 					type: "string",
-					description: "User or bot that triggered the release. Falls back to GITHUB_ACTOR env var."
+					description: "Override the orphan branch name (default: from .tooling.json or 'bst/coverage-metrics')"
 				},
-				prerelease: {
+				json: {
 					type: "boolean",
-					description: "Mark the release as a prerelease"
+					description: "Emit the parsed records as JSON instead of the table"
 				}
 			},
-			async run({ args }) {
-				if (!args.url) {
-					log.info("No webhook URL configured — skipping post-release hook");
+			run({ args }) {
+				const targetDir = path.resolve(args.dir ?? ".");
+				const config = resolveCoverageConfig(targetDir);
+				const branch = args.branch ?? config.historyBranch;
+				const limit = args.limit ? Math.max(1, Number.parseInt(args.limit, 10) || 10) : 10;
+				const records = readRecords(createRealCoverageExecutor(), {
+					cwd: targetDir,
+					historyBranch: branch
+				});
+				if (records.length === 0) {
+					if (args.json === true) out("[]");
+					else out(`no coverage history recorded yet (branch: ${branch})`);
+					return;
+				}
+				const trailing = records.slice(-limit);
+				if (args.json === true) {
+					out(JSON.stringify(trailing));
 					return;
 				}
-				const secret = process.env["WEBHOOK_SECRET"];
-				const payload = args.tag || args.repository ? buildSimplePayload({
-					tag: args.tag ?? "",
-					repository: args.repository ?? process.env["GITHUB_REPOSITORY"] ?? "",
-					serverUrl: args["server-url"] ?? process.env["GITHUB_SERVER_URL"] ?? "https://github.com",
-					actor: args.actor ?? process.env["GITHUB_ACTOR"] ?? "github-actions[bot]",
-					prerelease: args.prerelease ?? false
-				}) : buildPayloadFromEnv();
-				await sendWebhookWithLogging(args.url, secret || void 0, payload);
+				out(formatTrendTable(trailing));
 			}
 		})
 	}
 });
-console.log(`@bensandee/tooling v0.55.2`);
+console.log(`@bensandee/tooling v0.57.0`);
 async function run() {
 	await runMain(main);
 	process.exit(process.exitCode ?? 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bensandee/tooling",
-  "version": "0.55.2",
+  "version": "0.57.0",
   "description": "CLI tool to bootstrap and maintain standardized TypeScript project tooling",
   "license": "MIT",
   "repository": {

package/tooling.schema.json

@@ -225,6 +225,39 @@
       "items": {
         "type": "string"
       }
+    },
+    "coverage": {
+      "description": "Coverage tracking configuration. Set to false to disable; omit for default-on (when a vitest config is present).",
+      "anyOf": [
+        {
+          "type": "boolean",
+          "const": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "history": {
+              "description": "How coverage history is persisted. 'orphan-branch' (default) appends to a dedicated branch; 'none' disables CI history but keeps the local ratchet.",
+              "type": "string",
+              "enum": ["orphan-branch", "none"]
+            },
+            "historyBranch": {
+              "description": "Orphan branch name for coverage history (default: 'bst/coverage-metrics')",
+              "type": "string"
+            },
+            "tolerancePp": {
+              "description": "Tolerance in percentage points for baseline comparison (default: 0.1)",
+              "type": "number",
+              "minimum": 0
+            },
+            "gateOnPullRequests": {
+              "description": "Run coverage on PR builds too (default: false; deferred follow-up)",
+              "type": "boolean"
+            }
+          },
+          "additionalProperties": false
+        }
+      ]
     }
   },
   "additionalProperties": false