contextdevkit 1.8.0

package/templates/contextkit/tools/scripts/tech-debt-scan.mjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+/**
+ * Deterministic tech-debt scanner — the engine behind `/tech-debt-sweep`.
+ *
+ * Walks the project's source files (skipping config.ledger.irrelevant paths),
+ * runs the regex detectors, and reports findings. Fast, zero-dependency.
+ *
+ * Usage:
+ *   node contextkit/tools/scripts/tech-debt-scan.mjs            # console summary
+ *   node contextkit/tools/scripts/tech-debt-scan.mjs --json     # machine-readable
+ *   node contextkit/tools/scripts/tech-debt-scan.mjs --write    # → contextkit/memory/tech-debt-board.md
+ *   node contextkit/tools/scripts/tech-debt-scan.mjs --quick    # red zone only (severity >= 4)
+ */
+import { 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 { PLATFORM_DIR, pathsFor } from '../../runtime/config/paths.mjs';
+import { ALL_DETECTORS, CODE_RE } from './tech-debt-detectors.mjs';
+
+const ROOT = process.cwd();
+const P = pathsFor(ROOT);
+const cfg = loadConfigSync(ROOT);
+const IRRELEVANT = (cfg.ledger?.irrelevant || []).concat(['.git/', `${PLATFORM_DIR}/tools/`, `${PLATFORM_DIR}/runtime/`, `${PLATFORM_DIR}/detectors/`]);
+const LINE_BUDGET = cfg.l5?.lineBudget || { yellow: 240, red: 308 };
+
+function isIgnored(rel) {
+  const norm = rel.replaceAll('\\', '/');
+  return IRRELEVANT.some((p) => norm === p || norm.startsWith(p));
+}
+
+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 (isIgnored(rel) || e.name.startsWith('.tmp')) continue;
+    if (e.isDirectory()) walk(abs, acc);
+    else if (CODE_RE.test(e.name)) acc.push(rel);
+  }
+  return acc;
+}
+
+/** Functions exported by a custom detector module: default (fn or array) + `detectors`. */
+function collectFns(mod) {
+  const out = [];
+  if (typeof mod.default === 'function') out.push(mod.default);
+  else if (Array.isArray(mod.default)) out.push(...mod.default.filter((x) => typeof x === 'function'));
+  if (Array.isArray(mod.detectors)) out.push(...mod.detectors.filter((x) => typeof x === 'function'));
+  return out;
+}
+
+/** Drop-in detectors from `contextkit/detectors/*.mjs`. Defensive — a broken one is skipped. */
+async function loadCustomDetectors() {
+  let files;
+  try {
+    files = readdirSync(P.detectors).filter((f) => f.endsWith('.mjs'));
+  } catch {
+    return [];
+  }
+  const fns = [];
+  for (const f of files) {
+    try {
+      fns.push(...collectFns(await import(pathToFileURL(resolve(P.detectors, f)).href)));
+    } catch {
+      /* a broken custom detector must never block the scan */
+    }
+  }
+  return fns;
+}
+
+function scan(quick, detectors) {
+  const files = walk(ROOT, []);
+  const findings = [];
+  for (const rel of files) {
+    let content;
+    try {
+      content = readFileSync(resolve(ROOT, rel), 'utf-8');
+    } catch {
+      continue;
+    }
+    for (const detector of detectors) {
+      try {
+        const opts = detector.name === 'detectLineBudget' ? LINE_BUDGET : undefined;
+        for (const f of detector(rel, content, opts) || []) findings.push(f);
+      } catch {
+        /* a custom detector must not break the scan */
+      }
+    }
+  }
+  const filtered = quick ? findings.filter((f) => f.severity >= 4) : findings;
+  filtered.sort((a, b) => b.severity - a.severity || a.path.localeCompare(b.path));
+  return { fileCount: files.length, findings: filtered };
+}
+
+function renderBoard({ fileCount, findings }) {
+  const out = [];
+  out.push('# Tech Debt Board');
+  out.push('');
+  out.push(`> Auto-generated by \`tech-debt-scan\` on ${new Date().toISOString().slice(0, 10)} — ${fileCount} files scanned, ${findings.length} finding(s).`);
+  out.push('> Human-reviewed, advisory. Regenerate any time.');
+  out.push('');
+  const byKind = {};
+  for (const f of findings) (byKind[f.kind] = byKind[f.kind] || []).push(f);
+  if (findings.length === 0) {
+    out.push('✅ No findings. Clean.');
+    return out.join('\n') + '\n';
+  }
+  for (const [kind, items] of Object.entries(byKind)) {
+    out.push(`## ${kind} (${items.length})`);
+    out.push('');
+    for (const f of items) {
+      const sev = '●'.repeat(f.severity);
+      out.push(`- ${sev} \`${f.path}${f.line ? `:${f.line}` : ''}\` — ${f.message}`);
+    }
+    out.push('');
+  }
+  return out.join('\n') + '\n';
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const detectors = [...ALL_DETECTORS, ...(await loadCustomDetectors())];
+  const report = scan(args.includes('--quick'), detectors);
+  if (args.includes('--ci')) {
+    // CI gate: fail the build on any RED-zone (severity 5) finding so the kit —
+    // or any project — can't regress past its own hard line-budget limit.
+    const red = report.findings.filter((f) => f.severity >= 5);
+    if (red.length > 0) {
+      console.error(`✗ tech-debt CI gate: ${red.length} RED-zone finding(s) (must be 0):`);
+      for (const f of red) console.error(`   ${'●'.repeat(f.severity)} ${f.path}${f.line ? ':' + f.line : ''} — ${f.message}`);
+      process.exit(1);
+    }
+    console.log(`✓ tech-debt CI gate: no RED-zone findings across ${report.fileCount} files.`);
+    return;
+  }
+  if (args.includes('--json')) {
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    return;
+  }
+  if (args.includes('--write')) {
+    writeFileSync(resolve(P.memory, 'tech-debt-board.md'), renderBoard(report), 'utf-8');
+    // Also dump the raw findings so the DevPipeline can ingest them deterministically.
+    writeFileSync(resolve(P.memory, 'tech-debt-findings.json'), JSON.stringify(report, null, 2), 'utf-8');
+    console.log(`✅ tech-debt-board.md + tech-debt-findings.json written — ${report.findings.length} finding(s) across ${report.fileCount} files.`);
+    console.log('   → feed the backlog:  node contextkit/tools/scripts/pipeline.mjs ingest contextkit/memory/tech-debt-findings.json --type chore');
+    return;
+  }
+  const counts = report.findings.reduce((m, f) => ((m[f.kind] = (m[f.kind] || 0) + 1), m), {});
+  console.log(`🧹 Tech debt: ${report.findings.length} finding(s) across ${report.fileCount} files.`);
+  for (const [k, n] of Object.entries(counts)) console.log(`   ${k}: ${n}`);
+  for (const f of report.findings.slice(0, 15)) console.log(`   ${'●'.repeat(f.severity)} ${f.path}${f.line ? ':' + f.line : ''} — ${f.message}`);
+  if (report.findings.length > 15) console.log(`   … and ${report.findings.length - 15} more (use --write for the full board).`);
+}
+
+main().catch((err) => {
+  console.error('tech-debt-scan failed:', err?.message ?? err);
+  process.exit(1);
+});

