@fenglimg/fabric-cli 2.2.0-rc.1 → 2.2.0-rc.11

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/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

@@ -24,6 +24,7 @@
 // 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");
@@ -52,6 +53,22 @@ function atomicWrite(path, data) {
   }
 }
 
+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 (!fs.existsSync(path)) return null;
@@ -64,6 +81,17 @@ function readJsonState(projectRoot, fileName, validate) {
   }
 }
 
+async function readJsonStateAsync(projectRoot, fileName, validate) {
+  const path = cachePath(projectRoot, fileName);
+  try {
+    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));
@@ -73,6 +101,15 @@ function writeJsonState(projectRoot, fileName, value) {
   }
 }
 
+async function writeJsonStateAsync(projectRoot, fileName, value) {
+  try {
+    await atomicWriteAsync(cachePath(projectRoot, fileName), JSON.stringify(value));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function readTextState(projectRoot, fileName) {
   const path = cachePath(projectRoot, fileName);
   if (!fs.existsSync(path)) return null;
@@ -83,6 +120,15 @@ function readTextState(projectRoot, fileName) {
   }
 }
 
+async function readTextStateAsync(projectRoot, fileName) {
+  const path = cachePath(projectRoot, fileName);
+  try {
+    return (await fsp.readFile(path, "utf8")).trim();
+  } catch {
+    return null;
+  }
+}
+
 function writeTextState(projectRoot, fileName, text) {
   try {
     atomicWrite(cachePath(projectRoot, fileName), String(text));
@@ -92,12 +138,26 @@ function writeTextState(projectRoot, fileName, text) {
   }
 }
 
+async function writeTextStateAsync(projectRoot, fileName, text) {
+  try {
+    await atomicWriteAsync(cachePath(projectRoot, fileName), String(text));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 module.exports = {
   cachePath,
   readJsonState,
+  readJsonStateAsync,
   writeJsonState,
+  writeJsonStateAsync,
   readTextState,
+  readTextStateAsync,
   writeTextState,
+  writeTextStateAsync,
   atomicWrite,
+  atomicWriteAsync,
   CACHE_DIR_REL,
 };