@fenglimg/fabric-cli 2.0.0 → 2.0.1

package/package.json

@@ -1,16 +1,41 @@
 {
   "name": "@fenglimg/fabric-cli",
-  "version": "2.0.0",
+  "version": "2.0.1",
+  "description": "Fabric CLI — installs the MCP server + skills + hooks for Claude Code, Cursor, and Codex CLI; runs doctor / knowledge maintenance.",
+  "license": "MIT",
+  "author": "wangzhichao <fenglimg90@gmail.com>",
+  "homepage": "https://github.com/fenglimg/fabric-v2#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fenglimg/fabric-v2.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/fenglimg/fabric-v2/issues"
+  },
+  "keywords": [
+    "fabric",
+    "mcp",
+    "cli",
+    "claude-code",
+    "cursor",
+    "codex-cli",
+    "ai-knowledge-management"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
   "type": "module",
   "bin": {
-    "fab": "dist/index.js",
     "fabric": "dist/index.js"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "templates"
+    "templates",
+    "LICENSE",
+    "README.md"
   ],
   "dependencies": {
     "@clack/prompts": "^1.2.0",
@@ -20,8 +45,8 @@
     "tree-sitter-javascript": "^0.25.0",
     "tree-sitter-typescript": "^0.23.2",
     "web-tree-sitter": "^0.26.8",
-    "@fenglimg/fabric-server": "2.0.0",
-    "@fenglimg/fabric-shared": "2.0.0"
+    "@fenglimg/fabric-server": "2.0.1",
+    "@fenglimg/fabric-shared": "2.0.1"
   },
   "devDependencies": {
     "@types/node": "^22.15.0",

package/templates/hooks/cite-policy-evict.cjs

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+/**
+ * v2.0.0-rc.34 TASK-06 — cite-policy long-session evict sidecar.
+ *
+ * UserPromptSubmit hook (Claude Code only). Drives periodic cite-policy
+ * reminder injection in long sessions where attention decay erodes contract
+ * adherence (rc.32 Batch 1: 3.1% cite coverage baseline).
+ *
+ * Strategy: **turn-count window** (locked decision per rc.34 plan 2026-05-26;
+ * time-based and token-budget strategies pushed to rc.35). The hook maintains
+ * a per-session counter in `.fabric/.cache/cite-evict-state.json`; on each
+ * UserPromptSubmit, increment the counter and — when
+ * `turn_count % cite_evict_interval == 0` AND `cite_evict_interval > 0` —
+ * emit a compact cite-contract reminder via Claude Code's stdout JSON
+ * envelope (hookSpecificOutput.additionalContext, same channel as rc.33 W2
+ * knowledge-hint-broad reminder-to-context).
+ *
+ * Config: `cite_evict_interval` (number, default 0 = OFF, opt-in). Recommend
+ * 10-20 for active sessions; 5 for high-contract-criticality projects.
+ *
+ * State sidecar shape:
+ *   { session_id: string, turn_count: number }
+ *
+ * Session-boundary semantics: when incoming `session_id` (read from stdin
+ * payload) differs from sidecar's `session_id`, the counter resets to 1 (new
+ * session always starts at 1, never 0 — first turn is "turn 1" not "turn 0").
+ *
+ * Failure invariant: any error path (sidecar I/O failure, stdin parse error,
+ * config read failure) MUST end in silent exit 0. The hook never blocks user
+ * prompt submission on its own malfunction.
+ *
+ * Cross-client scope: Claude Code only (relies on hookSpecificOutput contract
+ * + UserPromptSubmit event registration). Codex CLI and Cursor don't have an
+ * equivalent event hook; cite-coverage telemetry there relies on Stop-hook
+ * fabric-hint and SessionStart knowledge-hint-broad (rc.33 W2 channel).
+ */
+
+// v2.0.0-rc.37 NEW-19: config + sidecar I/O now flow through shared libs so
+// the read-config-or-default and read/write-sidecar boilerplate lives in one
+// canonical place. Unguarded require mirrors knowledge-hint-broad's
+// banner-i18n import — the installer copies every lib/*.cjs alongside the hook.
+const { readConfigNumber } = require("./lib/config-cache.cjs");
+const { readJsonState, writeJsonState } = require("./lib/state-store.cjs");
+// v2.0.0-rc.37 NEW-30: client detect + stdin + channel-aware emit now flow
+// through the shared adapter (Claude Code stdout envelope vs Codex/Cursor
+// stderr). Replaces the local isClaudeCode + readStdinJson + inline emits.
+const { isClaudeCode, readStdinJson, emitContext } = require("./lib/client-adapter.cjs");
+
+// Sidecar basename resolved under .fabric/.cache/ by state-store.
+const EVICT_STATE_FILE_NAME = "cite-evict-state.json";
+
+// Default OFF (opt-in). Mirrors hint_broad_cooldown_hours and
+// archive_hint_cooldown_hours convention of "feature exists but inert until
+// user enables it." Schema in packages/shared/src/schemas/fabric-config.ts
+// caps at sensible bounds (positive int).
+// v2.0.0-rc.37 NEW-18: default flipped 0 (opt-in OFF) → 10 (default ON every
+// 10 turns) so users get cite-policy nudges out-of-the-box. Operators on
+// short / scripted sessions can still set `cite_evict_interval: 0` in
+// .fabric/fabric-config.json to opt back out. Per-NEW-1 reminder body now
+// uses the simplified 2-state vocabulary ([applied] / [dismissed:<reason>]).
+const DEFAULT_CITE_EVICT_INTERVAL = 10;
+
+/**
+ * Read .fabric/fabric-config.json#cite_evict_interval. Returns the parsed
+ * positive integer OR DEFAULT_CITE_EVICT_INTERVAL on any failure path
+ * (missing file, parse error, non-numeric value, negative). Mirrors the
+ * defensive config-read pattern in knowledge-hint-broad.cjs readBroadCooldownHours.
+ */
+function readEvictInterval(cwd) {
+  return readConfigNumber(cwd, "cite_evict_interval", DEFAULT_CITE_EVICT_INTERVAL, {
+    min: 0,
+    integer: true,
+  });
+}
+
+/**
+ * Read prior state sidecar. Returns `null` on first-run or any failure;
+ * callers treat null as "no prior state" (caller will write fresh state
+ * with turn_count=1).
+ */
+function readEvictState(cwd) {
+  return readJsonState(
+    cwd,
+    EVICT_STATE_FILE_NAME,
+    (parsed) =>
+      parsed &&
+      typeof parsed.session_id === "string" &&
+      typeof parsed.turn_count === "number" &&
+      Number.isInteger(parsed.turn_count) &&
+      parsed.turn_count >= 0,
+  );
+}
+
+function writeEvictState(cwd, sessionId, turnCount) {
+  // best-effort — counter loss is acceptable, hook never blocks
+  writeJsonState(cwd, EVICT_STATE_FILE_NAME, { session_id: sessionId, turn_count: turnCount });
+}
+
+/**
+ * Pure helper for unit-testing. Given current `turnCount` (post-increment)
+ * and `interval`, decide whether to emit the reminder.
+ *
+ * Contract:
+ *   - interval <= 0 → never emit (feature off)
+ *   - turnCount <= 0 → never emit (guard against bogus state)
+ *   - emit iff turnCount % interval === 0
+ *
+ * Examples:
+ *   evaluateCiteEvict(10, 10) → true  (10 % 10 === 0)
+ *   evaluateCiteEvict(20, 10) → true
+ *   evaluateCiteEvict(15, 10) → false
+ *   evaluateCiteEvict(5, 0)   → false (off)
+ *   evaluateCiteEvict(0, 10)  → false (no turns yet)
+ */
+function evaluateCiteEvict(turnCount, interval) {
+  if (typeof interval !== "number" || interval <= 0) return false;
+  if (typeof turnCount !== "number" || turnCount <= 0) return false;
+  return turnCount % interval === 0;
+}
+
+/**
+ * Build the cite-contract reminder body. Compact — under 10 lines. The
+ * fully-specified contract lives in `.fabric/AGENTS.md` Cite policy section;
+ * the reminder is a tactical re-anchor, not the canonical reference.
+ *
+ * Returns a multi-line string ready for hookSpecificOutput.additionalContext.
+ */
+function renderReminder(turnCount, interval) {
+  // v2.0.0-rc.37 NEW-1: cite policy simplified 4-state → 2-state.
+  // [applied] consolidates planned/recalled/chained-from; dismissed:<reason>
+  // unchanged. Old tags still parse for back-compat.
+  return [
+    `[fabric cite-evict] long-session reminder (turn ${turnCount}, interval ${interval}):`,
+    "Before edit / decide / propose plan, write KB: <id> (<≤8字 用法>) [applied|dismissed:<reason>] OR KB: none [<reason>].",
+    "Verify [applied] by actually fetching KB body via fab_recall(paths) or fab_plan_context → fab_get_knowledge_sections (no fabricated ids).",
+    "decisions/pitfalls [applied] cite MUST end with contract: → <operator> [<operator>...] where operator ∈ {edit:<glob> !edit:<glob> require:<symbol> forbid:<symbol> skip:<reason>}.",
+    "skip reasons: sequencing | conditional | semantic | aesthetic | architectural | other:<text>.",
+    "KB: none sentinels: [no-relevant] (queried but nothing matched) | [not-applicable] (pure exploration / read-only / user Q&A).",
+    "Audit: fabric doctor --cite-coverage — this rule does not block work, only records.",
+  ].join("\n");
+}
+
+async function main(env) {
+  try {
+    const cwd =
+      (env && typeof env.cwd === "string" && env.cwd) ||
+      process.env.CLAUDE_PROJECT_DIR ||
+      process.cwd();
+
+    const interval = readEvictInterval(cwd);
+    if (interval <= 0) {
+      return; // feature off — silent exit
+    }
+
+    // Read stdin payload (Claude Code passes hook_event_name; Codex/Cursor
+    // SessionStart payloads are smaller but still JSON). Tests inject
+    // env.payload to bypass the stdin read.
+    const payload = env && env.payload !== undefined ? env.payload : await readStdinJson();
+
+    // v2.0.0-rc.37 NEW-21: SessionStart-mode parity for Codex/Cursor.
+    // When the hook fires on SessionStart (instead of UserPromptSubmit),
+    // emit ONE unconditional cite-policy reminder to stderr. This gives
+    // Codex/Cursor users the cite-contract nudge at session boot — lower
+    // cadence than Claude Code's per-prompt UserPromptSubmit window, but
+    // strictly better than 0 (rc.32 cite-coverage baseline 3.1% measured
+    // when Codex/Cursor had no cite-reminder surface at all).
+    const eventName =
+      payload && typeof payload.hook_event_name === "string"
+        ? payload.hook_event_name
+        : null;
+    const sessionStartMode =
+      (env && env.forceSessionStart === true) || eventName === "SessionStart";
+
+    const streams = (env && env.stdio) || {};
+
+    if (sessionStartMode) {
+      // One-shot stderr emit (knowledge-hint-broad convention). forceStderr
+      // pins stderr even on Claude Code — Codex/Cursor parse stderr; CC
+      // SessionStart also surfaces stderr to the user.
+      emitContext(renderReminder(/* turnCount = */ 0, interval), {
+        forceStderr: true,
+        streams,
+      });
+      return;
+    }
+
+    // Claude Code UserPromptSubmit path (unchanged from rc.34 TASK-06).
+    // Skip Claude Code-specific stdout envelope on Codex/Cursor when not
+    // in SessionStart mode (no UserPromptSubmit event registration there).
+    if (!isClaudeCode() && !(env && env.forceClaudeCode === true)) {
+      return;
+    }
+
+    const sessionId =
+      payload && typeof payload.session_id === "string" && payload.session_id.length > 0
+        ? payload.session_id
+        : "anonymous";
+
+    const prior = readEvictState(cwd);
+    const turnCount = prior && prior.session_id === sessionId ? prior.turn_count + 1 : 1;
+    writeEvictState(cwd, sessionId, turnCount);
+
+    if (!evaluateCiteEvict(turnCount, interval)) {
+      return; // not on a window boundary — silent
+    }
+
+    // Claude Code UserPromptSubmit: stdout JSON envelope. client:'cc' forces
+    // the envelope since the isClaudeCode/forceClaudeCode gate above already
+    // confirmed this is the Claude Code path.
+    emitContext(renderReminder(turnCount, interval), {
+      client: "cc",
+      eventName: "UserPromptSubmit",
+      streams,
+    });
+  } catch {
+    // Silent — never block user prompt on hook failure.
+  }
+}
+
+module.exports = {
+  main,
+  evaluateCiteEvict,
+  renderReminder,
+  readEvictInterval,
+  readEvictState,
+  writeEvictState,
+};
+
+if (require.main === module) {
+  main();
+}

package/templates/hooks/configs/README.md

@@ -1,6 +1,6 @@
 # Client hook config templates
 
-These JSON files are **fragment templates** consumed by `fabric init` and
+These JSON files are **fragment templates** consumed by `fabric install` and
 `fabric hooks install`. They are not standalone client config files.
 
 The supported clients are pinned by `packages/shared/src/schemas/fabric-config.ts`
@@ -27,11 +27,34 @@ config (`~/.codex/config.toml`) is TOML.
 
 ## cursor-hooks.json
 
-Written to (or merged into) the user repo's `.cursor/hooks.json`. Mirrors the
-Codex `events.Stop[]` envelope shape — Cursor's hook event vocabulary is
-not stable across releases, so the canonical Stop-on-tool-finish lifecycle hook
-is the only entry we register today. SessionStart / PreToolUse slots are left
-unfilled for rc.6 to add when their semantics stabilise.
+Written to (or merged into) the user repo's `.cursor/hooks.json`. Schema
+authoritative source: https://cursor.com/cn/docs/hooks. Top-level requires
+`version: 1` (number literal, NOT string) and a `hooks` object (NOT `events`)
+keyed by camelCase event names: `stop`, `sessionStart`, `preToolUse`. Per-entry
+shape stays flat (Codex-style): `{command, matcher?, type?, timeout?,
+loop_limit?, failClosed?}`. rc.14 TASK-001 corrected rc.13's wrong top-level
+envelope (was `{events: {Stop, SessionStart, PreToolUse}}` PascalCase, which
+Cursor rejects with "Config version must be a number; Config hooks must be an
+object").
+
+## Per-client schema comparison (v2.0.0-rc.37 NEW-29)
+
+Each host program enforces its own wire format — `fabric install` cannot
+serialize one shared shape across all three. Differences are pinned here
+side-by-side so anyone editing one config knows what the others require.
+
+| Axis                 | Claude Code                              | Codex CLI                                          | Cursor                                          |
+| -------------------- | ---------------------------------------- | -------------------------------------------------- | ----------------------------------------------- |
+| Settings file        | `.claude/settings.json`                  | `.codex/hooks.json`                                | `.cursor/hooks.json`                            |
+| Top-level envelope   | `hooks: { ... }` (no version)            | `events: { ... }` (no version)                     | `{ version: 1, hooks: { ... } }` (number, not string) |
+| Event-name case      | PascalCase: `Stop`, `SessionStart`, `PreToolUse`, `UserPromptSubmit` | PascalCase: `Stop`, `SessionStart`, `PreToolUse`     | camelCase: `stop`, `sessionStart`, `preToolUse` |
+| Per-entry shape      | Nested matcher: `[{matcher, hooks:[{type:"command", command}]}]` | Flat: `[{command, matcher?}]`                      | Flat: `[{command, matcher?, type?, timeout?, loop_limit?, failClosed?}]` |
+| Path interpolation   | `${CLAUDE_PROJECT_DIR}` (env var)        | `"$(git rev-parse --show-toplevel)"` (shell expansion) | project-relative (resolved by Cursor)           |
+| Cite-policy event    | `UserPromptSubmit` (per-prompt)          | `SessionStart` 2nd entry (rc.37 NEW-21 parity)     | `sessionStart` 2nd entry (rc.37 NEW-21 parity)  |
+
+Whenever a hook is added to one config, walk this table and add the equivalent
+entry to the other two — `fabric install` merges each into its respective
+target verbatim, so missing entries silently degrade the cross-client surface.
 
 ## fabric-hint.cjs script paths
 

package/templates/hooks/configs/claude-code.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": ".claude/hooks/fabric-hint.cjs"
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/fabric-hint.cjs"
           }
         ]
       }
