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

package/dist/index.js

@@ -3,180 +3,290 @@ import {
   EVENT_LEDGER_PATH,
   LEDGER_PATH,
   LEGACY_LEDGER_PATH,
-  RULE_SECTION_NAMES,
   buildRuleMeta,
   computeRuleTestIndex,
   computeRulesBasedAgentsMeta,
   deriveRuleMetaLayer,
   deriveRuleMetaTopologyType,
+  ensureRulesFresh,
+  flushAndSyncEventLedger,
   getEventLedgerPath,
   getLedgerPath,
   getLegacyLedgerPath,
   getRuleSections,
   isSameRuleTestIndex,
   planContext,
+  reconcileRules,
   resolveProjectRoot,
   runDoctorFix,
   runDoctorReport,
   stableStringify,
   writeRuleMeta
-} from "./chunk-PTFSYO4Y.js";
+} from "./chunk-E3BHIUIW.js";
 
 // src/index.ts
+import { existsSync as existsSync2 } from "fs";
 import { readFile } from "fs/promises";
-import { join, resolve } from "path";
+import { join as join2, resolve } from "path";
 import { fileURLToPath } from "url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
+// src/services/in-flight-tracker.ts
+function createInFlightTracker() {
+  const active = /* @__PURE__ */ new Map();
+  let resolveDrained = null;
+  return {
+    enter(id) {
+      active.set(id, Date.now());
+    },
+    exit(id) {
+      active.delete(id);
+      if (active.size === 0 && resolveDrained) {
+        resolveDrained();
+        resolveDrained = null;
+      }
+    },
+    drain(deadlineMs) {
+      const startedWith = active.size;
+      if (startedWith === 0) return Promise.resolve({ drained: 0, timed_out: 0 });
+      return new Promise((resolve2) => {
+        const timer = setTimeout(() => {
+          const drainedCount = startedWith - active.size;
+          resolveDrained = null;
+          resolve2({ drained: drainedCount, timed_out: active.size });
+        }, deadlineMs);
+        resolveDrained = () => {
+          clearTimeout(timer);
+          resolve2({ drained: startedWith, timed_out: 0 });
+        };
+      });
+    },
+    size() {
+      return active.size;
+    }
+  };
+}
+
 // src/tools/plan-context.ts
