@fenglimg/fabric-cli 1.6.0 → 1.8.0-rc.1

package/templates/husky/pre-commit

@@ -1,24 +1,9 @@
-#!/bin/sh
-# Fabric pre-commit hook — sub-300ms budget via single Node process
-# Runs: sync-meta --check-only → human-lint → ledger-append --staged → meta-guard
-# Uses local binary (no npx spawn) to avoid 3× Node startup cost.
-
-FAB_BIN="./node_modules/.bin/fab"
-
-if [ ! -x "$FAB_BIN" ]; then
-  echo "fabric: $FAB_BIN not found. Run 'pnpm install' at repo root." >&2
-  exit 1
-fi
-
-# Single Node invocation covering all three checks + meta guard.
-# The `pre-commit` meta-command chains sync-meta/human-lint/ledger-append
-# inside one process for minimal startup overhead.
-"$FAB_BIN" pre-commit || exit $?
-
-# Guard: block manual edits to .fabric/agents.meta.json
-if git diff --cached --name-only | grep -q '^\.fabric/agents\.meta\.json$'; then
-  if [ "$FAB_ALLOW_META_EDIT" != '1' ]; then
-    echo '.fabric/agents.meta.json cannot be manually edited; use fab_update_registry or set FAB_ALLOW_META_EDIT=1' >&2
-    exit 1
-  fi
-fi
+#!/bin/sh
+# Fabric pre-commit hook: block manual edits to generated metadata.
+
+if git diff --cached --name-only | grep -q '^\.fabric/agents\.meta\.json$'; then
+  if [ "$FAB_ALLOW_META_EDIT" != '1' ]; then
+    echo '.fabric/agents.meta.json cannot be manually edited; update .fabric/rules and run fabric doctor --fix, or set FAB_ALLOW_META_EDIT=1' >&2
+    exit 1
+  fi
+fi

package/templates/skill-source/fabric-init/SOURCE.md

