@fenglimg/fabric-cli 0.1.4 → 1.1.0

package/dist/{ledger-append-EGIKSMU5.js → ledger-append-XZ5SX4O5.js}

@@ -2,7 +2,8 @@
 import {
   ledgerAppendCommand,
   ledger_append_default
-} from "./chunk-U376IPKT.js";
+} from "./chunk-F2BXHPM5.js";
+import "./chunk-6ICJICVU.js";
 export {
   ledger_append_default as default,
   ledgerAppendCommand

package/dist/{pre-commit-CXPH7BZH.js → pre-commit-BLSUMT3P.js}

@@ -1,17 +1,20 @@
 #!/usr/bin/env node
+import {
+  ledger_append_default
+} from "./chunk-F2BXHPM5.js";
 import {
   resolveDevModeTarget
 } from "./chunk-AEOYCVBG.js";
 import {
   sync_meta_default
-} from "./chunk-T3WQUWW4.js";
-import "./chunk-P4KVFB2T.js";
+} from "./chunk-6UUPKSDE.js";
 import {
   human_lint_default
-} from "./chunk-CZ7U6ULM.js";
+} from "./chunk-L43IGJ6X.js";
+import "./chunk-WWNXR34K.js";
 import {
-  ledger_append_default
-} from "./chunk-U376IPKT.js";
+  t
+} from "./chunk-6ICJICVU.js";
 
 // src/commands/pre-commit.ts
 import { defineCommand } from "citty";