@@ -17,7 +17,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": ".claude/hooks/knowledge-hint-broad.cjs"
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/knowledge-hint-broad.cjs"
           }
         ]
       }
@@ -28,7 +28,18 @@
         "hooks": [
           {
             "type": "command",
-            "command": ".claude/hooks/knowledge-hint-narrow.cjs"
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/knowledge-hint-narrow.cjs"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/cite-policy-evict.cjs"
           }
         ]
       }

package/templates/hooks/configs/codex-hooks.json

@@ -2,18 +2,21 @@
   "events": {
     "Stop": [
       {
-        "command": ".codex/hooks/fabric-hint.cjs"
+        "command": "\"$(git rev-parse --show-toplevel)/.codex/hooks/fabric-hint.cjs\""
       }
     ],
     "SessionStart": [
       {
-        "command": ".codex/hooks/knowledge-hint-broad.cjs"
+        "command": "\"$(git rev-parse --show-toplevel)/.codex/hooks/knowledge-hint-broad.cjs\""
+      },
+      {
+        "command": "\"$(git rev-parse --show-toplevel)/.codex/hooks/cite-policy-evict.cjs\""
       }
     ],
     "PreToolUse": [
       {
         "matcher": "Edit|Write|MultiEdit",
-        "command": ".codex/hooks/knowledge-hint-narrow.cjs"
+        "command": "\"$(git rev-parse --show-toplevel)/.codex/hooks/knowledge-hint-narrow.cjs\""
       }
     ]
   }

package/templates/hooks/configs/cursor-hooks.json

@@ -1,16 +1,14 @@
 {
-  "events": {
-    "Stop": [
-      {
-        "command": ".cursor/hooks/fabric-hint.cjs"
-      }
+  "version": 1,
+  "hooks": {
+    "stop": [
+      { "command": ".cursor/hooks/fabric-hint.cjs" }
     ],
-    "SessionStart": [
-      {
-        "command": ".cursor/hooks/knowledge-hint-broad.cjs"
-      }
+    "sessionStart": [
+      { "command": ".cursor/hooks/knowledge-hint-broad.cjs" },
+      { "command": ".cursor/hooks/cite-policy-evict.cjs" }
     ],
-    "PreToolUse": [
+    "preToolUse": [
       {
         "matcher": "Edit|Write|MultiEdit",
         "command": ".cursor/hooks/knowledge-hint-narrow.cjs"