@1agh/maude 0.22.2 → 0.24.0

package/cli/lib/cache.mjs

@@ -0,0 +1,407 @@
+// Sidecar cache layer — Phase C / DDR-061.
+//
+// A tiny, zero-dependency JSON cache that lets expensive cross-session work
+// (ux-research-agent discovery, codebase-intelligence scans, design-context
+// token parsing, security-review reuse) be reused instead of recomputed.
+//
+// Used by:
+//   - cli/commands/cache.mjs       (`maude cache list|clear|inspect|stats`)
+//   - plugins/design/agents/ux-research-agent.md   (research/domain + research/project)
+//   - plugins/flow/skills/codebase-intelligence/SKILL.md   (codebase-intelligence)
+//   - plugins/design/commands/{edit,new}.md         (design-context)
+//   - plugins/flow/commands/{done,validate,validate-security}.md   (security)
+//   - plugins/flow/commands/validate.md                            (validate — skip-if-clean)
+//
+// On-disk layout (relative to the cache root, default `<repo>/.ai/cache/`):
+//
+//   .ai/cache/
+//   ├── _stats.json                              # hit/miss counters (best-effort telemetry)
+//   ├── research/domain/<slug>.<sha8>.json       # committed — shareable per-domain pool
+//   ├── research/project/<repo-sha>/<sha>.json   # gitignored — brief-specific layer
+//   ├── codebase-intelligence/<files-sha>.json   # committed — keyed on git SHA
+//   ├── design-context/<ds-name>/<tokens-sha>.json
+//   ├── security/<head-sha>.json                 # gitignored — review reuse, 1 h TTL
+//   ├── scenario/<name>/<route-sha>.json         # gitignored — per-run
+//   └── validate/<branch>.json                   # gitignored — skip-if-clean, 24 h TTL
+//
+// ## Invalidation policy (load-bearing — see C6 + .ai/cache/README.md)
+//
+//   | Layer                  | Fresh window (ttlMs) | Hard ceiling (maxAgeMs) | Invalidates on        |
+//   | ---------------------- | -------------------- | ----------------------- | --------------------- |
+//   | research/domain        | 7 days               | 30 days                 | domain slug change    |
+//   | research/project       | 30 days              | 90 days                 | brief SHA change      |
+//   | codebase-intelligence  | until SHA changes    | —                       | git HEAD / files SHA  |
+//   | design-context         | until tokens change  | —                       | tokens.css mtime SHA  |
+//   | security               | 1 hour               | 1 hour                  | HEAD SHA change       |
+//   | scenario               | until covered change | —                       | covered-file mtime    |
+//   | validate               | 24 hours             | 24 hours                | tree fingerprint Δ    |
+//
+// Most layers are keyed on a content/SHA so the key itself IS the invalidation
+// signal (a changed input produces a new key → guaranteed miss). The TTL fields
+// matter for the time-decayed layers (research/*, security) where the same key
+// can legitimately go stale without its inputs changing.
+//
+// Correctness > hit-rate: a wrong cached payload silently biases everything
+// downstream, so `getOrCompute` only serves a *stale* (past-ttl, within-maxAge)
+// entry as a fallback when `compute()` THROWS — never speculatively.
+
+import { spawnSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
+
+const STATS_FILE = '_stats.json';
+const RESERVED = new Set([STATS_FILE, 'README.md']);
+
+// Written into a fresh cache root the first time the cache is used on a machine,
+// so the invalidation policy is discoverable next to the data it governs.
+// This file is gitignored (see ai-skeleton/gitignore + repo .gitignore).
+const README = `# Maude sidecar cache
+
+Generated by \`cli/lib/cache.mjs\` (Phase C / DDR-061). Reusable, cross-session
+results for expensive work so the same computation is not re-run every invocation.
+
+## Layers
+
+| Layer                   | Key                          | Fresh (ttl) | Ceiling (maxAge) | Invalidates on        | Git      |
+| ----------------------- | ---------------------------- | ----------- | ---------------- | --------------------- | -------- |
+| \`research/domain\`        | \`<domain-slug>.<sha8>\`       | 7 days      | 30 days          | domain slug change    | committed |
+| \`research/project\`       | \`<repo-sha>/<brief-sha>\`     | 30 days     | 90 days          | brief SHA change      | ignored  |
+| \`codebase-intelligence\`  | \`<files-or-head-sha>\`        | until SHA Δ | —                | git HEAD / files SHA  | committed |
+| \`design-context\`         | \`<ds-name>/<tokens-sha>\`     | until Δ     | —                | tokens.css mtime SHA  | ignored  |
+| \`security\`               | \`<head-sha>\`                 | 1 hour      | 1 hour           | HEAD SHA change       | ignored  |
+| \`scenario\`               | \`<name>/<covers-sha>\`        | until Δ     | —                | covered-file mtime    | ignored  |
+| \`validate\`               | \`<branch>\`                   | 24 hours    | 24 hours         | tree fingerprint Δ    | ignored  |
+
+## Invalidation policy (load-bearing — correctness > hit-rate)
+
+- Most layers are **content-addressed**: the key embeds a SHA of the inputs, so
+  a changed input produces a new key → a guaranteed miss. The key IS the
+  invalidation signal.
+- The **time-decayed** layers (\`research/*\`, \`security\`) can go stale without
+  their inputs changing, so they carry an explicit TTL. \`security\` is a hard
+  1-hour window keyed on HEAD; \`research/domain\` is fresh for 7 days and is
+  served stale (up to 30 days) ONLY as a fallback when recompute throws.
+- A wrong cached payload silently biases everything downstream, so
+  \`getOrCompute\` never serves a stale entry speculatively — only on compute error.
+
+## Management
+
+\`\`\`sh
+maude cache list              # layers, entry counts, sizes, last-write
+maude cache stats             # hit/miss counters per layer
+maude cache inspect <layer>   # pretty-print entries in a layer
+maude cache clear [layer]     # wipe one layer, or everything
+\`\`\`
+`;
+
+const ensuredReadme = new Set();
+
+// Lazily drop the README into a fresh cache root (once per root per process).
+function ensureReadme(cacheRoot) {
+  if (ensuredReadme.has(cacheRoot)) return;
+  ensuredReadme.add(cacheRoot);
+  try {
+    const readmePath = join(cacheRoot, 'README.md');
+    if (!existsSync(readmePath)) {
+      mkdirSync(cacheRoot, { recursive: true });
+      writeFileSync(readmePath, README, 'utf8');
+    }
+  } catch {
+    /* documentation is non-fatal */
+  }
+}
+
+/**
+ * Resolve the cache root directory.
+ * Order: opts.cacheDir → $MAUDE_CACHE_DIR → $CLAUDE_PROJECT_DIR/.ai/cache → cwd/.ai/cache.
+ */
+export function resolveCacheRoot(opts = {}) {
+  if (opts.cacheDir) return resolve(opts.cacheDir);
+  if (process.env.MAUDE_CACHE_DIR) return resolve(process.env.MAUDE_CACHE_DIR);
+  if (process.env.CLAUDE_PROJECT_DIR) return resolve(process.env.CLAUDE_PROJECT_DIR, '.ai/cache');
+  return resolve(process.cwd(), '.ai/cache');
+}
+
+// Resolve <root>/<layer>/<key>.json, refusing any path that escapes the root.
+function entryPath(cacheRoot, layer, key) {
+  if (typeof layer !== 'string' || layer.length === 0) {
+    throw new TypeError('cache: layer must be a non-empty string');
+  }
+  if (typeof key !== 'string' || key.length === 0) {
+    throw new TypeError('cache: key must be a non-empty string');
+  }
+  const full = resolve(cacheRoot, layer, `${key}.json`);
+  const rel = relative(cacheRoot, full);
+  if (rel.startsWith('..') || rel.startsWith(sep) || resolve(cacheRoot, rel) !== full) {
+    throw new Error(`cache: layer/key escapes cache root: ${layer}/${key}`);
+  }
+  return full;
+}
+
+// tempfile + rename — readers never observe a half-written file, and two
+// concurrent writers each land an intact JSON document (last rename wins).
+function atomicWriteJson(filePath, obj) {
+  mkdirSync(resolve(filePath, '..'), { recursive: true });
+  const tmp = `${filePath}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(obj, null, 2)}\n`, 'utf8');
+  renameSync(tmp, filePath);
+}
+
+function bumpStat(cacheRoot, layer, kind) {
+  // Best-effort telemetry — never throw into the caller's hot path.
+  try {
+    const statsPath = join(cacheRoot, STATS_FILE);
+    let stats = { hits: {}, misses: {}, since: Date.now() };
+    if (existsSync(statsPath)) {
+      try {
+        stats = JSON.parse(readFileSync(statsPath, 'utf8'));
+      } catch {
+        /* corrupt stats — reset */
+      }
+    }
+    stats.hits ||= {};
+    stats.misses ||= {};
+    const bucket = kind === 'hit' ? stats.hits : stats.misses;
+    bucket[layer] = (bucket[layer] || 0) + 1;
+    atomicWriteJson(statsPath, stats);
+  } catch {
+    /* telemetry is non-fatal */
+  }
+}
+
+/**
+ * Record a hit/miss against a layer's counters. Lets out-of-process callers
+ * (the `maude cache get` CLI used by plugin slash-commands) feed the same
+ * telemetry `getOrCompute` does, so `maude cache stats` reflects real usage.
+ */
+export function recordAccess(layer, kind, opts = {}) {
+  bumpStat(resolveCacheRoot(opts), layer, kind === 'hit' ? 'hit' : 'miss');
+}
+
+/**
+ * Read a cache entry. Returns `null` on miss or corruption.
+ * @returns {{value:any, meta:object, writtenAt:number, ageMs:number, path:string}|null}
+ */
+export function check(layer, key, opts = {}) {
+  const cacheRoot = resolveCacheRoot(opts);
+  const filePath = entryPath(cacheRoot, layer, key);
+  if (!existsSync(filePath)) return null;
+  let entry;
+  try {
+    entry = JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null; // treat corrupt entries as a miss
+  }
+  if (!entry || typeof entry !== 'object' || typeof entry.writtenAt !== 'number') return null;
+  return {
+    value: entry.value,
+    meta: entry.meta || {},
+    writtenAt: entry.writtenAt,
+    ageMs: Date.now() - entry.writtenAt,
+    path: filePath,
+  };
+}
+
+/**
+ * Write a cache entry atomically.
+ * @returns {{path:string, writtenAt:number}}
+ */
+export function write(layer, key, value, meta = {}, opts = {}) {
+  const cacheRoot = resolveCacheRoot(opts);
+  const filePath = entryPath(cacheRoot, layer, key);
+  ensureReadme(cacheRoot);
+  const writtenAt = Date.now();
+  atomicWriteJson(filePath, { v: 1, layer, key, writtenAt, meta, value });
+  return { path: filePath, writtenAt };
+}
+
+/**
+ * Get-or-compute. Returns the cached value when fresh (age ≤ ttlMs), otherwise
+ * runs `compute()`, caches the result, and returns it. If `compute()` throws
+ * and a stale-but-not-expired entry exists (age ≤ maxAgeMs), that stale value
+ * is served as a graceful fallback; otherwise the error propagates.
+ *
+ * @param {object}   o
+ * @param {string}   o.layer
+ * @param {string}   o.key
+ * @param {number}   [o.ttlMs=Infinity]   fresh window; within it the cache is returned directly
+ * @param {number}   [o.maxAgeMs=Infinity] hard ceiling for stale-on-error fallback
+ * @param {boolean}  [o.force=false]      bypass the cache read; always recompute
+ * @param {Function} o.compute            () => value | Promise<value>
+ * @param {object}   [o.meta]             stored alongside the value
+ */
+export async function getOrCompute({
+  layer,
+  key,
+  ttlMs = Number.POSITIVE_INFINITY,
+  maxAgeMs = Number.POSITIVE_INFINITY,
+  force = false,
+  compute,
+  meta = {},
+  ...opts
+}) {
+  const cacheRoot = resolveCacheRoot(opts);
+  const hit = check(layer, key, { cacheDir: cacheRoot });
+  if (!force && hit && hit.ageMs <= ttlMs) {
+    bumpStat(cacheRoot, layer, 'hit');
+    return hit.value;
+  }
+  bumpStat(cacheRoot, layer, 'miss');
+  try {
+    const value = await compute();
+    write(layer, key, value, meta, { cacheDir: cacheRoot });
+    return value;
+  } catch (err) {
+    if (hit && hit.ageMs <= maxAgeMs) return hit.value; // stale-on-error fallback
+    throw err;
+  }
+}
+
+/**
+ * Remove a single entry, a whole layer subtree, or (with no layer) every entry.
+ * Never deletes the cache root itself, the README, or _stats.json on a layer clear.
+ */
+export function clear(layer, key, opts = {}) {
+  const cacheRoot = resolveCacheRoot(opts);
+  if (!existsSync(cacheRoot)) return { removed: 0 };
+  if (layer && key) {
+    const filePath = entryPath(cacheRoot, layer, key);
+    if (existsSync(filePath)) {
+      rmSync(filePath);
+      return { removed: 1 };
+    }
+    return { removed: 0 };
+  }
+  if (layer) {
+    const dir = resolve(cacheRoot, layer);
+    const rel = relative(cacheRoot, dir);
+    if (rel.startsWith('..') || resolve(cacheRoot, rel) !== dir) {
+      throw new Error(`cache: layer escapes cache root: ${layer}`);
+    }
+    if (existsSync(dir)) {
+      rmSync(dir, { recursive: true, force: true });
+      return { removed: 1 };
+    }
+    return { removed: 0 };
+  }
+  // Wipe everything except the README; reset stats.
+  let removed = 0;
+  for (const name of readdirSync(cacheRoot)) {
+    if (name === 'README.md') continue;
+    rmSync(join(cacheRoot, name), { recursive: true, force: true });
+    removed += 1;
+  }
+  return { removed };
+}
+
+/**
+ * List layers with aggregate stats. Each entry: { layer, entries, bytes, newest }.
+ */
+export function list(opts = {}) {
+  const cacheRoot = resolveCacheRoot(opts);
+  if (!existsSync(cacheRoot)) return [];
+  const layers = new Map();
+  const walk = (dir, topLayer) => {
+    for (const name of readdirSync(dir)) {
+      if (dir === cacheRoot && RESERVED.has(name)) continue;
+      const full = join(dir, name);
+      const st = statSync(full);
+      if (st.isDirectory()) {
+        walk(full, topLayer || name);
+      } else if (name.endsWith('.json') && topLayer) {
+        const agg = layers.get(topLayer) || { layer: topLayer, entries: 0, bytes: 0, newest: 0 };
+        agg.entries += 1;
+        agg.bytes += st.size;
+        agg.newest = Math.max(agg.newest, st.mtimeMs);
+        layers.set(topLayer, agg);
+      }
+    }
+  };
+  walk(cacheRoot, null);
+  return [...layers.values()].sort((a, b) => a.layer.localeCompare(b.layer));
+}
+
+/**
+ * Enumerate the entries within one layer. Each: { key, writtenAt, ageMs, bytes }.
+ * The `key` is the entry path relative to the layer dir, sans `.json` extension.
+ */
+export function entries(layer, opts = {}) {
+  const cacheRoot = resolveCacheRoot(opts);
+  const layerDir = resolve(cacheRoot, layer);
+  const rel = relative(cacheRoot, layerDir);
+  if (rel.startsWith('..') || resolve(cacheRoot, rel) !== layerDir) {
+    throw new Error(`cache: layer escapes cache root: ${layer}`);
+  }
+  if (!existsSync(layerDir)) return [];
+  const out = [];
+  const walk = (dir) => {
+    for (const name of readdirSync(dir)) {
+      const full = join(dir, name);
+      const st = statSync(full);
+      if (st.isDirectory()) {
+        walk(full);
+      } else if (name.endsWith('.json')) {
+        let writtenAt = st.mtimeMs;
+        try {
+          const parsed = JSON.parse(readFileSync(full, 'utf8'));
+          if (typeof parsed.writtenAt === 'number') writtenAt = parsed.writtenAt;
+        } catch {
+          /* fall back to mtime */
+        }
+        out.push({
+          key: relative(layerDir, full).slice(0, -'.json'.length),
+          writtenAt,
+          ageMs: Date.now() - writtenAt,
+          bytes: st.size,
+        });
+      }
+    }
+  };
+  walk(layerDir);
+  return out.sort((a, b) => b.writtenAt - a.writtenAt);
+}
+
+/**
+ * Read the hit/miss counters. Returns { hits, misses, since } (empty maps if none).
+ */
+export function stats(opts = {}) {
+  const cacheRoot = resolveCacheRoot(opts);
+  const statsPath = join(cacheRoot, STATS_FILE);
+  if (!existsSync(statsPath)) return { hits: {}, misses: {}, since: null };
+  try {
+    const s = JSON.parse(readFileSync(statsPath, 'utf8'));
+    return { hits: s.hits || {}, misses: s.misses || {}, since: s.since || null };
+  } catch {
+    return { hits: {}, misses: {}, since: null };
+  }
+}
+
+/**
+ * Convenience: 8-char hex digest of arbitrary input, for building cache keys.
+ * Uses git's object hashing via a pure JS fallback-free path is unnecessary —
+ * callers usually pass a git SHA directly; this is for slug/brief digests.
+ */
+export function sha8(input) {
+  const r = spawnSync('git', ['hash-object', '--stdin'], {
+    input: String(input),
+    encoding: 'utf8',
+  });
+  if (r.status === 0 && r.stdout) return r.stdout.trim().slice(0, 8);
+  // Fallback: tiny non-crypto FNV-1a → 8 hex chars (only when git is absent).
+  let h = 0x811c9dc5;
+  const str = String(input);
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(16).padStart(8, '0');
+}