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

package/dist/index.js

@@ -1,3 +1,4 @@
+import "./chunk-LXNCAKJZ.js";
 import {
   PROTECTED_TOKENS,
   createTranslator,
@@ -6,8 +7,25 @@ import {
   enMessages,
   normalizeLocale,
   zhCNMessages
-} from "./chunk-KNZIX6IL.js";
-import "./chunk-LXNCAKJZ.js";
+} from "./chunk-7A3RSITZ.js";
+import {
+  annotateIntentRequestSchema,
+  getRulesAnnotations,
+  getRulesInputSchema,
+  getRulesOutputSchema,
+  historyStateQuerySchema,
+  humanLockApproveRequestSchema,
+  humanLockFileParamsSchema,
+  ledgerQuerySchema,
+  ledgerSourceSchema,
+  planContextAnnotations,
+  planContextInputSchema,
+  planContextOutputSchema,
+  ruleSectionsAnnotations,
+  ruleSectionsInputSchema,
+  ruleSectionsOutputSchema,
+  structuredWarningSchema
+} from "./chunk-KV27CZH3.js";
 
 // src/schemas/agents-meta.ts
 import { z } from "zod";
@@ -49,7 +67,8 @@ var agentsMetaNodeBaseSchema = z.object({
     tier: z.enum(["always", "path", "description"]),
     description: z.string().optional()
   }).optional(),
