@fenglimg/fabric-cli 2.0.0 → 2.0.1

package/templates/hooks/lib/client-adapter.cjs

@@ -0,0 +1,106 @@
+/**
+ * v2.0.0-rc.37 NEW-30: shared client-protocol adapter for hook scripts.
+ *
+ * The three host clients (Claude Code / Codex CLI / Cursor) differ in how a
+ * hook surfaces context back to the model:
+ *   - Claude Code reads a stdout JSON envelope
+ *     ({ hookSpecificOutput: { hookEventName, additionalContext } }).
+ *   - Codex CLI and Cursor read plain stderr text.
+ * Each hook had its own copy of the detect-client + read-stdin + pick-channel
+ * logic (fabric-hint.detectClient, cite-policy-evict.isClaudeCode + readStdinJson,
+ * knowledge-hint-broad inline CLAUDE_PROJECT_DIR check). This module is the
+ * single canonical implementation so the protocol choice lives in one place.
+ *
+ * Provides:
+ *   - detectClient(dirnameHint?) → 'cc' | 'codex' | 'cursor' | undefined
+ *       3-tier: FABRIC_HINT_CLIENT env override → CLAUDE_PROJECT_DIR (cc) →
+ *       __dirname path heuristic (.claude / .codex / .cursor). dirnameHint
+ *       defaults to this lib's own dir (which still lives under the client
+ *       dir, e.g. .claude/hooks/lib), so the heuristic stays accurate.
+ *   - isClaudeCode() → boolean   (CLAUDE_PROJECT_DIR present)
+ *   - readStdinJson({ timeoutMs }) → Promise<object | null>
+ *       Async stdin JSON reader; null on parse error / closed stdin / timeout.
+ *   - emitContext(text, { client, eventName, streams, forceStderr }) → void
+ *       Standardised output: Claude Code → stdout JSON envelope; Codex/Cursor
+ *       → plain stderr. forceStderr pins stderr even on Claude Code (used for
+ *       SessionStart one-shot reminders). Best-effort — never throws.
+ *
+ * Never-throw contract (KT-DEC-0007): every path degrades silently rather than
+ * blocking the host's main flow.
+ */
+
+function isClaudeCode() {
+  return (
+    typeof process.env.CLAUDE_PROJECT_DIR === "string" &&
+    process.env.CLAUDE_PROJECT_DIR.length > 0
+  );
+}
+
+function detectClient(dirnameHint) {
+  const envClient = process.env.FABRIC_HINT_CLIENT;
+  if (typeof envClient === "string" && envClient.length > 0) {
+    const normalised = envClient.trim().toLowerCase();
+    if (normalised === "cc" || normalised === "codex" || normalised === "cursor") {
+      return normalised;
+    }
+  }
+  if (isClaudeCode()) return "cc";
+  // Path heuristic against the caller's directory (defaults to this lib's dir,
+  // which sits under the client root, e.g. .codex/hooks/lib).
+  const dir = typeof dirnameHint === "string" && dirnameHint.length > 0 ? dirnameHint : __dirname;
+  try {
+    if (dir.includes(".claude/") || dir.includes(".claude\\")) return "cc";
+    if (dir.includes(".codex/") || dir.includes(".codex\\")) return "codex";
+    if (dir.includes(".cursor/") || dir.includes(".cursor\\")) return "cursor";
+  } catch {
+    // fall through
+  }
+  return undefined;
+}
+
+function readStdinJson(opts) {
+  const { timeoutMs = 1000 } = opts || {};
+  return new Promise((resolve) => {
+    let buffer = "";
+    process.stdin.on("data", (chunk) => {
+      buffer += chunk;
+    });
+    process.stdin.on("end", () => {
+      try {
+        resolve(JSON.parse(buffer));
+      } catch {
+        resolve(null);
+      }
+    });
+    process.stdin.on("error", () => resolve(null));
+    // Defensive timeout: if stdin never closes (host bug), give up.
+    setTimeout(() => resolve(null), timeoutMs).unref();
+  });
+}
+
+function emitContext(text, opts) {
+  const { client, eventName = "UserPromptSubmit", streams = {}, forceStderr = false } = opts || {};
+  const stdout = streams.stdout || process.stdout;
+  const stderr = streams.stderr || process.stderr;
+  const useStdoutEnvelope =
+    !forceStderr && (client === "cc" || (client === undefined && isClaudeCode()));
+  try {
+    if (useStdoutEnvelope) {
+      const envelope = {
+        hookSpecificOutput: { hookEventName: eventName, additionalContext: text },
+      };
+      stdout.write(`${JSON.stringify(envelope)}\n`);
+    } else {
+      stderr.write(`${text}\n`);
+    }
+  } catch {
+    // best-effort — never throw
+  }
+}
+
+module.exports = {
+  isClaudeCode,
+  detectClient,
+  readStdinJson,
+  emitContext,
+};

