@fenglimg/fabric-cli 2.0.0-rc.30 → 2.0.0-rc.34

package/templates/hooks/knowledge-hint-broad.cjs

@@ -49,10 +49,12 @@
 const { spawnSync } = require("node:child_process");
 const {
   existsSync,
+  mkdirSync,
   readdirSync,
   readFileSync,
+  writeFileSync,
 } = require("node:fs");
-const { join } = require("node:path");
+const { dirname, join } = require("node:path");
 
 // rc.16 TASK-003: shared banner-i18n lib (resolves fabric_language config and
 // renders localized banner text). Mirror of the wiring in fabric-hint.cjs
@@ -89,6 +91,30 @@ const KNOWLEDGE_CANONICAL_TYPES = [
 ];
 const DEFAULT_UNDERSEED_NODE_THRESHOLD = 10;
 
+// v2.0.0-rc.33 W2-1 (P0-9): TopK upper bound on broad-scoped entries surfaced
+// per SessionStart fire. Keeps the banner inside ~1 screenful so the agent
+// actually reads the top-priority entries instead of triaging a wall of text.
+// Overridable via fabric-config.json#hint_broad_top_k (range 1..50).
+const DEFAULT_HINT_BROAD_TOP_K = 8;
+
+// v2.0.0-rc.33 W2-5 (P1-8): cooldown (in hours) between broad-hint re-emits.
+// Default 0 preserves rc.32 behavior — every SessionStart re-fires the banner.
+// Cache key uses a separate sidecar from the fabric-hint Signal A/B/C cache
+// so the two cooldowns don't interfere.
+const DEFAULT_HINT_BROAD_COOLDOWN_HOURS = 0;
+const MS_PER_HOUR = 60 * 60 * 1000;
+const HINT_BROAD_LAST_EMIT_FILE = join(
+  ".fabric",
+  ".cache",
+  "knowledge-hint-broad-last-emit",
+);
+
+// v2.0.0-rc.33 W2-6 (P0-7): when true, emit banner as
+// hookSpecificOutput.additionalContext JSON on stdout (Claude Code PreToolUse
+// contract) so the model receives the reminder in-context. Stderr remains the
+// human-facing channel for logs / breadcrumbs.
+const DEFAULT_HINT_REMINDER_TO_CONTEXT = true;
+
 // -----------------------------------------------------------------------------
 // rc.8 underseed self-check helpers.
 //
@@ -153,6 +179,97 @@ function readUnderseedThreshold(projectRoot) {
   return DEFAULT_UNDERSEED_NODE_THRESHOLD;
 }
 
