@decohere/ci-tools 0.0.1-dev.10

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@decohere/ci-tools",
+  "version": "0.0.1-dev.10",
+  "description": "CI utility scripts for badge generation, coverage reporting, pages artifact assembly, and GitHub API tooling",
+  "keywords": [
+    "typescript",
+    "ci",
+    "badges",
+    "coverage",
+    "github-actions",
+    "decohere"
+  ],
+  "license": "ISC",
+  "author": "Typesmiths",
+  "type": "module",
+  "exports": {
+    "./lib/svg": "./src/lib/svg.mjs",
+    "./lib/lcov": "./src/lib/lcov.mjs",
+    "./coverage/badge": "./src/coverage/badge.mjs",
+    "./coverage/report": "./src/coverage/report.mjs",
+    "./coverage/enforce-thresholds": "./src/coverage/enforce-thresholds.mjs",
+    "./badges/ci-status": "./src/badges/ci-status.mjs",
+    "./pages/artifact": "./src/pages/artifact.mjs",
+    "./pages/smoke": "./src/pages/smoke.mjs",
+    "./audit/summarize": "./src/audit/summarize.mjs",
+    "./audit/enforce": "./src/audit/enforce.mjs",
+    "./audit/upsert-issue": "./src/audit/upsert-issue.mjs",
+    "./bench/bench": "./src/bench/bench.mjs",
+    "./bench/trace": "./src/bench/trace.mjs",
+    "./changeset/aggregate-changelog": "./src/changeset/aggregate-changelog.mjs",
+    "./changeset/check-status": "./src/changeset/check-status.mjs",
+    "./github/create-issue": "./src/github/create-issue.mjs",
+    "./github/ensure-metadata": "./src/github/ensure-metadata.mjs",
+    "./github/create-or-update-pr": "./src/github/create-or-update-pr.mjs"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "dependencies": {},
+  "devDependencies": {}
+}

package/src/audit/enforce.mjs

@@ -0,0 +1,22 @@
+import { readFileSync } from "node:fs";
+
+const auditFilePath = process.argv[2] ?? "npm-audit.json";
+
+let data = null;
+try {
+	data = JSON.parse(readFileSync(auditFilePath, "utf8"));
+} catch {
+	console.error(`Security gate failed: could not parse ${auditFilePath}.`);
+	process.exit(1);
+}
+
+const vulnerabilities = data.metadata?.vulnerabilities ?? {};
+const high = vulnerabilities.high ?? 0;
+const critical = vulnerabilities.critical ?? 0;
+
+if (high > 0 || critical > 0) {
+	console.error(`Security gate failed: high=${high}, critical=${critical}`);
+	process.exit(1);
+}
+
+console.log("Security gate passed: no high/critical vulnerabilities found.");

package/src/audit/summarize.mjs

@@ -0,0 +1,46 @@
+import { appendFileSync, readFileSync } from "node:fs";
+
+const auditFilePath = process.argv[2] ?? "npm-audit.json";
+
+function writeSummary(lines) {
+	const summaryText = `${lines.join("\n")}\n`;
+	if (process.env.GITHUB_STEP_SUMMARY) {
+		appendFileSync(process.env.GITHUB_STEP_SUMMARY, summaryText);
+		return;
+	}
+	process.stdout.write(summaryText);
+}
+
+let data = null;
+try {
+	data = JSON.parse(readFileSync(auditFilePath, "utf8"));
+} catch {
+	writeSummary([
+		"## Security Audit",
+		"",
+		"- npm audit output could not be parsed.",
+		`- See uploaded \`${auditFilePath}\` artifact for raw output.`,
+	]);
+	process.exit(0);
+}
+
+const vulnerabilities = data.metadata?.vulnerabilities ?? {};
+const info = vulnerabilities.info ?? 0;
+const low = vulnerabilities.low ?? 0;
+const moderate = vulnerabilities.moderate ?? 0;
+const high = vulnerabilities.high ?? 0;
+const critical = vulnerabilities.critical ?? 0;
+const total = vulnerabilities.total ?? info + low + moderate + high + critical;
+
+writeSummary([
+	"## Security Audit",
+	"",
+	`| Severity  | Count |`,
+	`|-----------|-------|`,
+	`| Critical  | ${critical} |`,
+	`| High      | ${high} |`,
+	`| Moderate  | ${moderate} |`,
+	`| Low       | ${low} |`,
+	`| Info      | ${info} |`,
+	`| **Total** | **${total}** |`,
+]);

