@pareto4/pp-core 1.11.0 → 1.12.0

package/scripts/dev-env.cjs

@@ -0,0 +1,462 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * dev-env.cjs — keep a stable pp-core install and a development build apart.
+ *
+ *   stable [<tag>] [--dir <dir>] [--runtime <id>]  worktree on the latest release tag, installed --global
+ *   dev-setup [--config-dir <dir>] [--no-shell] npm ci, install the dev profile, put claude-dev on PATH
+ *   install [--config-dir <dir>] [--no-build]   build, install into a separate Claude profile
+ *   install --local [<dir>] [--no-build]        build, install into a sandbox project
+ *   claude [--config-dir <dir>] [-- <args>]     start the Claude CLI on the dev profile
+ *
+ * Defaults: the worktree is pp-core-stable next to the main checkout; the profile is
+ * PP_DEV_CONFIG_DIR, else ~/.claude-dev; the sandbox is ../pp-sandbox.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync, spawnSync } = require('node:child_process');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const ROOT = path.resolve(__dirname, '..');
+const INSTALLER = path.join(ROOT, 'bin', 'install.js');
+
+const USAGE = [
+  'Usage:',
+  '  npm run setup [-- [<tag>] [--dir <dir>] [--runtime <id>]]',
+  '  npm run dev:setup [-- [--config-dir <dir>] [--no-shell]]',
+  '  npm run dev:install [-- [--config-dir <dir>] [--no-build]]',
+  '  npm run dev:install -- --local [<dir>] [--no-build]',
+  '  npm run dev:claude [-- <claude args>]',
+].join('\n');
+
+function parseStableArgs(rest) {
+  const opts = { command: 'stable', tag: null, dir: null, runtime: 'claude' };
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === '--dir') {
+      const value = rest[++i];
+      if (!value) return { error: '--dir requires a path' };
+      opts.dir = value;
+    } else if (arg === '--runtime') {
+      const value = rest[++i];
+      if (!value) return { error: '--runtime requires a runtime id' };
+      opts.runtime = value;
+    } else if (!arg.startsWith('-') && opts.tag === null) {
+      opts.tag = arg;
+    } else {
+      return { error: `unknown option: ${arg}` };
+    }
+  }
+  return opts;
+}
+
+function parseDevSetupArgs(rest) {
+  const opts = { command: 'dev-setup', configDir: null, shell: true };
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === '--config-dir') {
+      const value = rest[++i];
+      if (!value) return { error: '--config-dir requires a path' };
+      opts.configDir = value;
+    } else if (arg === '--no-shell') {
+      opts.shell = false;
+    } else {
+      return { error: `unknown option: ${arg}` };
+    }
+  }
+  return opts;
+}
+
+function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  if (command === 'stable') return parseStableArgs(rest);
+  if (command === 'dev-setup') return parseDevSetupArgs(rest);
+  if (command !== 'install' && command !== 'claude') {
+    return { error: `unknown command: ${command === undefined ? '(none)' : command}` };
+  }
+  const opts = { command, configDir: null, local: false, localDir: null, build: true, passthrough: [] };
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === '--') {
+      opts.passthrough = rest.slice(i + 1);
+      break;
+    }
+    if (arg === '--config-dir') {
+      const value = rest[++i];
+      if (!value) return { error: '--config-dir requires a path' };
+      opts.configDir = value;
+    } else if (command === 'install' && arg === '--local') {
+      opts.local = true;
+      if (rest[i + 1] && !rest[i + 1].startsWith('-')) opts.localDir = rest[++i];
+    } else if (command === 'install' && arg === '--no-build') {
+      opts.build = false;
+    } else if (command === 'claude') {
+      opts.passthrough = rest.slice(i);
+      break;
+    } else {
+      return { error: `unknown option: ${arg}` };
+    }
+  }
+  if (opts.local && opts.configDir) return { error: '--local and --config-dir cannot be combined' };
+  return opts;
+}
+
+// Real path of the longest existing prefix: Windows 8.3 short names and symlinks compare equal to what git prints.
+function canonicalPath(p) {
+  const resolved = path.resolve(p);
+  try {
+    return fs.realpathSync.native(resolved);
+  } catch {
+    const parent = path.dirname(resolved);
+    return parent === resolved ? resolved : path.join(canonicalPath(parent), path.basename(resolved));
+  }
+}
+
+function samePath(a, b) {
+  const norm = (p) => (process.platform === 'win32' ? canonicalPath(p).toLowerCase() : canonicalPath(p));
+  return norm(a) === norm(b);
+}
+
+function isInside(child, parent) {
+  const rel = path.relative(path.resolve(parent), path.resolve(child));
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+function resolveConfigDir(opts, env = process.env, home = os.homedir()) {
+  return path.resolve(opts.configDir || env.PP_DEV_CONFIG_DIR || path.join(home, '.claude-dev'));
+}
+
+function resolveLocalDir(opts, root = ROOT) {
+  return path.resolve(opts.localDir || path.join(root, '..', 'pp-sandbox'));
+}
+
+// The stable profile is ~/.claude; overwriting it with a dev build is what this script exists to avoid.
+function assertNotStableProfile(dir, home = os.homedir()) {
+  if (samePath(dir, path.join(home, '.claude'))) {
+    throw new ExitError(1, `Refusing to install a dev build into the stable profile ${dir}.`);
+  }
+}
+
+// A sandbox inside the repo inherits its git root, so it would not behave like a user project.
+function assertOutsideRepo(dir, root = ROOT) {
+  if (isInside(dir, root)) {
+    throw new ExitError(1, `Sandbox ${dir} is inside the pp-core checkout; pick a directory outside ${root}.`);
+  }
+}
+
+function npmCliPath() {
+  const npmCli = process.env.npm_execpath;
+  if (!npmCli) {
+    throw new ExitError(1, 'Run this through npm (npm run setup / npm run dev:install), or pass --no-build after building yourself.');
+  }
+  return npmCli;
+}
+
+function runNpm(args, cwd) {
+  execFileSync(process.execPath, [npmCliPath(), ...args], { cwd, stdio: 'inherit' });
+}
+
+function runBuild() {
+  runNpm(['run', 'build'], ROOT);
+}
+
+function git(args, cwd) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+
+// Highest vX.Y.Z (or X.Y.Z) tag; pre-release tags are skipped.
+function pickLatestTag(tags) {
+  const parsed = tags
+    .map((tag) => ({ tag, m: /^v?(\d+)\.(\d+)\.(\d+)$/.exec(tag) }))
+    .filter((t) => t.m)
+    .map((t) => ({ tag: t.tag, v: t.m.slice(1).map(Number) }));
+  parsed.sort((a, b) => b.v[0] - a.v[0] || b.v[1] - a.v[1] || b.v[2] - a.v[2]);
+  return parsed.length ? parsed[0].tag : null;
+}
+
+// Next to the main checkout, so running this from any worktree finds the same directory.
+function resolveStableDir(opts, repo = ROOT) {
+  if (opts.dir) return path.resolve(opts.dir);
+  const commonDir = path.resolve(repo, git(['rev-parse', '--git-common-dir'], repo));
+  return path.join(path.dirname(commonDir), '..', 'pp-core-stable');
+}
+
+// The runtimes install.js takes as --<id>, read from the capability manifests so no build is needed.
+function listRuntimes(root = ROOT) {
+  const capDir = path.join(root, 'capabilities');
+  return fs.readdirSync(capDir).flatMap((name) => {
+    try {
+      const cap = JSON.parse(fs.readFileSync(path.join(capDir, name, 'capability.json'), 'utf8'));
+      return cap.role === 'runtime' ? [{ id: cap.id, title: cap.title || cap.id }] : [];
+    } catch {
+      return [];
+    }
+  }).sort((a, b) => a.id.localeCompare(b.id));
+}
+
+function resolveRuntime(id, root = ROOT) {
+  const runtimes = listRuntimes(root);
+  const found = runtimes.find((r) => r.id === id);
+  if (!found) {
+    throw new ExitError(2, `Unknown runtime: ${id}. Choose one of: ${runtimes.map((r) => r.id).join(', ')}.`);
+  }
+  return found;
+}
+
+function listWorktrees(repo) {
+  return git(['worktree', 'list', '--porcelain'], repo)
+    .split(/\r?\n/)
+    .filter((line) => line.startsWith('worktree '))
+    .map((line) => path.resolve(line.slice('worktree '.length)));
+}
+
+// Adds the worktree at the tag, or moves an existing clean one to it; never touches your own checkout.
+function prepareStableWorktree({ repo, dir, tag }) {
+  try {
+    git(['rev-parse', '--verify', '--quiet', `refs/tags/${tag}`], repo);
+  } catch {
+    throw new ExitError(1, `Tag ${tag} does not exist in ${repo}.`);
+  }
+  let known = listWorktrees(repo).some((w) => samePath(w, dir));
+  // A worktree folder deleted by hand stays registered; prune it so it is added again.
+  if (known && !fs.existsSync(dir)) {
+    git(['worktree', 'prune'], repo);
+    known = false;
+  }
+  if (!known) {
+    if (fs.existsSync(dir)) {
+      throw new ExitError(1, `${dir} exists but is not a worktree of ${repo}; pass --dir <other dir>.`);
+    }
+    git(['worktree', 'add', '--detach', dir, tag], repo);
+    return;
+  }
+  if (git(['status', '--porcelain'], dir) !== '') {
+    throw new ExitError(1, `The stable worktree ${dir} has local changes; commit or discard them first.`);
+  }
+  git(['checkout', '--quiet', '--detach', tag], dir);
+}
+
+function installStable(opts) {
+  const runtime = resolveRuntime(opts.runtime);
+  npmCliPath();
+  const dir = resolveStableDir(opts);
+  try {
+    git(['fetch', '--tags', '--quiet', 'origin'], ROOT);
+  } catch {
+    process.stderr.write('Could not fetch tags from origin; using the tags already in this clone.\n');
+  }
+  const tag = opts.tag || pickLatestTag(git(['tag', '--list'], ROOT).split(/\r?\n/));
+  if (!tag) throw new ExitError(1, 'No release tag found; pass one: npm run setup -- <tag>.');
+  prepareStableWorktree({ repo: ROOT, dir, tag });
+  process.stdout.write(`Stable worktree ${dir} is on ${tag}.\n`);
+  runNpm(['ci'], dir);
+  runNpm(['run', 'build'], dir);
+  execFileSync(process.execPath, [path.join(dir, 'bin', 'install.js'), `--${runtime.id}`, '--global'], { cwd: dir, stdio: 'inherit' });
+  const again = runtime.id === 'claude' ? 'npm run setup' : `npm run setup -- --runtime ${runtime.id}`;
+  process.stdout.write(`\npp-core ${tag} is installed as the global pp-core for ${runtime.title}. Update later with: ${again}\n`);
+}
+
+// The statusline shows a DEV badge with this build's branch and commit when this file is present.
+function devBuildInfo(root = ROOT, now = new Date()) {
+  const info = { checkout: root, installedAt: now.toISOString() };
+  try {
+    const branch = git(['rev-parse', '--abbrev-ref', 'HEAD'], root);
+    if (branch !== 'HEAD') info.branch = branch;
+    info.commit = git(['rev-parse', '--short', 'HEAD'], root);
+    info.dirty = git(['status', '--porcelain'], root) !== '';
+  } catch {
+    // Not a git checkout: the badge still shows DEV, without a ref.
+  }
+  return info;
+}
+
+function installProfile(opts) {
+  const dir = resolveConfigDir(opts);
+  assertNotStableProfile(dir);
+  if (opts.build) runBuild();
+  execFileSync(process.execPath, [INSTALLER, '--claude', '--global', '--config-dir', dir], { stdio: 'inherit' });
+  fs.writeFileSync(path.join(dir, 'pp-dev-build.json'), `${JSON.stringify(devBuildInfo(), null, 2)}\n`);
+  process.stdout.write(`\nDev profile ready in ${dir}. From a project folder: claude-dev, or npm --prefix "${ROOT}" run dev:claude\n`);
+}
+
+function installSandbox(opts) {
+  const dir = resolveLocalDir(opts);
+  assertOutsideRepo(dir);
+  if (opts.build) runBuild();
+  fs.mkdirSync(dir, { recursive: true });
+  if (!fs.existsSync(path.join(dir, '.git'))) execFileSync('git', ['init', '-q'], { cwd: dir, stdio: 'inherit' });
+  execFileSync(process.execPath, [INSTALLER, '--claude', '--local'], { cwd: dir, stdio: 'inherit' });
+  process.stdout.write(
+    `\nSandbox ready in ${dir}. Skills still come from the global install, and its hooks run alongside the\n` +
+    'sandbox hooks; use the dev profile (npm run dev:install) to test skills or hooks.\n'
+  );
+}
+
+// npm runs scripts in the package root; INIT_CWD is the directory the command was typed in.
+function resolveLaunchDir(env = process.env) {
+  return path.resolve(env.INIT_CWD || process.cwd());
+}
+
+function launchClaude(opts) {
+  const dir = resolveConfigDir(opts);
+  assertNotStableProfile(dir);
+  if (!fs.existsSync(path.join(dir, 'pp-core', 'VERSION'))) {
+    throw new ExitError(1, `No pp-core install in ${dir}; run npm run dev:install first.`);
+  }
+  const cwd = resolveLaunchDir();
+  process.stdout.write(`Starting Claude in ${cwd} on the dev profile ${dir}.\n`);
+  const result = spawnSync('claude', opts.passthrough, {
+    cwd,
+    stdio: 'inherit',
+    env: { ...process.env, CLAUDE_CONFIG_DIR: dir },
+  });
+  if (result.error) {
+    throw new ExitError(1, `Could not start claude (${result.error.code}); set CLAUDE_CONFIG_DIR=${dir} and start it yourself.`);
+  }
+  return result.status === null ? 1 : result.status;
+}
+
+const LAUNCHER_START = '# >>> pp-core claude-dev >>>';
+const LAUNCHER_END = '# <<< pp-core claude-dev <<<';
+
+// macOS/Linux: a `claude-dev` shell function in the rc file, Claude on the dev profile in any folder.
+function renderRcLauncher(configDir) {
+  return [
+    `${LAUNCHER_START} (written by npm run dev:setup in the pp-core checkout)`,
+    `claude-dev() { CLAUDE_CONFIG_DIR='${configDir.replace(/'/g, "'\\''")}' claude "$@"; }`,
+    LAUNCHER_END,
+  ].join('\n');
+}
+
+// Replaces an earlier block in place, so running dev:setup again never adds a second copy.
+function upsertLauncher(text, block) {
+  const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const existing = new RegExp(`^${esc(LAUNCHER_START)}[^\\n]*\\n[\\s\\S]*?^${esc(LAUNCHER_END)}[^\\n]*`, 'm');
+  if (existing.test(text)) return text.replace(existing, () => block);
+  if (text === '') return `${block}\n`;
+  return `${text}${text.endsWith('\n') ? '' : '\n'}\n${block}\n`;
+}
+
+// Windows: command files on the user PATH. A shell profile under Documents is often behind
+// Controlled Folder Access, which blocks node.exe and powershell.exe alike.
+function windowsLauncherDir(env = process.env, home = os.homedir()) {
+  return path.join(env.LOCALAPPDATA || path.join(home, 'AppData', 'Local'), 'pp-core', 'bin');
+}
+
+// setlocal keeps CLAUDE_CONFIG_DIR inside this one run, for cmd and PowerShell callers alike.
+function renderCmdLauncher(configDir) {
+  return ['@echo off', 'setlocal', `set "CLAUDE_CONFIG_DIR=${configDir}"`, 'claude %*', ''].join('\r\n');
+}
+
+// Git Bash on Windows looks up extensionless scripts on PATH, not .cmd files.
+function renderShLauncher(configDir) {
+  return ['#!/bin/sh', `CLAUDE_CONFIG_DIR='${configDir.replace(/'/g, "'\\''")}' exec claude "$@"`, ''].join('\n');
+}
+
+function pathHasEntry(raw, dir) {
+  const norm = (p) => p.trim().replace(/[\\/]+$/, '').toLowerCase();
+  return raw.split(';').some((entry) => entry.trim() !== '' && norm(entry) === norm(dir));
+}
+
+function appendPathEntry(raw, dir) {
+  const trimmed = raw.replace(/;+$/, '');
+  return trimmed === '' ? dir : `${trimmed};${dir}`;
+}
+
+function powershell(script) {
+  return execFileSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+// Reads HKCU\Environment\Path unexpanded, so %VAR% entries and the value kind survive the rewrite.
+function addToUserPath(dir) {
+  const read = "$k = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment'); " +
+    "$raw = $k.GetValue('Path', '', 'DoNotExpandEnvironmentNames'); " +
+    "$kind = if ($k.GetValueNames() -contains 'Path') { $k.GetValueKind('Path') } else { 'ExpandString' }; " +
+    '[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("$kind|$raw"))';
+  const decoded = Buffer.from(powershell(read).trim(), 'base64').toString('utf8');
+  const bar = decoded.indexOf('|');
+  const kind = decoded.slice(0, bar);
+  const raw = decoded.slice(bar + 1);
+  if (pathHasEntry(raw, dir)) return false;
+  const value = Buffer.from(appendPathEntry(raw, dir), 'utf8').toString('base64');
+  // Setting and clearing a throwaway user variable broadcasts WM_SETTINGCHANGE, so new terminals see the PATH.
+  powershell("$k = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment', $true); " +
+    `$k.SetValue('Path', [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${value}')), '${kind === 'String' ? 'String' : 'ExpandString'}'); $k.Close(); ` +
+    "[Environment]::SetEnvironmentVariable('PP_CORE_PATH_REFRESH', '1', 'User'); " +
+    "[Environment]::SetEnvironmentVariable('PP_CORE_PATH_REFRESH', $null, 'User')");
+  return true;
+}
+
+function writeWindowsLaunchers(dir, configDir) {
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'claude-dev.cmd'), renderCmdLauncher(configDir));
+  fs.writeFileSync(path.join(dir, 'claude-dev'), renderShLauncher(configDir), { mode: 0o755 });
+}
+
+function installLauncher(configDir) {
+  if (process.platform === 'win32') {
+    const dir = windowsLauncherDir();
+    writeWindowsLaunchers(dir, configDir);
+    process.stdout.write(`claude-dev is in ${dir}\n`);
+    process.stdout.write(addToUserPath(dir) ? `Added ${dir} to your user PATH.\n` : `${dir} is already on your user PATH.\n`);
+    return;
+  }
+  const rc = path.join(os.homedir(), (process.env.SHELL || '').endsWith('zsh') ? '.zshrc' : '.bashrc');
+  const current = fs.existsSync(rc) ? fs.readFileSync(rc, 'utf8') : '';
+  fs.writeFileSync(rc, upsertLauncher(current, renderRcLauncher(configDir)));
+  process.stdout.write(`claude-dev is defined in ${rc}\n`);
+}
+
+function devSetup(opts) {
+  runNpm(['ci'], ROOT);
+  installProfile({ configDir: opts.configDir, build: true });
+  if (opts.shell) installLauncher(resolveConfigDir(opts));
+  const start = opts.shell ? 'claude-dev' : `npm --prefix "${ROOT}" run dev:claude`;
+  process.stdout.write(
+    `\nDone. Open a new terminal window, go to the project you want to work in and run: ${start}\n` +
+    'After a change to pp-core, run npm run dev:install to update the dev profile.\n'
+  );
+}
+
+function main(argv = process.argv.slice(2)) {
+  const opts = parseArgs(argv);
+  if (opts.error) throw new ExitError(2, `${opts.error}\n${USAGE}`);
+  if (opts.command === 'claude') return launchClaude(opts);
+  if (opts.command === 'dev-setup') devSetup(opts);
+  else if (opts.command === 'stable') installStable(opts);
+  else if (opts.local) installSandbox(opts);
+  else installProfile(opts);
+  return 0;
+}
+
+if (require.main === module) runMain(() => main());
+
+module.exports = {
+  parseArgs,
+  resolveConfigDir,
+  resolveLocalDir,
+  resolveStableDir,
+  resolveLaunchDir,
+  devBuildInfo,
+  renderRcLauncher,
+  upsertLauncher,
+  windowsLauncherDir,
+  renderCmdLauncher,
+  renderShLauncher,
+  writeWindowsLaunchers,
+  pathHasEntry,
+  appendPathEntry,
+  pickLatestTag,
+  listRuntimes,
+  resolveRuntime,
+  prepareStableWorktree,
+  assertNotStableProfile,
+  assertOutsideRepo,
+  samePath,
+};

