@fenglimg/fabric-server 1.7.0 → 1.8.0-rc.1

package/dist/{http-6LFZLHCN.js → http-MEFXOG3L.js}

@@ -1,7 +1,5 @@
 import {
   AGENTS_MD_RESOURCE_URI,
-  AgentsMetaFileMissingError,
-  AgentsMetaInvalidError,
   EVENT_LEDGER_PATH,
   LEDGER_PATH,
   LEGACY_LEDGER_PATH,
@@ -11,12 +9,13 @@ import {
   getLedgerPath,
   getLegacyLedgerPath,
   getRules,
+  invalidateRuleSyncCooldown,
   isNodeError,
   readAgentsMeta,
   readEventLedger,
   runDoctorReport,
   sha256
-} from "./chunk-PTFSYO4Y.js";
+} from "./chunk-E3BHIUIW.js";
 
 // src/http.ts
 import { randomUUID as randomUUID2 } from "crypto";
@@ -28,6 +27,7 @@ import {
 import chokidar2 from "chokidar";
 
 // src/api/_error.ts
+import { FabricError } from "@fenglimg/fabric-shared/errors";
 function sendError(res, status, code, message, details) {
   const payload = {
     error: {
@@ -48,49 +48,15 @@ function sendUnknownError(res, error) {
   sendError(res, normalized.status, normalized.code, normalized.message, normalized.details);
 }
 function normalizeApiError(error) {
-  if (error instanceof Error && "status" in error && "code" in error && typeof error.status === "number" && typeof error.code === "string") {
+  if (error instanceof FabricError) {
     return {
-      status: error.status,
+      status: error.httpStatus,
       code: error.code,
-      message: error.message
-    };
-  }
-  if (error instanceof AgentsMetaFileMissingError) {
-    return {
-      status: 404,
-      code: error.code,
-      message: error.message
-    };
-  }
-  if (error instanceof AgentsMetaInvalidError) {
-    return {
-      status: 500,
-      code: error.code,
-      message: error.message
+      message: error.message,
+      details: error.details
     };
   }
   if (error instanceof Error) {
-    if (error.message.startsWith("Path escapes project root:")) {
-      return {
-        status: 403,
-        code: "PATH_OUTSIDE_PROJECT_ROOT",
-        message: error.message
-      };
-    }
-    if (error.message.startsWith("Cannot find human lock entry:")) {
-      return {
-        status: 404,
-        code: "HUMAN_LOCK_ENTRY_NOT_FOUND",
-        message: error.message
-      };
-    }
-    if (error.message.startsWith("Cannot find ledger entry:")) {
-      return {
-        status: 404,
-        code: "LEDGER_ENTRY_NOT_FOUND",
-        message: error.message
-      };
-    }
     return {
       status: 500,
       code: "INTERNAL_ERROR",
@@ -213,7 +179,7 @@ function parseLedgerLine(line, index) {
   }
 }
 async function readLedgerFromEventLedger(projectRoot) {
-  const events = await readEventLedger(projectRoot);
+  const { events } = await readEventLedger(projectRoot);
   const grouped = /* @__PURE__ */ new Map();
   for (const event of events) {
     const entry = projectLedgerEvent(event);
@@ -687,17 +653,26 @@ import { historyStateQuerySchema } from "@fenglimg/fabric-shared";
 import { execFile } from "child_process";
 import { promisify } from "util";
 import { agentsMetaSchema as agentsMetaSchema2 } from "@fenglimg/fabric-shared";
+import { IOFabricError, RuleError } from "@fenglimg/fabric-shared/errors";
 var execFileAsync = promisify(execFile);
 var AGENTS_META_GIT_PATH = ".fabric/agents.meta.json";
-var HistoryReplayError = class extends Error {
-  constructor(message, code, status) {
-    super(message);
-    this.code = code;
-    this.status = status;
-    this.name = "HistoryReplayError";
-  }
-  code;
-  status;
+var HistoryStateNotFoundError = class extends IOFabricError {
+  code = "HISTORY_STATE_NOT_FOUND";
+  httpStatus = 404;
+  constructor(message, opts) {
+    super(message, {
+      actionHint: opts?.actionHint ?? "Ensure the ledger exists and the requested timestamp or entry ID is within its range"
+    });
+  }
+};
+var LedgerEntryNotFoundError = class extends RuleError {
+  code = "LEDGER_ENTRY_NOT_FOUND";
+  httpStatus = 404;
+  constructor(message, opts) {
+    super(message, {
+      actionHint: opts?.actionHint ?? "Verify the ledger entry ID exists in the current ledger"
+    });
+  }
 };
 async function rehydrateAgentsMetaAt(projectRoot, target) {
   const ledger = await readLedger(projectRoot);
@@ -705,10 +680,8 @@ async function rehydrateAgentsMetaAt(projectRoot, target) {
   const replayedEntries = ledger.slice(0, selectedIndex + 1);
   const selectedEntry = replayedEntries.at(-1);
   if (selectedEntry === void 0) {
-    throw new HistoryReplayError(
-      "Cannot rehydrate history state because the ledger is empty.",
-      "HISTORY_STATE_NOT_FOUND",
-      404
+    throw new HistoryStateNotFoundError(
+      "Cannot rehydrate history state because the ledger is empty."
     );
   }
   const commitCandidates = collectCommitCandidates(replayedEntries);
@@ -743,10 +716,8 @@ function resolveTargetIndex(ledger, target) {
   if ("ledgerEntryId" in target) {
     const index = ledger.findIndex((entry) => entry.id === target.ledgerEntryId);
     if (index === -1) {
-      throw new HistoryReplayError(
-        `Cannot find ledger entry: ${target.ledgerEntryId}`,
-        "LEDGER_ENTRY_NOT_FOUND",
-        404
+      throw new LedgerEntryNotFoundError(
+        `Cannot find ledger entry: ${target.ledgerEntryId}`
       );
     }
     return index;
@@ -756,10 +727,8 @@ function resolveTargetIndex(ledger, target) {
       return index;
     }
   }
-  throw new HistoryReplayError(
-    `Cannot find ledger entry at or before timestamp: ${new Date(target.timestamp).toISOString()}`,
-    "HISTORY_STATE_NOT_FOUND",
-    404
+  throw new HistoryStateNotFoundError(
+    `Cannot find ledger entry at or before timestamp: ${new Date(target.timestamp).toISOString()}`
   );
 }
 function collectCommitCandidates(entries) {
@@ -869,7 +838,7 @@ async function annotateIntent(projectRoot, input) {
   const entries = await readLedger(projectRoot);
   const parentEntry = entries.find((entry2) => entry2.id === input.ledger_entry_id);
   if (parentEntry === void 0) {
-    throw new Error(`Cannot find ledger entry: ${input.ledger_entry_id}`);
+    throw new LedgerEntryNotFoundError(`Cannot find ledger entry: ${input.ledger_entry_id}`);
   }
   const lastEntry = entries[entries.length - 1];
   if (lastEntry?.source === "human" && lastEntry.parent_ledger_entry_id === input.ledger_entry_id && lastEntry.annotation === input.annotation) {
@@ -1205,7 +1174,7 @@ var JsonlEventStore = class {
     return streamId;
   }
   async readEvents() {
-    const eventLedgerEvents = await readEventLedger(this.projectRoot);
+    const { events: eventLedgerEvents } = await readEventLedger(this.projectRoot);
     const projectedEvents = eventLedgerEvents.flatMap((event) => {
       if (event.event_type !== "mcp_event") {
         return [];
@@ -1240,6 +1209,33 @@ var JsonlEventStore = class {
     return raw.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0).map((line) => parseStoredMcpEvent(line)).filter((event) => event !== null);
   }
 };
+function handleCacheWatcherEvent(relativePath, projectRoot, sessions, timers) {
+  const normalized = relativePath.replaceAll("\\", "/");
+  if (normalized === ".fabric/agents.meta.json") {
+    contextCache.invalidate("file_watch", projectRoot);
+    clearTimeout(timers.getToolListTimer());
+    timers.setToolListTimer(
+      setTimeout(() => {
+        notifyAllSessions(sessions, "tools/list_changed");
+      }, NOTIFY_DEBOUNCE_MS)
+    );
+    return;
+  }
+  if (normalized === ".fabric/bootstrap/README.md") {
+    contextCache.invalidate("file_watch", projectRoot);
+    clearTimeout(timers.getAgentsMdTimer());
+    timers.setAgentsMdTimer(
+      setTimeout(() => {
+        notifyAllSessions(sessions, "resource_updated", AGENTS_MD_RESOURCE_URI);
+      }, NOTIFY_DEBOUNCE_MS)
+    );
+    return;
+  }
+  if (normalized.startsWith(".fabric/rules/") && normalized.endsWith(".md")) {
+    contextCache.invalidate("file_watch", projectRoot);
+    invalidateRuleSyncCooldown(projectRoot);
+  }
+}
 function createFabricHttpApp(options) {
   const { projectRoot, host = DEFAULT_HOST, authToken, dashboardDistPath, dev } = options;
   const app = createMcpExpressApp({ host });
@@ -1247,7 +1243,11 @@ function createFabricHttpApp(options) {
   const sessions = /* @__PURE__ */ new Map();
   process.env.FABRIC_PROJECT_ROOT = projectRoot;
   const cacheWatcher = chokidar2.watch(
-    [".fabric/agents.meta.json", ".fabric/bootstrap/README.md"],
+    [
+      ".fabric/agents.meta.json",
+      ".fabric/bootstrap/README.md",
+      ".fabric/rules/**/*.md"
+    ],
     {
       cwd: projectRoot,
       ignoreInitial: true,
@@ -1259,22 +1259,21 @@ function createFabricHttpApp(options) {
   );
   let agentsMdNotifyTimer;
   let toolListNotifyTimer;
-  cacheWatcher.on("change", (relativePath) => {
-    const normalized = relativePath.replaceAll("\\", "/");
-    if (normalized === ".fabric/agents.meta.json") {
-      contextCache.invalidate("file_watch", projectRoot);
-      clearTimeout(toolListNotifyTimer);
-      toolListNotifyTimer = setTimeout(() => {
-        notifyAllSessions(sessions, "tools/list_changed");
-      }, NOTIFY_DEBOUNCE_MS);
-    } else if (normalized === ".fabric/bootstrap/README.md") {
-      contextCache.invalidate("file_watch", projectRoot);
-      clearTimeout(agentsMdNotifyTimer);
-      agentsMdNotifyTimer = setTimeout(() => {
-        notifyAllSessions(sessions, "resource_updated", AGENTS_MD_RESOURCE_URI);
-      }, NOTIFY_DEBOUNCE_MS);
-    }
-  });
+  const onCacheWatcherEvent = (relativePath) => {
+    handleCacheWatcherEvent(relativePath, projectRoot, sessions, {
+      getAgentsMdTimer: () => agentsMdNotifyTimer,
+      getToolListTimer: () => toolListNotifyTimer,
+      setAgentsMdTimer: (t) => {
+        agentsMdNotifyTimer = t;
+      },
+      setToolListTimer: (t) => {
+        toolListNotifyTimer = t;
+      }
+    });
+  };
+  cacheWatcher.on("change", onCacheWatcherEvent);
+  cacheWatcher.on("add", onCacheWatcherEvent);
+  cacheWatcher.on("unlink", onCacheWatcherEvent);
   let disposed = false;
   app.dispose = async () => {
     if (disposed) {
@@ -1407,5 +1406,5 @@ function isNodeError3(error) {
 }
 export {
   createFabricHttpApp,
-  notifyAllSessions
+  handleCacheWatcherEvent
 };

package/dist/index.d.ts

@@ -1,6 +1,18 @@
 import { Server } from 'node:http';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { AgentsMeta, RuleTestIndex, AgentsLayer, AgentsTopologyType } from '@fenglimg/fabric-shared';
+import { IOFabricError } from '@fenglimg/fabric-shared/errors';
+
+interface InFlightTracker {
+    enter(requestId: string): void;
+    exit(requestId: string): void;
+    drain(deadlineMs: number): Promise<{
+        drained: number;
+        timed_out: number;
+    }>;
+    size(): number;
+}
+declare function createInFlightTracker(): InFlightTracker;
 
 declare const LEDGER_PATH = ".fabric/.intent-ledger.jsonl";
 declare const LEGACY_LEDGER_PATH = ".intent-ledger.jsonl";
@@ -10,7 +22,7 @@ declare function getLegacyLedgerPath(projectRoot: string): string;
 declare function getEventLedgerPath(projectRoot: string): string;
 
 type DoctorStatus = "ok" | "warn" | "error";
-type DoctorIssueKind = "fixable_error" | "manual_error" | "warning";
+type DoctorIssueKind = "fixable_error" | "manual_error" | "warning" | "info";
 type DoctorCheck = {
     name: string;
     status: DoctorStatus;
@@ -18,6 +30,7 @@ type DoctorCheck = {
     kind?: DoctorIssueKind;
     code?: string;
     fixable?: boolean;
+    actionHint?: string;
 };
 type DoctorIssue = {
     code: string;
@@ -43,6 +56,7 @@ type DoctorSummary = {
     fixableErrorCount: number;
     manualErrorCount: number;
     warningCount: number;
+    infoCount: number;
     targetFiles: Record<string, boolean>;
 };
 type DoctorReport = {
@@ -51,6 +65,7 @@ type DoctorReport = {
     fixable_errors: DoctorIssue[];
     manual_errors: DoctorIssue[];
     warnings: DoctorIssue[];
+    infos: DoctorIssue[];
     summary: DoctorSummary;
 };
 type DoctorFixReport = {
@@ -88,8 +103,137 @@ declare function stableStringify(value: unknown): string;
 /** MCP resource URI for the project's bootstrap README (L0 rules) file. */
 declare const AGENTS_MD_RESOURCE_URI = "fabric://bootstrap-readme";
 
-declare function createFabricServer(): McpServer;
+/**
+ * Synchronously fsync the event ledger file to ensure OS page-cache buffers are
+ * flushed to durable storage. Must be called AFTER in-flight drain but BEFORE
+ * server.close() — Gemini G1 ordering requirement.
+ *
+ * Uses sync APIs intentionally: we are inside a signal handler and need
+ * guaranteed completion before process.exit().
+ */
+declare function flushAndSyncEventLedger(projectRoot: string): void;
+
+/**
+ * rule-sync.ts — Rule-sync orchestrator framework (R28, TASK-011)
+ *
+ * Public surface: ensureRulesFresh, reconcileRules + exported types.
+ * Internal helpers are co-located in this file.
+ * Does NOT wire any consumers (MCP tools, doctor, watchers).
+ *
+ * Distinction between the two public entry points:
+ *
+ * - `ensureRulesFresh`: detects drift, emits ledger events, invalidates cache.
+ *   Does NOT rewrite agents.meta.json. Optimised for hot-path consumers (MCP tools).
+ *
+ * - `reconcileRules`: full scan + rewrites agents.meta.json (via rule-meta-builder)
+ *   + emits ledger events. Used by startup (TASK-022) and doctor repair (TASK-023).
+ */
+interface RuleSyncOptions {
+    mode?: "incremental" | "full";
+    /** When true, invalid frontmatter throws RuleValidationError (default: false — collect as warning). */
+    throwOnInvalidFrontmatter?: boolean;
+}
+interface StructuredWarning {
+    code: string;
+    file: string;
+    line?: number;
+    action_hint: string;
+}
+/**
+ * Granular ledger event shape for rule-sync operations.
+ * These are returned in RuleSyncReport and also appended to the event ledger
+ * using the nearest available ledger event type (rule_drift_detected /
+ * baseline_synced). The shape below is what callers receive in `.events`.
+ */
+interface RuleSyncLedgerEvent {
+    type: "rule_content_changed" | "rule_added" | "rule_removed";
+    stable_id: string;
+    path: string;
+    prev_hash: string | null;
+    new_hash: string | null;
+    changed_fields: string[];
+    source: "ensureRulesFresh" | "reconcileRules";
+}
+/** Alias so the public API says LedgerEvent (as documented). */
+type LedgerEvent = RuleSyncLedgerEvent;
+interface RuleSyncReport {
+    status: "fresh" | "reconciled" | "errors";
+    events: LedgerEvent[];
+    warnings: StructuredWarning[];
+    reconciled_files?: string[];
+}
+/**
+ * Detects drift between disk and agents.meta.json, emits ledger events, and
+ * invalidates the cache. Does NOT rewrite agents.meta.json. Optimised for
+ * hot-path consumers (MCP tools).
+ */
+declare function ensureRulesFresh(projectRoot: string, opts?: RuleSyncOptions): Promise<RuleSyncReport>;
+interface ReconcileRulesOptions {
+    /** Identifies who triggered the reconcile; controls which summary ledger event is written. */
+    trigger?: "startup" | "doctor" | "manual";
+}
+/**
+ * Full scan + rewrites agents.meta.json with ground-truth disk state + emits
+ * ledger events. Used by startup (TASK-022) and doctor repair (TASK-023).
+ * Returns reconciled_files listing all paths whose meta was updated.
+ *
+ * When `opts.trigger` is `'startup'`, a `meta_reconciled_on_startup` summary
+ * ledger event is appended after per-file drift events. Other trigger values
+ * append a `meta_reconciled` event. Omitting the trigger skips the summary.
+ */
+declare function reconcileRules(projectRoot: string, opts?: ReconcileRulesOptions): Promise<RuleSyncReport>;
+
+declare class ServeLockHeldError extends IOFabricError {
+    readonly code = "SERVE_LOCK_HELD";
+    readonly httpStatus = 423;
+}
+interface LockState {
+    pid: number;
+    acquiredAt: number;
+    host?: string;
+}
+interface AcquireOptions {
+    force?: boolean;
+}
+declare function acquireLock(projectRoot: string, opts?: AcquireOptions): void;
+declare function releaseLock(projectRoot: string): void;
+declare function readLockState(projectRoot: string): LockState | null;
+declare function checkLockOrThrow(projectRoot: string, opts?: AcquireOptions): void;
+
+/**
+ * Returns an info-level startup message when CLAUDE.md or AGENTS.md exist at
+ * the project root, or null when neither is present.
+ *
+ * Extracted as a pure helper so unit tests can exercise it without spawning
+ * a full server (TASK-034).
+ */
+declare function formatPreexistingRootMessage(projectRoot: string): string | null;
+
+declare function createFabricServer(tracker?: InFlightTracker): McpServer;
 declare function startStdioServer(): Promise<void>;
+/**
+ * Dependencies for the shutdown handler factory. Tests inject `exit` to assert
+ * exit-code behavior without terminating the test process.
+ */
+interface ShutdownHandlerDeps {
+    signal: NodeJS.Signals;
+    tracker: InFlightTracker;
+    projectRoot: string;
+    closeServer: () => Promise<void>;
+    /** Override for tests; defaults to `process.exit`. */
+    exit?: (code: number) => never;
+    /** Override for tests; defaults to 5000ms (Gemini G1). */
+    drainDeadlineMs?: number;
+}
+/**
+ * Builds a same-signal shutdown handler implementing server.md I1:
+ *   - First invocation: drain in-flight (5s) → fsync ledger → close server → exit(0)
+ *   - Second invocation of the same signal (while first is in flight): exit(1)
+ *
+ * Each call to this factory returns an independent handler with its own
+ * `invoked` flag, so per-signal dedup is isolated.
+ */
+declare function createShutdownHandler(deps: ShutdownHandlerDeps): () => void;
 declare function startHttpServer(options: {
     port: number;
     projectRoot: string;
@@ -99,4 +243,4 @@ declare function startHttpServer(options: {
     dev?: boolean;
 }): Promise<Server>;
 
-export { AGENTS_MD_RESOURCE_URI, type DoctorFixReport, type DoctorIssue, type DoctorReport, EVENT_LEDGER_PATH, LEDGER_PATH, LEGACY_LEDGER_PATH, type RuleMetaBuildResult, type RuleMetaBuildSource, type WriteRuleMetaOptions, buildRuleMeta, computeRuleTestIndex, computeRulesBasedAgentsMeta, createFabricServer, deriveRuleMetaLayer, deriveRuleMetaTopologyType, getEventLedgerPath, getLedgerPath, getLegacyLedgerPath, isSameRuleTestIndex, runDoctorFix, runDoctorReport, stableStringify, startHttpServer, startStdioServer, writeRuleMeta };
+export { AGENTS_MD_RESOURCE_URI, type AcquireOptions, type DoctorFixReport, type DoctorIssue, type DoctorReport, EVENT_LEDGER_PATH, type InFlightTracker, LEDGER_PATH, LEGACY_LEDGER_PATH, type LedgerEvent, type LockState, type ReconcileRulesOptions, type RuleMetaBuildResult, type RuleMetaBuildSource, type RuleSyncLedgerEvent, type RuleSyncOptions, type RuleSyncReport, ServeLockHeldError, type ShutdownHandlerDeps, type StructuredWarning, type WriteRuleMetaOptions, acquireLock, buildRuleMeta, checkLockOrThrow, computeRuleTestIndex, computeRulesBasedAgentsMeta, createFabricServer, createInFlightTracker, createShutdownHandler, deriveRuleMetaLayer, deriveRuleMetaTopologyType, ensureRulesFresh, flushAndSyncEventLedger, formatPreexistingRootMessage, getEventLedgerPath, getLedgerPath, getLegacyLedgerPath, isSameRuleTestIndex, readLockState, reconcileRules, releaseLock, runDoctorFix, runDoctorReport, stableStringify, startHttpServer, startStdioServer, writeRuleMeta };