@@ -0,0 +1,157 @@
+# fabric-init — Canonical Skill Source
+
+> This file is the single source of truth for the fabric-init skill.
+> Do NOT edit the per-client SKILL.md files directly.
+> Run `packages/cli/scripts/derive-skills.ts` to regenerate them from this source.
+
+## Precondition
+
+MUST: Read `.fabric/forensic.json` before taking any other action. If the file does not
+exist, stop immediately and tell the user: run `fab init` first to generate the evidence
+package.
+
+MUST: Check `.fabric/init-context.json`. If it already exists, stop and report that this
+repository appears to have completed initialization already.
+
+MUST: Treat `.fabric/bootstrap/README.md` as the authoritative initialization guide for
+the current repository.
+
+MUST: Use `.fabric/forensic.json` and repository structure as evidence when deciding what
+to do next.
+
+MUST: Preserve protected tokens exactly as written — see the Protected Tokens section.
+
+NEVER: Claim initialization is complete without having checked `.fabric/init-context.json`.
+
+NEVER: Rewrite or translate protected tokens.
+
+NEVER: Ignore `.fabric/bootstrap/README.md` when determining the next initialization step.
+
+Treat the following state as initialization pending:
+
+- `.fabric/forensic.json` exists
+- `.fabric/init-context.json` does not exist
+
+## Execution Flow — 3 Phases / 3 Rounds
+
+### Phase 1 — Framework Confirmation (1 round, efficient)
+
+Display a summary of `framework`, `topology.by_ext`, and `entry_points` from
+`.fabric/forensic.json`. Ask the user 1–2 clarifying questions about the framework
+architecture.
+
+Example (Cocos Creator 3.x):
+
+> I detected a Cocos Creator 3.8 project. Main scripts are in `assets/scripts` using the
+> `@ccclass + extends Component` pattern. Please confirm: (1) Is this a TypeScript project
+> (not JavaScript)? (2) Are node references injected mainly via `@property(Node)`, or via
+> `find/getChildByName`?
+
+Store the user's answers as verified framework assumptions before proceeding to Phase 2.
+
+### Phase 2 — Invariant Extraction (1 round, critical)
+
+Based on the `recommendations_for_skill` list in `.fabric/forensic.json`, ask the user
+3–5 invariant questions covering three categories:
+
+- `ban`: things that must never appear — e.g. `any`, `async` in `update()`, find-by-name
+- `require`: things that must always be present — e.g. strict TypeScript, `@ccclass`
+  decorator, imports only from `cc`
+- `protect`: directories or files that AI must not modify — typically
+  `assets/prefabs/**`, `assets/scenes/**`, `**/*.meta`
+
+Principles:
+
+- Ask only about invariants, not about preferences.
+- Each question accepts only yes / no / a concrete rule — never accept vague answers.
+- Do not auto-infer hard constraints the user has not confirmed.
+
+### Phase 3 — Construction and Landing (1 round, automated)
+
+#### 3.1 Write `.fabric/init-context.json`
+
+Fields required:
+
+- `framework`
+- `architecture_patterns`
+- `invariants`
+- `domain_groups`
+- `interview_trail`
+- `forensic_ref`
+
+Writing rules:
+
+- `invariants[].type` MUST be one of `ban`, `require`, `protect`.
+- `domain_groups` is inferred from `entry_points` and interview results.
+- `interview_trail[]` MUST record the raw Q&A from Phase 1 and Phase 2.
+- `forensic_ref` MUST be `.fabric/forensic.json`.
+
+#### 3.2 Generate layered `AGENTS.md`
+
+Root `AGENTS.md` requirements:
+
+- MUST be within 300 lines.
+- Structure:
+  - `# {projectName} — L0 AGENTS.md`
+  - `<!-- fab:index -->`: populated with the `domain_groups` index
+  - `## L0 AI Constraints`: derived from invariants, grouped by `ban`, `require`, `protect`
+  - `## @HUMAN`: protect paths and any human-declared protection rules
+  - `## L1 Candidate Notes`: candidate sub-module descriptions for each domain group
+
+If `domain_groups.length >= 2`, generate a `{group_path}/AGENTS.md` for each group.
+Maximum depth is L3; total nesting MUST NOT exceed 4 levels.
+
+#### 3.3 Update `.fabric/agents.meta.json`
+
+- The `nodes` tree MUST match the generated AGENTS hierarchy.
+- Update the hash of every AGENTS.md file that was written.
+- Maintain a consistent internal revision hash chain.
+
+#### 3.4 Final output
+
+List all generated files for the user and recommend running `fabric doctor --fix` for
+ongoing maintenance.
+
+## Hard Rules
+
+- Zero TODO: never generate `TODO`, `TBD`, placeholders, or stubs in output files.
+- No YAML frontmatter in outputs: generated `AGENTS.md` files MUST NOT contain YAML
+  frontmatter.
+- Root `AGENTS.md` MUST be <= 300 lines.
+- Total AGENTS nesting MUST be <= 4 levels.
+- Do not auto-infer invariants the user has not confirmed.
+- When content is uncertain, omit it — do not leave placeholders.
+
+## Output Contract
+
+On successful completion the following files exist or are updated:
+
+| File | Action |
+|------|--------|
+| `.fabric/init-context.json` | Created with all required fields |
+| `AGENTS.md` | Created (root L0) |
+| `{group_path}/AGENTS.md` | Created for each domain group (when applicable) |
+| `.fabric/agents.meta.json` | Updated nodes tree + hashes |
+
+On failure or early termination the skill MUST leave no partial files. If a write fails
+mid-sequence, report the failure and the exact file that was not written.
+
+## Protected Tokens
+
+The following tokens MUST be preserved exactly as shown — same casing, same punctuation,
+never translated:
+
+| Token | Type |
+|-------|------|
+| `AGENTS.md` | Filename |
+| `FABRIC.md` | Filename |
+| `.fabric/agents.meta.json` | Path |
+| `.fabric/init-context.json` | Path |
+| `.fabric/forensic.json` | Path |
+| `.fabric/bootstrap/README.md` | Path |
+| `MUST` | Keyword |
+| `NEVER` | Keyword |
+| `fab init` | CLI command |
+| `fabric doctor --fix` | CLI command |
+| `<!-- fab:index -->` | HTML comment marker |
+| `@HUMAN` | Section marker |