package/scripts/lib/allowlist-ratchet.cjs

@@ -233,4 +233,106 @@ function assertFileBaseline({ label, current, baseline, fail, updateHint }) {
   return { grown, shrunk, added, removed };
 }
 
-module.exports = { assertWithinAllowlist, assertTightCeiling, assertFileBaseline };
+/**
+ * Assert that each artifact's measured size stays within a per-change DELTA
+ * BUDGET of its committed baseline (workflow size budget policy, 2026-10-11).
+ *
+ * Unlike `assertFileBaseline` (exact-byte pins), small growth is absorbed by a
+ * slack so routine edits need no baseline commit, while large or cumulative
+ * growth still fails by name:
+ *
+ * - A file may exceed its baseline by at most `perFileSlack` bytes.
+ * - The SUM of all positive overages may not exceed `totalSlack` bytes, so many
+ *   small growths cannot add up to a large one unseen.
+ * - Shrinking always passes and never needs a baseline commit.
+ * - A file with no baseline entry (ADDED) or a baseline entry with no file
+ *   (REMOVED) fails: the baseline must name exactly the files on disk.
+ *   Recording either needs no reason.
+ * - An EMPTY baseline fails: with no entries every file is "added", but an
+ *   explicit message makes the vacuous-pass case impossible to misread.
+ *
+ * Overage is measured against the committed baseline, not the previous commit,
+ * so the slack is a budget that a re-baseline resets — not a per-commit
+ * allowance that can be spent again on every commit.
+ *
+ * @param {object} opts
+ * @param {string} opts.label - Guard name (used in messages).
+ * @param {Object<string, number>} opts.current  - Measured sizes by name.
+ * @param {Object<string, number>} opts.baseline - Committed sizes by name
+ *                                  (numbers only; strip metadata keys first).
+ * @param {number} opts.perFileSlack - Max bytes one file may exceed its baseline.
+ * @param {number} opts.totalSlack   - Max sum of all positive overages.
+ * @param {function(string): void} opts.fail - Invoked once per violation category.
+ * @param {string} [opts.updateHint] - Remediation hint appended to growth failures.
+ * @returns {{ overages: Array<{name:string,from:number,to:number,delta:number}>,
+ *             totalOverage: number,
+ *             shrunk: Array<{name:string,from:number,to:number,delta:number}>,
+ *             added: string[], removed: string[] }}
+ */
+function assertDeltaBudget({ label, current, baseline, perFileSlack, totalSlack, fail, updateHint }) {
+  const currentNames = new Set(Object.keys(current));
+  const baselineNames = new Set(Object.keys(baseline));
+  const hint = updateHint ? `\n${updateHint}` : '';
+
+  if (baselineNames.size === 0) {
+    fail(
+      `[${label}] the committed baseline has no size entries — an empty baseline would make ` +
+        `every growth check pass vacuously. Regenerate it with \`npm run size:baseline\`.`
+    );
+  }
+
+  const added = [...currentNames].filter((n) => !baselineNames.has(n)).sort();
+  const removed = [...baselineNames].filter((n) => !currentNames.has(n)).sort();
+
+  const overages = [];
+  const shrunk = [];
+  for (const name of [...currentNames].filter((n) => baselineNames.has(n)).sort()) {
+    const from = baseline[name];
+    const to = current[name];
+    if (!Number.isInteger(from) || from < 0) {
+      fail(`[${label}] baseline entry ${name} is not a non-negative integer byte size: ${JSON.stringify(from)}`);
+      continue;
+    }
+    if (to > from) overages.push({ name, from, to, delta: to - from });
+    else if (to < from) shrunk.push({ name, from, to, delta: from - to });
+  }
+  const totalOverage = overages.reduce((sum, o) => sum + o.delta, 0);
+  const fmt = (o) => `  - ${o.name}: ${o.from} → ${o.to} (+${o.delta})`;
+
+  const overFile = overages.filter((o) => o.delta > perFileSlack);
+  if (overFile.length > 0) {
+    fail(
+      `[${label}] ${overFile.length} file(s) grew more than the per-file slack of ${perFileSlack} bytes ` +
+        `past the committed baseline. Shrink them (extract content lazily), or re-baseline with a ` +
+        `reason: npm run size:baseline -- --reason "<why this growth is needed>"\n` +
+        `${overFile.map(fmt).join('\n')}${hint}`
+    );
+  }
+
+  if (totalOverage > totalSlack) {
+    fail(
+      `[${label}] total growth past the committed baseline is ${totalOverage} bytes, over the total ` +
+        `slack of ${totalSlack} bytes (each file may be under its own slack — the sum is what failed). ` +
+        `Shrink, or re-baseline with a reason: npm run size:baseline -- --reason "<why>"\n` +
+        `${overages.map(fmt).join('\n')}${hint}`
+    );
+  }
+
+  if (added.length > 0) {
+    fail(
+      `[${label}] ${added.length} file(s) are not in the baseline — run \`npm run size:baseline\` ` +
+        `to record them (no --reason needed for new files).\n${added.map((n) => `  - ${n}`).join('\n')}`
+    );
+  }
+
+  if (removed.length > 0) {
+    fail(
+      `[${label}] ${removed.length} baseline entry(ies) no longer exist — run \`npm run size:baseline\` ` +
+        `to drop them (no --reason needed).\n${removed.map((n) => `  - ${n}`).join('\n')}`
+    );
+  }
+
+  return { overages, totalOverage, shrunk, added, removed };
+}
+
+module.exports = { assertWithinAllowlist, assertTightCeiling, assertFileBaseline, assertDeltaBudget };