contextdevkit 1.8.0

package/templates/contextkit/tools/scripts/clean-drive.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * OPTIONAL utility — removes cloud-sync contamination from a git repo.
+ *
+ * Google Drive / OneDrive desktop clients sometimes seed `desktop.ini` files
+ * recursively inside `.git/` (refs, objects, hooks). git then tries to read
+ * them as refs and dies with `fatal: bad object`. They also create `.tmp.drive*`
+ * working folders at the repo root. This removes both. Idempotent, defensive.
+ *
+ * Mostly relevant on Windows when the repo lives inside a synced folder.
+ *
+ * Usage (CLI):  node contextkit/tools/scripts/clean-drive.mjs
+ * Library:      import { cleanCloudContamination } from './clean-drive.mjs'
+ */
+import { readdirSync, rmSync, unlinkSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** @param {string} [root] @returns {{ desktopIniInGit: number, tmpFolders: number }} */
+export function cleanCloudContamination(root = process.cwd()) {
+  return {
+    desktopIniInGit: removeDesktopIniRecursive(resolve(root, '.git')),
+    tmpFolders: removeTmpFolders(root),
+  };
+}
+
+function removeDesktopIniRecursive(dir) {
+  let count = 0;
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+  for (const e of entries) {
+    const full = join(dir, e.name);
+    if (e.isDirectory()) count += removeDesktopIniRecursive(full);
+    else if (e.name === 'desktop.ini') {
+      try {
+        unlinkSync(full);
+        count++;
+      } catch {
+        /* best effort */
+      }
+    }
+  }
+  return count;
+}
+
+function removeTmpFolders(root) {
+  let count = 0;
+  let entries;
+  try {
+    entries = readdirSync(root, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+  for (const e of entries) {
+    if (e.isDirectory() && (e.name.startsWith('.tmp.drive') || e.name.startsWith('.tmp.onedrive'))) {
+      try {
+        rmSync(join(root, e.name), { recursive: true, force: true });
+        count++;
+      } catch {
+        /* Drive may hold a lock */
+      }
+    }
+  }
+  return count;
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const r = cleanCloudContamination(process.cwd());
+  if (r.desktopIniInGit > 0 || r.tmpFolders > 0) {
+    console.log(`✓ cleaned ${r.desktopIniInGit} desktop.ini in .git/, ${r.tmpFolders} .tmp.* folder(s)`);
+  } else {
+    console.log('✓ already clean — no cloud-sync contamination found');
+  }
+}

package/templates/contextkit/tools/scripts/context-config.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * Inspect or edit `contextkit/config.json` reliably (backs the `/context-config`
+ * command). Zero-dependency; uses optional zod validation if installed.
+ *
+ * Usage:
+ *   node contextkit/tools/scripts/context-config.mjs show [dotted.path]
+ *   node contextkit/tools/scripts/context-config.mjs set <dotted.path> <value>
+ *
+ * Values are coerced to the existing leaf type: numbers, booleans, and JSON
+ * arrays/objects parse; everything else stays a string. Writing always
+ * pretty-prints with 2-space indent and validates structure first.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { pathsFor } from '../../runtime/config/paths.mjs';
+
+const ROOT = process.cwd();
+const CONFIG = pathsFor(ROOT).config;
+
+function load() {
+  if (!existsSync(CONFIG)) return {};
+  return JSON.parse(readFileSync(CONFIG, 'utf-8').replace(/^/, ''));
+}
+
+function getAt(obj, path) {
+  return path.split('.').reduce((cur, k) => (cur == null ? undefined : cur[k]), obj);
+}
+
+function setAt(obj, path, value) {
+  const segs = path.split('.');
+  let cur = obj;
+  for (let i = 0; i < segs.length - 1; i++) {
+    if (cur[segs[i]] == null || typeof cur[segs[i]] !== 'object') cur[segs[i]] = {};
+    cur = cur[segs[i]];
+  }
+  cur[segs[segs.length - 1]] = value;
+  return obj;
+}
+
+function coerce(existing, raw) {
+  if (typeof existing === 'number') {
+    const n = Number(raw);
+    if (Number.isNaN(n)) throw new Error(`expected a number, got "${raw}"`);
+    return n;
+  }
+  if (typeof existing === 'boolean') {
+    if (raw === 'true') return true;
+    if (raw === 'false') return false;
+    throw new Error(`expected true/false, got "${raw}"`);
+  }
+  if (Array.isArray(existing) || raw.trim().startsWith('[') || raw.trim().startsWith('{')) {
+    return JSON.parse(raw);
+  }
+  return raw;
+}
+
+async function maybeValidate(cfg) {
+  try {
+    const { validateConfig, formatZodError } = await import('../../runtime/config/schema.mjs');
+    const res = validateConfig(cfg);
+    if (!res.ok) {
+      console.error('Refusing to write — schema validation failed:\n' + formatZodError(res.error));
+      process.exit(1);
+    }
+    return true;
+  } catch {
+    return false; // zod not installed — skip strict validation
+  }
+}
+
+async function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+  const cfg = load();
+
+  if (!cmd || cmd === 'show') {
+    const path = rest[0];
+    const value = path ? getAt(cfg, path) : cfg;
+    console.log(JSON.stringify(value, null, 2));
+    return;
+  }
+
+  if (cmd === 'set') {
+    const [path, ...valParts] = rest;
+    const raw = valParts.join(' ');
+    if (!path || raw === '') {
+      console.error('Usage: context-config.mjs set <dotted.path> <value>');
+      process.exit(1);
+    }
+    const existing = getAt(cfg, path);
+    let value;
+    try {
+      value = coerce(existing, raw);
+    } catch (err) {
+      console.error(`Bad value: ${err.message}`);
+      process.exit(1);
+    }
+    setAt(cfg, path, value);
+    const validated = await maybeValidate(cfg);
+    writeFileSync(CONFIG, JSON.stringify(cfg, null, 2) + '\n', 'utf-8');
+    console.log(`✅ set ${path} = ${JSON.stringify(value)}${validated ? ' (zod-validated)' : ''}`);
+    return;
+  }
+
+  console.error(`Unknown command "${cmd}". Use: show [path] | set <path> <value>`);
+  process.exit(1);
+}
+
+main().catch((err) => {
+  console.error('context-config failed:', err.message);
+  process.exit(1);
+});

package/templates/contextkit/tools/scripts/context-level.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * Shows or changes the ContextDevKit activation level FROM INSIDE a project —
+ * no need for the kit repo to be present. Updates `contextkit/config.json`
+ * `level` AND recomposes `.claude/settings.json` hook wiring.
+ *
+ * Usage:
+ *   node contextkit/tools/scripts/context-level.mjs        # show current level
+ *   node contextkit/tools/scripts/context-level.mjs 3      # move to Level 3
+ *
+ * After changing level, restart Claude Code so it reloads the hooks.
+ */
+import { existsSync } from 'node:fs';
+import { readFile, writeFile, mkdir, chmod, rename } from 'node:fs/promises';
+import { resolve, dirname } from 'node:path';
+import { composeSettings } from '../../runtime/config/settings-compose.mjs';
+import { loadConfigSync } from '../../runtime/config/load.mjs';
+import { LEVEL_LABELS as LABELS, MAX_LEVEL, MIN_LEVEL, isValidLevel } from '../../runtime/config/levels.mjs';
+import { pathsFor } from '../../runtime/config/paths.mjs';
+
+const ROOT = process.cwd();
+const CONFIG = pathsFor(ROOT).config;
+const SETTINGS = resolve(ROOT, '.claude/settings.json');
+
+async function installGitHooks() {
+  const hooksDir = resolve(ROOT, '.git/hooks');
+  if (!existsSync(resolve(ROOT, '.git'))) return false;
+  await mkdir(hooksDir, { recursive: true });
+  const wrappers = {
+    'pre-commit': '#!/bin/sh\nnode contextkit/runtime/git-hooks/pre-commit.mjs\n',
+    'commit-msg': '#!/bin/sh\nnode contextkit/runtime/git-hooks/commit-msg.mjs "$1"\n',
+    'pre-push': '#!/bin/sh\nnode contextkit/runtime/git-hooks/pre-push.mjs\n',
+  };
+  for (const [name, body] of Object.entries(wrappers)) {
+    const p = resolve(hooksDir, name);
+    // Back up a pre-existing non-ours hook (husky/lint-staged) before replacing it.
+    if (existsSync(p) && !(await readFile(p, 'utf-8').catch(() => '')).includes('contextkit/runtime/git-hooks')) {
+      const backup = `${p}.bak`;
+      if (!existsSync(backup)) await rename(p, backup);
+    }
+    await writeFile(p, body, 'utf-8');
+    await chmod(p, 0o755).catch(() => {});
+  }
+  return true;
+}
+
+async function main() {
+  const current = loadConfigSync(ROOT).level;
+  const arg = process.argv[2];
+
+  if (!arg) {
+    console.log(`Current ContextDevKit level: L${current}\n`);
+    for (const [k, v] of Object.entries(LABELS)) console.log(`${Number(k) <= current ? '✓' : ' '} ${v}`);
+    console.log(`\nChange with:  node contextkit/tools/scripts/context-level.mjs <${MIN_LEVEL}-${MAX_LEVEL}>`);
+    return;
+  }
+
+  const level = Number(arg);
+  if (!isValidLevel(level)) {
+    console.error(`Level must be an integer ${MIN_LEVEL}–${MAX_LEVEL}.`);
+    process.exit(1);
+  }
+
+  // 1. config.json level
+  let cfg = {};
+  try {
+    cfg = JSON.parse((await readFile(CONFIG, 'utf-8')).replace(/^/, ''));
+  } catch {
+    /* will create */
+  }
+  cfg.level = level;
+  await mkdir(dirname(CONFIG), { recursive: true });
+  await writeFile(CONFIG, JSON.stringify(cfg, null, 2) + '\n', 'utf-8');
+
+  // 2. settings.json hooks
+  let existing = null;
+  try {
+    existing = JSON.parse((await readFile(SETTINGS, 'utf-8')).replace(/^/, ''));
+  } catch {
+    /* fresh */
+  }
+  await mkdir(dirname(SETTINGS), { recursive: true });
+  await writeFile(SETTINGS, JSON.stringify(composeSettings(existing, level), null, 2) + '\n', 'utf-8');
+
+  // 3. git hooks at L >= 3
+  if (level >= 3) await installGitHooks();
+
+  console.log(`✅ ContextDevKit moved from L${current} → L${level}.`);
+  if (level >= 4 && !existsSync(resolve(ROOT, '.claude/agents'))) {
+    console.log('ℹ️  Level 4 uses sub-agents. Copy them with the kit installer or add your own to .claude/agents/.');
+  }
+  console.log('↻  Restart Claude Code to load the new hook wiring.');
+}
+
+main().catch((err) => {
+  console.error('❌ context-level failed:', err);
+  process.exit(1);
+});

package/templates/contextkit/tools/scripts/context-pack.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+/**
+ * Context pack — one bounded "start of work" bundle. [ADR-0027]
+ *
+ * Collapses the 3–5 sequential reads `/dev-start`, `/state` and `/ship` each do
+ * (latest session + CHANGELOG `[Unreleased]` + immutable rules + open tasks +
+ * recent ADRs) into a SINGLE script call — fewer tokens AND fewer round-trips.
+ * Reuses `digestLatestSession` (the same digest the boot hook shows — single
+ * source) and the ADR core. Read-only, zero third-party deps. Every section is
+ * best-effort: a missing source is skipped with a note, never an error.
+ *
+ * Usage:
+ *   node contextkit/tools/scripts/context-pack.mjs          # human bundle
+ *   node contextkit/tools/scripts/context-pack.mjs --json
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { pathsFor } from '../../runtime/config/paths.mjs';
+import { digestLatestSession, extractUnreleased, readChangelog } from '../../runtime/hooks/boot-context-readers.mjs';
+import { section } from '../../runtime/hooks/md-extract.mjs';
+import { ADR_FILENAME_RE, parseAdr, renderCatalogLine } from './adr-digest-core.mjs';
+
+const ROOT = process.cwd();
+const P = pathsFor(ROOT);
+const args = process.argv.slice(2);
+const flag = (name) => args.includes(name);
+const readSafe = (abs) => readFile(abs, 'utf-8').catch(() => null);
+
+/** The numbered `⛔ Immutable rules` block from CLAUDE.md (capped), or null. */
+async function immutableRules() {
+  const text = await readSafe(resolve(ROOT, 'CLAUDE.md'));
+  if (!text) return null;
+  const body = section(text.split('\n'), 'immutable rules')
+    .filter((l) => l.trim())
+    .slice(0, 12)
+    .join('\n')
+    .trim();
+  return body || null;
+}
+
+/** The N most recent ADRs as catalog lines, or null. */
+async function recentAdrs(limit = 5) {
+  let files = [];
+  try {
+    files = await readdir(P.decisions);
+  } catch {
+    return null;
+  }
+  const names = files.filter((f) => ADR_FILENAME_RE.test(f) && f !== '_TEMPLATE.md').sort().reverse().slice(0, limit);
+  const lines = [];
+  for (const name of names) {
+    const text = await readSafe(resolve(P.decisions, name));
+    if (text !== null) lines.push(renderCatalogLine(parseAdr(text, name)));
+  }
+  return lines.length ? lines.join('\n') : null;
+}
+
+const FM = (raw, key) => (new RegExp(`^${key}:\\s*(.+)$`, 'm').exec(raw)?.[1] || '').replace(/^["']|["']$/g, '').trim();
+const PRIORITY_ORDER = { P0: 0, P1: 1, P2: 2, P3: 3 };
+
+/** Open backlog tasks (id · priority · title), highest priority first, capped. */
+async function openBacklog(cap = 8) {
+  let files = [];
+  try {
+    files = await readdir(resolve(P.pipeline, 'backlog'));
+  } catch {
+    return null;
+  }
+  const tasks = [];
+  for (const name of files.filter((f) => /^\d+-.*\.md$/.test(f))) {
+    const text = await readSafe(resolve(P.pipeline, 'backlog', name));
+    if (text === null) continue;
+    tasks.push({ id: FM(text, 'id') || name.split('-')[0], priority: FM(text, 'priority') || 'P3', title: FM(text, 'title') || name });
+  }
+  if (tasks.length === 0) return null;
+  tasks.sort((a, b) => (PRIORITY_ORDER[a.priority] ?? 9) - (PRIORITY_ORDER[b.priority] ?? 9) || String(a.id).localeCompare(String(b.id)));
+  return tasks.slice(0, cap).map((t) => `- **${t.priority}** · #${t.id} · ${t.title}`).join('\n');
+}
+
+async function build() {
+  const [session, unreleased, rules, adrs, backlog] = await Promise.all([
+    digestLatestSession(ROOT),
+    readChangelog(ROOT).then((c) => extractUnreleased(c)),
+    immutableRules(),
+    recentAdrs(),
+    openBacklog(),
+  ]);
+  return { session, unreleased, rules, adrs, backlog };
+}
+
+function render(pack) {
+  const out = ['# 🧭 Context pack — start of work\n'];
+  const block = (title, body, emptyNote) => {
+    out.push(`## ${title}`);
+    out.push('');
+    out.push(body && body.trim() ? body.trim() : `_${emptyNote}_`);
+    out.push('');
+  };
+  block('🗓️ Last session', pack.session?.content, 'no registered sessions yet');
+  block('📝 Unreleased (CHANGELOG)', pack.unreleased, 'nothing unreleased');
+  block('⛔ Immutable rules', pack.rules, 'no CLAUDE.md immutable-rules block found');
+  block('🛠️ Open backlog (top by priority)', pack.backlog, 'no open backlog tasks');
+  block('🏛️ Recent decisions (ADRs)', pack.adrs, 'no ADRs yet');
+  out.push('> Reason over this pack; open a full session log / ADR / ticket only on demand. [ADR-0027]');
+  return out.join('\n');
+}
+
+async function main() {
+  const pack = await build();
+  if (flag('--json')) {
+    process.stdout.write(JSON.stringify(pack, null, 2) + '\n');
+    return;
+  }
+  console.log(render(pack));
+}
+
+main().catch((err) => {
+  console.error('❌ context-pack failed:', err?.message ?? err);
+  process.exit(1);
+});

package/templates/contextkit/tools/scripts/contract-scan.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+/**
+ * Generic Contract Drift detector (L5/L6).
+ *
+ * "Contract" = the public surface other code/consumers depend on. You declare
+ * which files form it via `contextkit/config.json` → `l5.contractGlobs` (prefixes
+ * or exact paths). This extracts exported identifiers from those files and
+ * compares against a committed baseline, flagging REMOVALS/RENAMES (the
+ * breaking changes) — additions are fine.
+ *
+ * Usage:
+ *   node contextkit/tools/scripts/contract-scan.mjs --save     # write/refresh baseline
+ *   node contextkit/tools/scripts/contract-scan.mjs            # diff vs baseline (exit 1 on removals)
+ *   node contextkit/tools/scripts/contract-scan.mjs --json
+ *
+ * Baseline: contextkit/memory/contract-baseline.json (commit it).
+ * Regex-based, language-agnostic-ish (JS/TS export forms): named/declaration
+ * exports incl. `declare`/`abstract`/generators, `export default`, namespace
+ * re-exports (`export * [as N] from`), and type-only `export type { … }`. Good
+ * signal by default; for AST precision install `acorn` (or point
+ * `CONTEXT_CONTRACT_PARSER` at a parser) — used **only if importable**, so the
+ * zero-dep default holds. Advisory by default; wire into CI to block breaking
+ * changes without an intentional version bump.
+ */
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { loadConfigSync } from '../../runtime/config/load.mjs';
+import { pathsFor } from '../../runtime/config/paths.mjs';
+
+const ROOT = process.cwd();
+const BASELINE = pathsFor(ROOT).contractBaseline;
+const GLOBS = loadConfigSync(ROOT).l5?.contractGlobs || [];
+
+// Declarations: export [declare] [abstract] [async] <kw> NAME (function may be a generator).
+const EXPORT_RE = /export\s+(?:declare\s+)?(?:abstract\s+)?(?:async\s+)?(?:const|let|var|function\*?|class|interface|type|enum)\s+([A-Za-z_$][\w$]*)/g;
+// Named (re-)exports incl. type-only blocks: export [type] { a, b as c, type D }.
+const NAMED_RE = /export\s*(?:type\s+)?\{([^}]*)\}/g;
+// Default export — tracked as the `default` symbol (removing it is breaking).
+const DEFAULT_RE = /export\s+default\b/;
+// Namespace re-export: export * [as NS] from '...'.
+const STAR_RE = /export\s*\*\s*(?:as\s+([A-Za-z_$][\w$]*)\s+)?from\s*['"]([^'"]+)['"]/g;
+
+function matchesGlob(rel) {
+  return GLOBS.some((g) => rel === g || rel.startsWith(g));
+}
+
+function walk(dir, acc) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return acc;
+  }
+  for (const e of entries) {
+    const abs = join(dir, e.name);
+    const rel = relative(ROOT, abs).replaceAll('\\', '/');
+    if (rel.startsWith('node_modules') || rel.startsWith('.git')) continue;
+    if (e.isDirectory()) walk(abs, acc);
+    else if (/\.(ts|tsx|js|jsx|mjs)$/.test(e.name) && matchesGlob(rel)) acc.push(rel);
+  }
+  return acc;
+}
+
+function extractExports(content) {
+  const seen = new Set();
+  let m;
+  EXPORT_RE.lastIndex = 0;
+  while ((m = EXPORT_RE.exec(content)) !== null) seen.add(m[1]);
+  NAMED_RE.lastIndex = 0;
+  while ((m = NAMED_RE.exec(content)) !== null) {
+    for (const raw of m[1].split(',')) {
+      // Drop an inline `type ` modifier and any `as` alias, keep the exposed name.
+      const part = raw.trim().replace(/^type\s+/, '').split(/\s+as\s+/).pop().replace(/[^A-Za-z0-9_$]/g, '');
+      if (part) seen.add(part);
+    }
+  }
+  STAR_RE.lastIndex = 0;
+  while ((m = STAR_RE.exec(content)) !== null) seen.add(m[1] || `* from ${m[2]}`);
+  if (DEFAULT_RE.test(content)) seen.add('default');
+  return [...seen];
+}
+
+/**
+ * Optional AST parser — zero-dep DEFAULT (regex). If a parser module is importable
+ * (name from `CONTEXT_CONTRACT_PARSER`, else `acorn`), use it for precise extraction;
+ * otherwise fall back to regex. Installing `acorn` upgrades JS precision opt-in —
+ * the kit ships nothing, preserving the zero-dep invariant. [→ ADR-0003]
+ */
+async function loadParser() {
+  const name = process.env.CONTEXT_CONTRACT_PARSER || 'acorn';
+  const spec = /[\\/]/.test(name) ? pathToFileURL(resolve(ROOT, name)).href : name;
+  try {
+    return await import(spec);
+  } catch {
+    return null;
+  }
+}
+
+/** Exported names via AST (precise). Returns null when the file can't be parsed. */
+function extractExportsAst(content, parser) {
+  let ast;
+  try {
+    ast = parser.parse(content, { sourceType: 'module', ecmaVersion: 'latest', allowHashBang: true });
+  } catch {
+    return null;
+  }
+  const names = new Set();
+  for (const node of ast.body || []) {
+    if (node.type === 'ExportDefaultDeclaration') {
+      names.add('default');
+    } else if (node.type === 'ExportAllDeclaration') {
+      names.add(node.exported ? node.exported.name : `* from ${node.source?.value ?? ''}`);
+    } else if (node.type === 'ExportNamedDeclaration') {
+      for (const spec of node.specifiers || []) names.add(spec.exported?.name ?? spec.exported?.value);
+      if (node.declaration?.id?.name) names.add(node.declaration.id.name);
+      for (const d of node.declaration?.declarations || []) if (d.id?.name) names.add(d.id.name);
+    }
+  }
+  return [...names].filter(Boolean);
+}
+
+/** Exported names for one file: AST when a parser is present and the file parses, else regex. */
+function extractFor(content, parser) {
+  if (parser) {
+    const viaAst = extractExportsAst(content, parser);
+    if (viaAst) return viaAst;
+  }
+  return extractExports(content);
+}
+
+function snapshot(parser) {
+  const surface = {};
+  for (const rel of walk(ROOT, [])) {
+    try {
+      surface[rel] = extractFor(readFileSync(resolve(ROOT, rel), 'utf-8'), parser).sort();
+    } catch {
+      /* skip */
+    }
+  }
+  return surface;
+}
+
+function diff(base, current) {
+  const removals = [];
+  for (const [file, names] of Object.entries(base)) {
+    const now = new Set(current[file] || []);
+    for (const name of names) if (!now.has(name)) removals.push(`${file} → ${name}`);
+  }
+  return removals;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (GLOBS.length === 0) {
+    console.log('ℹ️  No l5.contractGlobs configured — nothing to track. Set them via /context-config to enable.');
+    return;
+  }
+  const current = snapshot(await loadParser());
+  if (args.includes('--save')) {
+    writeFileSync(BASELINE, JSON.stringify(current, null, 2) + '\n', 'utf-8');
+    const total = Object.values(current).reduce((n, a) => n + a.length, 0);
+    console.log(`✅ contract baseline saved — ${Object.keys(current).length} files, ${total} exported symbols.`);
+    return;
+  }
+  if (!existsSync(BASELINE)) {
+    console.log('No baseline yet. Run with --save to create contextkit/memory/contract-baseline.json, then commit it.');
+    return;
+  }
+  const removals = diff(JSON.parse(readFileSync(BASELINE, 'utf-8')), current);
+  if (args.includes('--json')) {
+    process.stdout.write(JSON.stringify({ removals }, null, 2) + '\n');
+  } else if (removals.length === 0) {
+    console.log('✅ No contract drift — no exported symbols removed/renamed.');
+  } else {
+    console.error(`🛑 Contract drift — ${removals.length} removed/renamed export(s):`);
+    for (const r of removals) console.error(`   - ${r}`);
+    console.error('\nIf intentional, bump the version (BREAKING CHANGE) and refresh the baseline with --save.');
+  }
+  process.exit(removals.length > 0 ? 1 : 0);
+}
+
+main().catch((err) => {
+  console.error('contract-scan failed:', err?.message ?? err);
+  process.exit(1);
+});