@fenglimg/fabric-cli 1.8.0-rc.3 → 2.0.0-rc.8

package/dist/plan-context-hint-QMUPAXIB.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+import {
+  resolveDevMode
+} from "./chunk-OBQU6NHO.js";
+
+// src/commands/plan-context-hint.ts
+import { defineCommand } from "citty";
+import { planContext } from "@fenglimg/fabric-server";
+var ALL_PATHS_SENTINEL = "**";
+var planContextHintCommand = defineCommand({
+  meta: {
+    name: "plan-context-hint",
+    description: "Emit versioned knowledge hint JSON to stdout. Used by rc.6 hooks and the fabric-import skill."
+  },
+  args: {
+    paths: {
+      type: "string",
+      description: "Comma-separated list of file paths to compute narrow hints for."
+    },
+    all: {
+      type: "boolean",
+      description: "Return the full broad+narrow set with no path filter.",
+      default: false
+    },
+    target: {
+      type: "string",
+      description: "Override the project root (defaults to cwd / dev-mode resolution)."
+    }
+  },
+  async run({ args }) {
+    try {
+      const output = await runPlanContextHint({
+        paths: parsePathsArg(args.paths),
+        all: args.all === true,
+        target: args.target
+      });
+      process.stdout.write(`${JSON.stringify(output)}
+`);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      process.stderr.write(`plan-context-hint failed: ${message}
+`);
+      process.exitCode = 1;
+    }
+  }
+});
+var plan_context_hint_default = planContextHintCommand;
+async function runPlanContextHint(opts) {
+  const all = opts.all === true;
+  const explicitPaths = (opts.paths ?? []).filter((p) => p.length > 0);
+  const targetPaths = all ? [ALL_PATHS_SENTINEL] : explicitPaths.length > 0 ? explicitPaths : [ALL_PATHS_SENTINEL];
+  const resolution = resolveDevMode(opts.target, process.cwd());
+  const result = await planContext(resolution.target, {
+    paths: targetPaths
+  });
+  const sharedIndex = result.shared.description_index;
+  const narrowSource = all ? sharedIndex : (
+    // Path mode: union of per-entry description_index across requested
+    // paths, deduped by stable_id. This is identical to `shared` for L0/L1
+    // entries (always included) and additionally captures L2 entries whose
+    // scope_glob matches the requested path.
+    dedupeByStableId(result.entries.flatMap((entry) => entry.description_index))
+  );
+  const narrow = narrowSource.map((item) => ({
+    id: item.stable_id,
+    type: item.type ?? item.description.knowledge_type ?? "",
+    maturity: item.maturity ?? item.description.maturity ?? "",
+    summary: item.description.summary
+  }));
+  return {
+    version: 1,
+    revision_hash: result.revision_hash,
+    target_paths: targetPaths,
+    narrow,
+    broad_count: sharedIndex.length
+  };
+}
+function parsePathsArg(raw) {
+  if (raw === void 0 || raw.length === 0) {
+    return [];
+  }
+  return raw.split(",").map((part) => part.trim()).filter((part) => part.length > 0);
+}
+function dedupeByStableId(items) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const item of items) {
+    if (seen.has(item.stable_id)) continue;
+    seen.add(item.stable_id);
+    result.push(item);
+  }
+  return result;
+}
+export {
+  plan_context_hint_default as default,
+  planContextHintCommand,
+  runPlanContextHint
+};

package/dist/scan-LMK3UCWL.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import {
+  __testing__,
+  createScanReport,
+  deriveTagsFromForensic,
+  formatKnowledgeId,
+  runInitScan,
+  scanCommand,
+  scan_default
+} from "./chunk-EYIDD2YS.js";
+import "./chunk-WWNXR34K.js";
+import "./chunk-6ICJICVU.js";
+import "./chunk-OBQU6NHO.js";
+export {
+  __testing__,
+  createScanReport,
+  scan_default as default,
+  deriveTagsFromForensic,
+  formatKnowledgeId,
+  runInitScan,
+  scanCommand
+};

package/dist/{serve-466QXQ5Q.js → serve-H554BHLG.js}

@@ -1,11 +1,15 @@
 #!/usr/bin/env node
 import {
-  createDebugLogger,
   paint,
-  resolveDevMode,
-  symbol,
+  symbol
+} from "./chunk-WWNXR34K.js";
+import {
   t
-} from "./chunk-QPCRBQ5Y.js";
+} from "./chunk-6ICJICVU.js";
+import {
+  createDebugLogger,
+  resolveDevMode
+} from "./chunk-OBQU6NHO.js";
 
 // src/commands/serve.ts
 import { defineCommand } from "citty";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fenglimg/fabric-cli",