-import { z } from "zod";
-var inputSchema = {
-  paths: z.array(z.string()).min(1).describe("Candidate file paths to build neutral rule selection context for"),
-  intent: z.string().optional().describe("User-stated requirement or implementation intent; used only to build a neutral requirement profile"),
-  known_tech: z.array(z.string()).optional().describe("Known technologies involved in the requirement profile"),
-  detected_entities: z.record(z.array(z.string())).optional().describe("Optional path-keyed detected entities for the requirement profile"),
-  client_hash: z.string().optional().describe("Revision hash from a prior fab_plan_context response; enables stale detection"),
-  correlation_id: z.string().optional().describe("Optional caller-provided correlation id for Event Ledger records"),
-  session_id: z.string().optional().describe("Optional caller-provided session id for Event Ledger records")
-};
-var ruleDescriptionSchema = z.object({
-  summary: z.string(),
-  intent_clues: z.array(z.string()),
-  tech_stack: z.array(z.string()),
-  impact: z.array(z.string()),
-  must_read_if: z.string(),
-  entities: z.array(z.string()).optional()
-});
-var descriptionIndexItemSchema = z.object({
-  stable_id: z.string(),
-  level: z.enum(["L0", "L1", "L2"]),
-  required: z.boolean(),
-  selectable: z.boolean(),
-  description: ruleDescriptionSchema
-});
-var requirementProfileSchema = z.object({
-  target_path: z.string(),
-  path_segments: z.array(z.string()),
-  extension: z.string(),
-  inferred_domain: z.array(z.string()),
-  known_tech: z.array(z.string()),
-  user_intent: z.string(),
-  intent_tokens: z.array(z.string()),
-  impact_hints: z.array(z.string()),
-  detected_entities: z.array(z.string())
-});
-var selectionPolicySchema = z.object({
-  required_levels: z.tuple([z.literal("L0"), z.literal("L2")]),
-  ai_selectable_levels: z.tuple([z.literal("L1")]),
-  final_fetch_rule: z.literal("required_stable_ids + ai_selected_l1_stable_ids")
-});
-var outputSchema = z.object({
-  revision_hash: z.string(),
-  stale: z.boolean(),
-  selection_token: z.string(),
-  entries: z.array(
-    z.object({
-      path: z.string(),
-      requirement_profile: requirementProfileSchema,
-      description_index: z.array(descriptionIndexItemSchema),
-      required_stable_ids: z.array(z.string()),
-      ai_selectable_stable_ids: z.array(z.string()),
-      initial_selected_stable_ids: z.array(z.string()),
-      selection_policy: selectionPolicySchema
-    })
-  ),
-  shared: z.object({
-    required_stable_ids: z.array(z.string()),
-    ai_selectable_stable_ids: z.array(z.string()),
-    description_index: z.array(descriptionIndexItemSchema),
-    preflight_diagnostics: z.array(
-      z.object({
-        code: z.literal("missing_description"),
-        severity: z.literal("warn"),
-        message: z.string(),
-        stable_ids: z.array(z.string()).optional(),
-        path: z.string().optional()
-      })
-    )
-  })
-});
-function registerPlanContext(server) {
+import { randomUUID } from "crypto";
+import {
+  planContextAnnotations,
+  planContextInputSchema,
+  planContextOutputSchema
+} from "@fenglimg/fabric-shared/schemas/api-contracts";
+import { enforcePayloadLimit } from "@fenglimg/fabric-shared/node/mcp-payload-guard";
+
+// src/config-loader.ts
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+function readFabricConfig(projectRoot) {
+  const configPath = join(projectRoot, "fabric.config.json");
+  if (!existsSync(configPath)) {
+    return {};
+  }
+  const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`Expected object in ${configPath}`);
+  }
+  return parsed;
+}
+function readPayloadLimits(projectRoot) {
+  return readFabricConfig(projectRoot).mcpPayloadLimits;
+}
+
+// src/tools/plan-context.ts
+function registerPlanContext(server, tracker) {
   server.registerTool(
     "fab_plan_context",
     {
       description: "Use during plan or architecture phases to build a neutral Fabric rule description index and selection token before fetching rule sections.",
-      inputSchema,
-      outputSchema,
-      annotations: { readOnlyHint: true }
+      inputSchema: planContextInputSchema,
+      outputSchema: planContextOutputSchema,
+      annotations: planContextAnnotations
     },
     async ({ paths, intent, known_tech, detected_entities, client_hash, correlation_id, session_id }) => {
-      const projectRoot = resolveProjectRoot();
-      const result = await planContext(projectRoot, {
-        paths,
-        intent,
-        known_tech,
-        detected_entities,
-        client_hash,
-        correlation_id,
-        session_id
-      });
-      return {
-        content: [{ type: "text", text: JSON.stringify(result) }],
-        structuredContent: result
-      };
+      const requestId = randomUUID();
+      tracker?.enter(requestId);
+      try {
+        const projectRoot = resolveProjectRoot();
+        const syncReport = await ensureRulesFresh(projectRoot);
+        const result = await planContext(projectRoot, {
+          paths,
+          intent,
+          known_tech,
+          detected_entities,
+          client_hash,
+          correlation_id,
+          session_id
+        });
+        const response = {
+          ...result,
+          warnings: [...syncReport.warnings]
+        };
+        const payloadLimits = readPayloadLimits(projectRoot);
+        const serialized = JSON.stringify(response);
+        const guardResult = enforcePayloadLimit(serialized, payloadLimits);
+        if (guardResult.warning) {
+          response.warnings = [
+            ...response.warnings,
+            {
+              code: guardResult.warning.code,
+              file: "<response>",
+              action_hint: "Consider narrowing the request scope to reduce response size"
+            }
+          ];
+        }
+        return {
+          content: [{ type: "text", text: JSON.stringify(response) }],
+          structuredContent: response
+        };
+      } finally {
+        tracker?.exit(requestId);
+      }
     }
   );
 }
 
 // src/tools/rule-sections.ts