+/**
+ * v2.0.0-rc.33 W2-1: resolve hint_broad_top_k from fabric-config.json. Slices
+ * the broad entry list to TopK before group/truncation render. Validates the
+ * schema's 1..50 range inline so a malformed config silently falls back.
+ */
+function readBroadTopK(projectRoot) {
+  const configPath = join(projectRoot, FABRIC_DIR_REL, FABRIC_CONFIG_FILE);
+  if (!existsSync(configPath)) return DEFAULT_HINT_BROAD_TOP_K;
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+    const v = parsed && parsed.hint_broad_top_k;
+    if (typeof v === "number" && Number.isFinite(v) && v >= 1 && v <= 50) {
+      return Math.floor(v);
+    }
+  } catch {
+    // fall through to default
+  }
+  return DEFAULT_HINT_BROAD_TOP_K;
+}
+
+/**
+ * v2.0.0-rc.33 W2-5: resolve hint_broad_cooldown_hours. Schema clamps 0..168;
+ * 0 means "no cooldown" (re-emit on every SessionStart, rc.32 behavior).
+ */
+function readBroadCooldownHours(projectRoot) {
+  const configPath = join(projectRoot, FABRIC_DIR_REL, FABRIC_CONFIG_FILE);
+  if (!existsSync(configPath)) return DEFAULT_HINT_BROAD_COOLDOWN_HOURS;
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+    const v = parsed && parsed.hint_broad_cooldown_hours;
+    if (typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= 168) {
+      return v;
+    }
+  } catch {
+    // fall through to default
+  }
+  return DEFAULT_HINT_BROAD_COOLDOWN_HOURS;
+}
+
+/**
+ * v2.0.0-rc.33 W2-6: resolve hint_reminder_to_context. Boolean flag — when
+ * true (default) the hook writes a Claude-Code-shaped JSON envelope to stdout
+ * carrying the banner under hookSpecificOutput.additionalContext so the model
+ * receives the reminder in-context. Stderr stays informational either way.
+ */
+function readReminderToContext(projectRoot) {
+  const configPath = join(projectRoot, FABRIC_DIR_REL, FABRIC_CONFIG_FILE);
+  if (!existsSync(configPath)) return DEFAULT_HINT_REMINDER_TO_CONTEXT;
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+    const v = parsed && parsed.hint_reminder_to_context;
+    if (typeof v === "boolean") return v;
+  } catch {
+    // fall through to default
+  }
+  return DEFAULT_HINT_REMINDER_TO_CONTEXT;
+}
+
+/**
+ * v2.0.0-rc.33 W2-5: read/write the broad-hint last-emit timestamp sidecar.
+ * Distinct from fabric-hint's shown-cache so signal cooldowns stay isolated.
+ * Returns epoch ms or null when missing/unreadable.
+ */
+function readBroadLastEmit(projectRoot) {
+  const p = join(projectRoot, HINT_BROAD_LAST_EMIT_FILE);
+  if (!existsSync(p)) return null;
+  try {
+    const raw = readFileSync(p, "utf8").trim();
+    if (raw.length === 0) return null;
+    const asNum = Number(raw);
+    if (Number.isFinite(asNum) && asNum > 0) return asNum;
+    const ms = Date.parse(raw);
+    if (Number.isFinite(ms)) return ms;
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+function writeBroadLastEmit(projectRoot, nowMs) {
+  const p = join(projectRoot, HINT_BROAD_LAST_EMIT_FILE);
+  try {
+    if (!existsSync(dirname(p))) {
+      mkdirSync(dirname(p), { recursive: true });
+    }
+    writeFileSync(p, String(nowMs));
+  } catch {
+    // Silent — sidecar failure must never block session start.
+  }
+}
+
 /**
  * Classify the on-disk import lifecycle by reading
  * `.fabric/.import-state.json`. Returns one of:
@@ -245,8 +362,24 @@ const CLI_TIMEOUT_MS = 2000;
 
 // Maximum summary length per entry. Keeps each line bounded so stderr does
 // not blow up terminal width with multi-paragraph summaries from sloppy
-// pending entries. Truncation appends an ellipsis.
-const SUMMARY_MAX_LEN = 80;
+// pending entries. Truncation appends an ellipsis. v2.0.0-rc.33 W4-A3:
+// `hint_summary_max_len` in fabric-config overrides this default (range 40..240).
+const DEFAULT_SUMMARY_MAX_LEN = 80;
+
+function readSummaryMaxLen(projectRoot) {
+  const configPath = join(projectRoot, FABRIC_DIR_REL, FABRIC_CONFIG_FILE);
+  if (!existsSync(configPath)) return DEFAULT_SUMMARY_MAX_LEN;
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+    const v = parsed && parsed.hint_summary_max_len;
+    if (typeof v === "number" && Number.isFinite(v) && v >= 40 && v <= 240) {
+      return Math.floor(v);
+    }
+  } catch {
+    // fall through to default
+  }
+  return DEFAULT_SUMMARY_MAX_LEN;
+}
 
 // Canonical type order — render groups in this sequence so output is stable
 // across runs (Object.keys iteration order is insertion order, but the JSON
@@ -288,6 +421,11 @@ const MATURITY_DRAFT = "draft";
  */
 function invokePlanContextHint(cwd) {
   const candidates = ["fabric", "fab"];
+  // rc.31 NEW-6: capture the last meaningful failure so we can surface it on
+  // stderr before fail-open. Without this, hook silently swallows backend
+  // crashes (e.g. agents_meta_invalid → plan-context-hint exits with stderr
+  // payload and the AI / user never sees KB chain is dead).
+  let lastFailure = null;
   for (const bin of candidates) {
     let res;
     try {
@@ -300,17 +438,37 @@ function invokePlanContextHint(cwd) {
     } catch {
       continue; // spawn throw (extremely rare) — try next candidate
     }
-    // ENOENT surfaces as error on the result object.
-    if (res.error || res.status === null || res.status !== 0) continue;
+    // ENOENT surfaces as error on the result object. Skip silently for ENOENT
+    // (bin not installed is expected for `fabric` when only `fab` is shipped).
+    if (res.error) {
+      if (res.error.code !== "ENOENT") {
+        lastFailure = { bin, reason: String(res.error.message || res.error.code || res.error) };
+      }
+      continue;
+    }
+    if (res.status === null || res.status !== 0) {
+      const stderrSnip = (res.stderr || "").trim().slice(0, 240);
+      if (stderrSnip.length > 0) {
+        lastFailure = { bin, reason: stderrSnip };
+      }
+      continue;
+    }
     const raw = (res.stdout || "").trim();
     if (raw.length === 0) continue;
     try {
       const parsed = JSON.parse(raw);
       if (parsed && typeof parsed === "object") return parsed;
-    } catch {
-      // malformed JSON — try next bin (unlikely to differ, but no harm)
+    } catch (err) {
+      lastFailure = { bin, reason: `malformed JSON from plan-context-hint: ${String(err && err.message || err)}` };
     }
   }
+  if (lastFailure !== null) {
+    // Single warning line — never throws, never blocks the hook. Lets users /
+    // AI notice that the KB chain is degraded instead of being silently empty.
+    process.stderr.write(
+      `[fabric-hint] plan-context-hint (${lastFailure.bin}) failed: ${lastFailure.reason.replace(/\n/g, " ")}\n`,
+    );
+  }
   return null;
 }
 
@@ -351,17 +509,21 @@ function groupEntries(narrow) {
   return { typeOrder, byType };
 }
 
-function truncateSummary(raw) {
+// v2.0.0-rc.33 W4-A3: maxLen is now caller-supplied (sourced from
+// fabric-config#hint_summary_max_len in main; tests + ad-hoc callers may
+// omit to fall back to DEFAULT_SUMMARY_MAX_LEN).
+function truncateSummary(raw, maxLen) {
   const s = typeof raw === "string" ? raw : "";
   // Collapse newlines / runs of whitespace so each entry fits one line.
   const flat = s.replace(/\s+/g, " ").trim();
-  if (flat.length <= SUMMARY_MAX_LEN) return flat;
-  return `${flat.slice(0, SUMMARY_MAX_LEN - 1)}…`;
+  const cap = typeof maxLen === "number" && maxLen > 0 ? maxLen : DEFAULT_SUMMARY_MAX_LEN;
+  if (flat.length <= cap) return flat;
+  return `${flat.slice(0, cap - 1)}…`;
 }
 
-function formatEntryLine(entry) {
+function formatEntryLine(entry, maxLen) {
   const id = entry.id || "(no-id)";
-  const summary = truncateSummary(entry.summary);
+  const summary = truncateSummary(entry.summary, maxLen);
   return summary.length > 0 ? `    - ${id} · ${summary}` : `    - ${id}`;
 }
 
@@ -370,7 +532,7 @@ function formatEntryLine(entry) {
  * Each entry gets one line: `    - <id> · <summary>`. Type/maturity headers
  * group the listing.
  */
-function renderFull(narrow) {
+function renderFull(narrow, maxLen) {
   const { typeOrder, byType } = groupEntries(narrow);
   const lines = [];
   for (const type of typeOrder) {
@@ -389,7 +551,7 @@ function renderFull(narrow) {
     for (const maturity of maturities) {
       lines.push(`  [${type}] (${maturity}):`);
       for (const entry of maturityMap.get(maturity)) {
-        lines.push(formatEntryLine(entry));
+        lines.push(formatEntryLine(entry, maxLen));
       }
     }
   }
@@ -402,7 +564,7 @@ function renderFull(narrow) {
  * an inline id list (no summary); draft (and unknown) buckets collapse to a
  * count.
  */
-function renderTruncated(narrow) {
+function renderTruncated(narrow, maxLen) {
   const { typeOrder, byType } = groupEntries(narrow);
   const lines = [];
   for (const type of typeOrder) {
@@ -413,7 +575,7 @@ function renderTruncated(narrow) {
     if (proven && proven.length > 0) {
       lines.push(`  [${type}] proven (${proven.length}):`);
       for (const entry of proven) {
-        lines.push(formatEntryLine(entry));
+        lines.push(formatEntryLine(entry, maxLen));
       }
     }
 
@@ -450,7 +612,7 @@ function renderTruncated(narrow) {
  * after writing exactly one stderr breadcrumb so operators grepping a stuck-
  * banner report can diagnose the version drift without source-diving.
  */
-function renderSummary(payload) {
+function renderSummary(payload, maxLen) {
   if (!payload || payload.version !== 2) {
     if (payload && payload.version !== undefined) {
       try {
@@ -473,7 +635,7 @@ function renderSummary(payload) {
     ? `[fabric] Session start — ${entries.length} broad-scoped knowledge entries available (truncated):`
     : `[fabric] Session start — ${entries.length} broad-scoped knowledge entries available:`;
 
-  const body = truncated ? renderTruncated(entries) : renderFull(entries);
+  const body = truncated ? renderTruncated(entries, maxLen) : renderFull(entries, maxLen);
 
   const lines = [banner, ...body];
   const revHash = typeof payload.revision_hash === "string" ? payload.revision_hash : null;
@@ -532,7 +694,33 @@ function renderSummary(payload) {
 function main(env, stdio) {
   try {
     const cwd = (env && env.cwd) || process.cwd();
+    const now = (env && env.now) || new Date();
+    const nowMs = now instanceof Date ? now.getTime() : Number(now);
     const err = (stdio && stdio.stderr) || process.stderr;
+    const out = (stdio && stdio.stdout) || process.stdout;
+
+    // v2.0.0-rc.33 W2-5 (P1-8): cooldown gate. When configured > 0 hours, the
+    // broad banner stays silent for that many hours after a successful emit.
+    // 0 (default) preserves rc.32 behavior — every SessionStart re-fires the
+    // banner. Test seam env.skipCooldown bypasses for unit tests.
+    const cooldownHours = readBroadCooldownHours(cwd);
+    if (cooldownHours > 0 && !(env && env.skipCooldown === true)) {
+      const lastEmitMs = readBroadLastEmit(cwd);
+      if (
+        typeof lastEmitMs === "number" &&
+        // rc.34 TASK-01 + review-fix (Gemini P1): when lastEmit is in the
+        // FUTURE relative to now (backward clock skew — NTP sync /
+        // suspend-wake / TZ change), the gate fires immediately. Otherwise
+        // standard cooldown check. Math.max(0, …) was a no-op (silent for
+        // cooldown + |skew| under both formulations); this guard actually
+        // heals the skew on the next invocation by treating future-stamped
+        // sidecar as "expired."
+        nowMs >= lastEmitMs &&
+        nowMs - lastEmitMs < cooldownHours * MS_PER_HOUR
+      ) {
+        return; // still in cooldown — silent
+      }
+    }
 
     // Test seam: env.payload short-circuits the CLI spawn so unit tests can
     // feed canned plan-context-hint JSON without depending on a built CLI.
@@ -540,6 +728,16 @@ function main(env, stdio) {
       env && env.payload !== undefined ? env.payload : invokePlanContextHint(cwd);
     if (payload === null || payload === undefined) return; // silent
 
+    // v2.0.0-rc.33 W2-1 (P0-9): apply TopK slice BEFORE renderSummary so the
+    // grouped/truncation rendering operates on the bounded set. Slicing here
+    // (not inside renderSummary) keeps the formatter pure — it never has to
+    // know about the cap.
+    const topK = readBroadTopK(cwd);
+    const slicedPayload =
+      payload && Array.isArray(payload.entries) && payload.entries.length > topK
+        ? { ...payload, entries: payload.entries.slice(0, topK) }
+        : payload;
+
     // rc.8 underseed self-check: decide whether to surface the one-line
     // `/fabric-import` recommendation banner alongside the broad summary.
     const recommendImport = shouldRecommendImport(cwd);
@@ -548,8 +746,10 @@ function main(env, stdio) {
     // SessionStart fire (Skill-style progressive disclosure). The prior
     // revision_hash cooldown gate (rc.7 T8 — rc.11) was removed because
     // compact/clear-triggered SessionStart re-fires must re-inject the menu
-    // for the agent's working memory.
-    const lines = renderSummary(payload);
+    // for the agent's working memory. rc.33 W2-5 reintroduces an opt-in
+    // hours-based cooldown via fabric-config (see gate above).
+    const summaryMaxLen = readSummaryMaxLen(cwd);
+    const lines = renderSummary(slicedPayload, summaryMaxLen);
 
     if (recommendImport) {
       // rc.16 TASK-003: resolve fabric_language ONCE per invocation (only when
@@ -562,9 +762,52 @@ function main(env, stdio) {
 
     if (lines.length === 0) return; // nothing to say — silent exit
 
+    // Stderr: always emit (human-facing breadcrumb + legacy contract).
     for (const line of lines) {
       err.write(`${line}\n`);
     }
+
+    // v2.0.0-rc.33 W2-6 (P0-7): stdout JSON envelope. When
+    // hint_reminder_to_context is true (default), serialize the same banner
+    // body as Claude Code's SessionStart hookSpecificOutput shape so the model
+    // receives the reminder IN-CONTEXT (rc.32 baseline cite-coverage 3.1%
+    // root cause: reminders never entered model context). Stderr stays the
+    // host-facing channel.
+    //
+    // Failure to write JSON envelope must NOT crash the hook — stderr already
+    // delivered, the stdout layer is best-effort.
+    // v2.0.0-rc.33 W4 review-fix (gemini High-1): the stdout JSON envelope
+    // is Claude Code-specific (hookSpecificOutput.additionalContext contract).
+    // Codex CLI / Cursor don't parse it — leaking it to their stdout risks
+    // either polluting the terminal or crashing the host's hook-parsing
+    // pipeline. CLAUDE_PROJECT_DIR is set by CC when invoking hooks (see
+    // packages/cli/templates/hooks/configs/claude-code.json sigil paths);
+    // its presence is the single-bit "this is Claude Code" signal.
+    const isClaudeCode =
+      typeof process.env.CLAUDE_PROJECT_DIR === "string" &&
+      process.env.CLAUDE_PROJECT_DIR.length > 0;
+    const reminderToContext = readReminderToContext(cwd) && isClaudeCode;
+    if (reminderToContext && !(env && env.skipStdout === true)) {
+      try {
+        const envelope = {
+          hookSpecificOutput: {
+            hookEventName: "SessionStart",
+            additionalContext: lines.join("\n"),
+          },
+        };
+        out.write(`${JSON.stringify(envelope)}\n`);
+      } catch {
+        // Best-effort — stderr is the durable contract
+      }
+    }
+
+    // v2.0.0-rc.33 W2-5 (P1-8): record successful emit timestamp for the
+    // cooldown gate's next-invocation check. Skip when cooldown is disabled
+    // (cooldownHours === 0) to avoid polluting the FS with a never-read
+    // sidecar on rc.32-style "no cooldown" workspaces.
+    if (cooldownHours > 0 && !(env && env.skipCooldownWrite === true)) {
+      writeBroadLastEmit(cwd, nowMs);
+    }
   } catch {
     // Silent — never block session start on hook failure.
   }
@@ -583,16 +826,28 @@ module.exports = {
   readUnderseedThreshold,
   isImportTouched,
   shouldRecommendImport,
+  // v2.0.0-rc.33 W2-1 / W2-5 / W2-6 helpers.
+  readBroadTopK,
+  readBroadCooldownHours,
+  readReminderToContext,
+  readBroadLastEmit,
+  writeBroadLastEmit,
+  readSummaryMaxLen,
   CONSTANTS: {
     TRUNCATION_THRESHOLD,
     CLI_TIMEOUT_MS,
-    SUMMARY_MAX_LEN,
+    SUMMARY_MAX_LEN: DEFAULT_SUMMARY_MAX_LEN,
+    DEFAULT_SUMMARY_MAX_LEN,
     CANONICAL_TYPE_ORDER,
     MATURITY_PROVEN,
     MATURITY_VERIFIED,
     MATURITY_DRAFT,
     DEFAULT_UNDERSEED_NODE_THRESHOLD,
     KNOWLEDGE_CANONICAL_TYPES,
+    DEFAULT_HINT_BROAD_TOP_K,
+    DEFAULT_HINT_BROAD_COOLDOWN_HOURS,
+    DEFAULT_HINT_REMINDER_TO_CONTEXT,
+    HINT_BROAD_LAST_EMIT_FILE,
   },
 };