-  "version": "1.8.0-rc.3",
+  "version": "2.0.0-rc.8",
   "type": "module",
   "bin": {
     "fab": "dist/index.js",
@@ -20,8 +20,8 @@
     "tree-sitter-javascript": "^0.25.0",
     "tree-sitter-typescript": "^0.23.2",
     "web-tree-sitter": "^0.26.8",
-    "@fenglimg/fabric-server": "1.8.0-rc.3",
-    "@fenglimg/fabric-shared": "1.8.0-rc.3"
+    "@fenglimg/fabric-server": "2.0.0-rc.8",
+    "@fenglimg/fabric-shared": "2.0.0-rc.8"
   },
   "devDependencies": {
     "@types/node": "^22.15.0",

package/templates/agents-md/AGENTS.md.template

@@ -1,21 +1,59 @@
-# { projectName } — Fabric Bootstrap Protocol
-
-## CORE RULES (DO NOT TRANSLATE)
-
-MUST: Treat this file as the Fabric Protocol bootstrap for this repository.
-MUST: Treat `.fabric/rules/` as the source of truth for all Fabric rule bodies.
-MUST: Before ANY code reading, architecture planning, or logic modification, call `fab_plan_context(paths=[<target file>])`, then call `fab_get_rule_sections`.
-MUST: When creating or changing an L1/L2 rule node, keep `.fabric/agents.meta.json` synchronized through Fabric tooling.
-MUST: Preserve protected tokens exactly: `AGENTS.md`, `.fabric/rules/`, `.fabric/agents.meta.json`, `fab_plan_context`, `fab_get_rule_sections`, `rule sources`, `rule source mirroring`, `MUST`, `NEVER`.
-NEVER: Add import-style directive lines to this bootstrap file.
-NEVER: Put framework, domain, repository rule bodies, or submodule rules in this file.
-NEVER: Create colocated `AGENTS.md` rule files under source directories.
-
+# { projectName } — Fabric Bootstrap Protocol
+
+## CORE RULES (DO NOT TRANSLATE)
+
+MUST: Treat this file as the Fabric Protocol bootstrap for this repository.
+MUST: Treat `.fabric/knowledge/` as the source of truth for all Fabric knowledge entries.
+MUST: Before ANY code reading, architecture planning, or logic modification, call `fab_plan_context(paths=[<target file>])`, then call `fab_get_knowledge_sections`.
+MUST: When creating or changing a knowledge entry, keep `.fabric/agents.meta.json` synchronized through Fabric tooling (never hand-edit).
+MUST: Preserve protected tokens exactly: `AGENTS.md`, `.fabric/knowledge/`, `.fabric/agents.meta.json`, `fab_plan_context`, `fab_get_knowledge_sections`, `knowledge sources`, `MUST`, `NEVER`.
+NEVER: Add import-style directive lines to this bootstrap file.
+NEVER: Put domain knowledge bodies, framework rules, or repository specifics in this file.
+NEVER: Create colocated `AGENTS.md` knowledge files under source directories.
+NEVER: Hand-edit anything under `.fabric/knowledge/pending/` outside of the proposal/review workflow.
+
 ## 使用说明 / Explanation
 
-- 本文件只负责启动 Fabric Bootstrap Protocol，不承载项目业务规则。
+- 本文件只负责启动 Fabric Bootstrap Protocol，不承载项目业务知识。
 - 详细 bootstrap 说明位于 `.fabric/bootstrap/README.md`。
 - Detected framework kind: `{ frameworkKind }`.
-- This repository uses `rule source mirroring`: source directories contain ZERO rule files, while `.fabric/rules/` mirrors source paths for AI constraints.
-- 根级规则应放在 `.fabric/rules/root.md`；跨领域规则应放在 `.fabric/rules/_cross/`。
-- If `.fabric/rules/root.md` is missing, continue with the Fabric initialization flow before normal coding.
+- This repository uses `knowledge mirroring`: source directories contain ZERO knowledge files, while `.fabric/knowledge/` holds all AI-facing constraints, organized by knowledge type.
+- 跨领域、根级知识应放在对应的 `.fabric/knowledge/{type}/` 子目录下。
+- If `.fabric/knowledge/` is empty after init, continue with the Fabric initialization flow before normal coding.
+
+## Knowledge layer (v2)
+
+Fabric v2 organises every AI-facing knowledge entry along three orthogonal axes: **type**, **maturity**, and **layer**. All entries live as flat markdown files with YAML frontmatter — no nesting, no implicit hierarchies.
+
+### 5 knowledge types
+
+Each entry lives in exactly one of these subdirectories of `.fabric/knowledge/`:
+
+- `decisions/` — architectural / design decisions (the "why" behind a choice, with rejected alternatives)
+- `pitfalls/` — known traps, footguns, and "do-not-do-X" lessons learned the hard way
+- `guidelines/` — actionable rules and conventions the AI should follow when generating or modifying code
+- `models/` — domain models, data shapes, and conceptual abstractions (entities, invariants)
+- `processes/` — multi-step workflows, runbooks, and operational sequences
+
+### 3 maturity levels
+
+The `maturity` frontmatter field expresses how trusted an entry is:
+
+- `draft` — newly captured, not yet reviewed; the AI may consult it but should treat it as provisional
+- `verified` — reviewed and confirmed correct in the current codebase; safe to rely on
+- `proven` — verified and battle-tested across multiple changes; treat as authoritative
+
+Promotion is one-way (`draft` → `verified` → `proven`); demotion happens only via the review workflow.
+
+### 2 layers (dual-root)
+
+Knowledge lives in two physical roots that share the same schema:
+
+- `~/.fabric/knowledge/` — **personal layer** (per-user, NOT committed). Entries here use the `KP-` stable_id prefix. Use this layer for individual preferences, scratch notes, and cross-project habits.
+- `<repo>/.fabric/knowledge/` — **team layer** (committed to the repo). Entries here use the `KT-` stable_id prefix. Use this layer for anything every contributor (human or AI) should respect.
+
+A given entry belongs to exactly one layer; layer-flip (KP ↔ KT) is the only legal mutation of stable_id.
+
+### Proposal staging: `pending/`
+
+`.fabric/knowledge/pending/` is the staging area for proposed entries awaiting review. The async-review workflow (`fabric-review` skill, rc.3) promotes pending entries into one of the 5 type subdirectories once accepted, or archives them on rejection. **Never** hand-edit files under `pending/` directly — use the proposal tooling.

package/templates/bootstrap/CLAUDE.md

@@ -1,7 +1,7 @@
 # Fabric Bootstrap
 - 主说明文档已收敛到 `.fabric/bootstrap/README.md`。
 - 项目级 bootstrap 入口仍然是 `AGENTS.md`。
-- 修改任何文件前必须调用 `fab_plan_context(paths=[<被改文件>])`，再调用 `fab_get_rule_sections` 获取规则段落。
+- 修改任何文件前必须调用 `fab_plan_context(paths=[<被改文件>])`，再调用 `fab_get_knowledge_sections` 获取规则段落。
 MCP 和 doctor 会写入 `.fabric/events.jsonl`。
 - 规则 baseline 变更通过 `fabric doctor --fix` 接受。
 

package/templates/bootstrap/codex-AGENTS-header.md

@@ -1,6 +1,6 @@
 # Fabric Bootstrap
 - 主说明文档已收敛到 `.fabric/bootstrap/README.md`。
 - 此 header 仅用于把 Codex 引导到 Fabric 项目级规则入口。
-- 修改任何文件前必须调用 `fab_plan_context(paths=[<被改文件>])`，再调用 `fab_get_rule_sections` 获取规则段落。
+- 修改任何文件前必须调用 `fab_plan_context(paths=[<被改文件>])`，再调用 `fab_get_knowledge_sections` 获取规则段落。
 MCP 和 doctor 会写入 `.fabric/events.jsonl`。
 - 规则 baseline 变更通过 `fabric doctor --fix` 接受。

package/templates/bootstrap/cursor-fabric-bootstrap.mdc

@@ -5,6 +5,6 @@ description: Fabric Protocol bootstrap rules
 
 # Fabric Bootstrap
 - 本项目使用 Fabric Protocol 管理规则。
-- **任何文件修改前**，必须先调 MCP tool `fab_plan_context(paths=[<被改文件>])`，再调 `fab_get_rule_sections` 获取规则段落。
+- **任何文件修改前**，必须先调 MCP tool `fab_plan_context(paths=[<被改文件>])`，再调 `fab_get_knowledge_sections` 获取规则段落。
 - 新建或调整 L1/L2 节点时，修改规则源文件后运行 `fabric doctor --fix` 接受 baseline，**严禁**直接编辑 `.fabric/agents.meta.json`。
 Fabric 会把 MCP 和 doctor 行为写入 `.fabric/events.jsonl`。

package/templates/hooks/configs/README.md

@@ -0,0 +1,73 @@
+# Client hook config templates
+
+These JSON files are **fragment templates** consumed by `fabric init` and
+`fabric hooks install`. They are not standalone client config files.
+
+The supported clients are pinned by `packages/shared/src/schemas/fabric-config.ts`
+to Claude Code, Cursor, and Codex CLI. Adding a new client requires extending
+that schema first.
+
+## claude-code.json
+
+Deep-merged into the user repo's `.claude/settings.json` by the init pipeline.
+Registers `fabric-hint.cjs` under `hooks.Stop[]` with `matcher: "*"`. The
+existing `mcpServers`, `permissions`, and any other top-level keys in the user's
+settings.json are preserved.
+
+The `hooks.Stop[]` array merge needs special-case handling (array-append with
+dedupe by `command` string) because `packages/cli/src/config/json.ts:18` default
+`deepMerge` REPLACES arrays. The mergeClaudeCodeHookConfig helper owns that
+wiring.
+
+## codex-hooks.json
+
+Written to (or merged into) the user repo's `.codex/hooks.json`. NOTE: Codex
+project-level hooks file is JSON, **not** TOML — only the user-level Codex MCP
+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.
+
+## fabric-hint.cjs script paths
+
+- Claude: `.claude/hooks/fabric-hint.cjs` (project-relative)
+- Codex:  `.codex/hooks/fabric-hint.cjs`  (project-relative)
+- Cursor: `.cursor/hooks/fabric-hint.cjs` (project-relative)
+
+The single shared script lives at `packages/cli/templates/hooks/fabric-hint.cjs`
+in this repo and is copied into all three `<client>/hooks/` destinations by the
+install wiring. The script emits stdout JSON
+`{decision:"block", reason, signal, recommended_skill}` with exit 0 when one of
+three signals trips:
+
+- **archive** (rc.5 TASK-015): 24h elapsed since last `knowledge_proposed`
+  event. Silent on a never-archived workspace (that case is the **import**
+  signal's domain). Recommends the `fabric-archive` skill. The previous
+  `5 plan_contexts` count branch (rc.2) was dropped because rc.5+ hooks
+  auto-fire plan_context events; rc.6 will reintroduce an Edit-count signal
+  via a PreToolUse sidecar.
+- **review** (rc.3): pending knowledge count >= 10, OR oldest pending entry >= 7
+  days old. Recommends the `fabric-review` skill.
+- **import** (rc.5): canonical knowledge node count < `underseed_node_threshold`
+  (default 10) AND `init_scan_completed` event >= 24h ago AND no
+  `knowledge_proposed` event in last 24h. Recommends the `fabric-import` skill.
+
+Precedence: archive > review > import. After firing, the hook stays silent for
+`archive_hint_cooldown_hours` (default 12h, keyed by `signal` so the three
+signals share a cache file but throttle independently).
+
+The script is silent + exit 0 when no signal trips. It NEVER blocks tool
+execution on its own failure — any read/parse error is swallowed.
+
+## Historical note: archive-hint.cjs rename
+
+Pre-rc.5, this script was named `archive-hint.cjs` (only the archive signal
+existed). rc.5 TASK-010 renamed it to `fabric-hint.cjs` to reflect its expanded
+three-signal scope. The cooldown cache file is intentionally still named
+`archive-hint-shown.json` so an in-place upgrade does not flush the user's
+existing throttle state.

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

@@ -0,0 +1,37 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/fabric-hint.cjs"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/knowledge-hint-broad.cjs"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/knowledge-hint-narrow.cjs"
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,20 @@
+{
+  "events": {
+    "Stop": [
+      {
+        "command": ".codex/hooks/fabric-hint.cjs"
+      }
+    ],
+    "SessionStart": [
+      {
+        "command": ".codex/hooks/knowledge-hint-broad.cjs"
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "command": ".codex/hooks/knowledge-hint-narrow.cjs"
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,20 @@
+{
+  "events": {
+    "Stop": [
+      {
+        "command": ".cursor/hooks/fabric-hint.cjs"
+      }
+    ],
+    "SessionStart": [
+      {
+        "command": ".cursor/hooks/knowledge-hint-broad.cjs"
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "command": ".cursor/hooks/knowledge-hint-narrow.cjs"
+      }
+    ]
+  }
+}