-import { z as z2 } from "zod";
-var inputSchema2 = {
-  selection_token: z2.string().min(1).describe("Selection token returned by fab_plan_context"),
-  sections: z2.array(z2.enum(RULE_SECTION_NAMES)).min(1).describe("Structured rule sections to fetch"),
-  ai_selected_stable_ids: z2.array(z2.string()).describe("AI-selected L1 stable_ids chosen from fab_plan_context ai_selectable_stable_ids"),
-  ai_selection_reasons: z2.record(z2.string().min(1)).describe("Reason for each AI-selected L1 stable_id"),
-  correlation_id: z2.string().optional().describe("Optional caller-provided correlation id for Event Ledger records"),
-  session_id: z2.string().optional().describe("Optional caller-provided session id for Event Ledger records")
-};
-var outputSchema2 = z2.object({
-  revision_hash: z2.string(),
-  precedence: z2.tuple([z2.literal("L2"), z2.literal("L1"), z2.literal("L0")]),
-  selected_stable_ids: z2.array(z2.string()),
-  rules: z2.array(
-    z2.object({
-      stable_id: z2.string(),
-      level: z2.enum(["L0", "L1", "L2"]),
-      path: z2.string(),
-      sections: z2.record(z2.string())
-    })
-  ),
-  diagnostics: z2.array(
-    z2.object({
-      code: z2.literal("missing_section"),
-      severity: z2.literal("warn"),
-      stable_id: z2.string(),
-      section: z2.enum(RULE_SECTION_NAMES),
-      message: z2.string()
-    })
-  )
-});
-function registerRuleSections(server) {
+import { randomUUID as randomUUID2 } from "crypto";
+import {
+  ruleSectionsAnnotations,
+  ruleSectionsInputSchema,
+  ruleSectionsOutputSchema
+} from "@fenglimg/fabric-shared/schemas/api-contracts";
+import { enforcePayloadLimit as enforcePayloadLimit2 } from "@fenglimg/fabric-shared/node/mcp-payload-guard";
+function registerRuleSections(server, tracker) {
   server.registerTool(
     "fab_get_rule_sections",
     {
       description: "Fetch structured Fabric rule sections after fab_plan_context. Required L0/L2 rules are merged with AI-selected L1 rules server-side.",
-      inputSchema: inputSchema2,
-      outputSchema: outputSchema2,
-      annotations: { readOnlyHint: true }
+      inputSchema: ruleSectionsInputSchema,
+      outputSchema: ruleSectionsOutputSchema,
+      annotations: ruleSectionsAnnotations
     },
     async (input) => {
-      const projectRoot = resolveProjectRoot();
-      const result = await getRuleSections(projectRoot, input);
-      return {
-        content: [{ type: "text", text: JSON.stringify(result) }],
-        structuredContent: result
-      };
+      const requestId = randomUUID2();
+      tracker?.enter(requestId);
+      try {
+        const projectRoot = resolveProjectRoot();
+        const syncReport = await ensureRulesFresh(projectRoot);
+        const result = await getRuleSections(projectRoot, input);
+        const response = {
+          ...result,
+          warnings: [...syncReport.warnings]
+        };
+        const payloadLimits = readPayloadLimits(projectRoot);
+        const serialized = JSON.stringify(response);
+        const guardResult = enforcePayloadLimit2(serialized, payloadLimits);
+        if (guardResult.warning) {
+          response.warnings = [
+            ...response.warnings,
+            {
+              code: guardResult.warning.code,
+              file: "<response>",
+              action_hint: "Consider narrowing the request scope to reduce response size"
+            }
+          ];
+        }
+        return {
+          content: [{ type: "text", text: JSON.stringify(response) }],
+          structuredContent: response
+        };
+      } finally {
+        tracker?.exit(requestId);
+      }
+    }
+  );
+}
+
+// src/services/serve-lock.ts
+import fs from "fs";
+import path from "path";
+import { IOFabricError } from "@fenglimg/fabric-shared/errors";
+var LOCK_FILENAME = ".serve.lock";
+var ServeLockHeldError = class extends IOFabricError {
+  code = "SERVE_LOCK_HELD";
+  httpStatus = 423;
+};
+function lockPath(projectRoot) {
+  return path.join(projectRoot, ".fabric", LOCK_FILENAME);
+}
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    const err = e;
+    if (err.code === "ESRCH") return false;
+    if (err.code === "EPERM") return true;
+    throw e;
+  }
+}
+function acquireLock(projectRoot, opts) {
+  const p = lockPath(projectRoot);
+  if (fs.existsSync(p)) {
+    let state = null;
+    try {
+      state = JSON.parse(fs.readFileSync(p, "utf8"));
+    } catch {
+    }
+    if (state && state.pid && state.pid !== process.pid && isAlive(state.pid) && !opts?.force) {
+      throw new ServeLockHeldError(
+        `serve lock held by live PID ${state.pid}`,
+        {
+          actionHint: `Stop the other process (PID ${state.pid}) or run with --force to override`,
+          details: state
+        }
+      );
+    }
+    if (state && state.pid && !isAlive(state.pid)) {
+      process.stderr.write(`[serve-lock] stale lock from PID ${state.pid} \u2014 overwriting
+`);
+    }
+  }
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(
+    p,
+    JSON.stringify({ pid: process.pid, acquiredAt: Date.now(), host: process.env.HOSTNAME })
+  );
+}
+function releaseLock(projectRoot) {
+  const p = lockPath(projectRoot);
+  try {
+    if (fs.existsSync(p)) {
+      const state = JSON.parse(fs.readFileSync(p, "utf8"));
+      if (state.pid === process.pid) {
+        fs.unlinkSync(p);
+      }
+    }
+  } catch {
+  }
+}
+function readLockState(projectRoot) {
+  const p = lockPath(projectRoot);
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function checkLockOrThrow(projectRoot, opts) {
+  const state = readLockState(projectRoot);
+  if (state === null) return;
+  if (state.pid === process.pid) return;
+  if (!isAlive(state.pid)) {
+    process.stderr.write(`[serve-lock] stale lock from PID ${state.pid} \u2014 ignoring
+`);
+    return;
+  }
+  if (opts?.force) return;
+  throw new ServeLockHeldError(
+    `serve lock held by live PID ${state.pid}`,
+    {
+      actionHint: `Stop the other serve process (PID ${state.pid}) before running this command, or pass --force to override`,
+      details: state
     }
   );
 }
@@ -192,13 +302,20 @@ function formatError(error) {
   }
   return `Unknown error: ${String(error)}`;
 }
