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

package/dist/index.d.ts

@@ -1,17 +1,42 @@
 import { Server } from 'node:http';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { AuditMode, LedgerEntry, HumanLockEntry } from '@fenglimg/fabric-shared';
+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";
+declare const EVENT_LEDGER_PATH = ".fabric/events.jsonl";
 declare function getLedgerPath(projectRoot: string): string;
 declare function getLegacyLedgerPath(projectRoot: string): string;
+declare function getEventLedgerPath(projectRoot: string): string;
 
 type DoctorStatus = "ok" | "warn" | "error";
+type DoctorIssueKind = "fixable_error" | "manual_error" | "warning" | "info";
 type DoctorCheck = {
     name: string;
     status: DoctorStatus;
     message: string;
+    kind?: DoctorIssueKind;
+    code?: string;
+    fixable?: boolean;
+    actionHint?: string;
+};
+type DoctorIssue = {
+    code: string;
+    name: string;
+    message: string;
+    path?: string;
 };
 type DoctorSummary = {
     target: string;
@@ -24,81 +49,53 @@ type DoctorSummary = {
         path: string;
         reason: string;
     }>;
-    driftCount: number;
-    protectedPathCount: number;
-    protectedPathsIntact: boolean;
-    lastLedgerEntryTs: number | null;
-    lastLedgerEntryAgeMs: number | null;
     metaRevision: string | null;
-    ledgerPath: string;
-    legacyLedgerPath: string;
-    legacyLedgerDetected: boolean;
-    audit: {
-        enabled: boolean;
-        mode: AuditMode;
-        checkedPathCount: number;
-        violationCount: number;
-        windowMs: number;
-    } | null;
+    computedMetaRevision: string | null;
+    ruleCount: number;
+    eventLedgerPath: string;
+    fixableErrorCount: number;
+    manualErrorCount: number;
+    warningCount: number;
+    infoCount: number;
+    targetFiles: Record<string, boolean>;
 };
 type DoctorReport = {
     status: DoctorStatus;
     checks: DoctorCheck[];
+    fixable_errors: DoctorIssue[];
+    manual_errors: DoctorIssue[];
+    warnings: DoctorIssue[];
+    infos: DoctorIssue[];
     summary: DoctorSummary;
-    audit: DoctorAuditReport | null;
 };
 type DoctorFixReport = {
     changed: boolean;
-    migratedLedger: boolean;
+    fixed: DoctorIssue[];
+    remaining_manual_errors: DoctorIssue[];
+    warnings: DoctorIssue[];
     message: string;
     report: DoctorReport;
 };
-type DoctorAuditViolation = {
-    editTs: number;
-    entryId: string;
-    intent: string;
-    lastRuleAccessTs: number | null;
-    path: string;
-};
-type DoctorAuditReport = {
-    mode: AuditMode;
-    skipped: boolean;
-    windowMs: number;
-    checkedPathCount: number;
-    violationCount: number;
-    violations: DoctorAuditViolation[];
-};
 declare function runDoctorReport(target: string): Promise<DoctorReport>;
 declare function runDoctorFix(target: string): Promise<DoctorFixReport>;
-declare function runDoctorAuditReport(target: string, options?: {
-    force?: boolean;
-    mode?: AuditMode;
-    windowMs?: number;
-}): Promise<DoctorAuditReport>;
-
-type StoredLedgerEntry = LedgerEntry & {
-    id: string;
-};
-
-type HumanLockStatus = HumanLockEntry & {
-    drift: boolean;
-    current_hash: string;
-};
-declare function readHumanLock(projectRoot: string): Promise<HumanLockStatus[]>;
-declare function readHumanLockEntry(projectRoot: string, file: string): Promise<HumanLockStatus | null>;
 
-type ApproveHumanLockInput = {
-    file: string;
-    start_line: number;
-    end_line: number;
-    new_hash: string;
+type RuleMetaBuildSource = "doctor_fix" | "sync_meta";
+type RuleMetaBuildResult = {
+    meta: AgentsMeta;
+    ruleTestIndex: RuleTestIndex;
+    changed: boolean;
 };
-type ApproveHumanLockResult = {
-    updated: boolean;
-    entry: HumanLockStatus;
-    ledger_entry?: StoredLedgerEntry;
+type WriteRuleMetaOptions = {
+    source: RuleMetaBuildSource;
 };
-declare function approveHumanLock(projectRoot: string, input: ApproveHumanLockInput): Promise<ApproveHumanLockResult>;
+declare function buildRuleMeta(projectRootInput: string): Promise<RuleMetaBuildResult>;
+declare function writeRuleMeta(projectRootInput: string, options: WriteRuleMetaOptions): Promise<RuleMetaBuildResult>;
+declare function computeRulesBasedAgentsMeta(projectRootInput: string, existingMeta?: AgentsMeta): Promise<AgentsMeta>;
+declare function computeRuleTestIndex(projectRootInput: string, computedMeta: AgentsMeta, previousIndex?: RuleTestIndex): Promise<RuleTestIndex>;
+declare function deriveRuleMetaLayer(relativePath: string): AgentsLayer;
+declare function deriveRuleMetaTopologyType(relativePath: string): AgentsTopologyType;
+declare function isSameRuleTestIndex(left: RuleTestIndex, right: RuleTestIndex): boolean;
+declare function stableStringify(value: unknown): string;
 
 /**
  * Shared constants used across the server package.
@@ -106,8 +103,137 @@ declare function approveHumanLock(projectRoot: string, input: ApproveHumanLockIn
 /** 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;
@@ -117,4 +243,4 @@ declare function startHttpServer(options: {
     dev?: boolean;
 }): Promise<Server>;
 
-export { AGENTS_MD_RESOURCE_URI, type ApproveHumanLockInput, type ApproveHumanLockResult, type DoctorAuditReport, type DoctorFixReport, type DoctorReport, type HumanLockStatus, LEDGER_PATH, LEGACY_LEDGER_PATH, approveHumanLock, createFabricServer, getLedgerPath, getLegacyLedgerPath, readHumanLock, readHumanLockEntry, runDoctorAuditReport, runDoctorFix, runDoctorReport, startHttpServer, startStdioServer };
+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 };