package/templates/hooks/lib/config-cache.cjs

@@ -0,0 +1,107 @@
+/**
+ * v2.0.0-rc.37 NEW-19: shared fabric-config reader for hook scripts.
+ *
+ * Before this lib, every hook re-implemented the same defensive
+ * `readFileSync(.fabric/fabric-config.json) → JSON.parse → validate one key →
+ * fall back to default` boilerplate, once PER KEY (knowledge-hint-broad alone
+ * read the file 5× per SessionStart fire: cooldown / top_k / underseed /
+ * summary_max_len / reminder_to_context). This module centralises the read +
+ * mtime-keyed memoisation so a single hook fire parses the config once.
+ *
+ * Provides:
+ *   - readConfig(projectRoot) → object
+ *       Parsed fabric-config.json (memoised on path+mtime). Returns `{}` on
+ *       any failure (missing file / parse error / non-object). Never throws.
+ *       mtime-keyed so a config rewrite mid-process (test harness) invalidates
+ *       the cached value automatically — production hooks are single-shot so
+ *       the common case is one stat + one parse.
+ *   - readConfigNumber(root, key, fallback, { min, max, integer }) → number
+ *   - readConfigBoolean(root, key, fallback) → boolean
+ *   - readConfigString(root, key, fallback) → string
+ *       Typed getters with inline range/shape validation; any miss → fallback.
+ *   - configPathFor(projectRoot) → absolute config path
+ *   - clearConfigCache() → void   (test helper)
+ *
+ * Never-throw contract: every export degrades to its fallback rather than
+ * throwing, preserving the reminder-layer hook invariant (KT-DEC-0007: hooks
+ * never block on their own malfunction).
+ */
+
+const { existsSync, readFileSync, statSync } = require("node:fs");
+const { join } = require("node:path");
+
+const FABRIC_DIR_REL = ".fabric";
+const FABRIC_CONFIG_FILE = "fabric-config.json";
+
+// path → { mtime, value }. Per-process; mtime-keyed for test-mutation safety.
+const _cache = new Map();
+
+function configPathFor(projectRoot) {
+  return join(projectRoot, FABRIC_DIR_REL, FABRIC_CONFIG_FILE);
+}
+
+function readConfig(projectRoot) {
+  const path = configPathFor(projectRoot);
+  let mtime;
+  try {
+    if (!existsSync(path)) {
+      _cache.delete(path);
+      return {};
+    }
+    mtime = statSync(path).mtimeMs;
+  } catch {
+    return {};
+  }
+  const cached = _cache.get(path);
+  if (cached && cached.mtime === mtime) return cached.value;
+  let value = {};
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    if (raw && typeof raw === "object") value = raw;
+  } catch {
+    value = {};
+  }
+  _cache.set(path, { mtime, value });
+  return value;
+}
+
+function clearConfigCache() {
+  _cache.clear();
+}
+
+// opts:
+//   min / max   — inclusive range; out-of-range → fallback
+//   integer     — require Number.isInteger; non-integer → fallback (strict)
+//   floor       — accept any in-range number, return Math.floor(v) (lenient)
+// `integer` and `floor` are independent: `integer` rejects fractional values,
+// `floor` truncates them. Pick whichever matches the caller's legacy contract.
+function readConfigNumber(projectRoot, key, fallback, opts) {
+  const { min, max, integer, floor } = opts || {};
+  const v = readConfig(projectRoot)[key];
+  if (typeof v === "number" && Number.isFinite(v)) {
+    if (integer && !Number.isInteger(v)) return fallback;
+    if (typeof min === "number" && v < min) return fallback;
+    if (typeof max === "number" && v > max) return fallback;
+    return floor ? Math.floor(v) : v;
+  }
+  return fallback;
+}
+
+function readConfigBoolean(projectRoot, key, fallback) {
+  const v = readConfig(projectRoot)[key];
+  return typeof v === "boolean" ? v : fallback;
+}
+
+function readConfigString(projectRoot, key, fallback) {
+  const v = readConfig(projectRoot)[key];
+  return typeof v === "string" && v.length > 0 ? v : fallback;
+}
+
+module.exports = {
+  readConfig,
+  clearConfigCache,
+  readConfigNumber,
+  readConfigBoolean,
+  readConfigString,
+  configPathFor,
+};