package/src/audit/upsert-issue.mjs

@@ -0,0 +1,90 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const auditFilePath = process.argv[2] ?? "npm-audit.json";
+const ISSUE_TITLE = "security(ci): npm audit vulnerabilities detected";
+
+function runGh(args) {
+	const result = spawnSync("gh", args, { encoding: "utf8", env: process.env });
+	if (result.status !== 0) {
+		throw new Error(result.stderr || result.stdout || `gh command failed: ${args.join(" ")}`);
+	}
+	return result.stdout;
+}
+
+function readAuditSummary(filePath) {
+	const data = JSON.parse(readFileSync(filePath, "utf8"));
+	const vulnerabilities = data.metadata?.vulnerabilities ?? {};
+	const info = vulnerabilities.info ?? 0;
+	const low = vulnerabilities.low ?? 0;
+	const moderate = vulnerabilities.moderate ?? 0;
+	const high = vulnerabilities.high ?? 0;
+	const critical = vulnerabilities.critical ?? 0;
+	const total = vulnerabilities.total ?? info + low + moderate + high + critical;
+	return { total, critical, high, moderate, low, info };
+}
+
+function buildBody(summary) {
+	const runUrl =
+		process.env.GITHUB_SERVER_URL && process.env.GITHUB_REPOSITORY && process.env.GITHUB_RUN_ID
+			? `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}`
+			: "(run URL unavailable)";
+	const sha = process.env.GITHUB_SHA ? process.env.GITHUB_SHA.slice(0, 12) : "unknown";
+
+	return [
+		"## npm audit detected vulnerabilities",
+		"",
+		`- Total: ${summary.total}`,
+		`- Critical: ${summary.critical}`,
+		`- High: ${summary.high}`,
+		`- Moderate: ${summary.moderate}`,
+		`- Low: ${summary.low}`,
+		`- Info: ${summary.info}`,
+		"",
+		`- Commit: ${sha}`,
+		`- Workflow run: ${runUrl}`,
+		"",
+		"This issue is managed by CI and will be updated on subsequent main-branch runs while vulnerabilities remain.",
+	].join("\n");
+}
+
+function findExistingIssueNumber() {
+	const output = runGh([
+		"issue",
+		"list",
+		"--state",
+		"open",
+		"--limit",
+		"200",
+		"--json",
+		"number,title",
+	]);
+	const issues = JSON.parse(output);
+	return issues.find((issue) => issue.title === ISSUE_TITLE)?.number ?? null;
+}
+
+if (!existsSync(auditFilePath)) {
+	console.log(`No audit file found at ${auditFilePath}; skipping issue update.`);
+	process.exit(0);
+}
+
+const summary = readAuditSummary(auditFilePath);
+if (summary.total === 0) {
+	console.log("No vulnerabilities found; skipping issue create/update.");
+	process.exit(0);
+}
+
+const body = buildBody(summary);
+const tempFile = path.join(os.tmpdir(), `npm-audit-issue-${Date.now()}.md`);
+writeFileSync(tempFile, body, "utf8");
+
+const existingIssueNumber = findExistingIssueNumber();
+if (existingIssueNumber) {
+	runGh(["issue", "comment", String(existingIssueNumber), "--body-file", tempFile]);
+	console.log(`Updated existing issue #${existingIssueNumber}.`);
+} else {
+	runGh(["issue", "create", "--title", ISSUE_TITLE, "--body-file", tempFile]);
+	console.log("Created new npm audit tracking issue.");
+}

package/src/badges/ci-status.mjs

