@ijfw/memory-server 1.4.3 → 1.5.0

package/src/lib/repo-map.js

@@ -0,0 +1,392 @@
+// v1.5.0 audit-MED-tok-M1 — Repo-map / brief-compaction for subagent dispatch.
+//
+// Problem: subagent briefs that "dump the source" currently consume 5-10x
+// more input tokens than necessary. The orchestrator does not know which
+// files matter to a given task, so it conservatively includes everything.
+//
+// Solution (Aider-style, simplified): walk the repo, score each file with
+// TF-IDF on its symbols + path, and emit a compact map that fits in a fixed
+// token budget (default 1k tokens). The brief gets prepended with this map
+// so a downstream subagent can read it instead of crawling the tree.
+//
+// Design choices:
+//   - Zero deps (no tree-sitter, no fs-walk libs). The IJFW project rule is
+//     pure-Node. Symbol extraction is a regex pass (good enough for JS/TS/
+//     Python/Go signatures + markdown headings). PageRank is approximated
+//     with TF-IDF importance ranking — cheap, deterministic, and stable
+//     across runs.
+//   - Respects .gitignore via a simple parse (no glob library). The parse
+//     handles the common patterns: line comments, blank lines, leading "!"
+//     negations, trailing "/" directory markers, and "*" wildcards.
+//   - Token budget is enforced post-rank: take the top-N files until the
+//     running estimate of token cost (chars / 4) exceeds the budget.
+//
+// Public API:
+//   buildRepoMap({ rootDir, budgetTokens=1000, maxFiles=200, extensions=[...] })
+//     returns { files: [{ path, summary, importance }], totalTokens, truncated }
+//
+//   compactBriefForSubagent({ baseBrief, repoMap, maxPrefixTokens })
+//     returns { brief: string, repoMapTokens, baseBriefTokens }
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, sep, basename, extname } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_BUDGET_TOKENS = 1000;
+const DEFAULT_MAX_FILES     = 200;
+const TOKENS_PER_CHAR       = 1 / 4;  // ~4 chars per token (Anthropic/OpenAI average)
+
+// File extensions considered "code" by default. Markdown/JSON ride along
+// because they often carry the most-informative summaries (README, package.json).
+const DEFAULT_EXTENSIONS = new Set([
+  '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx',
+  '.py', '.go', '.rs', '.rb', '.java', '.kt', '.swift',
+  '.c', '.cc', '.cpp', '.h', '.hpp',
+  '.md', '.json', '.yaml', '.yml', '.toml',
+]);
+
+// Always-skip directory names (independent of .gitignore). These are
+// universally noise for repo-map purposes.
+const ALWAYS_SKIP_DIRS = new Set([
+  '.git', 'node_modules', '.svn', '.hg', '__pycache__',
+  '.next', '.nuxt', '.cache', '.vercel', 'dist', 'build', 'coverage',
+  '.pytest_cache', '.mypy_cache', '.tox', 'venv', '.venv', 'env',
+  // IJFW-specific noise
+  '.ijfw', '.planning',
+]);
+
+// ---------------------------------------------------------------------------
+// .gitignore parsing — minimal but covers the cases that matter.
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a .gitignore file into a list of matcher objects.
+ * Each matcher is { pattern, negate, dirOnly, anchored, regex }.
+ *
+ * @param {string} content
+ * @returns {Array}
+ */
+export function parseGitignore(content) {
+  if (typeof content !== 'string') return [];
+  const matchers = [];
+  for (const rawLine of content.split('\n')) {
+    let line = rawLine.replace(/\r$/, '');
+    line = line.replace(/\s+$/, '');
+    if (line.length === 0) continue;
+    if (line.startsWith('#')) continue;
+    let negate = false;
+    if (line.startsWith('!')) {
+      negate = true;
+      line = line.slice(1);
+    }
+    let anchored = false;
+    if (line.startsWith('/')) {
+      anchored = true;
+      line = line.slice(1);
+    }
+    let dirOnly = false;
+    if (line.endsWith('/')) {
+      dirOnly = true;
+      line = line.slice(0, -1);
+    }
+    if (line.length === 0) continue;
+    matchers.push({ pattern: line, negate, dirOnly, anchored, regex: globToRegex(line, anchored) });
+  }
+  return matchers;
+}
+
+// Glob -> RegExp. Supports: *, **, ?, character classes.
+function globToRegex(glob, anchored) {
+  let re = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        re += '.*';
+        i++;
+        if (glob[i + 1] === '/') i++;
+      } else {
+        re += '[^/]*';
+      }
+    } else if (c === '?') {
+      re += '[^/]';
+    } else if (c === '.' || c === '+' || c === '(' || c === ')' || c === '|' || c === '^' || c === '$' || c === '\\') {
+      re += '\\' + c;
+    } else if (c === '/') {
+      re += '/';
+    } else {
+      re += c;
+    }
+  }
+  const prefix = anchored ? '^' : '(^|.*/)';
+  const suffix = '(/.*)?$';
+  return new RegExp(prefix + re + suffix);
+}
+
+/**
+ * Test a relative posix-style path against parsed .gitignore matchers.
+ * Returns true if the path should be IGNORED.
+ *
+ * @param {string} relPathPosix
+ * @param {boolean} isDir
+ * @param {Array} matchers
+ * @returns {boolean}
+ */
+export function isIgnored(relPathPosix, isDir, matchers) {
+  let ignored = false;
+  for (const m of matchers) {
+    if (m.dirOnly && !isDir) continue;
+    if (m.regex.test(relPathPosix)) {
+      ignored = !m.negate;
+    }
+  }
+  return ignored;
+}
+
+// ---------------------------------------------------------------------------
+// Filesystem walk
+// ---------------------------------------------------------------------------
+
+function* walkFiles(rootDir, matchers, extensions) {
+  const stack = [rootDir];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const ent of entries) {
+      const abs = join(dir, ent.name);
+      const rel = relative(rootDir, abs).split(sep).join('/');
+      if (ent.isDirectory()) {
+        if (ALWAYS_SKIP_DIRS.has(ent.name)) continue;
+        if (isIgnored(rel, true, matchers)) continue;
+        stack.push(abs);
+      } else if (ent.isFile()) {
+        if (isIgnored(rel, false, matchers)) continue;
+        if (extensions && !extensions.has(extname(ent.name).toLowerCase())) continue;
+        yield { abs, rel };
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Symbol extraction + TF-IDF
+// ---------------------------------------------------------------------------
+
+// Heuristic regex-based symbol extractor. Catches:
+//   - JS/TS: function foo, const foo =, class Foo, export ...
+//   - Python: def foo, class Foo
+//   - Go: func Foo
+//   - Markdown: ^# heading text
+// The goal is "stable enough to rank importance", not perfect AST parsing.
+/* eslint-disable security/detect-unsafe-regex --
+ * SYMBOL_PATTERNS scans developer-authored source code files on the local
+ * filesystem (not untrusted network input). Each alternation segment is
+ * bounded by the source file's line length and the identifier character
+ * class is bounded by line content. ReDoS attack surface is not present
+ * because the input is repo content the developer chose to add.
+ */
+const SYMBOL_PATTERNS = [
+  /(?:^|\n)\s*(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/g,
+  /(?:^|\n)\s*(?:export\s+)?class\s+([A-Za-z_$][\w$]*)/g,
+  /(?:^|\n)\s*(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=/g,
+  /(?:^|\n)\s*def\s+([A-Za-z_][\w]*)/g,
+  /(?:^|\n)\s*func\s+(?:\([^)]*\)\s+)?([A-Z][\w]*)/g,
+  /(?:^|\n)#{1,3}\s+(.{1,80})/g,
+];
+/* eslint-enable security/detect-unsafe-regex */
+
+function extractSymbols(content) {
+  const symbols = [];
+  for (const pat of SYMBOL_PATTERNS) {
+    let m;
+    pat.lastIndex = 0;
+    while ((m = pat.exec(content)) !== null) {
+      const s = m[1];
+      if (s && s.length > 0) symbols.push(s.trim());
+    }
+  }
+  return symbols;
+}
+
+// Build a TF-IDF importance score per file. "Document" = file's symbols +
+// path components. "Corpus" = all scanned files. Files with more distinctive
+// symbols (rare across the corpus) score higher.
+function tfidfScore(perFileTokens) {
+  const docFreq = new Map();
+  for (const tokens of perFileTokens.values()) {
+    const uniq = new Set(tokens);
+    for (const t of uniq) docFreq.set(t, (docFreq.get(t) || 0) + 1);
+  }
+  const N = perFileTokens.size;
+  const scores = new Map();
+  for (const [path, tokens] of perFileTokens.entries()) {
+    if (tokens.length === 0) { scores.set(path, 0); continue; }
+    const tf = new Map();
+    for (const t of tokens) tf.set(t, (tf.get(t) || 0) + 1);
+    let score = 0;
+    for (const [t, count] of tf.entries()) {
+      const df = docFreq.get(t) || 1;
+      const idf = Math.log((N + 1) / df) + 1;
+      score += (count / tokens.length) * idf;
+    }
+    scores.set(path, score);
+  }
+  return scores;
+}
+
+// ---------------------------------------------------------------------------
+// Public API: buildRepoMap
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a compact, importance-ranked map of the repo.
+ *
+ * @param {object} args
+ * @param {string} args.rootDir
+ * @param {number} [args.budgetTokens=1000]
+ * @param {number} [args.maxFiles=200]
+ * @param {Set<string>|string[]} [args.extensions]
+ * @returns {{ files: Array<{path:string, summary:string, importance:number}>, totalTokens:number, truncated:boolean, scannedCount:number }}
+ */
+export function buildRepoMap({ rootDir, budgetTokens = DEFAULT_BUDGET_TOKENS, maxFiles = DEFAULT_MAX_FILES, extensions } = {}) {
+  if (typeof rootDir !== 'string' || rootDir.length === 0) {
+    throw new TypeError('buildRepoMap: rootDir is required');
+  }
+  try {
+    const st = statSync(rootDir);
+    if (!st.isDirectory()) throw new Error('rootDir must be a directory');
+  } catch (err) {
+    throw new Error(`buildRepoMap: cannot access rootDir "${rootDir}": ${err.message}`);
+  }
+
+  const extSet = extensions instanceof Set
+    ? extensions
+    : Array.isArray(extensions)
+      ? new Set(extensions.map(e => e.toLowerCase()))
+      : DEFAULT_EXTENSIONS;
+
+  let matchers = [];
+  try {
+    const giContent = readFileSync(join(rootDir, '.gitignore'), 'utf8');
+    matchers = parseGitignore(giContent);
+  } catch {
+    matchers = [];
+  }
+
+  const perFileTokens = new Map();
+  const perFileSummary = new Map();
+  let scannedCount = 0;
+  for (const { abs, rel } of walkFiles(rootDir, matchers, extSet)) {
+    scannedCount++;
+    if (scannedCount > 10_000) break;
+    let content = '';
+    try {
+      content = readFileSync(abs, 'utf8');
+    } catch {
+      continue;
+    }
+    if (content.length > 256 * 1024) content = content.slice(0, 256 * 1024);
+
+    const symbols = extractSymbols(content);
+    const pathTokens = rel.split(/[/.]/).filter(t => t.length > 1);
+    perFileTokens.set(rel, [...symbols, ...pathTokens]);
+
+    const distinct = [...new Set(symbols)].slice(0, 3);
+    const firstLine = (content.split('\n').find(l => l.trim().length > 0) || '').trim().slice(0, 80);
+    const summary = distinct.length > 0
+      ? `${distinct.join(', ')}${firstLine ? ` - ${firstLine}` : ''}`
+      : firstLine || basename(rel);
+    perFileSummary.set(rel, summary);
+  }
+
+  const scores = tfidfScore(perFileTokens);
+  const ranked = [...perFileTokens.keys()]
+    .map(p => ({ path: p, summary: perFileSummary.get(p) || basename(p), importance: scores.get(p) || 0 }))
+    .sort((a, b) => b.importance - a.importance);
+
+  const limited = ranked.slice(0, maxFiles);
+
+  const out = [];
+  let running = 0;
+  let truncated = false;
+  for (const entry of limited) {
+    const line = `${entry.path}: ${entry.summary}\n`;
+    const cost = Math.ceil(line.length * TOKENS_PER_CHAR);
+    if (running + cost > budgetTokens) {
+      truncated = true;
+      break;
+    }
+    out.push(entry);
+    running += cost;
+  }
+
+  return { files: out, totalTokens: running, truncated, scannedCount };
+}
+
+// ---------------------------------------------------------------------------
+// Public API: compactBriefForSubagent
+// ---------------------------------------------------------------------------
+
+/**
+ * Inject a repo-map prefix block in front of a subagent brief.
+ *
+ * @param {object} args
+ * @param {string} args.baseBrief
+ * @param {object} args.repoMap                 - output of buildRepoMap()
+ * @param {number} [args.maxPrefixTokens=1000]
+ * @returns {{ brief: string, repoMapTokens: number, baseBriefTokens: number }}
+ */
+export function compactBriefForSubagent({ baseBrief, repoMap, maxPrefixTokens = DEFAULT_BUDGET_TOKENS } = {}) {
+  if (typeof baseBrief !== 'string') {
+    throw new TypeError('compactBriefForSubagent: baseBrief must be a string');
+  }
+  if (!repoMap || !Array.isArray(repoMap.files)) {
+    return {
+      brief: baseBrief,
+      repoMapTokens: 0,
+      baseBriefTokens: Math.ceil(baseBrief.length * TOKENS_PER_CHAR),
+    };
+  }
+
+  const header = '--- REPO MAP (importance-ranked, regex-extracted) ---\n';
+  const footer = '--- END REPO MAP ---\n\n';
+  const fixedCost = Math.ceil((header.length + footer.length) * TOKENS_PER_CHAR);
+  let budget = Math.max(0, maxPrefixTokens - fixedCost);
+
+  const lines = [];
+  let running = 0;
+  for (const f of repoMap.files) {
+    const line = `${f.path}: ${f.summary}\n`;
+    const cost = Math.ceil(line.length * TOKENS_PER_CHAR);
+    if (running + cost > budget) break;
+    lines.push(line);
+    running += cost;
+  }
+
+  const prefix = lines.length > 0
+    ? header + lines.join('') + footer
+    : '';
+
+  const brief = prefix + baseBrief;
+  return {
+    brief,
+    repoMapTokens: prefix.length > 0 ? Math.ceil(prefix.length * TOKENS_PER_CHAR) : 0,
+    baseBriefTokens: Math.ceil(baseBrief.length * TOKENS_PER_CHAR),
+  };
+}
+
+// Constants exported for tests + docs.
+export const REPO_MAP_DEFAULTS = {
+  budgetTokens: DEFAULT_BUDGET_TOKENS,
+  maxFiles: DEFAULT_MAX_FILES,
+  tokensPerChar: TOKENS_PER_CHAR,
+  extensions: DEFAULT_EXTENSIONS,
+};

package/src/lib/shasum-verify.js

@@ -0,0 +1,164 @@
+// shasum-verify.js -- cross-verify a target npm release against the GitLab
+// release asset shasum. Second-factor integrity check on top of
+// `npm audit signatures` (F-SEC-7, v1.5.0 audit-H2.2).
+//
+// THREAT MODEL
+//   `npm audit signatures` proves the tarball was signed by the package's
+//   npm registry signing keys. This module independently fetches the
+//   shasum the publisher recorded on the GitLab release page and compares
+//   it against the npm-reported tarball shasum. A divergence means either
+//   the npm registry is serving a tampered tarball, OR the GitLab release
+//   was tampered with, OR the publisher made an inconsistent release.
+//   In all cases: refuse to install.
+//
+// MODES
+//   verified -- npm and GitLab shasums both available and match.
+//   mismatch -- both available but DIFFER. Fail closed.
+//   advisory -- GitLab side missing (older release, no shasum published,
+//               or transient fetch failure). Caller decides whether to
+//               proceed: interactive prompts for confirmation, non-
+//               interactive must abort.
+//   error    -- npm side missing (no shasum reported by `npm view`).
+//               This indicates a deeper problem; refuse to install.
+//
+// CALLER CONTRACT
+//   verifyShasumCrossSource(version, opts, deps) returns
+//     { ok: boolean, mode, npmShasum, releaseShasum, message }
+//   The orchestrator MUST refuse to install when ok === false.
+//   advisory mode returns ok: true with a `requiresConfirmation: true`
+//   flag so the orchestrator can prompt or fail-closed in non-interactive.
+
+import { spawnSync } from 'node:child_process';
+
+// Default GitLab project path. Kept here so tests can override.
+export const DEFAULT_GITLAB_PROJECT = 'therealseandonahoe%2Fijfw';
+
+// Hex shasum extractor. Accepts standalone hex lines (sha1=40 hex, sha256=64
+// hex) or the common labelled forms used in release notes:
+//   shasum: <hex>
+//   sha1:   <hex>
+//   sha256: <hex>
+//   sha512: <hex>
+// Returns the first 40-or-more hex run that looks like a shasum.
+// Case-insensitive comparison happens at compare time.
+const SHASUM_LABEL_RE = /(?:shasum|sha-?(?:1|256|512))\s*[:=]\s*([a-f0-9]{40,128})/i;
+const SHASUM_BARE_RE = /\b([a-f0-9]{40})\b/i; // sha1 length is what npm publishes
+const SHASUM256_BARE_RE = /\b([a-f0-9]{64})\b/i;
+
+export function extractShasumFromText(text) {
+  if (!text || typeof text !== 'string') return null;
+  const labelMatch = text.match(SHASUM_LABEL_RE);
+  if (labelMatch) return labelMatch[1].toLowerCase();
+  // Fall back to bare hex runs only if a label wasn't found. Prefer sha256
+  // first because sha1 has higher false-positive risk in narrative text.
+  const m256 = text.match(SHASUM256_BARE_RE);
+  if (m256) return m256[1].toLowerCase();
+  const m1 = text.match(SHASUM_BARE_RE);
+  if (m1) return m1[1].toLowerCase();
+  return null;
+}
+
+// Default deps: real npm + real curl. Tests inject pure-JS mocks.
+const DEFAULT_DEPS = Object.freeze({
+  // (pkg, version) -> { ok, shasum, message }
+  fetchNpmShasum(pkg, version) {
+    const ref = `${pkg}@${version}`;
+    const r = spawnSync('npm', ['view', ref, 'dist.shasum', '--json'], {
+      encoding: 'utf8',
+      timeout: 15_000,
+      shell: process.platform === 'win32',
+    });
+    if (r.error) return { ok: false, message: `spawn-${r.error.code || 'unknown'}` };
+    if (r.signal) return { ok: false, message: `killed by ${r.signal}` };
+    if (r.status !== 0) {
+      const stderr = (r.stderr || '').trim();
+      return { ok: false, message: stderr || `npm view exited ${r.status}` };
+    }
+    // npm view ... --json returns the string wrapped in quotes
+    const raw = (r.stdout || '').trim().replace(/^"|"$/g, '');
+    if (!/^[a-f0-9]{40}$/i.test(raw)) {
+      return { ok: false, message: `npm returned non-shasum: ${raw.slice(0, 80)}` };
+    }
+    return { ok: true, shasum: raw.toLowerCase() };
+  },
+  // (project, version) -> { ok, body, message }
+  fetchGitlabReleaseBody(project, version) {
+    const url = `https://gitlab.com/api/v4/projects/${project}/releases/v${version}`;
+    const r = spawnSync('curl', ['-fsSL', '-H', 'User-Agent: ijfw', url], {
+      encoding: 'utf8',
+      timeout: 10_000,
+    });
+    if (r.error) return { ok: false, message: `spawn-${r.error.code || 'unknown'}` };
+    if (r.signal) return { ok: false, message: `killed by ${r.signal}` };
+    if (r.status !== 0) {
+      return { ok: false, message: `curl exited ${r.status}` };
+    }
+    try {
+      const data = JSON.parse(r.stdout || '{}');
+      return { ok: true, body: data.description || '' };
+    } catch {
+      return { ok: false, message: 'release JSON parse failed' };
+    }
+  },
+});
+
+// version: semver string (validated by caller)
+// opts: { pkg = '@ijfw/install', project = DEFAULT_GITLAB_PROJECT }
+// deps: optional mock injection
+export function verifyShasumCrossSource(version, opts = {}, deps = DEFAULT_DEPS) {
+  const pkg = opts.pkg || '@ijfw/install';
+  const project = opts.project || DEFAULT_GITLAB_PROJECT;
+  const fetchNpm = deps.fetchNpmShasum || DEFAULT_DEPS.fetchNpmShasum;
+  const fetchRelease = deps.fetchGitlabReleaseBody || DEFAULT_DEPS.fetchGitlabReleaseBody;
+
+  const npmRes = fetchNpm(pkg, version);
+  if (!npmRes.ok) {
+    return {
+      ok: false,
+      mode: 'error',
+      npmShasum: null,
+      releaseShasum: null,
+      message: `npm shasum lookup failed: ${npmRes.message}`,
+    };
+  }
+  const npmShasum = String(npmRes.shasum || '').toLowerCase();
+
+  const releaseRes = fetchRelease(project, version);
+  if (!releaseRes.ok) {
+    return {
+      ok: true,
+      mode: 'advisory',
+      requiresConfirmation: true,
+      npmShasum,
+      releaseShasum: null,
+      message: `release shasum unavailable (${releaseRes.message}); proceed only with explicit confirmation`,
+    };
+  }
+  const releaseShasum = extractShasumFromText(releaseRes.body);
+  if (!releaseShasum) {
+    return {
+      ok: true,
+      mode: 'advisory',
+      requiresConfirmation: true,
+      npmShasum,
+      releaseShasum: null,
+      message: 'GitLab release does not list a shasum for this version; proceed only with explicit confirmation',
+    };
+  }
+  if (releaseShasum.toLowerCase() !== npmShasum) {
+    return {
+      ok: false,
+      mode: 'mismatch',
+      npmShasum,
+      releaseShasum: releaseShasum.toLowerCase(),
+      message: `shasum mismatch: npm=${npmShasum} release=${releaseShasum.toLowerCase()}`,
+    };
+  }
+  return {
+    ok: true,
+    mode: 'verified',
+    npmShasum,
+    releaseShasum: releaseShasum.toLowerCase(),
+    message: 'shasum cross-verified (npm dist.shasum matches GitLab release asset)',
+  };
+}

package/src/lib/sketches-gc.js

@@ -0,0 +1,132 @@
+// sketches-gc.js -- v1.5.0 audit-MED-design-#9.
+//
+// Auto-archive sketches older than N days from .planning/sketches/ to
+// .planning/sketches/.archive/.  Idempotent.  Zero deps.  Pure stdlib.
+//
+// Design notes:
+//   - "Sketches" are throwaway HTML mockups under .planning/sketches/<name>/.
+//     Without GC they accumulate indefinitely -- the audit MED.
+//   - Default age: 30 days (configurable via opts.maxAgeMs).
+//   - Archive layout: .planning/sketches/.archive/<original-name>/.  If a name
+//     collision happens (re-archived twice), suffix with timestamp.
+//   - mtime is used (not ctime) -- editing a sketch keeps it fresh.
+//   - Walks ONE level deep.  Each top-level entry under sketches/ is either a
+//     directory (a sketch) or a stray file (also archived).
+//   - Returns {archived: [{from, to}], skipped: [{path, reason}], scannedAt}.
+//
+// Used by:
+//   - `ijfw run sketches-gc [--root <dir>] [--max-age-days <n>] [--dry-run]`
+//     via cross-orchestrator-cli.js
+//   - Any cron / hook that wants a maintenance pass.
+
+import { existsSync, mkdirSync, readdirSync, renameSync, statSync } from 'node:fs';
+import { join, basename } from 'node:path';
+
+const DEFAULT_MAX_AGE_DAYS = 30;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+/**
+ * Run a GC pass over a sketches directory.
+ *
+ * @param {object} opts
+ * @param {string} [opts.root]         Sketches root.  Default: .planning/sketches relative to cwd.
+ * @param {number} [opts.maxAgeMs]     Max age in ms.  Default: 30 days.
+ * @param {number} [opts.maxAgeDays]   Convenience -- overrides maxAgeMs when set.
+ * @param {boolean} [opts.dryRun]      When true, return the plan but do not move anything.
+ * @param {Date}   [opts.now]          Reference "now" -- injected for tests.
+ * @returns {{archived: Array<{from:string,to:string,ageDays:number}>, skipped: Array<{path:string,reason:string}>, scannedAt:string, archiveDir:string, root:string}}
+ */
+export function runSketchesGc(opts = {}) {
+  const root = opts.root || join(process.cwd(), '.planning', 'sketches');
+  const now = opts.now instanceof Date ? opts.now : new Date();
+  const maxAgeMs =
+    typeof opts.maxAgeDays === 'number'
+      ? opts.maxAgeDays * MS_PER_DAY
+      : typeof opts.maxAgeMs === 'number'
+        ? opts.maxAgeMs
+        : DEFAULT_MAX_AGE_DAYS * MS_PER_DAY;
+  const dryRun = opts.dryRun === true;
+
+  const archived = [];
+  const skipped = [];
+  const archiveDir = join(root, '.archive');
+  const scannedAt = now.toISOString();
+
+  if (!existsSync(root)) {
+    return { archived, skipped, scannedAt, archiveDir, root };
+  }
+
+  // Ensure archive dir exists (unless dry-run, then we just record intent).
+  if (!dryRun && !existsSync(archiveDir)) {
+    mkdirSync(archiveDir, { recursive: true, mode: 0o755 });
+  }
+
+  let entries;
+  try {
+    entries = readdirSync(root, { withFileTypes: true });
+  } catch (e) {
+    return { archived, skipped: [{ path: root, reason: `readdir-failed: ${e.code || e.message}` }], scannedAt, archiveDir, root };
+  }
+
+  for (const entry of entries) {
+    const name = entry.name;
+    // Skip the archive dir itself + dotfiles (hidden state, READMEs, etc.).
+    if (name === '.archive') continue;
+    if (name.startsWith('.')) {
+      skipped.push({ path: join(root, name), reason: 'dotfile' });
+      continue;
+    }
+    const src = join(root, name);
+    let st;
+    try {
+      st = statSync(src);
+    } catch (e) {
+      skipped.push({ path: src, reason: `stat-failed: ${e.code || e.message}` });
+      continue;
+    }
+    const ageMs = now.getTime() - st.mtimeMs;
+    if (ageMs < maxAgeMs) {
+      skipped.push({ path: src, reason: `fresh (age ${Math.round(ageMs / MS_PER_DAY)}d)` });
+      continue;
+    }
+
+    // Resolve destination.  Collision -> suffix with timestamp.
+    let dest = join(archiveDir, name);
+    if (existsSync(dest)) {
+      const stamp = now.toISOString().replace(/[:.]/g, '-');
+      dest = join(archiveDir, `${name}.${stamp}`);
+    }
+
+    if (dryRun) {
+      archived.push({ from: src, to: dest, ageDays: Math.round(ageMs / MS_PER_DAY) });
+      continue;
+    }
+
+    try {
+      renameSync(src, dest);
+      archived.push({ from: src, to: dest, ageDays: Math.round(ageMs / MS_PER_DAY) });
+    } catch (e) {
+      skipped.push({ path: src, reason: `rename-failed: ${e.code || e.message}` });
+    }
+  }
+
+  return { archived, skipped, scannedAt, archiveDir, root };
+}
+
+/**
+ * Human-readable summary of a GC result -- one line per category.
+ * @param {ReturnType<typeof runSketchesGc>} result
+ */
+export function formatGcResult(result) {
+  const lines = [];
+  lines.push(`sketches-gc -- scanned ${result.root} at ${result.scannedAt}`);
+  lines.push(`  archived: ${result.archived.length}`);
+  for (const a of result.archived) {
+    lines.push(`    ${basename(a.from)}  (${a.ageDays}d)  ->  ${a.to}`);
+  }
+  lines.push(`  skipped:  ${result.skipped.length}`);
+  for (const s of result.skipped) {
+    lines.push(`    ${basename(s.path)}  -- ${s.reason}`);
+  }
+  return lines.join('\n');
+}