@fenglimg/fabric-cli 2.1.0-rc.2 → 2.2.0-rc.10

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

@@ -1,27 +1,27 @@
 /**
  * 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
+ * The two host clients (Claude Code / Codex CLI) 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.
+ *   - Codex CLI reads 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
+ *   - detectClient(dirnameHint?) → 'cc' | 'codex' | undefined
  *       3-tier: FABRIC_HINT_CLIENT env override → CLAUDE_PROJECT_DIR (cc) →
- *       __dirname path heuristic (.claude / .codex / .cursor). dirnameHint
+ *       __dirname path heuristic (.claude / .codex). 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
+ *       Standardised output: Claude Code → stdout JSON envelope; Codex
  *       → plain stderr. forceStderr pins stderr even on Claude Code (used for
  *       SessionStart one-shot reminders). Best-effort — never throws.
  *
@@ -40,7 +40,7 @@ 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") {
+    if (normalised === "cc" || normalised === "codex") {
       return normalised;
     }
   }
@@ -51,7 +51,6 @@ function detectClient(dirnameHint) {
   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
   }
@@ -98,9 +97,69 @@ function emitContext(text, opts) {
   }
 }
 
+// v2.2 dual-sink (Goal A / D7): two-channel emit. Unlike emitContext (which
+// picks ONE channel), emitDualSink surfaces a knowledge breadcrumb to BOTH the
+// human and the AI in one render, split into two fields, with the protocol
+// shaped per client:
+//
+//   cc / codex (symmetric, D7): a single stdout JSON envelope carrying
+//     { systemMessage: <human>,                          // the human sink
+//       hookSpecificOutput: { hookEventName, additionalContext: <ai> } }  // AI sink
+//     camelCase + nested. `systemMessage` is the universal human-facing field
+//     (verified against official hook docs in the mode④ design session); it is
+//     what fixes the "stderr human channel is dead on CC" gap — CC suppresses
+//     hook stderr at exit 0, so the human never saw the old breadcrumb.
+//
+//   unknown client (detection failed, not CC): fall back to a plain stderr
+//     breadcrumb (human preferred, else ai) — no known JSON contract to target.
+//
+// Either field may be null/empty: pass { human, ai } and only the present
+// channels are written (e.g. a PreToolUse miss passes human:null → AI-only;
+// nudge_mode silent passes human:null too). The AI field is ALWAYS the caller's
+// to decide independently — this fn never derives one channel from the other,
+// preserving the flow ⊥ observation invariant (D5).
+//
+// Never-throw contract (KT-DEC-0007): every path degrades silently.
+function emitDualSink(payload, opts) {
+  const { human = null, ai = null } = payload || {};
+  const { client, eventName = "SessionStart", streams = {} } = opts || {};
+  const stdout = streams.stdout || process.stdout;
+  const stderr = streams.stderr || process.stderr;
+  const hasHuman = typeof human === "string" && human.length > 0;
+  const hasAi = typeof ai === "string" && ai.length > 0;
+  const resolved = client || detectClient();
+  try {
+    const useEnvelope =
+      resolved === "cc" ||
+      resolved === "codex" ||
+      (resolved === undefined && isClaudeCode());
+    if (useEnvelope) {
+      const envelope = {};
+      if (hasHuman) envelope.systemMessage = human;
+      if (hasAi) {
+        envelope.hookSpecificOutput = {
+          hookEventName: eventName,
+          additionalContext: ai,
+        };
+      }
+      if (Object.keys(envelope).length > 0) {
+        stdout.write(`${JSON.stringify(envelope)}\n`);
+      }
+      return;
+    }
+    // Unknown client: no JSON contract — surface the human breadcrumb (or ai)
+    // on stderr as a last resort so something is visible.
+    const fallback = hasHuman ? human : hasAi ? ai : null;
+    if (fallback !== null) stderr.write(`${fallback}\n`);
+  } catch {
+    // best-effort — never throw
+  }
+}
+
 module.exports = {
   isClaudeCode,
   detectClient,
   readStdinJson,
   emitContext,
+  emitDualSink,
 };

package/templates/hooks/lib/injection-log.cjs

@@ -0,0 +1,91 @@
+// v2.2 HK3-telemetry (W3-T1): injection-side telemetry. `.fabric/metrics.jsonl`
+// (server) records the CONSUMPTION side — which knowledge the agent actually
+// fetched/consumed. But nothing recorded the INJECTION side — which knowledge a
+// hook OFFERED the agent at SessionStart / PreToolUse. Without that denominator
+// the "true hit rate" (consumed ÷ injected) cannot be computed: a high consume
+// count tells you nothing if the hook injected ten times as many entries.
+//
+// This lib appends one row per injection to `.fabric/injections.jsonl`:
+//   { ts, surface: "broad"|"narrow", count, stable_ids: [...], revision_hash }
+//
+// Best-effort + synchronous: hooks are short-lived processes, so a sync append
+// is simpler than threading async, and ANY failure is swallowed — telemetry
+// must never break or delay the hook (failure invariant: silent). Concurrent
+// writers from multiple windows are serialized with an advisory lock (see
+// appendLockedLine below) so a contended write can't corrupt a line.
+
+const { appendFileSync, mkdirSync, openSync, closeSync, statSync, rmSync } = require("node:fs");
+const { join, dirname } = require("node:path");
+
+// Multi-window concurrency guard (ADJ-W3-INJECTION-CONCURRENCY): the same repo
+// is frequently edited from several client sessions at once, so multiple hook
+// processes can append to injections.jsonl simultaneously. A bare appendFileSync
+// can interleave a partial write under contention and corrupt a line. We guard
+// each append with an advisory lock file created atomically via O_EXCL ("wx"):
+//   - acquired  → write the row, then release the lock
+//   - contended → DROP this row. Telemetry is best-effort; a missing row only
+//                 shrinks the denominator slightly, and dropping is what keeps
+//                 the ledger from ever being corrupted by an interleave.
+//   - stale     → a holder that crashed leaves the lock behind; reclaim it once
+//                 past STALE_LOCK_MS so contention can't wedge forever.
+const STALE_LOCK_MS = 5000;
+
+function appendLockedLine(path, line) {
+  const lockPath = `${path}.lock`;
+  let fd;
+  try {
+    fd = openSync(lockPath, "wx"); // atomic create-exclusive = acquire
+  } catch (err) {
+    if (!err || err.code !== "EEXIST") return; // unexpected → drop (best-effort)
+    try {
+      if (Date.now() - statSync(lockPath).mtimeMs <= STALE_LOCK_MS) return; // fresh holder → drop
+      rmSync(lockPath, { force: true }); // stale holder crashed → reclaim
+      fd = openSync(lockPath, "wx");
+    } catch {
+      return; // racing another reclaimer → drop
+    }
+  }
+  try {
+    closeSync(fd);
+    appendFileSync(path, line);
+  } finally {
+    try {
+      rmSync(lockPath, { force: true });
+    } catch {
+      /* lock already released */
+    }
+  }
+}
+
+/**
+ * Append one injection record to `<projectRoot>/.fabric/injections.jsonl`.
+ *
+ * @param {string} projectRoot
+ * @param {{ surface: "broad"|"narrow", stableIds?: string[], count?: number, revisionHash?: string|null, ts?: number }} record
+ */
+function logInjection(projectRoot, record) {
+  try {
+    if (!projectRoot || !record || typeof record.surface !== "string") {
+      return;
+    }
+    const stableIds = Array.isArray(record.stableIds) ? record.stableIds.filter((id) => typeof id === "string") : [];
+    const count = typeof record.count === "number" ? record.count : stableIds.length;
+    if (count <= 0) {
+      return; // nothing injected → no row (keeps the denominator honest)
+    }
+    const row = {
+      ts: typeof record.ts === "number" ? record.ts : Date.now(),
+      surface: record.surface,
+      count,
+      stable_ids: stableIds,
+      revision_hash: typeof record.revisionHash === "string" ? record.revisionHash : null,
+    };
+    const path = join(projectRoot, ".fabric", "injections.jsonl");
+    mkdirSync(dirname(path), { recursive: true });
+    appendLockedLine(path, `${JSON.stringify(row)}\n`);
+  } catch {
+    // Telemetry is best-effort — never crash or delay the hook.
+  }
+}
+
+module.exports = { logInjection, appendLockedLine };