package/templates/skill-source/fabric-init/clients.json

@@ -0,0 +1,17 @@
+{
+  "claude": {
+    "outputName": "fabric-init",
+    "frontmatter": {
+      "name": "fabric-init",
+      "description": "Use this skill when fab init just completed, when forensic.json was 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"]
+    }
+  },
+  "codex": {
+    "outputName": "fabric-init",
+    "frontmatter": {
+      "name": "fabric-init",
+      "description": "Use this skill when .fabric/forensic.json exists and this repository still needs the remaining Fabric initialization steps."
+    }
+  }
+}

package/dist/approve-YT4DEABS.js

@@ -1,138 +0,0 @@
-#!/usr/bin/env node
-import {
-  padEnd
-} from "./chunk-WWNXR34K.js";
-import {
-  t
-} from "./chunk-6ICJICVU.js";
-
-// src/commands/approve.ts
-import { createInterface } from "readline/promises";
-import { stdin as input, stdout as output } from "process";
-import { isAbsolute, resolve } from "path";
-import { approveHumanLock, readHumanLock } from "@fenglimg/fabric-server";
-import { defineCommand, renderUsage } from "citty";
-var approveCommand = defineCommand({
-  meta: {
-    name: "approve",
-    description: t("cli.approve.description")
-  },
-  args: {
-    all: {
-      type: "boolean",
-      description: t("cli.approve.args.all.description"),
-      default: false
-    },
-    interactive: {
-      type: "boolean",
-      description: t("cli.approve.args.interactive.description"),
-      default: false
-    },
-    target: {
-      type: "string",
-      description: t("cli.approve.args.target.description"),
-      default: process.cwd()
-    }
-  },
-  async run({ args }) {
-    const target = normalizeTarget(args.target);
-    if (args.all === args.interactive) {
-      writeStdout(await renderUsage(approveCommand));
-      process.exitCode = 1;
-      return;
-    }
-    if (args.all) {
-      await runApproveAll(target);
-      return;
-    }
-    await runApproveInteractive(target);
-  }
-});
-var approve_default = approveCommand;
-async function runApproveAll(projectRoot) {
-  const driftEntries = await readDriftEntries(projectRoot);
-  if (driftEntries.length === 0) {
-    writeStdout(t("cli.approve.no-drift"));
-    return;
-  }
-  let approvedCount = 0;
-  for (const entry of driftEntries) {
-    await approveEntry(projectRoot, entry);
-    approvedCount += 1;
-  }
-  writeStdout(t("cli.approve.summary", { approved: String(approvedCount), skipped: "0", total: String(driftEntries.length) }));
-}
-async function runApproveInteractive(projectRoot) {
-  const driftEntries = await readDriftEntries(projectRoot);
-  if (driftEntries.length === 0) {
-    writeStdout(t("cli.approve.no-drift"));
-    return;
-  }
-  const rl = createInterface({ input, output });
-  let approvedCount = 0;
-  let skippedCount = 0;
-  try {
-    for (const entry of driftEntries) {
-      writeStdout(formatEntry(entry));
-      const answer = (await rl.question(t("cli.approve.prompt"))).trim().toLowerCase();
-      if (answer === "y" || answer === "yes") {
-        await approveEntry(projectRoot, entry);
-        approvedCount += 1;
-        writeStdout(t("cli.approve.approved-one", { location: formatLocation(entry) }));
-        continue;
-      }
-      skippedCount += 1;
-      writeStdout(t("cli.approve.skipped-one", { location: formatLocation(entry) }));
-    }
-  } finally {
-    rl.close();
-  }
-  writeStdout(
-    t("cli.approve.summary", {
-      approved: String(approvedCount),
-      skipped: String(skippedCount),
-      total: String(driftEntries.length)
-    })
-  );
-}
-async function readDriftEntries(projectRoot) {
-  const entries = await readHumanLock(projectRoot);
-  return entries.filter((entry) => entry.drift);
-}
-async function approveEntry(projectRoot, entry) {
-  await approveHumanLock(projectRoot, {
-    file: entry.file,
-    start_line: entry.start_line,
-    end_line: entry.end_line,
-    new_hash: entry.current_hash
-  });
-}
-function normalizeTarget(targetInput) {
-  return isAbsolute(targetInput) ? targetInput : resolve(process.cwd(), targetInput);
-}
-function formatEntry(entry) {
-  return [
-    formatLocation(entry),
-    `${padEnd(t("cli.approve.table.expected"), 10)} ${shortenHash(entry.hash)}`,
-    `${padEnd(t("cli.approve.table.current"), 10)} ${shortenHash(entry.current_hash)}`
-  ].join("\n");
-}
-function formatLocation(entry) {
-  return `${entry.file}:${entry.start_line}-${entry.end_line}`;
-}
-function shortenHash(value) {
-  if (value === "missing") {
-    return t("cli.shared.missing");
-  }
-  return value.slice(0, 15);
-}
-function writeStdout(message) {
-  process.stdout.write(`${message}
-`);
-}
-export {
-  approveCommand,
-  approve_default as default,
-  runApproveAll,
-  runApproveInteractive
-};