-function createFabricServer() {
+function formatPreexistingRootMessage(projectRoot) {
+  const preexisting = [];
+  if (existsSync2(join2(projectRoot, "CLAUDE.md"))) preexisting.push("CLAUDE.md");
+  if (existsSync2(join2(projectRoot, "AGENTS.md"))) preexisting.push("AGENTS.md");
+  if (preexisting.length === 0) return null;
+  return `[startup] info: detected ${preexisting.join(", ")} at project root. Note: Fabric serves rules from .fabric/rules/ via MCP \u2014 root markdown files are not auto-loaded into the AI context.`;
+}
+function createFabricServer(tracker) {
   const server = new McpServer({
     name: "fabric-context-server",
-    version: "1.7.0"
+    version: "1.8.0-rc.1"
   });
-  registerPlanContext(server);
-  registerRuleSections(server);
+  registerPlanContext(server, tracker);
+  registerRuleSections(server, tracker);
   server.registerResource(
     "bootstrap README",
     AGENTS_MD_RESOURCE_URI,
@@ -208,7 +325,7 @@ function createFabricServer() {
     },
     async (_uri) => {
       const projectRoot = process.env.FABRIC_PROJECT_ROOT ?? process.cwd();
-      const content = await readFile(join(projectRoot, ".fabric", "bootstrap", "README.md"), "utf8");
+      const content = await readFile(join2(projectRoot, ".fabric", "bootstrap", "README.md"), "utf8");
       return {
         contents: [
           {
@@ -223,12 +340,73 @@ function createFabricServer() {
   return server;
 }
 async function startStdioServer() {
-  const server = createFabricServer();
+  const tracker = createInFlightTracker();
+  const projectRoot = resolveProjectRoot();
+  const syncStart = Date.now();
+  const reconcileResult = await reconcileRules(projectRoot, { trigger: "startup" });
+  const syncDurationMs = Date.now() - syncStart;
+  process.stderr.write(
+    `[startup] rule sync: status=${reconcileResult.status}, events=${reconcileResult.events.length}, ${syncDurationMs}ms
+`
+  );
+  const rootMsg = formatPreexistingRootMessage(projectRoot);
+  if (rootMsg !== null) {
+    process.stderr.write(`${rootMsg}
+`);
+  }
+  const server = createFabricServer(tracker);
   const transport = new StdioServerTransport();
   await server.connect(transport);
+  const closeServer = async () => {
+    await server.close();
+  };
+  process.on(
+    "SIGINT",
+    createShutdownHandler({ signal: "SIGINT", tracker, projectRoot, closeServer })
+  );
+  process.on(
+    "SIGTERM",
+    createShutdownHandler({ signal: "SIGTERM", tracker, projectRoot, closeServer })
+  );
+  process.on(
+    "SIGHUP",
+    createShutdownHandler({ signal: "SIGHUP", tracker, projectRoot, closeServer })
+  );
+}
+function createShutdownHandler(deps) {
+  const exit = deps.exit ?? ((code) => process.exit(code));
+  const deadlineMs = deps.drainDeadlineMs ?? 5e3;
+  let invoked = false;
+  return () => {
+    void (async () => {
+      if (invoked) {
+        process.stderr.write(`
+[shutdown] ${deps.signal} repeated \u2014 forcing exit(1)
+`);
+        exit(1);
+        return;
+      }
+      invoked = true;
+      process.stderr.write(
+        `
+[shutdown] ${deps.signal} received \u2014 draining ${deps.tracker.size()} requests (${deadlineMs / 1e3}s deadline)
+`
+      );
+      const result = await deps.tracker.drain(deadlineMs);
+      process.stderr.write(`[shutdown] drained ${result.drained}, timed_out ${result.timed_out}
+`);
+      flushAndSyncEventLedger(deps.projectRoot);
+      process.stderr.write("[shutdown] ledger fsynced; closing server\n");
+      try {
+        await deps.closeServer();
+      } catch {
+      }
+      exit(0);
+    })();
+  };
 }
 async function startHttpServer(options) {
-  const { createFabricHttpApp } = await import("./http-6LFZLHCN.js");
+  const { createFabricHttpApp } = await import("./http-MEFXOG3L.js");
   const { port, projectRoot, host = "127.0.0.1", authToken, dashboardDistPath, dev } = options;
   const app = createFabricHttpApp({ projectRoot, host, authToken, dashboardDistPath, dev });
   return await new Promise((resolveServer, rejectServer) => {
@@ -258,16 +436,27 @@ export {
   EVENT_LEDGER_PATH,
   LEDGER_PATH,
   LEGACY_LEDGER_PATH,
+  ServeLockHeldError,
+  acquireLock,
   buildRuleMeta,
+  checkLockOrThrow,
   computeRuleTestIndex,
   computeRulesBasedAgentsMeta,
   createFabricServer,
+  createInFlightTracker,
+  createShutdownHandler,
   deriveRuleMetaLayer,
   deriveRuleMetaTopologyType,
+  ensureRulesFresh,
+  flushAndSyncEventLedger,
+  formatPreexistingRootMessage,
   getEventLedgerPath,
   getLedgerPath,
   getLegacyLedgerPath,
   isSameRuleTestIndex,
+  readLockState,
+  reconcileRules,
+  releaseLock,
   runDoctorFix,
   runDoctorReport,
   stableStringify,