@@ -20,20 +23,22 @@ async function runOrFail(name, cmd, args) {
   try {
     await cmd.run?.({ args });
   } catch (err) {
-    process.stderr.write(`fabric pre-commit: ${name} failed \u2014 ${err.message}
-`);
+    process.stderr.write(
+      `${t("cli.pre-commit.run-failed", { name, message: err.message })}
+`
+    );
     process.exit(1);
   }
 }
 var pre_commit_default = defineCommand({
   meta: {
     name: "pre-commit",
-    description: "\u590D\u5408 pre-commit \u94A9\u5B50 \u2014\u2014 \u5728\u5355\u4E00 Node \u8FDB\u7A0B\u4E2D\u4F9D\u6B21\u6267\u884C sync-meta --check-only\u3001human-lint\u3001ledger-append --staged\uFF0C300ms \u5185\u5B8C\u6210\u3002"
+    description: t("cli.pre-commit.description")
   },
   args: {
     target: {
       type: "string",
-      description: "\u9879\u76EE\u6839\u76EE\u5F55\uFF08\u9ED8\u8BA4\u4E3A\u5F53\u524D\u76EE\u5F55\u6216 EXTERNAL_FIXTURE_PATH\uFF09\u3002"
+      description: t("cli.pre-commit.args.target.description")
     }
   },
   async run({ args }) {

package/dist/{scan-UASZQLQP.js → scan-JBGFRB7P.js}

@@ -3,9 +3,10 @@ import {
   createScanReport,
   scanCommand,
   scan_default
-} from "./chunk-BWZHNZG6.js";
+} from "./chunk-JWUO6TIS.js";
 import "./chunk-AEOYCVBG.js";
-import "./chunk-P4KVFB2T.js";
+import "./chunk-WWNXR34K.js";
+import "./chunk-6ICJICVU.js";
 export {
   createScanReport,
   scan_default as default,

package/dist/serve-4J2CQY25.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+import {
+  createDebugLogger,
+  resolveDevMode
+} from "./chunk-AEOYCVBG.js";
+import {
+  paint,
+  symbol
+} from "./chunk-WWNXR34K.js";
+import {
+  t
+} from "./chunk-6ICJICVU.js";
+
+// src/commands/serve.ts
+import { defineCommand } from "citty";
+import { startHttpServer } from "@fenglimg/fabric-server";
+var DEFAULT_PORT = 7373;
+var serveCommand = defineCommand({
+  meta: {
+    name: "serve",
+    description: t("cli.serve.description")
+  },
+  args: {
+    port: {
+      type: "string",
+      description: t("cli.serve.args.port.description"),
+      default: String(DEFAULT_PORT)
+    },
+    host: {
+      type: "string",
+      description: t("cli.serve.args.host.description"),
+      default: "127.0.0.1"
+    },
+    target: {
+      type: "string",
+      description: t("cli.serve.args.target.description")
+    },
+    debug: {
+      type: "boolean",
+      description: t("cli.serve.args.debug.description"),
+      default: false
+    }
+  },
+  async run({ args }) {
+    const workspaceRoot = process.cwd();
+    const logger = createDebugLogger(args.debug);
+    const resolution = resolveDevMode(args.target, workspaceRoot);
+    const port = parsePort(args.port);
+    const requestedHost = parseHost(args.host);
+    const authToken = readAuthTokenFromEnv();
+    const host = validateHost(requestedHost, authToken);
+    logger(`serve target source: ${resolution.source}`);
+    for (const step of resolution.chain) {
+      logger(step);
+    }
+    try {
+      await startHttpServer({
+        port,
+        projectRoot: resolution.target,
+        host,
+        authToken
+      });
+    } catch (error) {
+      if (isNodeError(error) && error.code === "EADDRINUSE") {
+        throw new Error(t("cli.serve.error.port-in-use", { port: String(port), nextPort: String(port + 1) }));
+      }
+      throw error;
+    }
+    console.log(`${symbol.ok} ${paint.ai(t("cli.serve.ready.title"))} ${paint.human(`http://${host}:${port}`)}`);
+  }
+});
+var serve_default = serveCommand;
+function parsePort(value) {
+  const port = Number.parseInt(value ?? String(DEFAULT_PORT), 10);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(t("cli.shared.invalid-port", { value: value ?? "<unset>" }));
+  }
+  return port;
+}
+function parseHost(value) {
+  const host = value?.trim() ?? "127.0.0.1";
+  if (host.length === 0) {
+    throw new Error(t("cli.shared.invalid-host-empty"));
+  }
+  return host;
+}
+function readAuthTokenFromEnv() {
+  const token = process.env.FABRIC_AUTH_TOKEN;
+  return token === void 0 || token.length === 0 ? void 0 : token;
+}
+function validateHost(host, authToken) {
+  if (authToken !== void 0) {
+    return host;
+  }
+  if (!isLoopbackHost(host)) {
+    console.error(
+      `${symbol.warn} ${paint.warn(t("cli.serve.warning.host-fallback", { host }))}`
+    );
+    return "127.0.0.1";
+  }
+  return host;
+}
+function isLoopbackHost(host) {
+  return host === "127.0.0.1" || host === "localhost" || host === "::1";
+}
+function isNodeError(error) {
+  return error instanceof Error;
+}
+export {
+  serve_default as default,
+  serveCommand
+};

package/dist/{sync-meta-YTG5V3Y6.js → sync-meta-THZSEM7Y.js}

@@ -1,12 +1,16 @@
 #!/usr/bin/env node
 import {
   computeAgentsMeta,
+  deriveLayer,
+  deriveTopologyType,
   syncMetaCommand,
   sync_meta_default
-} from "./chunk-T3WQUWW4.js";
-import "./chunk-P4KVFB2T.js";
+} from "./chunk-6UUPKSDE.js";
+import "./chunk-6ICJICVU.js";
 export {
   computeAgentsMeta,
   sync_meta_default as default,
+  deriveLayer,
+  deriveTopologyType,
   syncMetaCommand
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fenglimg/fabric-cli",
-  "version": "0.1.4",
+  "version": "1.1.0",
   "type": "module",
   "bin": {
     "fab": "dist/index.js"
@@ -11,19 +11,23 @@
     "dist",
     "templates"
   ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch"
-  },
   "dependencies": {
-    "@fenglimg/fabric-server": "^0.1.0",
     "@iarna/toml": "^2.2.5",
-    "citty": "^0.2.2"
+    "citty": "^0.2.2",
+    "picocolors": "^1.1.1",
+    "string-width": "^7.2.0",
+    "@fenglimg/fabric-shared": "1.1.0",
+    "@fenglimg/fabric-server": "1.1.0"
   },
   "devDependencies": {
     "@types/iarna__toml": "^2.0.5",
     "@types/node": "^22.15.0",
     "tsup": "^8.5.0",
     "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run"
   }
-}
+}

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

@@ -1,29 +1,20 @@
-# { projectName } — L0 AGENTS.md
-
-// TODO: describe project purpose.
-
-<!-- TODO: tech stack: detected framework is { frameworkKind }. Verify this manually before replacing TODOs. -->
-
-<!-- fab:index -->
-<!-- /fab:index -->
-
-## Human Documentation References
-
-// TODO: reference README.md sections that are source-of-truth for humans.
-// TODO: reference CONTRIBUTING.md if this project has one.
-
-## L0 AI Constraints
-
-// TODO: list hard constraints, e.g., ban any, require TypeScript strict.
-// TODO: list commands AI may run for validation.
-// TODO: list files or directories AI must not modify without permission.
-
-## @HUMAN
-
-// TODO: human-owned decisions live here. AI must not rewrite locked sentences.
-// TODO: placeholder locked sentence 1.
-// TODO: placeholder locked sentence 2.
-
-## L1 Candidate Notes
-
-// TODO: identify domain folders that may need scoped AGENTS.md files.
+# { projectName } — Fabric Bootstrap Protocol
+
+## CORE RULES (DO NOT TRANSLATE)
+
+MUST: Treat this file as the Fabric Protocol bootstrap for this repository.
+MUST: Treat `.fabric/agents/` as the authoritative home for all AI shadow constraints.
+MUST: Before ANY code reading, architecture planning, or logic modification, call `fab_get_rules(path=<target file>)`.
+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/agents/`, `.fabric/agents.meta.json`, `fab_get_rules`, `shadow constraints`, `Shadow 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.
+
+## 使用说明 / Explanation
+
+- 本文件只负责启动 Fabric Bootstrap Protocol，不承载项目业务规则。
+- Detected framework kind: `{ frameworkKind }`.
+- This repository uses `Shadow Mirroring`: source directories contain ZERO rule files, while `.fabric/agents/` mirrors source paths for AI constraints.
+- 根级规则应放在 `.fabric/agents/root.md`；跨领域规则应放在 `.fabric/agents/_cross/`。
+- If `.fabric/agents/root.md` is missing, stop normal coding and run the initialization flow that creates shadow constraints.

package/templates/agents-md/variants/cocos.md

@@ -0,0 +1,20 @@
+# { projectName } — Fabric Bootstrap Protocol
+
+## CORE RULES (DO NOT TRANSLATE)
+
+MUST: Treat this file as the Fabric Protocol bootstrap for this repository.
+MUST: Treat `.fabric/agents/` as the authoritative home for all AI shadow constraints.
+MUST: Before ANY code reading, architecture planning, or logic modification, call `fab_get_rules(path=<target file>)`.
+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/agents/`, `.fabric/agents.meta.json`, `fab_get_rules`, `shadow constraints`, `Shadow Mirroring`, `MUST`, `NEVER`.
+NEVER: Add import-style directive lines to this bootstrap file.
+NEVER: Put Cocos, asset, prefab, scene, repository rule bodies, or submodule rules in this file.
+NEVER: Create colocated `AGENTS.md` rule files under source directories.
+
+## 使用说明 / Explanation
+
+- 本文件只负责启动 Fabric Bootstrap Protocol，不承载 Cocos 业务或编辑器规则。
+- Detected framework kind: `cocos-creator`.
+- This repository uses `Shadow Mirroring`: source directories contain ZERO rule files, while `.fabric/agents/` mirrors source paths for AI constraints.
+- 根级规则应放在 `.fabric/agents/root.md`；跨领域规则应放在 `.fabric/agents/_cross/`。
+- If `.fabric/agents/root.md` is missing, stop normal coding and run the initialization flow that creates shadow constraints.

package/templates/agents-md/variants/next.md

@@ -0,0 +1,20 @@
+# { projectName } — Fabric Bootstrap Protocol
+
+## CORE RULES (DO NOT TRANSLATE)
+
+MUST: Treat this file as the Fabric Protocol bootstrap for this repository.
+MUST: Treat `.fabric/agents/` as the authoritative home for all AI shadow constraints.
+MUST: Before ANY code reading, architecture planning, or logic modification, call `fab_get_rules(path=<target file>)`.
+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/agents/`, `.fabric/agents.meta.json`, `fab_get_rules`, `shadow constraints`, `Shadow Mirroring`, `MUST`, `NEVER`.
+NEVER: Add import-style directive lines to this bootstrap file.
+NEVER: Put Next.js, route, repository rule bodies, or submodule rules in this file.
+NEVER: Create colocated `AGENTS.md` rule files under source directories.
+
+## 使用说明 / Explanation
+
+- 本文件只负责启动 Fabric Bootstrap Protocol，不承载 Next.js 业务或路由规则。
+- Detected framework kind: `next`.
+- This repository uses `Shadow Mirroring`: source directories contain ZERO rule files, while `.fabric/agents/` mirrors source paths for AI constraints.
+- 根级规则应放在 `.fabric/agents/root.md`；跨领域规则应放在 `.fabric/agents/_cross/`。
+- If `.fabric/agents/root.md` is missing, stop normal coding and run the initialization flow that creates shadow constraints.

package/templates/agents-md/variants/vite.md

@@ -0,0 +1,20 @@
+# { projectName } — Fabric Bootstrap Protocol
+
+## CORE RULES (DO NOT TRANSLATE)
+
+MUST: Treat this file as the Fabric Protocol bootstrap for this repository.
+MUST: Treat `.fabric/agents/` as the authoritative home for all AI shadow constraints.
+MUST: Before ANY code reading, architecture planning, or logic modification, call `fab_get_rules(path=<target file>)`.
+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/agents/`, `.fabric/agents.meta.json`, `fab_get_rules`, `shadow constraints`, `Shadow Mirroring`, `MUST`, `NEVER`.
+NEVER: Add import-style directive lines to this bootstrap file.
+NEVER: Put Vite, browser, repository rule bodies, or submodule rules in this file.
+NEVER: Create colocated `AGENTS.md` rule files under source directories.
+
+## 使用说明 / Explanation
+
+- 本文件只负责启动 Fabric Bootstrap Protocol，不承载 Vite 业务或浏览器规则。
+- Detected framework kind: `vite`.
+- This repository uses `Shadow Mirroring`: source directories contain ZERO rule files, while `.fabric/agents/` mirrors source paths for AI constraints.
+- 根级规则应放在 `.fabric/agents/root.md`；跨领域规则应放在 `.fabric/agents/_cross/`。
+- If `.fabric/agents/root.md` is missing, stop normal coding and run the initialization flow that creates shadow constraints.

package/templates/claude-hooks/agents-md-init-reminder.cjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+const { existsSync } = require("node:fs");
+const { join } = require("node:path");
+
+const forensicPath = join(process.cwd(), ".fabric", "forensic.json");
+const initContextPath = join(process.cwd(), ".fabric", "init-context.json");
+
+if (!existsSync(forensicPath) || existsSync(initContextPath)) {
+  process.exit(0);
+}
+
+process.stdout.write(
+  JSON.stringify({
+    decision: "block",
+    reason:
+      "fab init 已完成证据收集，但项目 AGENTS.md 初始化尚未完成。调用 agents-md-init skill (通过 Skill 工具) 完成 3 阶段初始化访谈。参考: .claude/skills/agents-md-init/SKILL.md + .fabric/forensic.json",
+  }),
+);

package/templates/claude-skills/agents-md-init/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: agents-md-init
+description: Use this skill when fab init just completed, when forensic.json generated, or when the user is asking to initialize AGENTS.md. This skill runs a 3-phase initialization interview, writes .fabric/init-context.json, generates layered AGENTS.md, and updates .fabric/agents.meta.json.
+allowed-tools: Read, Write, Glob, Grep, Bash
+---
+
+## Precondition
+
+必须先 Read `.fabric/forensic.json`。若该文件不存在，终止 skill 并告知用户：`请先运行 fab init 生成证据包`。
+
+把以下状态视为 initialization pending：
+
+- `.fabric/forensic.json` 存在
+- `.fabric/init-context.json` 不存在
+
+## 执行流程 (3 Phase / 3 Round)
+
+### Phase 1 — 框架确认(1 轮,高效)
+
+展示 `.fabric/forensic.json` 的 `framework`、`topology.by_ext`、`entry_points` 摘要，向用户提 1-2 个框架架构澄清问题。
+
+示例(Cocos Creator 3.x)：
+
+> 我检测到 Cocos Creator 3.8 项目，主要脚本在 `assets/scripts`，采用 `@ccclass + extends Component` 模式。请确认：(1) 这是 TypeScript 项目(非 JavaScript)对吗？(2) 节点引用主要通过 `@property(Node)` 注入，还是 `find/getChildByName`？
+
+将用户确认结果暂存为已验证 framework assumptions。
+
+### Phase 2 — 不变式提取(1 轮,关键)
+
+基于 `.fabric/forensic.json` 的 `recommendations_for_skill` 列表，向用户提 3-5 个 invariants 问题，覆盖三类：
+
+- `ban`：禁止 any、禁止 update() 中 async、禁止 find-by-name 等
+- `require`：必须 strict TypeScript、必须 `@ccclass` decorator、必须 import from `cc` only 等
+- `protect`：哪些目录或文件 AI 不能修改，一般是 `assets/prefabs/**`、`assets/scenes/**`、`**/*.meta`
+
+原则：
+
+- 只问 invariants，不问 preferences
+- 每个问题只接受 yes/no/具体规则，不接受模糊回答
+- 不要自动推测用户未确认的硬约束
+
+### Phase 3 — 构造与落地(1 轮,自动)
+
+1. 写入 `.fabric/init-context.json`，包含：
+
+- `framework`
+- `architecture_patterns`
+- `invariants`
+- `domain_groups`
+- `interview_trail`
+- `forensic_ref`
+
+写入规则：
+
+- `invariants[].type` 必须是 `ban`、`require`、`protect`
+- `domain_groups` 由 `entry_points` 和访谈结果推断
+- `interview_trail[]` 必须记录 Phase 1 和 Phase 2 的原始问答
+- `forensic_ref` 必须为 `.fabric/forensic.json`
+
+2. 生成分层 `AGENTS.md`：
+
+- 根 `AGENTS.md` 必须在 300 行以内，结构包含：
+- `# {projectName} — L0 AGENTS.md`
+- `<!-- fab:index -->`：填充 `domain_groups` 索引
+- `## L0 AI Constraints`：从 invariants 派生，按 `ban`、`require`、`protect` 分段
+- `## @HUMAN`：protect 路径和用户声明的人类保护规则
+- `## L1 Candidate Notes`：domain_groups 对应的候选子模块说明
+
+如果 `domain_groups.length >= 2`，为每个 group 生成 `{group_path}/AGENTS.md`。最多到 L3，总嵌套不超过 4 层。
+
+3. 更新 `.fabric/agents.meta.json` 的 nodes 树，保持 revision hash 链一致：
+
+- nodes 结构与生成后的 AGENTS 层级一致
+- 更新所有变更 AGENTS 文件的 hash
+- 保持 revision hash 链内部一致
+
+4. 最终输出：向用户列出生成文件清单，并建议后续维护时运行 `fab sync-meta`。
+
+## Hard Rules
+
+- Zero TODO: 不生成任何 `TODO`、`TBD`、placeholder、stub
+- No YAML frontmatter in outputs: 除本 skill 自身外，生成的 `AGENTS.md` 不得包含 YAML frontmatter
+- Root AGENTS.md <= 300 lines
+- AGENTS 嵌套总层级 <= 4
+- 不得自动推测用户未确认的 invariants
+- 有不确定内容时删除，不要留占位符