package/dist/bootstrap-VGL3AR26.js

@@ -1,16 +0,0 @@
-#!/usr/bin/env node
-import {
-  bootstrapCommand,
-  bootstrap_default,
-  installBootstrap
-} from "./chunk-T2WJF5I3.js";
-import "./chunk-QSAEGVKE.js";
-import "./chunk-AEOYCVBG.js";
-import "./chunk-WWNXR34K.js";
-import "./chunk-BEKSXO5N.js";
-import "./chunk-6ICJICVU.js";
-export {
-  bootstrapCommand,
-  bootstrap_default as default,
-  installBootstrap
-};

package/dist/chunk-2YW5CJ32.js

@@ -1,147 +0,0 @@
-#!/usr/bin/env node
-import {
-  t
-} from "./chunk-6ICJICVU.js";
-
-// src/commands/ledger-append.ts
-import { execSync } from "child_process";
-import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from "fs";
-import { basename, isAbsolute, resolve } from "path";
-import { getLedgerPath, getLegacyLedgerPath, LEGACY_LEDGER_PATH, LEDGER_PATH } from "@fenglimg/fabric-server";
-import { defineCommand } from "citty";
-var INITIAL_PARENT_SHA = "root";
-var ledgerAppendCommand = defineCommand({
-  meta: {
-    name: "ledger-append",
-    description: t("cli.ledger-append.description")
-  },
-  args: {
-    target: {
-      type: "string",
-      description: t("cli.ledger-append.args.target.description"),
-      default: process.cwd()
-    },
-    staged: {
-      type: "boolean",
-      description: t("cli.ledger-append.args.staged.description"),
-      default: false
-    }
-  },
-  async run({ args }) {
-    const target = normalizeTarget(args.target);
-    assertExistingDirectory(target);
-    if (!args.staged) {
-      writeStderr(t("cli.ledger-append.requires-staged"));
-      process.exitCode = 1;
-      return;
-    }
-    const stagedFiles = getStagedFiles(target).filter((file) => file !== LEGACY_LEDGER_PATH && file !== LEDGER_PATH);
-    if (stagedFiles.length === 0) {
-      return;
-    }
-    const intent = deriveIntent(stagedFiles);
-    const diffStat = readDiffStat(target).trim();
-    const entry = {
-      ts: Date.now(),
-      source: "human",
-      parent_sha: readParentSha(target),
-      intent,
-      affected_paths: stagedFiles,
-      diff_stat: diffStat
-    };
-    if (hasMatchingTailEntry(target, entry)) {
-      return;
-    }
-    const ledgerPath = getLedgerPath(target);
-    mkdirSync(resolve(target, ".fabric"), { recursive: true });
-    appendFileSync(ledgerPath, `${JSON.stringify(entry)}
-`, "utf8");
-    execGit(target, `git add ${LEDGER_PATH}`);
-  }
-});
-var ledger_append_default = ledgerAppendCommand;
-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 }));
-  }
-}
-function getStagedFiles(target) {
-  const output = execGit(target, "git diff --cached --name-only --no-renames");
-  return output.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
-}
-function readDiffStat(target) {
-  return execGit(target, "git diff --cached --stat");
-}
-function readParentSha(target) {
-  try {
-    return execGit(target, "git rev-parse --short HEAD").trim();
-  } catch {
-    return INITIAL_PARENT_SHA;
-  }
-}
-function deriveIntent(stagedFiles) {
-  const explicitIntent = process.env.FABRIC_INTENT?.trim();
-  if (explicitIntent) {
-    return explicitIntent;
-  }
-  const uniqueNames = Array.from(new Set(stagedFiles.map((file) => basename(file))));
-  const head = uniqueNames.slice(0, 2).join(", ");
-  const suffix = uniqueNames.length > 2 ? t("cli.ledger-append.intent.auto-more", { count: String(uniqueNames.length - 2) }) : "";
-  return t("cli.ledger-append.intent.auto", { head, suffix });
-}
-function hasMatchingTailEntry(target, entry) {
-  const ledgerPath = resolveTailLedgerPath(target);
-  if (!existsSync(ledgerPath)) {
-    return false;
-  }
-  const tail = readFileSync(ledgerPath, "utf8").trim().split(/\r?\n/).filter(Boolean).reverse().find((line) => isLedgerEntryLine(line));
-  if (!tail) {
-    return false;
-  }
-  try {
-    const parsed = JSON.parse(tail);
-    return parsed.parent_sha === entry.parent_sha && parsed.intent === entry.intent && Array.isArray(parsed.affected_paths) && parsed.affected_paths.length === entry.affected_paths.length && parsed.affected_paths.every((value, index) => value === entry.affected_paths[index]) && normalizeDiffStat(parsed.diff_stat) === normalizeDiffStat(entry.diff_stat);
-  } catch {
-    return false;
-  }
-}
-function resolveTailLedgerPath(target) {
-  const canonicalPath = getLedgerPath(target);
-  if (existsSync(canonicalPath)) {
-    return canonicalPath;
-  }
-  return getLegacyLedgerPath(target);
-}
-function isLedgerEntryLine(line) {
-  try {
-    const parsed = JSON.parse(line);
-    return parsed.kind !== "mcp-event";
-  } catch {
-    return false;
-  }
-}
-function normalizeDiffStat(diffStat) {
-  if (typeof diffStat !== "string") {
-    return "";
-  }
-  return diffStat.split(/\r?\n/).map((line) => line.trim()).map((line) => line.replace(/\s+\|\s+/g, " | ")).map((line) => line.replace(/\s+/g, " ")).filter((line) => line.length > 0).filter((line) => !line.includes(LEGACY_LEDGER_PATH)).filter((line) => !line.includes(LEDGER_PATH)).filter((line) => !/\d+ files? changed(?:, \d+ insertions?\(\+\))?(?:, \d+ deletions?\(-\))?$/.test(line.trim())).join("\n");
-}
-function execGit(target, command) {
-  return execSync(command, {
-    cwd: target,
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "pipe"]
-  });
-}
-function writeStderr(message) {
-  process.stderr.write(`${message}
-`);
-}
-
-export {
-  ledgerAppendCommand,
-  ledger_append_default
-};

package/dist/chunk-6ICJICVU.js

@@ -1,10 +0,0 @@
-#!/usr/bin/env node
-
-// src/i18n.ts
-import { createTranslator, detectNodeLocale } from "@fenglimg/fabric-shared";
-var locale = detectNodeLocale();
-var t = createTranslator(locale);
-
-export {
-  t
-};