package/templates/hooks/lib/nudge-policy.cjs

@@ -0,0 +1,117 @@
+/**
+ * v2.2 dual-sink (Goal A / D4): nudge_mode + observe.* resolver for hook scripts.
+ *
+ * This lib answers ONE question for the human-facing sink: given the configured
+ * nudge_mode preset, the per-event observe.* overrides, and the event's
+ * structural gate (PreToolUse hit / Stop value), should this lifecycle event
+ * emit a human-facing `systemMessage`, and at what verbosity?
+ *
+ * CORE INVARIANT (D5 / KT-DEC-0007): this resolver governs ONLY the human sink.
+ * It has NO say over the AI sink (`hookSpecificOutput.additionalContext`). The
+ * model receives the same knowledge regardless of how quiet the human channel
+ * is — flow ⊥ observation. There is deliberately no `emitAi()` here; callers
+ * always compute and emit the AI payload unconditionally, then ask this resolver
+ * whether to additionally surface a human breadcrumb. The dedicated invariant
+ * test asserts that no nudge_mode / observe combination changes the AI branch.
+ *
+ * Resolution order for `resolveHumanSink(projectRoot, event, gate)`:
+ *   1. observe.<event> === false      → suppress (explicit per-event mute wins)
+ *   2. structural gate fails           → suppress (PreToolUse miss / Stop low-value:
+ *      nothing meaningful to show the human, mode-independent per C5/D2/D6)
+ *   3. observe.<event> === true        → emit (explicit per-event opt-in)
+ *   4. nudge_mode === "silent"         → suppress (global human-channel mute)
+ *   5. otherwise                       → emit at the preset's verbosity
+ *
+ * `verbosity` (minimal | normal | verbose) is forwarded to the renderer so it
+ * can scale the human breadcrumb's detail; it never affects the AI payload.
+ *
+ * Never-throw contract: any read/parse failure degrades to the "normal" preset
+ * with the structural gate respected — a malfunctioning config must not silence
+ * the human channel by surprise (it falls back to the historical visible
+ * behavior), nor block the hook.
+ */
+
+const { readConfig } = require("./config-cache.cjs");
+
+const NUDGE_MODES = ["silent", "minimal", "normal", "verbose"];
+const DEFAULT_NUDGE_MODE = "normal";
+// The three observe.* event keys, mirroring observeConfigSchema in
+// packages/shared/src/schemas/fabric-config.ts. Hooks pass the matching key.
+const OBSERVE_EVENTS = ["session_start", "pre_tool_use", "stop"];
+
+/**
+ * Resolve the configured nudge_mode preset. Unknown / absent → "normal".
+ */
+function readNudgeMode(projectRoot) {
+  try {
+    const v = readConfig(projectRoot).nudge_mode;
+    return typeof v === "string" && NUDGE_MODES.includes(v) ? v : DEFAULT_NUDGE_MODE;
+  } catch {
+    return DEFAULT_NUDGE_MODE;
+  }
+}
+
+/**
+ * Resolve the per-event observe.* override for one event. Returns a strict
+ * boolean when explicitly set, otherwise undefined (preset decides). Tolerant of
+ * a malformed observe value (non-object → undefined).
+ */
+function readObserveOverride(projectRoot, event) {
+  try {
+    const observe = readConfig(projectRoot).observe;
+    if (!observe || typeof observe !== "object") return undefined;
+    const v = observe[event];
+    return typeof v === "boolean" ? v : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Decide whether `event` should emit a human-facing systemMessage, and at what
+ * verbosity. `gate` carries the event's structural signal:
+ *   - { hit: boolean }       for pre_tool_use (false = narrow miss → suppress)
+ *   - { highValue: boolean } for stop         (false = no high-value archive
+ *                                              candidate → suppress, D6 value-gate)
+ *   - {}                     for session_start (no structural gate)
+ * Omitting a gate field means "gate passes" (e.g. session_start never gates).
+ *
+ * Returns { emitHuman: boolean, verbosity: "minimal"|"normal"|"verbose", mode }.
+ */
+function resolveHumanSink(projectRoot, event, gate) {
+  const mode = readNudgeMode(projectRoot);
+  const verbosity = mode === "silent" ? "minimal" : mode;
+  const override = OBSERVE_EVENTS.includes(event)
+    ? readObserveOverride(projectRoot, event)
+    : undefined;
+
+  // 1. explicit per-event mute wins over everything (even a hit).
+  if (override === false) return { emitHuman: false, verbosity, mode };
+
+  // 2. structural gate (mode-independent, C5/D2/D6): nothing to show → mute.
+  const g = gate || {};
+  if (event === "pre_tool_use" && g.hit === false) {
+    return { emitHuman: false, verbosity, mode };
+  }
+  if (event === "stop" && g.highValue === false) {
+    return { emitHuman: false, verbosity, mode };
+  }
+
+  // 3. explicit per-event opt-in (gate already passed above).
+  if (override === true) return { emitHuman: true, verbosity, mode };
+
+  // 4. global human-channel mute.
+  if (mode === "silent") return { emitHuman: false, verbosity, mode };
+
+  // 5. preset default — emit at the preset's verbosity.
+  return { emitHuman: true, verbosity, mode };
+}
+
+module.exports = {
+  readNudgeMode,
+  readObserveOverride,
+  resolveHumanSink,
+  NUDGE_MODES,
+  DEFAULT_NUDGE_MODE,
+  OBSERVE_EVENTS,
+};

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

@@ -21,7 +21,10 @@
  * acceptable — the hook never blocks user flow on sidecar I/O, KT-DEC-0007).
  */
 
-const { existsSync, mkdirSync, readFileSync, writeFileSync } = require("node:fs");
+// Namespace import (not destructured) so the atomic write goes through a single
+// mutable fs reference — also what the atomicity tests spy on (ISS-016).
+const fs = require("node:fs");
+const fsp = require("node:fs/promises");
 const { dirname, join } = require("node:path");
 
 const CACHE_DIR_REL = join(".fabric", ".cache");
@@ -30,11 +33,47 @@ function cachePath(projectRoot, fileName) {
   return join(projectRoot, CACHE_DIR_REL, fileName);
 }
 
+// ISS-016: write to a unique temp file then rename over the target. rename is
+// atomic on POSIX, so a reader sees either the old or the new file in full —
+// never a truncated/garbled write from a crash or concurrent writer. The temp
+// suffix (pid + clock) keeps concurrent windows from colliding on the temp.
+function atomicWrite(path, data) {
+  fs.mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    fs.writeFileSync(tmp, data);
+    fs.renameSync(tmp, path);
+  } catch (err) {
+    try {
+      if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
+    } catch {
+      // best-effort temp cleanup
+    }
+    throw err;
+  }
+}
+
+async function atomicWriteAsync(path, data) {
+  await fsp.mkdir(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    await fsp.writeFile(tmp, data);
+    await fsp.rename(tmp, path);
+  } catch (err) {
+    try {
+      await fsp.rm(tmp, { force: true });
+    } catch {
+      // best-effort temp cleanup
+    }
+    throw err;
+  }
+}
+
 function readJsonState(projectRoot, fileName, validate) {
   const path = cachePath(projectRoot, fileName);
-  if (!existsSync(path)) return null;
+  if (!fs.existsSync(path)) return null;
   try {
-    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    const parsed = JSON.parse(fs.readFileSync(path, "utf8"));
     if (typeof validate === "function" && !validate(parsed)) return null;
     return parsed;
   } catch {
@@ -42,11 +81,29 @@ function readJsonState(projectRoot, fileName, validate) {
   }
 }
 
-function writeJsonState(projectRoot, fileName, value) {
+async function readJsonStateAsync(projectRoot, fileName, validate) {
   const path = cachePath(projectRoot, fileName);
   try {
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, JSON.stringify(value));
+    const parsed = JSON.parse(await fsp.readFile(path, "utf8"));
+    if (typeof validate === "function" && !validate(parsed)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function writeJsonState(projectRoot, fileName, value) {
+  try {
+    atomicWrite(cachePath(projectRoot, fileName), JSON.stringify(value));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function writeJsonStateAsync(projectRoot, fileName, value) {
+  try {
+    await atomicWriteAsync(cachePath(projectRoot, fileName), JSON.stringify(value));
     return true;
   } catch {
     return false;
@@ -55,19 +112,35 @@ function writeJsonState(projectRoot, fileName, value) {
 
 function readTextState(projectRoot, fileName) {
   const path = cachePath(projectRoot, fileName);
-  if (!existsSync(path)) return null;
+  if (!fs.existsSync(path)) return null;
   try {
-    return readFileSync(path, "utf8").trim();
+    return fs.readFileSync(path, "utf8").trim();
   } catch {
     return null;
   }
 }
 
-function writeTextState(projectRoot, fileName, text) {
+async function readTextStateAsync(projectRoot, fileName) {
   const path = cachePath(projectRoot, fileName);
   try {
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, String(text));
+    return (await fsp.readFile(path, "utf8")).trim();
+  } catch {
+    return null;
+  }
+}
+
+function writeTextState(projectRoot, fileName, text) {
+  try {
+    atomicWrite(cachePath(projectRoot, fileName), String(text));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function writeTextStateAsync(projectRoot, fileName, text) {
+  try {
+    await atomicWriteAsync(cachePath(projectRoot, fileName), String(text));
     return true;
   } catch {
     return false;
@@ -77,8 +150,14 @@ function writeTextState(projectRoot, fileName, text) {
 module.exports = {
   cachePath,
   readJsonState,
+  readJsonStateAsync,
   writeJsonState,
+  writeJsonStateAsync,
   readTextState,
+  readTextStateAsync,
   writeTextState,
+  writeTextStateAsync,
+  atomicWrite,
+  atomicWriteAsync,
   CACHE_DIR_REL,
 };