@@ -0,0 +1,52 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { createBadgeSvg, statusToColor, statusToText } from "../lib/svg.mjs";
+
+const repo = process.env.GITHUB_REPOSITORY;
+const token = process.env.GITHUB_TOKEN;
+const outputDir =
+	process.env.CI_BADGE_OUTPUT_DIR ?? path.join("projects", "ci-tools", "dist", "ci", "badges");
+
+if (repo == null || token == null) {
+	throw new Error("GITHUB_REPOSITORY and GITHUB_TOKEN are required");
+}
+
+const workflowFileName = "ci.yml";
+
+const branches = [
+	{ branch: "main", label: "CI Main", file: "ci-main.svg" },
+	{ branch: "release", label: "CI Release", file: "ci-release.svg" },
+];
+
+async function getLatestWorkflowRun(branch) {
+	const url =
+		`https://api.github.com/repos/${repo}/actions/workflows/${workflowFileName}/runs` +
+		`?branch=${branch}&event=push&status=completed&per_page=1`;
+	const response = await fetch(url, {
+		headers: {
+			Authorization: `Bearer ${token}`,
+			Accept: "application/vnd.github+json",
+		},
+	});
+
+	if (!response.ok) {
+		process.stderr.write(
+			`Warning: Failed to fetch workflow runs for ${branch}: ${response.status}. Using unknown badge status.\n`,
+		);
+		return null;
+	}
+
+	const data = await response.json();
+	return data.workflow_runs?.[0] ?? null;
+}
+
+await mkdir(outputDir, { recursive: true });
+
+for (const item of branches) {
+	const latestRun = await getLatestWorkflowRun(item.branch);
+	const status = latestRun?.status ?? "completed";
+	const conclusion = latestRun?.conclusion ?? "unknown";
+	const value = statusToText(status, conclusion);
+	const color = statusToColor(status, conclusion);
+	await writeFile(path.join(outputDir, item.file), createBadgeSvg(item.label, value, color));
+}

package/src/bench/bench.mjs