-  description: ruleDescriptionSchema.optional()
+  description: ruleDescriptionSchema.optional(),
+  sections: z.array(z.string()).optional()
 });
 var agentsMetaNodeSchema = z.preprocess((value) => {
   if (!isRecord(value) || typeof value.file !== "string") {
@@ -125,59 +144,35 @@ function isRecord(value) {
   return typeof value === "object" && value !== null;
 }
 
-// src/schemas/api-contracts.ts
+// src/schemas/rule-test-index.ts
 import { z as z2 } from "zod";
-var ledgerSourceSchema = z2.enum(["ai", "human"]);
-var timestampFilterSchema = z2.preprocess((value) => {
-  if (value === void 0 || value === null || value === "") {
-    return void 0;
-  }
-  if (typeof value === "number") {
-    return value;
-  }
-  if (typeof value === "string") {
-    const trimmed = value.trim();
-    if (trimmed.length === 0) {
-      return void 0;
-    }
-    if (/^\d+$/.test(trimmed)) {
-      return Number.parseInt(trimmed, 10);
-    }
-    const parsed = Date.parse(trimmed);
-    return Number.isNaN(parsed) ? value : parsed;
-  }
-  return value;
-}, z2.number().int().nonnegative());
-var ledgerQuerySchema = z2.object({
-  source: ledgerSourceSchema.optional(),
-  since: timestampFilterSchema.optional()
-});
-var historyStateQuerySchema = z2.object({
-  ledger_id: z2.string().trim().min(1).optional(),
-  ts: timestampFilterSchema.optional()
-}).superRefine((value, ctx) => {
-  const provided = [value.ledger_id, value.ts].filter((entry) => entry !== void 0);
-  if (provided.length !== 1) {
-    ctx.addIssue({
-      code: z2.ZodIssueCode.custom,
-      message: "Provide exactly one of ledger_id or ts.",
-      path: ["ledger_id"]
-    });
-  }
-});
-var humanLockApproveRequestSchema = z2.object({
-  file: z2.string().min(1),
-  start_line: z2.number().int().positive(),
-  end_line: z2.number().int().positive(),
-  new_hash: z2.string().min(1)
-});
-var humanLockFileParamsSchema = z2.object({
-  file: z2.string().min(1)
-});
-var annotateIntentRequestSchema = z2.object({
-  ledger_entry_id: z2.string().min(1),
-  annotation: z2.string().trim().min(1)
-});
+var RULE_TEST_INDEX_SCHEMA_VERSION = 1;
+var hashSchema = z2.string().min(1);
+var ruleTestLinkSchema = z2.object({
+  rule_stable_id: z2.string().min(1),
+  rule_file: z2.string().min(1),
+  rule_hash: hashSchema,
+  previous_rule_hash: hashSchema.optional(),
+  test_file: z2.string().min(1),
+  test_hash: hashSchema,
+  previous_test_hash: hashSchema.optional(),
+  annotation_line: z2.number().int().positive()
+}).strict();
+var ruleTestOrphanAnnotationSchema = z2.object({
+  rule_stable_id: z2.string().min(1),
+  test_file: z2.string().min(1),
+  test_hash: hashSchema,
+  previous_test_hash: hashSchema.optional(),
+  annotation_line: z2.number().int().positive()
+}).strict();
+var ruleTestIndexSchema = z2.object({
+  schema_version: z2.literal(RULE_TEST_INDEX_SCHEMA_VERSION),
+  generated_at: z2.string().datetime({ offset: true }),
+  revision: z2.string().min(1).optional(),
+  previous_revision: z2.string().min(1).optional(),
+  links: z2.array(ruleTestLinkSchema),
+  orphan_annotations: z2.array(ruleTestOrphanAnnotationSchema)
+}).strict();
 
 // src/schemas/ledger-entry.ts
 import { z as z3 } from "zod";
@@ -230,17 +225,19 @@ var clientPathsSchema = z5.object({
   claudeCodeCLI: z5.string().optional(),
   claudeCodeDesktop: z5.string().optional(),
   cursor: z5.string().optional(),
-  windsurf: z5.string().optional(),
-  rooCode: z5.string().optional(),
-  geminiCLI: z5.string().optional(),
   codexCLI: z5.string().optional()
-});
+}).passthrough();
+var mcpPayloadLimitsSchema = z5.object({
+  warnBytes: z5.number().int().positive().optional(),
+  hardBytes: z5.number().int().positive().optional()
+}).optional();
 var fabricConfigSchema = z5.object({
   clientPaths: clientPathsSchema.optional(),
   externalFixturePath: z5.string().optional(),
   scanIgnores: z5.array(z5.string()).optional(),
   auditMode: auditModeSchema.optional(),
-  audit_mode: auditModeSchema.optional()
+  audit_mode: auditModeSchema.optional(),
+  mcpPayloadLimits: mcpPayloadLimitsSchema
 });
 
 // src/schemas/forensic-report.ts
@@ -399,11 +396,179 @@ var fabricEventSchema = z8.discriminatedUnion("type", [
   ledgerAppendedEventSchema,
   driftDetectedEventSchema
 ]);
+
+// src/schemas/event-ledger.ts
+import { z as z9 } from "zod";
+var eventLedgerEnvelopeSchema = {
+  kind: z9.literal("fabric-event"),
+  id: z9.string(),
+  ts: z9.number().int().nonnegative(),
+  schema_version: z9.literal(1),
+  correlation_id: z9.string().optional(),
+  session_id: z9.string().optional()
+};
+var stringRecordSchema = z9.record(z9.string());
+var ruleContextPlannedEventSchema = z9.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z9.literal("rule_context_planned"),
+  target_paths: z9.array(z9.string()),
+  required_stable_ids: z9.array(z9.string()),
+  ai_selectable_stable_ids: z9.array(z9.string()),
+  final_stable_ids: z9.array(z9.string()),
+  selection_token: z9.string().optional(),
+  client_hash: z9.string().optional(),
+  intent: z9.string().optional(),
+  known_tech: z9.array(z9.string()).optional(),
+  diagnostics: z9.array(z9.unknown()).optional()
+});
+var ruleSelectionEventSchema = z9.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z9.literal("rule_selection"),
+  selection_token: z9.string(),
+  target_paths: z9.array(z9.string()),
+  required_stable_ids: z9.array(z9.string()),
+  ai_selectable_stable_ids: z9.array(z9.string()),
+  ai_selected_stable_ids: z9.array(z9.string()),
+  final_stable_ids: z9.array(z9.string()),
+  ai_selection_reasons: stringRecordSchema,
+  rejected_stable_ids: z9.array(z9.string()),
+  ignored_stable_ids: z9.array(z9.string())
+});
+var ruleSectionsFetchedEventSchema = z9.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z9.literal("rule_sections_fetched"),
+  selection_token: z9.string(),
+  target_paths: z9.array(z9.string()).optional(),
+  requested_sections: z9.array(z9.string()),
+  final_stable_ids: z9.array(z9.string()),
+  ai_selected_stable_ids: z9.array(z9.string()),
+  diagnostics: z9.array(z9.unknown()).optional()
+});
+var editIntentCheckedEventSchema = z9.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z9.literal("edit_intent_checked"),
+  path: z9.string(),
+  compliant: z9.boolean(),
+  intent: z9.string(),
+  ledger_entry_id: z9.string(),
+  ledger_source: z9.enum(["ai", "human"]).optional(),
+  commit_sha: z9.string().optional(),
+  parent_sha: z9.string().optional(),
+  parent_ledger_entry_id: z9.string().optional(),
+  diff_stat: z9.string().optional(),
+  annotation: z9.string().optional(),
+  matched_rule_context_ts: z9.number().int().nonnegative().nullable(),
+  window_ms: z9.number().int().nonnegative()
+});
+var ruleDriftDetectedEventSchema = z9.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z9.literal("rule_drift_detected"),
+  revision: z9.string().optional(),
+  drifted_stable_ids: z9.array(z9.string()),
+  missing_files: z9.array(z9.string()),
+  stale_files: z9.array(z9.string()),
+  details: z9.array(
+    z9.object({
+      file: z9.string(),
+      stable_id: z9.string(),
+      expected_hash: z9.string(),
+      actual_hash: z9.string().nullable()
+    })
+  ).optional()
+});
+var ruleBaselineAcceptedEventSchema = z9.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z9.literal("rule_baseline_accepted"),
+  revision: z9.string(),
+  previous_revision: z9.string().optional(),
+  accepted_stable_ids: z9.array(z9.string()),
+  source: z9.enum(["doctor_fix", "sync_meta"]).optional()
+});
+var baselineSyncedEventSchema = z9.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z9.literal("baseline_synced"),
+  revision: z9.string(),
+  previous_revision: z9.string().optional(),
+  synced_files: z9.array(z9.string()),
+  accepted_stable_ids: z9.array(z9.string()),
+  source: z9.enum(["doctor_fix", "sync_meta"])
+});
+var mcpEventLedgerEventSchema = z9.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z9.literal("mcp_event"),
+  mcp_event_id: z9.string(),
+  stream_id: z9.string(),
+  message: z9.unknown()
+});
+var reapplyCompletedEventSchema = z9.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z9.literal("reapply_completed"),
+  preserved_ledger: z9.boolean(),
+  preserved_meta: z9.boolean(),
+  rules_count: z9.number().int().nonnegative()
+});
+var eventLedgerTruncatedEventSchema = z9.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z9.literal("event_ledger_truncated"),
+  byte_offset: z9.number().int().nonnegative(),
+  byte_length: z9.number().int().nonnegative(),
+  corrupted_path: z9.string()
+});
+var mcpConfigMigratedEventSchema = z9.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z9.literal("mcp_config_migrated"),
+  source: z9.literal("doctor_fix"),
+  removed_from: z9.string()
+});
+var metaReconciledOnStartupEventSchema = z9.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z9.literal("meta_reconciled_on_startup"),
+  reconciled_files: z9.array(z9.string()),
+  duration_ms: z9.number().int().nonnegative(),
+  source: z9.literal("reconcileRules")
+});
+var metaReconciledEventSchema = z9.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z9.literal("meta_reconciled"),
+  reconciled_files: z9.array(z9.string()),
+  duration_ms: z9.number().int().nonnegative(),
+  trigger: z9.enum(["doctor", "manual"]),
+  source: z9.literal("reconcileRules")
+});
+var claudeSkillPathMigratedEventSchema = z9.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z9.literal("claude_skill_path_migrated"),
+  from: z9.string(),
+  to: z9.string()
+});
+var legacyClientPathPresentEventSchema = z9.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z9.literal("legacy_client_path_present"),
+  removed: z9.array(z9.string())
+});
+var eventLedgerEventSchema = z9.discriminatedUnion("event_type", [
+  ruleContextPlannedEventSchema,
+  ruleSelectionEventSchema,
+  ruleSectionsFetchedEventSchema,
+  editIntentCheckedEventSchema,
+  ruleDriftDetectedEventSchema,
+  ruleBaselineAcceptedEventSchema,
+  baselineSyncedEventSchema,
+  mcpEventLedgerEventSchema,
+  reapplyCompletedEventSchema,
+  eventLedgerTruncatedEventSchema,
+  mcpConfigMigratedEventSchema,
+  metaReconciledOnStartupEventSchema,
+  metaReconciledEventSchema,
+  claudeSkillPathMigratedEventSchema,
+  legacyClientPathPresentEventSchema
+]);
 export {
   AGENTS_META_IDENTITY_SOURCES,
   AGENTS_META_LAYERS,
   AGENTS_META_TOPOLOGY_TYPES,
   PROTECTED_TOKENS,
+  RULE_TEST_INDEX_SCHEMA_VERSION,
   agentsIdentitySourceSchema,
   agentsLayerSchema,
   agentsMetaNodeSchema,
@@ -412,7 +577,9 @@ export {
   aiLedgerEntrySchema,
   annotateIntentRequestSchema,
   auditModeSchema,
+  baselineSyncedEventSchema,
   candidateFileEntrySchema,
+  claudeSkillPathMigratedEventSchema,
   clientPathsSchema,
   createTranslator,
   defaultMessages,
@@ -422,7 +589,10 @@ export {
   deriveAgentsMetaTopologyType,
   detectNodeLocale,
   driftDetectedEventSchema,
+  editIntentCheckedEventSchema,
   enMessages,
+  eventLedgerEventSchema,
+  eventLedgerTruncatedEventSchema,
   fabricConfigSchema,
   fabricEventSchema,
   forensicAssertionCoverageSchema,
@@ -435,6 +605,9 @@ export {
   forensicReportSchema,
   forensicSamplingBudgetSchema,
   forensicTopologySchema,
+  getRulesAnnotations,
+  getRulesInputSchema,
+  getRulesOutputSchema,
   historyStateQuerySchema,
   humanLedgerEntrySchema,
   humanLockApproveRequestSchema,
@@ -452,12 +625,34 @@ export {
   ledgerEntrySchema,
   ledgerQuerySchema,
   ledgerSourceSchema,
+  legacyClientPathPresentEventSchema,
   lockApprovedEventSchema,
   lockDriftEventSchema,
+  mcpConfigMigratedEventSchema,
+  mcpEventLedgerEventSchema,
+  mcpPayloadLimitsSchema,
+  metaReconciledEventSchema,
+  metaReconciledOnStartupEventSchema,
   metaUpdatedEventSchema,
   normalizeLocale,
+  planContextAnnotations,
+  planContextInputSchema,
+  planContextOutputSchema,
+  reapplyCompletedEventSchema,
+  ruleBaselineAcceptedEventSchema,
+  ruleContextPlannedEventSchema,
   ruleDescriptionIndexItemSchema,
   ruleDescriptionSchema,
+  ruleDriftDetectedEventSchema,
+  ruleSectionsAnnotations,
+  ruleSectionsFetchedEventSchema,
+  ruleSectionsInputSchema,
+  ruleSectionsOutputSchema,
+  ruleSelectionEventSchema,
+  ruleTestIndexSchema,
+  ruleTestLinkSchema,
+  ruleTestOrphanAnnotationSchema,
+  structuredWarningSchema,
   withDerivedAgentsMetaNodeDefaults,
   zhCNMessages
 };

package/dist/node/atomic-write.d.ts

@@ -0,0 +1,14 @@
+interface AtomicWriteOptions {
+    fsync?: boolean;
+}
+interface AtomicWriteJsonOptions extends AtomicWriteOptions {
+    indent?: number;
+}
+declare function atomicWriteText(path: string, content: string, opts?: AtomicWriteOptions): Promise<void>;
+declare function atomicWriteJson(path: string, value: unknown, opts?: AtomicWriteJsonOptions): Promise<void>;
+interface LedgerWriteQueue {
+    append(path: string, line: string): Promise<void>;
+}
+declare function createLedgerWriteQueue(): LedgerWriteQueue;
+
+export { type AtomicWriteJsonOptions, type AtomicWriteOptions, type LedgerWriteQueue, atomicWriteJson, atomicWriteText, createLedgerWriteQueue };

package/dist/node/atomic-write.js

@@ -0,0 +1,60 @@
+// src/node/atomic-write.ts
+import { appendFile, open, rename, unlink, writeFile } from "fs/promises";
+function makeTmpSuffix() {
+  const rand = Math.floor(Math.random() * 65535).toString(16).padStart(4, "0");
+  return `.${process.pid}.${Date.now()}.${rand}.tmp`;
+}
+async function atomicWriteText(path, content, opts) {
+  const tmpPath = path + makeTmpSuffix();
+  try {
+    if (opts?.fsync) {
+      const fd = await open(tmpPath, "w");
+      try {
+        await fd.writeFile(content, "utf8");
+        await fd.datasync();
+      } finally {
+        await fd.close();
+      }
+    } else {
+      await writeFile(tmpPath, content, "utf8");
+    }
+    await rename(tmpPath, path);
+  } catch (err) {
+    try {
+      await unlink(tmpPath);
+    } catch {
+    }
+    throw err;
+  }
+}
+async function atomicWriteJson(path, value, opts) {
+  const indent = opts?.indent ?? 2;
+  const content = JSON.stringify(value, null, indent) + "\n";
+  await atomicWriteText(path, content, { fsync: opts?.fsync });
+}
+function createLedgerWriteQueue() {
+  const chains = /* @__PURE__ */ new Map();
+  async function doAppend(path, line) {
+    const normalized = line.endsWith("\n") ? line : line + "\n";
+    await appendFile(path, normalized, "utf8");
+  }
+  return {
+    append(path, line) {
+      const prev = chains.get(path) ?? Promise.resolve();
+      const next = prev.catch(() => void 0).then(() => doAppend(path, line));
+      chains.set(path, next);
+      const guarded = next.catch(() => void 0);
+      guarded.finally(() => {
+        if (chains.get(path) === next) {
+          chains.delete(path);
+        }
+      });
+      return next;
+    }
+  };
+}
+export {
+  atomicWriteJson,
+  atomicWriteText,
+  createLedgerWriteQueue
+};

package/dist/node/bootstrap-guide.d.ts

@@ -0,0 +1,12 @@
+declare const FABRIC_BOOTSTRAP_PATH = ".fabric/bootstrap/README.md";
+/**
+ * Build the content for .fabric/bootstrap/README.md.
+ *
+ * Produces the same structured bootstrap guide that `fab init` writes, using
+ * the detected framework kind and the project name from package.json.  This
+ * lives in shared so both the CLI and the server doctor --fix path can use the
+ * identical builder.
+ */
+declare function buildBootstrapContent(projectRoot: string): string;
+
+export { FABRIC_BOOTSTRAP_PATH, buildBootstrapContent };

package/dist/node/bootstrap-guide.js

@@ -0,0 +1,52 @@
+import {
+  detectFramework
+} from "../chunk-GI6L6VTT.js";
+
+// src/node/bootstrap-guide.ts
+import { existsSync, readFileSync } from "fs";
+import { join, parse } from "path";
+var FABRIC_BOOTSTRAP_PATH = ".fabric/bootstrap/README.md";
+function buildBootstrapContent(projectRoot) {
+  const framework = detectFramework(projectRoot);
+  const projectName = readProjectName(projectRoot) ?? parse(projectRoot).base;
+  const frameworkKind = framework.kind;
+  const content = `# ${projectName} \u2014 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.
+
+## Usage
+
+- This file bootstraps the Fabric Protocol; it does not carry project-specific rules.
+- Detailed bootstrap notes are in \`.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.
+- Root-level rules belong in \`.fabric/rules/root.md\`; cross-domain rules in \`.fabric/rules/_cross/\`.
+- If \`.fabric/rules/root.md\` is missing, complete the Fabric initialization flow before normal coding.
+`;
+  return content;
+}
+function readProjectName(projectRoot) {
+  const packageJsonPath = join(projectRoot, "package.json");
+  if (!existsSync(packageJsonPath)) {
+    return void 0;
+  }
+  try {
+    const raw = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+    return typeof raw.name === "string" && raw.name.length > 0 ? raw.name : void 0;
+  } catch {
+    return void 0;
+  }
+}
+export {
+  FABRIC_BOOTSTRAP_PATH,
+  buildBootstrapContent
+};

package/dist/node/mcp-payload-guard.d.ts

@@ -0,0 +1,16 @@
+interface PayloadGuardOptions {
+    warnBytes?: number;
+    hardBytes?: number;
+}
+interface PayloadGuardResult {
+    bytes: number;
+    warning?: {
+        code: 'mcp_payload_warn';
+        message: string;
+        bytes: number;
+        threshold: number;
+    };
+}
+declare function enforcePayloadLimit(serializedPayload: string, opts?: PayloadGuardOptions): PayloadGuardResult;
+
+export { type PayloadGuardOptions, type PayloadGuardResult, enforcePayloadLimit };

package/dist/node/mcp-payload-guard.js

@@ -0,0 +1,40 @@
+import {
+  MCPError
+} from "../chunk-3SZRB42B.js";
+
+// src/node/mcp-payload-guard.ts
+var McpPayloadTooLargeError = class extends MCPError {
+  code = "MCP_PAYLOAD_TOO_LARGE";
+  httpStatus = 413;
+};
+var DEFAULT_WARN = 16384;
+var DEFAULT_HARD = 65536;
+function enforcePayloadLimit(serializedPayload, opts) {
+  const warnAt = opts?.warnBytes ?? DEFAULT_WARN;
+  const hardAt = opts?.hardBytes ?? DEFAULT_HARD;
+  const bytes = Buffer.byteLength(serializedPayload, "utf8");
+  if (bytes > hardAt) {
+    throw new McpPayloadTooLargeError(
+      `MCP payload ${bytes} bytes exceeds hard limit ${hardAt}`,
+      {
+        actionHint: `Reduce response size or increase fabric.config.json mcpPayloadLimits.hardBytes`,
+        details: { bytes, threshold: hardAt }
+      }
+    );
+  }
+  if (bytes > warnAt) {
+    return {
+      bytes,
+      warning: {
+        code: "mcp_payload_warn",
+        message: `Payload ${bytes}B exceeds warning threshold ${warnAt}B`,
+        bytes,
+        threshold: warnAt
+      }
+    };
+  }
+  return { bytes };
+}
+export {
+  enforcePayloadLimit
+};