package/templates/contextkit/tools/scripts/token-report.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * Token economy & usage insight (roadmap #7 / L6).
+ *
+ * Reports Claude Code token usage for THIS project by reading the local session
+ * transcripts (`~/.claude/projects/<project>/<sessionId>.jsonl`). Aggregates
+ * input / output / cache tokens per session and per ISO week, and warns when a
+ * session crosses the configured budget (`tokens.budgetPerSession`). Read-only,
+ * local, zero third-party deps; reports **aggregated counts only**, never content.
+ * Degrades to a clear "no data" message when transcripts aren't found.
+ *
+ * Usage:
+ *   node contextkit/tools/scripts/token-report.mjs            # this project (table)
+ *   node contextkit/tools/scripts/token-report.mjs --json
+ *   node contextkit/tools/scripts/token-report.mjs --all      # every project, not just cwd
+ *   node contextkit/tools/scripts/token-report.mjs --from <dir>   # read transcripts from <dir>
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { loadConfigSync } from '../../runtime/config/load.mjs';
+
+const ROOT = process.cwd();
+const norm = (p) => String(p || '').replace(/\\/g, '/').toLowerCase().replace(/\/+$/, '');
+const ROOT_N = norm(ROOT);
+const args = process.argv.slice(2);
+const flag = (name) => args.includes(name);
+const opt = (name) => {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+
+/** All `.jsonl` transcript files under the source dir (recursive, shallow). */
+function findTranscripts(fromDir) {
+  const base = fromDir || join(homedir(), '.claude', 'projects');
+  const out = [];
+  const walk = (dir, depth) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const p = join(dir, e.name);
+      if (e.isDirectory() && depth < 3) walk(p, depth + 1);
+      else if (e.isFile() && e.name.endsWith('.jsonl')) out.push(p);
+    }
+  };
+  if (existsSync(base)) walk(base, 0);
+  return out;
+}
+
+function isoWeek(ts) {
+  const d = new Date(ts);
+  if (Number.isNaN(d.getTime())) return 'unknown';
+  const t = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
+  t.setUTCDate(t.getUTCDate() + 4 - (t.getUTCDay() || 7));
+  const yearStart = new Date(Date.UTC(t.getUTCFullYear(), 0, 1));
+  const week = Math.ceil(((t - yearStart) / 86400000 + 1) / 7);
+  return `${t.getUTCFullYear()}-W${String(week).padStart(2, '0')}`;
+}
+
+/** sessionId → token totals, built from `message.usage` entries (filtered by cwd unless --all). */
+function aggregate(files, all) {
+  const sessions = new Map();
+  for (const file of files) {
+    let text;
+    try {
+      text = readFileSync(file, 'utf-8');
+    } catch {
+      continue;
+    }
+    for (const line of text.split('\n')) {
+      if (!line.trim()) continue;
+      let entry;
+      try {
+        entry = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      const usage = entry?.message?.usage;
+      if (!usage) continue;
+      if (!all && norm(entry.cwd) !== ROOT_N) continue;
+      const sid = entry.sessionId || file;
+      const s = sessions.get(sid) || { input: 0, output: 0, cacheRead: 0, cacheCreate: 0, turns: 0, at: '', week: 'unknown' };
+      s.input += usage.input_tokens || 0;
+      s.output += usage.output_tokens || 0;
+      s.cacheRead += usage.cache_read_input_tokens || 0;
+      s.cacheCreate += usage.cache_creation_input_tokens || 0;
+      s.turns += 1;
+      if (entry.timestamp && entry.timestamp > s.at) {
+        s.at = entry.timestamp;
+        s.week = isoWeek(entry.timestamp);
+      }
+      sessions.set(sid, s);
+    }
+  }
+  return sessions;
+}
+
+const sessionTotal = (s) => s.input + s.output + s.cacheRead + s.cacheCreate;
+const n = (x) => x.toLocaleString('en-US');
+
+function summarize(sessions) {
+  const rows = [...sessions.entries()].map(([sid, s]) => ({ sid, ...s, total: sessionTotal(s) }));
+  rows.sort((a, b) => b.total - a.total);
+  const totals = rows.reduce(
+    (t, r) => ({ input: t.input + r.input, output: t.output + r.output, cacheRead: t.cacheRead + r.cacheRead, cacheCreate: t.cacheCreate + r.cacheCreate, total: t.total + r.total }),
+    { input: 0, output: 0, cacheRead: 0, cacheCreate: 0, total: 0 },
+  );
+  const weeks = {};
+  for (const r of rows) weeks[r.week] = (weeks[r.week] || 0) + r.total;
+  return { rows, totals, weeks, sessions: rows.length };
+}
+
+function main() {
+  const budget = loadConfigSync(ROOT).tokens || { budgetPerSession: 0, warnAtPct: 80 };
+  const files = findTranscripts(opt('--from'));
+  const { rows, totals, weeks, sessions } = summarize(aggregate(files, flag('--all')));
+
+  if (flag('--json')) {
+    process.stdout.write(JSON.stringify({ sessions, totals, weeks, budget, perSession: rows }, null, 2) + '\n');
+    return;
+  }
+
+  console.log('\n🪙  ContextDevKit token report' + (flag('--all') ? ' (all projects)' : ` — ${ROOT}`) + '\n');
+  if (sessions === 0) {
+    console.log('No token usage found in Claude Code transcripts (~/.claude/projects/).');
+    console.log('Open this project in Claude Code and run a session, then try again.');
+    return;
+  }
+  console.log(`Sessions: ${sessions}   Total tokens: ${n(totals.total)}`);
+  console.log(`  input ${n(totals.input)} · output ${n(totals.output)} · cache-read ${n(totals.cacheRead)} · cache-write ${n(totals.cacheCreate)}\n`);
+
+  const over = budget.budgetPerSession > 0 ? rows.filter((r) => r.total >= (budget.budgetPerSession * (budget.warnAtPct || 100)) / 100) : [];
+  console.log('Top sessions by tokens:');
+  for (const r of rows.slice(0, 10)) {
+    const pct = budget.budgetPerSession > 0 ? ` (${Math.round((r.total / budget.budgetPerSession) * 100)}% of budget)` : '';
+    const hot = budget.budgetPerSession > 0 && r.total >= (budget.budgetPerSession * (budget.warnAtPct || 100)) / 100 ? ' ⚠️' : '';
+    console.log(`  ${String(r.sid).slice(0, 8)}  ${n(r.total).padStart(12)}  (${r.turns} turns)${pct}${hot}`);
+  }
+  console.log('\nPer ISO week:');
+  for (const [week, total] of Object.entries(weeks).sort()) console.log(`  ${week}  ${n(total)}`);
+
+  if (budget.budgetPerSession > 0) {
+    console.log(`\nBudget: ${n(budget.budgetPerSession)}/session (warn at ${budget.warnAtPct}%).` + (over.length ? ` ⚠️ ${over.length} session(s) over the warn line.` : ' ✅ all within budget.'));
+  } else {
+    console.log('\nNo per-session budget set. Configure with: /context-config set tokens.budgetPerSession <n>');
+  }
+}
+
+main();

package/templates/contextkit/tools/scripts/visual-test.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * Visual / browser-driven testing harness — scaffolder (roadmap #6).
+ *
+ * The kit does NOT bundle or run the browser runner (Playwright/Selenium are heavy
+ * PROJECT dependencies that download real browsers) — it SCAFFOLDS a starter and the
+ * project owns the runner. Stack-aware: JS (@playwright/test) + Python
+ * (pytest-playwright). Zero-dependency, defensive, write-if-missing.
+ *
+ *   visual-test.mjs status [--json]            # is a visual harness set up here?
+ *   visual-test.mjs scaffold [--js | --python] # write a starter (won't clobber)
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+const ROOT = process.cwd();
+const has = (p) => existsSync(resolve(ROOT, p));
+const read = (p) => {
+  try {
+    return readFileSync(resolve(ROOT, p), 'utf-8');
+  } catch {
+    return '';
+  }
+};
+const readJson = (p) => {
+  try {
+    return JSON.parse(read(p).replace(/^/, ''));
+  } catch {
+    return null;
+  }
+};
+
+const JS_CONFIGS = ['playwright.config.js', 'playwright.config.ts', 'playwright.config.mjs', 'cypress.config.js'];
+
+function detectStacks() {
+  const stacks = [];
+  // A stack counts if its manifest exists OR a visual harness is already scaffolded
+  // (so `status` recognizes an existing harness even in a bare project).
+  if (has('package.json') || JS_CONFIGS.some(has)) stacks.push('js');
+  if (has('pyproject.toml') || has('requirements.txt') || has('tests/visual/conftest.py')) stacks.push('python');
+  return stacks;
+}
+
+function jsStatus() {
+  const pkg = readJson('package.json') || {};
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  return {
+    runner: deps.cypress ? 'cypress' : 'playwright-js',
+    dep: !!(deps['@playwright/test'] || deps.playwright || deps.cypress),
+    config: JS_CONFIGS.some(has),
+  };
+}
+
+function pyStatus() {
+  const text = read('pyproject.toml') + read('requirements.txt');
+  return { runner: 'playwright-python', dep: /pytest-playwright|playwright|selenium/.test(text), config: has('tests/visual') };
+}
+
+function buildStatus() {
+  const stacks = detectStacks();
+  const report = {
+    stacks,
+    js: stacks.includes('js') ? jsStatus() : null,
+    python: stacks.includes('python') ? pyStatus() : null,
+  };
+  report.set = !!((report.js && (report.js.dep || report.js.config)) || (report.python && (report.python.dep || report.python.config)));
+  return report;
+}
+
+function writeIfMissing(rel, content) {
+  const abs = resolve(ROOT, rel);
+  if (existsSync(abs)) return [];
+  mkdirSync(dirname(abs), { recursive: true });
+  writeFileSync(abs, content, 'utf-8');
+  return [rel];
+}
+
+function scaffoldJs() {
+  const esm = (readJson('package.json') || {}).type === 'module';
+  const config = esm
+    ? `import { defineConfig, devices } from '@playwright/test';\n\nexport default defineConfig({\n  testDir: './tests/visual',\n  use: { baseURL: process.env.BASE_URL || 'http://localhost:3000' },\n  projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],\n});\n`
+    : `const { defineConfig, devices } = require('@playwright/test');\n\nmodule.exports = defineConfig({\n  testDir: './tests/visual',\n  use: { baseURL: process.env.BASE_URL || 'http://localhost:3000' },\n  projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],\n});\n`;
+  const spec = `import { test, expect } from '@playwright/test';\n\n// Visual baseline. The first run creates the snapshot; later runs diff against it.\n// Update intentionally with:  npx playwright test --update-snapshots\ntest('home page — visual baseline', async ({ page }) => {\n  await page.goto('/');\n  await expect(page).toHaveScreenshot('home.png', { maxDiffPixelRatio: 0.01 });\n});\n`;
+  return [...writeIfMissing('playwright.config.js', config), ...writeIfMissing('tests/visual/home.spec.js', spec)];
+}
+
+function scaffoldPython() {
+  const conftest = `import os\nimport pytest\n\n\n@pytest.fixture(scope="session")\ndef base_url():\n    return os.environ.get("BASE_URL", "http://localhost:3000")\n`;
+  const test = `# Visual baseline with pytest-playwright. Install:\n#   pip install pytest-playwright && playwright install chromium\n# Run:  pytest tests/visual\nimport pathlib\n\nSNAP = pathlib.Path(__file__).parent / "__screenshots__"\n\n\ndef test_home_visual_baseline(page, base_url):\n    SNAP.mkdir(exist_ok=True)\n    page.goto(base_url)\n    # First run writes the baseline; later runs compare. Swap in your team's\n    # visual-diff assertion (e.g. pytest-playwright-visual) when you adopt one.\n    page.screenshot(path=str(SNAP / "home.png"))\n`;
+  return [...writeIfMissing('tests/visual/conftest.py', conftest), ...writeIfMissing('tests/visual/test_home_visual.py', test)];
+}
+
+function runScaffold(only) {
+  const stacks = only ? [only] : detectStacks().length ? detectStacks() : ['js'];
+  const written = [];
+  for (const s of stacks) written.push(...(s === 'python' ? scaffoldPython() : scaffoldJs()));
+  if (written.length === 0) {
+    console.log('🖼️  visual-test: starter already present (nothing written).');
+    return;
+  }
+  console.log(`🖼️  visual-test: scaffolded ${written.length} file(s):`);
+  for (const w of written) console.log(`   + ${w}`);
+  console.log('\nNext — install the runner (a PROJECT dependency, never the kit):');
+  if (stacks.includes('js')) console.log('   npm i -D @playwright/test && npx playwright install chromium');
+  if (stacks.includes('python')) console.log('   pip install pytest-playwright && playwright install chromium');
+  console.log('   Point baseURL / BASE_URL at your running app, then run the visual suite.');
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const cmd = args[0];
+  if (cmd === 'status') {
+    const report = buildStatus();
+    if (args.includes('--json')) {
+      process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+      return;
+    }
+    console.log(`🖼️  visual-test status — stacks: ${report.stacks.join(', ') || 'none'}`);
+    if (report.js) console.log(`   JS:     runner=${report.js.runner} dep=${report.js.dep} config=${report.js.config}`);
+    if (report.python) console.log(`   Python: dep=${report.python.dep} layout=${report.python.config}`);
+    console.log(report.set ? '   ✓ a visual harness looks set up.' : '   ✗ no visual harness yet — run: visual-test.mjs scaffold');
+    return;
+  }
+  if (cmd === 'scaffold') {
+    runScaffold(args.includes('--python') ? 'python' : args.includes('--js') ? 'js' : null);
+    return;
+  }
+  console.error('Usage: visual-test.mjs <status [--json] | scaffold [--js|--python]>');
+  process.exit(1);
+}
+
+main();

package/templates/contextkit/tools/scripts/watch.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+/**
+ * `/watch` — tail the active session ledger.
+ *
+ * Default: print every modification recorded in the current session's ledger,
+ * formatted one-per-line, then exit.
+ *
+ * `--follow` (`-f`): re-read the ledger every 500ms and print only entries
+ * that appeared since the last read. Exits cleanly on SIGINT (Ctrl-C).
+ *
+ * Zero deps. Reuses `readMostRecentLedger` from the runtime so the active
+ * session resolution stays single-sourced (rule 4).
+ *
+ * Refused-silently-to-false-negative posture: if the ledger cannot be read,
+ * print the error and exit non-zero. Never pretend "0 entries."
+ */
+import { readMostRecentLedger } from '../../runtime/hooks/ledger.mjs';
+
+const FOLLOW_INTERVAL_MS = 500;
+
+const args = process.argv.slice(2);
+const follow = args.includes('-f') || args.includes('--follow');
+
+/**
+ * Format one ledger modification for stdout.
+ *
+ * @param {{ path: string, tool: string, at: number }} mod
+ * @returns {string}
+ */
+export function parseLedgerEntry(mod) {
+  if (!mod || typeof mod !== 'object') return '';
+  const at = typeof mod.at === 'number' ? new Date(mod.at) : new Date();
+  const hh = String(at.getHours()).padStart(2, '0');
+  const mm = String(at.getMinutes()).padStart(2, '0');
+  const ss = String(at.getSeconds()).padStart(2, '0');
+  const tool = (mod.tool || '?').toUpperCase().padEnd(5, ' ');
+  const path = mod.path || '<no path>';
+  return `[${hh}:${mm}:${ss}] ${tool} ${path}`;
+}
+
+async function loadEntries() {
+  const result = await readMostRecentLedger();
+  if (!result) return { sessionId: null, entries: [] };
+  const entries = Array.isArray(result.ledger?.modifications)
+    ? result.ledger.modifications
+    : [];
+  return { sessionId: result.sessionId, entries };
+}
+
+async function printAllOnce() {
+  const { sessionId, entries } = await loadEntries();
+  if (!sessionId) {
+    process.stderr.write('no active session — `/log-session` to register or start a new one\n');
+    process.exit(1);
+  }
+  process.stdout.write(`# session ${sessionId} — ${entries.length} entr${entries.length === 1 ? 'y' : 'ies'}\n`);
+  for (const mod of entries) process.stdout.write(parseLedgerEntry(mod) + '\n');
+}
+
+async function follower() {
+  let printedCount = 0;
+  let lastSessionId = null;
+  const tick = async () => {
+    try {
+      const { sessionId, entries } = await loadEntries();
+      if (!sessionId) return;
+      if (sessionId !== lastSessionId) {
+        process.stdout.write(`# session ${sessionId}\n`);
+        lastSessionId = sessionId;
+        printedCount = 0;
+      }
+      for (let i = printedCount; i < entries.length; i++) {
+        process.stdout.write(parseLedgerEntry(entries[i]) + '\n');
+      }
+      printedCount = entries.length;
+    } catch (err) {
+      process.stderr.write(`watch: ${err.message}\n`);
+    }
+  };
+  await tick();
+  const handle = setInterval(tick, FOLLOW_INTERVAL_MS);
+  const stop = () => {
+    clearInterval(handle);
+    process.stdout.write('\n# watch stopped\n');
+    process.exit(0);
+  };
+  process.on('SIGINT', stop);
+  process.on('SIGTERM', stop);
+}
+
+const isMain = (() => {
+  try {
+    const url = new URL(import.meta.url);
+    const arg = process.argv[1] ? new URL('file://' + process.argv[1].replace(/\\/g, '/')) : null;
+    return arg && url.pathname.toLowerCase() === arg.pathname.toLowerCase();
+  } catch {
+    return false;
+  }
+})();
+
+if (isMain) {
+  (follow ? follower() : printAllOnce()).catch((err) => {
+    process.stderr.write(`watch: ${err.message}\n`);
+    process.exit(1);
+  });
+}