@@ -0,0 +1,411 @@
+#!/usr/bin/env node
+
+/**
+ * bench.mjs — run the forge benchmark and compare against the last saved baseline.
+ *
+ * Usage:
+ *   node bench.mjs              — run and compare, do not save
+ *   node bench.mjs save         — run, compare, and save as the new baseline
+ *   node bench.mjs report       — run and compare, do not save
+ *   BENCH_ITERATIONS=3 node bench.mjs
+ *
+ * Context ID
+ * ----------
+ * 16-char SHA-256 prefix of: platform|arch|cpu|cores|memGB|node
+ * Ensures history is always compared like-for-like across machines.
+ */
+
+import { spawnSync } from "node:child_process";
+import crypto from "node:crypto";
+import {
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import os from "node:os";
+import { join } from "node:path";
+
+const WORKSPACE_ROOT = process.cwd();
+const HISTORY_FILE = join(
+	WORKSPACE_ROOT,
+	"projects/ci-tools/dist/ci/bench/bench-history.json",
+);
+const VITEST_BIN = join(WORKSPACE_ROOT, "node_modules/.bin/vitest");
+const BENCH_FILE = "projects/terminal/e2e/build.benchmark.bench.ts";
+const CONFIG = join(WORKSPACE_ROOT, "vitest.e2e.config.ts");
+const TRACE_LOG_DIR = join(WORKSPACE_ROOT, ".decohere", "logs");
+const MAX_RUNS = 10;
+const command = process.argv[2] ?? "run";
+
+// ── Context ───────────────────────────────────────────────────────────────────
+
+function getContext() {
+	const cpus = os.cpus();
+	const nodeMajor = process.version.match(/^v(\d+)/)?.[1] ?? "?";
+	const rawEnv = process.env.BENCH_ENV ?? null;
+	return {
+		benchEnv: rawEnv ? `${rawEnv}-node${nodeMajor}` : "(local)",
+		date: new Date().toISOString(),
+		os: { platform: os.platform(), arch: os.arch() },
+		cpu: { model: cpus[0]?.model?.trim() ?? "unknown", count: cpus.length },
+		memoryGb: parseFloat((os.totalmem() / 1024 ** 3).toFixed(1)),
+		node: process.version,
+	};
+}
+
+function contextId(ctx) {
+	const key = [
+		ctx.os.platform,
+		ctx.os.arch,
+		ctx.cpu.model,
+		ctx.cpu.count,
+		ctx.memoryGb,
+		ctx.node,
+	].join("|");
+	return crypto.createHash("sha256").update(key).digest("hex").slice(0, 16);
+}
+
+function truthy(value, defaultValue = false) {
+	if (value == null) return defaultValue;
+	return !["0", "false", "no", "off"].includes(String(value).toLowerCase());
+}
+
+function toFileTimestamp(date = new Date()) {
+	const pad = (n) => String(n).padStart(2, "0");
+	return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
+}
+
+function toTraceSample(line, parsed, durationMs) {
+	return {
+		time: parsed.time,
+		name: parsed.name,
+		message: parsed.msg,
+		durationMs,
+		line,
+	};
+}
+
+function parseTraceSamples(rawOutput) {
+	const samples = [];
+	for (const rawLine of rawOutput.split(/\r?\n/)) {
+		const line = rawLine.trim();
+		if (!line.startsWith("{")) continue;
+
+		let parsed;
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			continue;
+		}
+
+		if (typeof parsed?.name !== "string" || typeof parsed?.msg !== "string") continue;
+		const match = parsed.msg.match(/^(.*):\s+([0-9]+(?:\.[0-9]+)?)ms$/);
+		if (match == null) continue;
+
+		const durationMs = Number(match[2]);
+		if (!Number.isFinite(durationMs)) continue;
+
+		samples.push({
+			className: parsed.name,
+			methodLabel: match[1],
+			methodName: match[1].split("(")[0],
+			durationMs,
+			sample: toTraceSample(rawLine, parsed, durationMs),
+		});
+	}
+	return samples;
+}
+
+function aggregateSamples(samples, keyBuilder) {
+	const aggregates = new Map();
+	for (const sample of samples) {
+		const key = keyBuilder(sample);
+		const current = aggregates.get(key) ?? {
+			key,
+			hitCount: 0,
+			totalMs: 0,
+			maxMs: 0,
+		};
+		current.hitCount += 1;
+		current.totalMs += sample.durationMs;
+		if (sample.durationMs > current.maxMs) current.maxMs = sample.durationMs;
+		aggregates.set(key, current);
+	}
+	return [...aggregates.values()];
+}
+
+function analyzeTraceOutput(rawOutput) {
+	const samples = parseTraceSamples(rawOutput);
+	if (samples.length === 0) {
+		process.stderr.write("\n⚠  No structured trace samples found to analyze.\n");
+		return;
+	}
+
+	const byMethod = aggregateSamples(
+		samples,
+		(sample) => `${sample.className}.${sample.methodName}`,
+	);
+	const byClass = aggregateSamples(samples, (sample) => sample.className);
+	const byHits = [...byMethod].sort((a, b) => b.hitCount - a.hitCount).slice(0, 10);
+	const byTotal = [...byMethod].sort((a, b) => b.totalMs - a.totalMs).slice(0, 10);
+	const byMax = [...byMethod].sort((a, b) => b.maxMs - a.maxMs).slice(0, 10);
+	const byClassTotal = [...byClass].sort((a, b) => b.totalMs - a.totalMs).slice(0, 5);
+	const totalTraceMs = samples.reduce((sum, sample) => sum + sample.durationMs, 0);
+	const hottest = [...samples].sort((a, b) => b.durationMs - a.durationMs).slice(0, 5);
+
+	process.stderr.write(
+		"\n┌─ Trace Analysis ─────────────────────────────────────────────────────────\n",
+	);
+	process.stderr.write(`│  Samples      : ${samples.length}\n`);
+	process.stderr.write(`│  Unique funcs : ${byMethod.length}\n`);
+	process.stderr.write(`│  Total traced : ${totalTraceMs.toFixed(2)}ms\n`);
+	process.stderr.write(`│  Avg sample   : ${(totalTraceMs / samples.length).toFixed(3)}ms\n`);
+	process.stderr.write(
+		"└──────────────────────────────────────────────────────────────────────────\n",
+	);
+
+	const printTable = (title, rows, valueFormatter) => {
+		process.stderr.write(`\n${title}\n`);
+		for (const row of rows) {
+			process.stderr.write(
+				`  ${valueFormatter(row).padStart(10)}  ${row.key}  (hits=${row.hitCount}, max=${row.maxMs.toFixed(2)}ms)\n`,
+			);
+		}
+	};
+
+	printTable("Top Functions By Hit Count", byHits, (row) => String(row.hitCount));
+	printTable("Top Functions By Total Time", byTotal, (row) => `${row.totalMs.toFixed(2)}ms`);
+	printTable(
+		"Top Functions By Worst Single Call",
+		byMax,
+		(row) => `${row.maxMs.toFixed(2)}ms`,
+	);
+	printTable(
+		"Top Classes By Total Trace Time",
+		byClassTotal,
+		(row) => `${row.totalMs.toFixed(2)}ms`,
+	);
+
+	process.stderr.write("\nSlowest Individual Samples\n");
+	for (const hot of hottest) {
+		process.stderr.write(
+			`  ${hot.durationMs.toFixed(2).padStart(10)}ms  ${hot.className}.${hot.methodLabel}\n`,
+		);
+	}
+}
+
+function getBenchmarks(vitestOutput) {
+	return vitestOutput.files
+		.flatMap((file) => file.groups)
+		.flatMap((group) => group.benchmarks);
+}
+
+function printBenchmarkComparison(currentRun, previousRun) {
+	if (previousRun == null) {
+		process.stderr.write("No previous saved run for this context; skipping comparison.\n");
+		return;
+	}
+
+	const currentBenchmarks = getBenchmarks(currentRun.vitestOutput);
+	const previousByName = new Map(
+		getBenchmarks(previousRun.vitestOutput).map((benchmark) => [benchmark.name, benchmark]),
+	);
+
+	process.stderr.write("Current Run vs Previous\n");
+	process.stderr.write(`  current : ${currentRun.date}\n`);
+	process.stderr.write(`  previous: ${previousRun.date}\n`);
+	process.stderr.write("\n");
+
+	const rows = currentBenchmarks.map((benchmark) => {
+		const previous = previousByName.get(benchmark.name);
+		if (previous == null) {
+			return {
+				name: benchmark.name,
+				current: `${benchmark.mean.toFixed(2)}ms`,
+				previous: "n/a",
+				delta: "n/a",
+				change: "n/a",
+			};
+		}
+
+		const delta = benchmark.mean - previous.mean;
+		const pct = previous.mean === 0 ? 0 : (delta / previous.mean) * 100;
+		const deltaSign = delta >= 0 ? "+" : "";
+		return {
+			name: benchmark.name,
+			current: `${benchmark.mean.toFixed(2)}ms`,
+			previous: `${previous.mean.toFixed(2)}ms`,
+			delta: `${deltaSign}${delta.toFixed(2)}ms`,
+			change: `${deltaSign}${pct.toFixed(2)}%`,
+		};
+	});
+
+	const headers = {
+		name: "Benchmark",
+		current: "Current",
+		previous: "Previous",
+		delta: "Delta",
+		change: "%",
+	};
+
+	const widths = {
+		name: Math.max(headers.name.length, ...rows.map((row) => row.name.length)),
+		current: Math.max(headers.current.length, ...rows.map((row) => row.current.length)),
+		previous: Math.max(headers.previous.length, ...rows.map((row) => row.previous.length)),
+		delta: Math.max(headers.delta.length, ...rows.map((row) => row.delta.length)),
+		change: Math.max(headers.change.length, ...rows.map((row) => row.change.length)),
+	};
+
+	const divider = [
+		"-".repeat(widths.name),
+		"-".repeat(widths.current),
+		"-".repeat(widths.previous),
+		"-".repeat(widths.delta),
+		"-".repeat(widths.change),
+	].join("-+-");
+
+	const formatRow = (row) =>
+		[
+			row.name.padEnd(widths.name),
+			row.current.padStart(widths.current),
+			row.previous.padStart(widths.previous),
+			row.delta.padStart(widths.delta),
+			row.change.padStart(widths.change),
+		].join(" | ");
+
+	process.stderr.write(`${formatRow(headers)}\n`);
+	process.stderr.write(`${divider}\n`);
+	for (const row of rows) {
+		process.stderr.write(`${formatRow(row)}\n`);
+	}
+
+	process.stderr.write("\n");
+}
+
+// ── Run ───────────────────────────────────────────────────────────────────────
+
+const ctx = getContext();
+const id = contextId(ctx);
+const iterations = process.env.BENCH_ITERATIONS ?? "5";
+const traceEnabled = process.env.FORGE_TRACE != null;
+const shouldSave = truthy(process.env.BENCH_SAVE, command === "save");
+const shouldAnalyzeTrace = traceEnabled && truthy(process.env.BENCH_ANALYZE_TRACE, true);
+const shouldCollectTraceLog = traceEnabled && truthy(process.env.BENCH_TRACE_LOG, true);
+const traceLogPath = shouldCollectTraceLog
+	? join(TRACE_LOG_DIR, `perf-trace-${toFileTimestamp()}.log`)
+	: null;
+
+if (traceLogPath != null) {
+	mkdirSync(TRACE_LOG_DIR, { recursive: true });
+}
+
+process.stderr.write(
+	[
+		"\n┌─ Benchmark Environment ─────────────────────────────────────────────────",
+		`│  Context ID : ${id}`,
+		`│  BENCH_ENV  : ${ctx.benchEnv}`,
+		`│  Date       : ${ctx.date}`,
+		`│  OS         : ${ctx.os.platform} ${ctx.os.arch}`,
+		`│  CPU        : ${ctx.cpu.model} × ${ctx.cpu.count}`,
+		`│  Memory     : ${ctx.memoryGb} GB`,
+		`│  Node       : ${ctx.node}`,
+		"└──────────────────────────────────────────────────────────────────────────\n\n",
+	].join("\n"),
+);
+
+if (traceEnabled) {
+	process.stderr.write("Trace mode enabled with structured pino logs for analysis.\n\n");
+}
+
+const tmpDir = mkdtempSync(`${os.tmpdir()}/ark-bench-`);
+const outJson = join(tmpDir, "output.json");
+
+try {
+	const result = spawnSync(
+		VITEST_BIN,
+		["bench", "--config", CONFIG, "--run", "--outputJson", outJson, BENCH_FILE],
+		{
+			cwd: WORKSPACE_ROOT,
+			stdio: traceEnabled ? "pipe" : "inherit",
+			encoding: traceEnabled ? "utf8" : undefined,
+			maxBuffer: 1024 * 1024 * 200,
+			env: {
+				...process.env,
+				NODE_OPTIONS: "",
+				BENCH_ITERATIONS: iterations,
+				...(traceEnabled
+					? { FORGE_TRACE_STRUCTURED: "1", LOG_LEVEL: process.env.LOG_LEVEL ?? "trace" }
+					: {}),
+			},
+		},
+	);
+
+	if (traceEnabled) {
+		const stdout = typeof result.stdout === "string" ? result.stdout : "";
+		const stderr = typeof result.stderr === "string" ? result.stderr : "";
+		if (stdout.length > 0) process.stdout.write(stdout);
+		if (stderr.length > 0) process.stderr.write(stderr);
+
+		const combined = `${stdout}${stderr.length > 0 ? `\n${stderr}` : ""}`;
+		if (traceLogPath != null) {
+			writeFileSync(traceLogPath, combined);
+			process.stderr.write(`\n✓  Trace log written: ${traceLogPath}\n`);
+		}
+
+		if (shouldAnalyzeTrace) {
+			analyzeTraceOutput(combined);
+		}
+	}
+
+	if (result.status !== 0) process.exit(result.status ?? 1);
+
+	if (!existsSync(outJson)) {
+		process.stderr.write("✗  No output JSON — bench may have errored internally.\n");
+		process.exit(1);
+	}
+
+	const output = JSON.parse(readFileSync(outJson, "utf8"));
+	const benches = output.files.flatMap((f) => f.groups).flatMap((g) => g.benchmarks);
+	const currentRun = { date: ctx.date, context: ctx, vitestOutput: output };
+
+	// Fail loud on NaN — vitest swallows errors in bench callbacks silently
+	const invalid = benches.filter((b) => !Number.isFinite(b.mean) || !b.sampleCount);
+	if (invalid.length > 0) {
+		process.stderr.write(
+			`✗  ${invalid.length} benchmark(s) have NaN results — check for errors in the bench callback:\n` +
+				invalid.map((b) => `   • ${b.name}`).join("\n") +
+				"\n",
+		);
+		process.exit(1);
+	}
+
+	// ── Save ──────────────────────────────────────────────────────────────────
+
+	const history = existsSync(HISTORY_FILE)
+		? JSON.parse(readFileSync(HISTORY_FILE, "utf8"))
+		: { runs: {} };
+
+	if (!history.runs[id]) history.runs[id] = { context: ctx, runs: [] };
+	const previousRun = history.runs[id].runs[0];
+
+	printBenchmarkComparison(currentRun, previousRun);
+
+	if (!shouldSave) {
+		process.stderr.write(`✓  Not saved  (mode: ${command}, baseline unchanged)\n\n`);
+		process.exit(0);
+	}
+
+	history.runs[id].context = ctx;
+	history.runs[id].runs.unshift(currentRun);
+	if (history.runs[id].runs.length > MAX_RUNS) history.runs[id].runs.length = MAX_RUNS;
+
+	writeFileSync(HISTORY_FILE, JSON.stringify(history, null, 2));
+
+	const stored = history.runs[id].runs.length;
+	process.stderr.write(`\n✓  Saved  (context: ${id}, runs stored: ${stored}/${MAX_RUNS})\n\n`);
+} finally {
+	rmSync(tmpDir, { recursive: true, force: true });
+}