@fenglimg/fabric-cli 2.0.0-rc.13 → 2.0.0-rc.21

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

@@ -615,9 +615,17 @@ function formatEntryLine(entry) {
 
 /**
  * Render the narrow-match block to an array of stderr lines. Returns []
- * when there is nothing to render (empty narrow set). Callers stay silent
+ * when there is nothing to render (empty entries set). Callers stay silent
  * on empty output.
  *
+ * Protocol gate (rc.18): only `payload.version === 2` payloads are
+ * rendered. Anything else returns []. When the payload exists but carries
+ * a mismatched (non-undefined) version, a one-line stderr breadcrumb is
+ * emitted as a debug aid — see `_protocol-v2-decisions.md` (Decision 2,
+ * "silent-skip + one-line stderr breadcrumb"). The wire field is
+ * `payload.entries` (renamed from `payload.narrow` in protocol v2,
+ * Decision 1).
+ *
  * Output shape:
  *   [fabric] N narrow-scoped knowledge entries match your edit targets:
  *     [<id>] (<type>/<maturity>) <summary>
@@ -625,13 +633,28 @@ function formatEntryLine(entry) {
  *   (如需重读 broad 决策，调 fab_plan_context 或 fabric plan-context-hint --all)
  */
 function renderSummary(payload) {
-  const narrow = Array.isArray(payload && payload.narrow) ? payload.narrow : [];
-  if (narrow.length === 0) return [];
+  if (!payload || payload.version !== 2) {
+    if (payload && payload.version !== undefined) {
+      // breadcrumb only if payload exists but version mismatches (avoid
+      // spam on null). Best-effort write — silent-on-failure honors the
+      // hook's "never block edits" contract.
+      try {
+        process.stderr.write(
+          `[fabric] hint payload version=${payload.version} unsupported (expected 2), skipping\n`,
+        );
+      } catch {
+        // ignore — stderr unavailable, silent-skip still applies
+      }
+    }
+    return [];
+  }
+  const entries = Array.isArray(payload.entries) ? payload.entries : [];
+  if (entries.length === 0) return [];
 
   const lines = [
-    `[fabric] ${narrow.length} narrow-scoped knowledge entries match your edit targets:`,
+    `[fabric] ${entries.length} narrow-scoped knowledge entries match your edit targets:`,
   ];
-  for (const entry of narrow) {
+  for (const entry of entries) {
     lines.push(formatEntryLine(entry));
   }
   lines.push("  (如需重读 broad 决策，调 fab_plan_context 或 fabric plan-context-hint --all)");
@@ -699,7 +722,8 @@ function main(env, stdio) {
         : invokePlanContextHint(cwd, paths);
     if (cliPayload === null || cliPayload === undefined) return;
 
-    const narrow = Array.isArray(cliPayload.narrow) ? cliPayload.narrow : [];
+    // Protocol v2 (rc.18 TASK-005): wire field is `entries`, no v1 shim.
+    const narrow = Array.isArray(cliPayload.entries) ? cliPayload.entries : [];
     if (narrow.length === 0) {
       // rc.6 TASK-023 (E6): silence-counter — matched-narrow == 0. The CLI
       // had a chance to match against the extracted paths but came back
@@ -764,7 +788,7 @@ function main(env, stdio) {
       });
     }
 
-    const lines = renderSummary({ ...cliPayload, narrow: gateDecision.narrow });
+    const lines = renderSummary({ ...cliPayload, entries: gateDecision.narrow });
     if (lines.length === 0) return;
     for (const line of lines) {
       err.write(`${line}\n`);

package/templates/hooks/lib/banner-i18n.cjs

@@ -0,0 +1,252 @@
+/**
+ * v2.0.0-rc.16 TASK-001 (F2-prep): shared banner-i18n library for hook scripts.
+ *
+ * Provides:
+ *   - readFabricLanguage(projectRoot) → 'zh-CN' | 'en' | 'zh-CN-hybrid' | 'match-existing'
+ *     Synchronously reads `fabric_language` from `.fabric/fabric-config.json`.
+ *     Mirrors the never-throw contract of the existing config readers in
+ *     fabric-hint.cjs (readReviewHintPendingCount, readMaintenanceHintDays, etc.):
+ *     missing file / parse error / missing field → returns 'zh-CN' (the
+ *     documented BACKWARD-COMPAT default — preserves rc.15 hard-coded zh-CN
+ *     hook output when fabric_language was never a configurable key).
+ *
+ *     'match-existing' is ONLY returned when explicitly set in config; per UX
+ *     i18n Policy class 1, renderBanner then folds 'match-existing' (and any
+ *     unknown variant) down to 'en'.
+ *
+ *     RC.16 TASK-002 NOTE: this default was originally 'match-existing' in
+ *     TASK-001 but was tightened to 'zh-CN' here so that the existing rc.7+
+ *     fabric-hint test fixtures (which never set fabric_language and expect
+ *     zh-CN substrings byte-identically) continue passing without modification.
+ *     Pre-user clean-slate policy: no shim, but back-compat for in-tree tests
+ *     is the right line — they encode the rc.15 user-visible contract.
+ *
+ *   - renderBanner(key, variant, params) → string
+ *     Renders one of the 11 banner fragments for the requested variant.
+ *     Variant fallback: STRINGS[key][variant] ?? STRINGS[key]['en'].
+ *     Unknown / 'match-existing' / missing → 'en' table.
+ *
+ *   - STRINGS — exported for test introspection only (read-only by convention).
+ *
+ * Banner keys (11 total):
+ *   Signal A (archive):     archiveLine1, archiveActivity, archiveCta
+ *   Signal B (review):      reviewLine1, reviewCta
+ *   Signal C (import):      importLine1, importCta
+ *   Signal D (maintenance): maintenanceLine1Never, maintenanceLine1Aged, maintenanceLine2
+ *   Broad hook:             broadImportBanner
+ *
+ * Protected tokens — NEVER translated, kept verbatim across all 4 variants:
+ *   - Slash commands: /fabric-archive, /fabric-review, /fabric-import
+ *   - CLI commands:   `fabric doctor --lint`
+ *   - Numeric / template substrings the existing tests assert on:
+ *       "${hoursElapsed.toFixed(1)}h" (e.g. "25.0h"), "阈值 ${N}h",
+ *       "${count} 条", "${nodeCount}/${threshold}", "${days} 天"
+ *   - 📋 Fabric: emoji prefix
+ *
+ * zh-CN-hybrid policy: Chinese narrative prose with English protected tokens
+ * preserved verbatim. In practice this matches zh-CN exactly because the
+ * banners already inline slash commands + CLI commands without translation;
+ * we keep the variant entries explicit anyway for forward-compat (future copy
+ * may diverge, e.g. mixing English connector words).
+ *
+ * match-existing policy: per UX i18n Policy class 1, falls back to 'en' at
+ * render time. The fallback decision is centralized in renderBanner; only an
+ * EXPLICIT `fabric_language: "match-existing"` in config triggers the en
+ * fallback. Unset / missing config defaults to 'zh-CN' (rc.15 back-compat).
+ *
+ * Pattern reference:
+ *   - Never-throw fs read: fabric-hint.cjs `_readConfigNumber`,
+ *     `readReviewHintPendingCount` (lines 720-743)
+ *   - hooks/lib/*.cjs precedent: session-digest-writer.cjs
+ */
+"use strict";
+
+const { existsSync, readFileSync } = require("node:fs");
+const { join } = require("node:path");
+
+const FABRIC_DIR = ".fabric";
+const CONFIG_FILE = "fabric-config.json";
+
+const VALID_LANGUAGES = ["zh-CN", "en", "zh-CN-hybrid", "match-existing"];
+// rc.16 TASK-002: backward-compat default. rc.15 and earlier hardcoded
+// zh-CN in the hook scripts; preserving zh-CN as the unset-default keeps
+// the rc.7+ fabric-hint test fixtures (which assert Chinese substrings
+// without ever setting fabric_language) green and matches the user-visible
+// contract real workspaces have observed since rc.7.
+const DEFAULT_LANGUAGE = "zh-CN";
+const RENDER_FALLBACK_VARIANT = "en";
+
+/**
+ * Read `fabric_language` from <projectRoot>/.fabric/fabric-config.json.
+ *
+ * Returns one of the four valid language codes. Missing file, malformed JSON,
+ * missing/unknown field value → DEFAULT_LANGUAGE ('zh-CN' — see comment on
+ * the constant for the back-compat rationale). NEVER throws — config-read
+ * failure must not block any hook.
+ */
+function readFabricLanguage(projectRoot) {
+  if (typeof projectRoot !== "string" || projectRoot.length === 0) {
+    return DEFAULT_LANGUAGE;
+  }
+  const configPath = join(projectRoot, FABRIC_DIR, CONFIG_FILE);
+  if (!existsSync(configPath)) return DEFAULT_LANGUAGE;
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+    const v = parsed && parsed.fabric_language;
+    if (typeof v === "string" && VALID_LANGUAGES.indexOf(v) !== -1) {
+      return v;
+    }
+  } catch {
+    // fall through to default
+  }
+  return DEFAULT_LANGUAGE;
+}
+
+// ---------------------------------------------------------------------------
+// String table
+// ---------------------------------------------------------------------------
+//
+// Each key maps variant -> (params) => string. Templates intentionally use
+// the same parameter names across all four variants so call sites pass one
+// shape. Substring contracts (see file header) are preserved verbatim across
+// translations; only narrative connector words shift.
+// ---------------------------------------------------------------------------
+
+const STRINGS = {
+  // ---- Signal A: archive ----------------------------------------------------
+  // Source (zh-CN): fabric-hint.cjs:614  `📋 Fabric: 距上次归档 ${parts}。`
+  // params: { parts } where parts is pre-joined `已过 25.0h（阈值 24h）` etc.
+  archiveLine1: {
+    "zh-CN": (p) => `📋 Fabric: 距上次归档 ${p.parts}。`,
+    en: (p) => `📋 Fabric: ${p.parts} since last archive.`,
+    "zh-CN-hybrid": (p) => `📋 Fabric: 距上次归档 ${p.parts}。`,
+  },
+
+  // Source (zh-CN): fabric-hint.cjs:619  `   最近活动集中在: ${activity}。`
+  // params: { activity }
+  archiveActivity: {
+    "zh-CN": (p) => `   最近活动集中在: ${p.activity}。`,
+    en: (p) => `   Recent activity centered on: ${p.activity}.`,
+    "zh-CN-hybrid": (p) => `   最近活动集中在: ${p.activity}。`,
+  },
+
+  // Source (zh-CN): fabric-hint.cjs:621  `   是否调 /fabric-archive 检查值得归档的决策/踩坑/复用?`
+  // params: {} — protected token /fabric-archive verbatim across all variants.
+  archiveCta: {
+    "zh-CN": () => "   是否调 /fabric-archive 检查值得归档的决策/踩坑/复用?",
+    en: () => "   Run /fabric-archive to review decisions/pitfalls/reusables worth archiving?",
+    "zh-CN-hybrid": () => "   是否调 /fabric-archive 检查值得归档的决策/踩坑/复用?",
+  },
+
+  // ---- Signal B: review -----------------------------------------------------
+  // Source (zh-CN): fabric-hint.cjs:651  `📋 Fabric: 已积累 ${stats.count} 条待审核知识${ageSuffix}。`
+  // params: { count, ageSuffix } — ageSuffix is " / 最早一条 N.N 天前" or "" (zh-CN only)
+  // For en variant we shape the suffix inline to keep substring "${count}" addressable.
+  reviewLine1: {
+    "zh-CN": (p) => `📋 Fabric: 已积累 ${p.count} 条待审核知识${p.ageSuffix || ""}。`,
+    en: (p) => {
+      const suffix =
+        p.ageSuffix && p.ageSuffix.length > 0
+          ? p.ageSuffix
+              .replace(" / 最早一条 ", " / oldest is ")
+              .replace(" 天前", "d old")
+          : "";
+      return `📋 Fabric: ${p.count} pending knowledge entries accumulated${suffix}.`;
+    },
+    "zh-CN-hybrid": (p) => `📋 Fabric: 已积累 ${p.count} 条待审核知识${p.ageSuffix || ""}。`,
+  },
+
+  // Source (zh-CN): fabric-hint.cjs:652  `   是否调 /fabric-review 审核 pending/ 条目?`
+  // params: {} — protected token /fabric-review verbatim across all variants.
+  reviewCta: {
+    "zh-CN": () => "   是否调 /fabric-review 审核 pending/ 条目?",
+    en: () => "   Run /fabric-review to triage pending/ entries?",
+    "zh-CN-hybrid": () => "   是否调 /fabric-review 审核 pending/ 条目?",
+  },
+
+  // ---- Signal C: import (underseed) ----------------------------------------
+  // Source (zh-CN): fabric-hint.cjs:697  `📋 Fabric: 知识库节点数 ${nodeCount}/${threshold}，距 init_scan_completed ${hoursSinceInit.toFixed(1)}h。`
+  // params: { nodeCount, threshold, hoursSinceInit } — caller supplies hoursSinceInit
+  //         already toFixed(1)'d (i.e. as string "24.5") to keep all rendering pure.
+  importLine1: {
+    "zh-CN": (p) =>
+      `📋 Fabric: 知识库节点数 ${p.nodeCount}/${p.threshold}，距 init_scan_completed ${p.hoursSinceInit}h。`,
+    en: (p) =>
+      `📋 Fabric: knowledge node count ${p.nodeCount}/${p.threshold}, ${p.hoursSinceInit}h since init_scan_completed.`,
+    "zh-CN-hybrid": (p) =>
+      `📋 Fabric: 知识库节点数 ${p.nodeCount}/${p.threshold}，距 init_scan_completed ${p.hoursSinceInit}h。`,
+  },
+
+  // Source (zh-CN): fabric-hint.cjs:698  `   是否调 /fabric-import 从 git 历史与现有文档回灌知识?`
+  // params: {} — protected token /fabric-import verbatim across all variants.
+  importCta: {
+    "zh-CN": () => "   是否调 /fabric-import 从 git 历史与现有文档回灌知识?",
+    en: () => "   Run /fabric-import to backfill knowledge from git history and existing docs?",
+    "zh-CN-hybrid": () => "   是否调 /fabric-import 从 git 历史与现有文档回灌知识?",
+  },
+
+  // ---- Signal D: maintenance -----------------------------------------------
+  // Source (zh-CN): fabric-hint.cjs:931  `📋 Fabric: 从未运行 lint 检查。`
+  // params: {} — substring "从未运行 lint 检查" is test-asserted (zh-CN test).
+  maintenanceLine1Never: {
+    "zh-CN": () => "📋 Fabric: 从未运行 lint 检查。",
+    en: () => "📋 Fabric: lint check has never been run.",
+    "zh-CN-hybrid": () => "📋 Fabric: 从未运行 lint 检查。",
+  },
+
+  // Source (zh-CN): fabric-hint.cjs:932  `📋 Fabric: 已 ${days} 天未跑 lint 检查（实际 ${ageDays.toFixed(1)}d）。`
+  // params: { days, ageDays } — ageDays caller-supplied as already-toFixed(1) string.
+  // Substring "已 N 天未跑 lint" is test-asserted (zh-CN test).
+  maintenanceLine1Aged: {
+    "zh-CN": (p) => `📋 Fabric: 已 ${p.days} 天未跑 lint 检查（实际 ${p.ageDays}d）。`,
+    en: (p) => `📋 Fabric: ${p.days} days since the last lint check (actual ${p.ageDays}d).`,
+    "zh-CN-hybrid": (p) => `📋 Fabric: 已 ${p.days} 天未跑 lint 检查（实际 ${p.ageDays}d）。`,
+  },
+
+  // Source (zh-CN): fabric-hint.cjs:929  `   是否调 \`fabric doctor --lint\` 看看知识库健康度?`
+  // params: {} — protected token `fabric doctor --lint` (with backticks) verbatim.
+  maintenanceLine2: {
+    "zh-CN": () => "   是否调 `fabric doctor --lint` 看看知识库健康度?",
+    en: () => "   Run `fabric doctor --lint` to check knowledge-base health?",
+    "zh-CN-hybrid": () => "   是否调 `fabric doctor --lint` 看看知识库健康度?",
+  },
+
+  // ---- Broad hook: import recommendation ------------------------------------
+  // Source (zh-CN): knowledge-hint-broad.cjs:262
+  //   "  📋 Fabric: 知识库稀疏，是否调 /fabric-import 从 git 历史与现有文档回灌知识?"
+  // Note: leading two spaces are intentional (existing banner indent).
+  // params: {} — protected token /fabric-import verbatim.
+  broadImportBanner: {
+    "zh-CN": () => "  📋 Fabric: 知识库稀疏，是否调 /fabric-import 从 git 历史与现有文档回灌知识?",
+    en: () =>
+      "  📋 Fabric: knowledge base is sparse — run /fabric-import to backfill from git history and existing docs?",
+    "zh-CN-hybrid": () =>
+      "  📋 Fabric: 知识库稀疏，是否调 /fabric-import 从 git 历史与现有文档回灌知识?",
+  },
+};
+
+/**
+ * Render a banner fragment for the requested variant.
+ *
+ * Variant resolution:
+ *   1. If STRINGS[key][variant] exists → use it.
+ *   2. Else fall back to STRINGS[key][RENDER_FALLBACK_VARIANT] ('en').
+ *   3. If key itself is unknown → returns "" (defensive; never throws).
+ *
+ * 'match-existing' is intentionally NOT in the STRINGS table so it folds
+ * down to the 'en' fallback per UX i18n Policy class 1.
+ */
+function renderBanner(key, variant, params) {
+  const entry = STRINGS[key];
+  if (!entry) return "";
+  const tmpl = entry[variant] || entry[RENDER_FALLBACK_VARIANT];
+  if (typeof tmpl !== "function") return "";
+  try {
+    return tmpl(params || {});
+  } catch {
+    // Defensive: a missing param shouldn't crash the hook.
+    return "";
+  }
+}
+
+module.exports = { readFabricLanguage, renderBanner, STRINGS };

package/dist/chunk-Q72D24BG.js

@@ -1,186 +0,0 @@
-#!/usr/bin/env node
-import {
-  addFabricKnowledgeBaseSection,
-  installArchiveHintHook,
-  installFabricArchiveSkill,
-  installFabricImportSkill,
-  installFabricReviewSkill,
-  installKnowledgeHintBroadHook,
-  installKnowledgeHintNarrowHook,
-  mergeClaudeCodeHookConfig,
-  mergeCodexHookConfig,
-  mergeCursorHookConfig,
-  readFabricLanguagePreference
-} from "./chunk-X7QPY5KH.js";
-import {
-  t
-} from "./chunk-6ICJICVU.js";
-
-// src/commands/hooks.ts
-import { existsSync, statSync } from "fs";
-import { isAbsolute, join, resolve } from "path";
-import { defineCommand } from "citty";
-var hooksCommand = defineCommand({
-  meta: {
-    name: "hooks",
-    description: t("cli.hooks.description")
-  },
-  subCommands: {
-    install: defineCommand({
-      meta: {
-        name: "install",
-        description: t("cli.hooks.install.description")
-      },
-      args: {
-        target: {
-          type: "string",
-          description: t("cli.hooks.install.args.target.description"),
-          default: process.cwd()
-        }
-      },
-      async run({ args }) {
-        const result = await installHooks(args.target);
-        for (const path of result.installed) {
-          console.log(`installed ${path}`);
-        }
-        for (const path of result.skipped) {
-          console.log(`skipped ${path}`);
-        }
-        for (const message of result.errors) {
-          console.error(`error ${message}`);
-        }
-      }
-    })
-  }
-});
-var hooks_default = hooksCommand;
-async function installHooks(target, _options = {}) {
-  const normalizedTarget = normalizeTarget(target);
-  assertExistingDirectory(normalizedTarget);
-  const results = [];
-  results.push(...await runStep(() => installFabricArchiveSkill(normalizedTarget)));
-  results.push(...await runStep(() => installFabricReviewSkill(normalizedTarget)));
-  results.push(...await runStep(() => installFabricImportSkill(normalizedTarget)));
-  results.push(...await runStep(() => installArchiveHintHook(normalizedTarget)));
-  results.push(...await runStep(() => installKnowledgeHintBroadHook(normalizedTarget)));
-  results.push(...await runStep(() => installKnowledgeHintNarrowHook(normalizedTarget)));
-  results.push(await runSingleStep("claude-hook-config", () => mergeClaudeCodeHookConfig(normalizedTarget)));
-  results.push(await runSingleStep("codex-hook-config", () => mergeCodexHookConfig(normalizedTarget)));
-  results.push(await runSingleStep("cursor-hook-config", () => mergeCursorHookConfig(normalizedTarget)));
-  const fabricLanguage = readFabricLanguagePreference(normalizedTarget);
-  results.push(...await runStep(() => addFabricKnowledgeBaseSection(normalizedTarget, fabricLanguage)));
-  results.push(...validateHookPaths(normalizedTarget));
-  return summarizeResults(results);
-}
-function validateHookPaths(projectRoot) {
-  const scripts = [
-    { stepSuffix: "", hookFile: "fabric-hint.cjs" },
-    { stepSuffix: "-broad", hookFile: "knowledge-hint-broad.cjs" },
-    { stepSuffix: "-narrow", hookFile: "knowledge-hint-narrow.cjs" }
-  ];
-  const clients = [
-    {
-      client: "claude",
-      configRel: join(".claude", "settings.json"),
-      hookDir: join(".claude", "hooks")
-    },
-    {
-      client: "codex",
-      configRel: join(".codex", "hooks.json"),
-      hookDir: join(".codex", "hooks")
-    },
-    {
-      client: "cursor",
-      configRel: join(".cursor", "hooks.json"),
-      hookDir: join(".cursor", "hooks")
-    }
-  ];
-  const results = [];
-  for (const { client, configRel, hookDir } of clients) {
-    const configPath = resolve(projectRoot, configRel);
-    if (!existsSync(configPath)) {
-      results.push({
-        step: `hook-validate-${client}`,
-        path: configPath,
-        status: "skipped",
-        message: "missing-config"
-      });
-      continue;
-    }
-    for (const { stepSuffix, hookFile } of scripts) {
-      const expectedHookPath = resolve(projectRoot, hookDir, hookFile);
-      const expectedHookRel = join(hookDir, hookFile);
-      const step = `hook-validate-${client}${stepSuffix}`;
-      if (!existsSync(expectedHookPath)) {
-        results.push({
-          step,
-          path: expectedHookPath,
-          status: "error",
-          message: `hook script missing: ${expectedHookRel}`
-        });
-        continue;
-      }
-      results.push({ step, path: expectedHookPath, status: "skipped", message: "ok" });
-    }
-  }
-  return results;
-}
-async function runStep(fn) {
-  try {
-    return await fn();
-  } catch (error) {
-    return [
-      {
-        step: "hook-install",
-        path: "",
-        status: "error",
-        message: error instanceof Error ? error.message : String(error)
-      }
-    ];
-  }
-}
-async function runSingleStep(step, fn) {
-  try {
-    return await fn();
-  } catch (error) {
-    return {
-      step,
-      path: "",
-      status: "error",
-      message: error instanceof Error ? error.message : String(error)
-    };
-  }
-}
-function summarizeResults(results) {
-  const installed = [];
-  const skipped = [];
-  const errors = [];
-  for (const r of results) {
-    switch (r.status) {
-      case "written":
-        installed.push(r.path);
-        break;
-      case "skipped":
-        skipped.push(r.path);
-        break;
-      case "error":
-        errors.push(`${r.step} ${r.path}: ${r.message ?? "unknown error"}`);
-        break;
-    }
-  }
-  return { installed, skipped, errors };
-}
-function normalizeTarget(targetInput) {
-  return isAbsolute(targetInput) ? targetInput : resolve(process.cwd(), targetInput);
-}
-function assertExistingDirectory(target) {
-  if (!existsSync(target) || !statSync(target).isDirectory()) {
-    throw new Error(t("cli.shared.target-invalid", { target }));
-  }
-}
-
-export {
-  hooksCommand,
-  hooks_default,
-  installHooks
-};