package/templates/hooks/lib/state-store.cjs

@@ -0,0 +1,84 @@
+/**
+ * v2.0.0-rc.37 NEW-19: shared `.fabric/.cache/` sidecar I/O for hook scripts.
+ *
+ * Hooks persist tiny per-session state (turn counters, last-emit timestamps,
+ * shown-hint sets) under `.fabric/.cache/`. Each hook had its own copy of the
+ * read-JSON-or-null / write-JSON-best-effort / read-text / write-text helpers
+ * (cite-policy-evict's readEvictState/writeEvictState, broad's
+ * readBroadLastEmit/writeBroadLastEmit, fabric-hint's shown-cache + edit-counter
+ * + maintenance-last-emit). This module is the single canonical implementation.
+ *
+ * Provides (all keyed on a bare `fileName` resolved under .fabric/.cache/):
+ *   - cachePath(projectRoot, fileName) → absolute path
+ *   - readJsonState(root, fileName, validate?) → parsed | null
+ *       null on missing / parse error / validate() === false. Never throws.
+ *   - writeJsonState(root, fileName, value) → boolean
+ *       mkdir -p + write; false on failure. Never throws.
+ *   - readTextState(root, fileName) → trimmed string | null
+ *   - writeTextState(root, fileName, text) → boolean
+ *
+ * Never-throw contract: write failures return false (counter loss is
+ * acceptable — the hook never blocks user flow on sidecar I/O, KT-DEC-0007).
+ */
+
+const { existsSync, mkdirSync, readFileSync, writeFileSync } = require("node:fs");
+const { dirname, join } = require("node:path");
+
+const CACHE_DIR_REL = join(".fabric", ".cache");
+
+function cachePath(projectRoot, fileName) {
+  return join(projectRoot, CACHE_DIR_REL, fileName);
+}
+
+function readJsonState(projectRoot, fileName, validate) {
+  const path = cachePath(projectRoot, fileName);
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (typeof validate === "function" && !validate(parsed)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function writeJsonState(projectRoot, fileName, value) {
+  const path = cachePath(projectRoot, fileName);
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readTextState(projectRoot, fileName) {
+  const path = cachePath(projectRoot, fileName);
+  if (!existsSync(path)) return null;
+  try {
+    return readFileSync(path, "utf8").trim();
+  } catch {
+    return null;
+  }
+}
+
+function writeTextState(projectRoot, fileName, text) {
+  const path = cachePath(projectRoot, fileName);
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, String(text));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  cachePath,
+  readJsonState,
+  writeJsonState,
+  readTextState,
+  writeTextState,
+  CACHE_DIR_REL,
+};

package/templates/hooks/lib/summary-fallback.cjs

@@ -0,0 +1,210 @@
+/**
+ * rc.35 TASK-06 (P0-10.b) — summary-fallback library.
+ *
+ * Resolves opaque hint entries (where `entry.summary === entry.id` so the
+ * AI sees no information beyond the id) by reading the entry's markdown
+ * file at `.fabric/knowledge/<type>/<id>--<slug>.md`, extracting the first
+ * paragraph under `## Summary`, and substituting that text into the entry
+ * before the hook renders it.
+ *
+ * Caching: results are stored in `.fabric/.cache/summary-fallback.json`
+ * keyed by the current `revision_hash` returned by plan-context-hint. The
+ * cache is wiped wholesale when the revision changes (cheap invariant —
+ * any meta rev bump implies entry text MAY have moved). Per-process call
+ * also benefits from in-memory dedup since the same opaque id may appear
+ * across narrow + broad paths.
+ *
+ * Design contract:
+ *   - Never throw. ANY failure (cache read, fs scan, file read) degrades
+ *     to a no-op — the original opaque summary is left untouched. Hooks
+ *     must remain best-effort.
+ *   - Idempotent over identical inputs. Two calls in succession with the
+ *     same revision_hash + entries set produce zero disk reads on the
+ *     second call.
+ *
+ * Public API (module.exports):
+ *   resolveOpaqueSummaries(entries, projectRoot, revisionHash) — returns
+ *     a NEW array of entries with `summary` substituted for opaque cases.
+ *     Original `entry.id` is preserved verbatim.
+ *
+ *   _extractFirstSummaryParagraph(md) — pure helper, exposed for testing.
+ *
+ *   _readCache / _writeCache — exposed for testing.
+ */
+
+const { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } = require("node:fs");
+const { join } = require("node:path");
+
+const CACHE_DIR_REL = ".fabric/.cache";
+const CACHE_FILE_REL = ".fabric/.cache/summary-fallback.json";
+const KNOWLEDGE_DIR_REL = ".fabric/knowledge";
+const SUMMARY_MAX_LEN = 80;
+const KNOWLEDGE_TYPE_DIRS = ["decisions", "pitfalls", "guidelines", "models", "processes"];
+
+function _isOpaque(entry) {
+  if (!entry || typeof entry.id !== "string" || typeof entry.summary !== "string") {
+    return false;
+  }
+  return entry.summary.trim() === entry.id.trim();
+}
+
+/**
+ * Pure helper: extract the first paragraph under a `## Summary` heading.
+ *
+ *   - `## Summary` is case-insensitive but level-sensitive (only H2).
+ *   - First paragraph = lines until blank line or next heading.
+ *   - Collapses whitespace + trims; returns `""` if no summary section or
+ *     the section is empty.
+ */
+function _extractFirstSummaryParagraph(md) {
+  if (typeof md !== "string" || md.length === 0) return "";
+  const lines = md.split(/\r?\n/);
+  let i = 0;
+  while (i < lines.length) {
+    if (/^##\s+summary\s*$/i.test(lines[i].trim())) {
+      i += 1;
+      break;
+    }
+    i += 1;
+  }
+  if (i >= lines.length) return "";
+  // Skip blank lines after the heading
+  while (i < lines.length && lines[i].trim().length === 0) i += 1;
+  // Collect until the next blank line or next heading
+  const buf = [];
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line.trim().length === 0) break;
+    if (/^#{1,6}\s/.test(line.trim())) break;
+    buf.push(line.trim());
+    i += 1;
+  }
+  const flat = buf.join(" ").replace(/\s+/g, " ").trim();
+  if (flat.length === 0) return "";
+  if (flat.length <= SUMMARY_MAX_LEN) return flat;
+  return `${flat.slice(0, SUMMARY_MAX_LEN - 1)}…`;
+}
+
+function _readCache(projectRoot) {
+  const cachePath = join(projectRoot, CACHE_FILE_REL);
+  if (!existsSync(cachePath)) return null;
+  try {
+    const raw = readFileSync(cachePath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && typeof parsed.revision === "string" && parsed.summaries && typeof parsed.summaries === "object") {
+      return parsed;
+    }
+  } catch {
+    // ignore — caller treats null as no-cache
+  }
+  return null;
+}
+
+function _writeCache(projectRoot, payload) {
+  try {
+    const cacheDir = join(projectRoot, CACHE_DIR_REL);
+    if (!existsSync(cacheDir)) mkdirSync(cacheDir, { recursive: true });
+    const cachePath = join(projectRoot, CACHE_FILE_REL);
+    writeFileSync(cachePath, JSON.stringify(payload), "utf8");
+  } catch {
+    // Best-effort — failing to persist cache is not an error
+  }
+}
+
+/**
+ * Scan `.fabric/knowledge/<type>/` for the canonical `<id>--<slug>.md`
+ * matching `stableId`. Tries the most likely type-dir first based on the
+ * entry's `type` hint, then falls back to scanning all canonical type
+ * directories. Returns the absolute path or null.
+ *
+ * The id→file mapping is unique by construction (stable_id is allocated
+ * once per file), so the first match wins.
+ */
+function _findEntryFile(projectRoot, stableId, typeHint) {
+  const baseDir = join(projectRoot, KNOWLEDGE_DIR_REL);
+  if (!existsSync(baseDir)) return null;
+  const tryOrder = [];
+  if (typeof typeHint === "string" && typeHint.length > 0) {
+    // Accept both singular and plural hints — find the plural form.
+    const lower = typeHint.toLowerCase();
+    const plural = KNOWLEDGE_TYPE_DIRS.find((d) => d === lower || d.startsWith(lower));
+    if (plural) tryOrder.push(plural);
+  }
+  for (const t of KNOWLEDGE_TYPE_DIRS) {
+    if (!tryOrder.includes(t)) tryOrder.push(t);
+  }
+  const prefix = `${stableId}--`;
+  for (const t of tryOrder) {
+    const typeDir = join(baseDir, t);
+    if (!existsSync(typeDir)) continue;
+    let files;
+    try {
+      files = readdirSync(typeDir);
+    } catch {
+      continue;
+    }
+    for (const f of files) {
+      if (f.startsWith(prefix) && f.endsWith(".md")) {
+        return join(typeDir, f);
+      }
+    }
+  }
+  return null;
+}
+
+function _resolveOne(projectRoot, entry) {
+  const filePath = _findEntryFile(projectRoot, entry.id, entry.type);
+  if (filePath === null) return "";
+  let md;
+  try {
+    md = readFileSync(filePath, "utf8");
+  } catch {
+    return "";
+  }
+  return _extractFirstSummaryParagraph(md);
+}
+
+/**
+ * Main API. Returns a new array of entries with `summary` swapped for
+ * the extracted fallback wherever the original summary was opaque AND
+ * the fallback extraction yielded a non-empty string. Non-opaque entries
+ * pass through unchanged.
+ */
+function resolveOpaqueSummaries(entries, projectRoot, revisionHash) {
+  if (!Array.isArray(entries) || entries.length === 0) return entries;
+  const cache = _readCache(projectRoot);
+  const cachedSummaries = cache && cache.revision === revisionHash && cache.summaries ? cache.summaries : {};
+  const nextCacheSummaries = { ...cachedSummaries };
+  let cacheChanged = cache === null || cache.revision !== revisionHash;
+  const result = entries.map((entry) => {
+    if (!_isOpaque(entry)) return entry;
+    const id = entry.id;
+    let fallback;
+    if (Object.prototype.hasOwnProperty.call(cachedSummaries, id)) {
+      fallback = cachedSummaries[id];
+    } else {
+      fallback = _resolveOne(projectRoot, entry);
+      nextCacheSummaries[id] = fallback;
+      cacheChanged = true;
+    }
+    if (typeof fallback === "string" && fallback.length > 0) {
+      return { ...entry, summary: fallback };
+    }
+    return entry;
+  });
+  if (cacheChanged) {
+    _writeCache(projectRoot, { revision: revisionHash, summaries: nextCacheSummaries });
+  }
+  return result;
+}
+
+module.exports = {
+  resolveOpaqueSummaries,
+  _extractFirstSummaryParagraph,
+  _readCache,
+  _writeCache,
+  _findEntryFile,
+  _isOpaque,
+  SUMMARY_MAX_LEN,
+  KNOWLEDGE_TYPE_DIRS,
+};