@fenglimg/fabric-server 1.0.0 → 1.2.0

package/dist/chunk-U3IQH5H6.js

@@ -0,0 +1,851 @@
+// src/services/doctor.ts
+import { createHash as createHash2 } from "crypto";
+import { existsSync, readFileSync as readFileSync2, readdirSync, statSync } from "fs";
+import { readFile as readFile4 } from "fs/promises";
+import { isAbsolute as isAbsolute2, join as join5, posix as posix2, resolve as resolve3 } from "path";
+import { forensicReportSchema } from "@fenglimg/fabric-shared";
+import { detectFramework } from "@fenglimg/fabric-shared/node";
+
+// src/meta-reader.ts
+import { readFileSync } from "fs";
+import { join } from "path";
+import { agentsMetaSchema } from "@fenglimg/fabric-shared";
+import { agentsMetaNodeSchema, agentsMetaSchema as agentsMetaSchema2 } from "@fenglimg/fabric-shared";
+var AgentsMetaFileMissingError = class extends Error {
+  constructor(metaPath) {
+    super(`Fabric agents metadata file is missing: ${metaPath}`);
+    this.metaPath = metaPath;
+    this.name = "AgentsMetaFileMissingError";
+  }
+  metaPath;
+  code = "FABRIC_META_MISSING";
+};
+var AgentsMetaInvalidError = class extends Error {
+  constructor(metaPath, cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    super(`Fabric agents metadata file is invalid: ${metaPath}. ${detail}`);
+    this.metaPath = metaPath;
+    this.name = "AgentsMetaInvalidError";
+  }
+  metaPath;
+  code = "FABRIC_META_INVALID";
+};
+function getAgentsMetaPath(projectRoot) {
+  return join(projectRoot, ".fabric", "agents.meta.json");
+}
+function resolveProjectRoot() {
+  return process.env.FABRIC_PROJECT_ROOT ?? process.cwd();
+}
+function readAgentsMeta(projectRoot) {
+  const metaPath = getAgentsMetaPath(projectRoot);
+  let raw;
+  try {
+    raw = readFileSync(metaPath, "utf8");
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      throw new AgentsMetaFileMissingError(metaPath);
+    }
+    throw error;
+  }
+  try {
+    return agentsMetaSchema.parse(JSON.parse(raw));
+  } catch (error) {
+    throw new AgentsMetaInvalidError(metaPath, error);
+  }
+}
+
+// src/services/audit-log.ts
+import { appendFile, mkdir, readFile } from "fs/promises";
+import { isAbsolute, join as join2, posix, relative, resolve as resolve2 } from "path";
+
+// src/services/_shared.ts
+import { resolve, sep } from "path";
+import { createHash } from "crypto";
+import { rename, writeFile } from "fs/promises";
+var FABRIC_DIR = ".fabric";
+var HUMAN_LOCK_FILE = "human-lock.json";
+var LEDGER_FILE = ".intent-ledger.jsonl";
+async function atomicWriteText(path, content) {
+  const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+  await writeFile(tempPath, content, "utf8");
+  await rename(tempPath, path);
+}
+function sha256(content) {
+  return `sha256:${createHash("sha256").update(content).digest("hex")}`;
+}
+function isNodeError(error) {
+  return error instanceof Error;
+}
+function assertPathWithinProjectRoot(projectRoot, file) {
+  const normalizedProjectRoot = resolve(projectRoot);
+  const absolutePath = resolve(normalizedProjectRoot, file);
+  const rootPrefix = normalizedProjectRoot.endsWith(sep) ? normalizedProjectRoot : `${normalizedProjectRoot}${sep}`;
+  if (!absolutePath.startsWith(rootPrefix)) {
+    throw new Error(`Path escapes project root: ${file}`);
+  }
+  return absolutePath;
+}
+
+// src/services/audit-log.ts
+var AUDIT_LOG_FILE = `${FABRIC_DIR}/audit.jsonl`;
+var DEFAULT_AUDIT_WINDOW_MS = 5 * 60 * 1e3;
+async function appendGetRulesAuditEvent(projectRoot, input) {
+  const entry = {
+    kind: "audit-event",
+    event: "get_rules",
+    ts: input.ts ?? Date.now(),
+    path: normalizeAuditPath(projectRoot, input.path),
+    client_hash: input.client_hash
+  };
+  await appendAuditLogEntries(projectRoot, [entry]);
+  return entry;
+}
+async function appendEditIntentAuditEvents(projectRoot, input) {
+  const ts = input.ts ?? Date.now();
+  const windowMs = input.window_ms ?? DEFAULT_AUDIT_WINDOW_MS;
+  const getRulesEntries = (await readAuditLog(projectRoot)).filter(isGetRulesAuditEntry);
+  const entries = input.affected_paths.map((affectedPath) => {
+    const path = normalizeAuditPath(projectRoot, affectedPath);
+    const matchedGetRules = findPrecedingGetRulesEvent(getRulesEntries, path, ts, windowMs);
+    return {
+      kind: "audit-event",
+      event: "edit_intent",
+      ts,
+      path,
+      compliant: matchedGetRules !== null,
+      intent: input.intent,
+      ledger_entry_id: input.ledger_entry_id,
+      matched_get_rules_ts: matchedGetRules?.ts ?? null,
+      window_ms: windowMs
+    };
+  });
+  if (entries.length === 0) {
+    return [];
+  }
+  await appendAuditLogEntries(projectRoot, entries);
+  return entries;
+}
+async function readAuditLog(projectRoot) {
+  const auditPath = join2(projectRoot, AUDIT_LOG_FILE);
+  let raw;
+  try {
+    raw = await readFile(auditPath, "utf8");
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+  return raw.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0).map(parseAuditLogLine).filter((entry) => entry !== null);
+}
+function findPrecedingGetRulesEvent(entries, path, ts, windowMs) {
+  let matched = null;
+  for (const entry of entries) {
+    if (entry.path !== path) {
+      continue;
+    }
+    if (entry.ts > ts) {
+      continue;
+    }
+    if (ts - entry.ts > windowMs) {
+      continue;
+    }
+    if (matched === null || entry.ts > matched.ts) {
+      matched = entry;
+    }
+  }
+  return matched;
+}
+function normalizeAuditPath(projectRoot, value) {
+  const normalizedProjectRoot = resolve2(projectRoot);
+  const candidate = isAbsolute(value) ? resolve2(value) : resolve2(normalizedProjectRoot, value);
+  const relativePath = relative(normalizedProjectRoot, candidate);
+  if (relativePath.length > 0 && relativePath !== "." && !relativePath.startsWith("..") && !isAbsolute(relativePath)) {
+    return posix.normalize(relativePath.split("\\").join("/"));
+  }
+  return posix.normalize(value.replaceAll("\\", "/"));
+}
+function isGetRulesAuditEntry(entry) {
+  return entry.event === "get_rules";
+}
+async function appendAuditLogEntries(projectRoot, entries) {
+  const auditPath = join2(projectRoot, AUDIT_LOG_FILE);
+  const auditDir = join2(projectRoot, FABRIC_DIR);
+  await mkdir(auditDir, { recursive: true });
+  await appendFile(auditPath, `${entries.map((entry) => JSON.stringify(entry)).join("\n")}
+`, "utf8");
+}
+function parseAuditLogLine(line) {
+  try {
+    const parsed = JSON.parse(line);
+    if (parsed.kind !== "audit-event" || typeof parsed.ts !== "number" || typeof parsed.path !== "string") {
+      return null;
+    }
+    if (parsed.event === "get_rules") {
+      return {
+        kind: "audit-event",
+        event: "get_rules",
+        ts: parsed.ts,
+        path: parsed.path,
+        client_hash: typeof parsed.client_hash === "string" ? parsed.client_hash : void 0
+      };
+    }
+    if (parsed.event === "edit_intent" && typeof parsed.compliant === "boolean" && typeof parsed.intent === "string" && typeof parsed.ledger_entry_id === "string" && (typeof parsed.matched_get_rules_ts === "number" || parsed.matched_get_rules_ts === null) && typeof parsed.window_ms === "number") {
+      return {
+        kind: "audit-event",
+        event: "edit_intent",
+        ts: parsed.ts,
+        path: parsed.path,
+        compliant: parsed.compliant,
+        intent: parsed.intent,
+        ledger_entry_id: parsed.ledger_entry_id,
+        matched_get_rules_ts: parsed.matched_get_rules_ts,
+        window_ms: parsed.window_ms
+      };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// src/services/read-human-lock.ts
+import { readFile as readFile2 } from "fs/promises";
+import { join as join3 } from "path";
+import { humanLockEntrySchema } from "@fenglimg/fabric-shared";
+async function readHumanLock(projectRoot) {
+  const document = await readHumanLockDocument(projectRoot);
+  return await Promise.all(
+    document.locked.map(async (entry) => {
+      const currentHash = await hashHumanLockedContent(projectRoot, entry);
+      return {
+        ...entry,
+        drift: currentHash !== entry.hash,
+        current_hash: currentHash
+      };
+    })
+  );
+}
+async function readHumanLockEntry(projectRoot, file) {
+  const entries = await readHumanLock(projectRoot);
+  return entries.find((entry) => entry.file === file) ?? null;
+}
+async function readHumanLockDocument(projectRoot) {
+  const humanLockPath = join3(projectRoot, FABRIC_DIR, HUMAN_LOCK_FILE);
+  const raw = await readFile2(humanLockPath, "utf8");
+  const parsed = JSON.parse(raw);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`Fabric human lock file is invalid: ${humanLockPath}`);
+  }
+  const rawObject = parsed;
+  const lockedResult = humanLockEntrySchema.array().safeParse(rawObject.locked ?? []);
+  if (!lockedResult.success) {
+    throw new Error(`Fabric human lock file is invalid: ${humanLockPath}`);
+  }
+  return {
+    path: humanLockPath,
+    rawObject,
+    locked: lockedResult.data
+  };
+}
+async function hashHumanLockedContent(projectRoot, entry) {
+  const targetPath = assertPathWithinProjectRoot(projectRoot, entry.file);
+  let content;
+  try {
+    content = await readFile2(targetPath, "utf8");
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      return "missing";
+    }
+    throw error;
+  }
+  const lines = content.split(/\r?\n/);
+  const slice = lines.slice(Math.max(entry.start_line - 1, 0), Math.max(entry.end_line, 0)).join("\n");
+  return sha256(slice);
+}
+
+// src/services/read-ledger.ts
+import { randomUUID } from "crypto";
+import { appendFile as appendFile2, readFile as readFile3 } from "fs/promises";
+import { join as join4 } from "path";
+import { ledgerEntrySchema } from "@fenglimg/fabric-shared";
+async function readLedger(projectRoot, options = {}) {
+  const ledgerPath = join4(projectRoot, LEDGER_FILE);
+  let raw;
+  try {
+    raw = await readFile3(ledgerPath, "utf8");
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+  return raw.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0).map((line, index) => parseLedgerLine(line, index)).filter((entry) => entry !== null).filter((entry) => options.source === void 0 || entry.source === options.source).filter((entry) => options.since === void 0 || entry.ts >= options.since);
+}
+async function appendLedgerEntry(projectRoot, entry) {
+  const ledgerPath = join4(projectRoot, LEDGER_FILE);
+  const nextEntry = ledgerEntrySchema.parse({
+    ...entry,
+    id: entry.id ?? `ledger:${randomUUID()}`
+  });
+  await appendFile2(ledgerPath, `${JSON.stringify(nextEntry)}
+`, "utf8");
+  return nextEntry;
+}
+function parseLedgerLine(line, index) {
+  try {
+    const parsed = JSON.parse(line);
+    if (parsed.kind === "mcp-event") {
+      return null;
+    }
+    const result = ledgerEntrySchema.safeParse(parsed);
+    if (!result.success) {
+      return null;
+    }
+    return {
+      ...result.data,
+      id: result.data.id ?? createDerivedId(index, line)
+    };
+  } catch {
+    return null;
+  }
+}
+function createDerivedId(index, line) {
+  return `ledger:${index + 1}:${sha256(line).slice("sha256:".length)}`;
+}
+
+// src/services/doctor.ts
+var SCRIPT_EXTENSIONS = /* @__PURE__ */ new Set([".js", ".jsx", ".ts", ".tsx"]);
+var IGNORED_DIRECTORIES = /* @__PURE__ */ new Set([
+  ".fabric",
+  ".git",
+  ".next",
+  ".turbo",
+  "Library",
+  "Temp",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules"
+]);
+var LEDGER_WARN_AFTER_MS = 3 * 24 * 60 * 60 * 1e3;
+var LEDGER_ERROR_AFTER_MS = 7 * 24 * 60 * 60 * 1e3;
+async function runDoctorReport(target) {
+  const projectRoot = normalizeTarget(target);
+  const framework = detectFramework(projectRoot);
+  const entryPoints = collectEntryPoints(projectRoot);
+  const [savedForensic, metaSnapshot, humanLockSnapshot, ledgerSnapshot, auditReport] = await Promise.all([
+    readSavedForensic(projectRoot),
+    inspectMetaRevision(projectRoot),
+    inspectHumanLock(projectRoot),
+    inspectLedger(projectRoot),
+    runDoctorAuditReport(projectRoot)
+  ]);
+  const checks = [
+    createForensicCheck(savedForensic, framework, entryPoints),
+    createFrameworkCheck(savedForensic, framework, entryPoints),
+    createMetaRevisionCheck(metaSnapshot),
+    createProtectedPathsCheck(humanLockSnapshot),
+    createLedgerCheck(ledgerSnapshot)
+  ];
+  if (!auditReport.skipped) {
+    checks.push(createAuditCheck(auditReport));
+  }
+  return {
+    status: reduceStatus(checks.map((check) => check.status)),
+    checks,
+    summary: {
+      target: projectRoot,
+      framework: {
+        kind: framework.kind,
+        version: framework.version,
+        subkind: framework.subkind
+      },
+      entryPoints,
+      driftCount: humanLockSnapshot.driftCount,
+      protectedPathCount: humanLockSnapshot.protectedPathCount,
+      protectedPathsIntact: humanLockSnapshot.present && humanLockSnapshot.driftCount === 0,
+      lastLedgerEntryTs: ledgerSnapshot.lastEntryTs,
+      lastLedgerEntryAgeMs: ledgerSnapshot.lastEntryAgeMs,
+      metaRevision: metaSnapshot.revision,
+      audit: auditReport.skipped ? null : {
+        enabled: true,
+        mode: auditReport.mode,
+        checkedPathCount: auditReport.checkedPathCount,
+        violationCount: auditReport.violationCount,
+        windowMs: auditReport.windowMs
+      }
+    },
+    audit: auditReport.skipped ? null : auditReport
+  };
+}
+async function runDoctorAuditReport(target, options = {}) {
+  const projectRoot = normalizeTarget(target);
+  const mode = options.mode ?? readDoctorAuditMode(projectRoot);
+  const windowMs = options.windowMs ?? DEFAULT_AUDIT_WINDOW_MS;
+  if (mode === "off" && options.force !== true) {
+    return {
+      mode,
+      skipped: true,
+      windowMs,
+      checkedPathCount: 0,
+      violationCount: 0,
+      violations: []
+    };
+  }
+  const [ledgerEntries, auditEntries] = await Promise.all([
+    readLedger(projectRoot, { source: "ai" }),
+    readAuditLog(projectRoot)
+  ]);
+  const getRulesEntries = auditEntries.filter(
+    (entry) => entry.event === "get_rules"
+  );
+  const { checkedPathCount, violations } = collectAuditViolations(
+    projectRoot,
+    ledgerEntries,
+    getRulesEntries,
+    windowMs
+  );
+  return {
+    mode,
+    skipped: false,
+    windowMs,
+    checkedPathCount,
+    violationCount: violations.length,
+    violations
+  };
+}
+function createForensicCheck(forensic, framework, entryPoints) {
+  if (!forensic.present) {
+    return {
+      name: "Forensic snapshot",
+      status: "error",
+      message: `${forensic.reason} Live scan detects ${formatFramework(framework)} with ${entryPoints.length} entry point${entryPoints.length === 1 ? "" : "s"}.`
+    };
+  }
+  return {
+    name: "Forensic snapshot",
+    status: "ok",
+    message: `Loaded .fabric/forensic.json for ${formatFramework(forensic.report.framework)} with ${forensic.report.entry_points.length} recorded entry point${forensic.report.entry_points.length === 1 ? "" : "s"}.`
+  };
+}
+function createFrameworkCheck(forensic, framework, entryPoints) {
+  if (framework.kind === "unknown") {
+    return {
+      name: "Framework fingerprint",
+      status: "warn",
+      message: "Unable to identify the project framework from current files."
+    };
+  }
+  if (!forensic.present) {
+    return {
+      name: "Framework fingerprint",
+      status: "warn",
+      message: `Live detection sees ${formatFramework(framework)} and ${entryPoints.length} entry point${entryPoints.length === 1 ? "" : "s"}, but no forensic baseline exists yet.`
+    };
+  }
+  const matches = forensic.report.framework.kind === framework.kind && forensic.report.framework.version === framework.version && forensic.report.framework.subkind === framework.subkind;
+  if (!matches) {
+    return {
+      name: "Framework fingerprint",
+      status: "warn",
+      message: `Forensic baseline says ${formatFramework(forensic.report.framework)}; live scan says ${formatFramework(framework)}.`
+    };
+  }
+  return {
+    name: "Framework fingerprint",
+    status: "ok",
+    message: `Framework baseline matches live scan: ${formatFramework(framework)} \xB7 ${entryPoints.length} current entry point${entryPoints.length === 1 ? "" : "s"}.`
+  };
+}
+function createMetaRevisionCheck(snapshot) {
+  if (!snapshot.present) {
+    return {
+      name: "Meta revision",
+      status: "error",
+      message: snapshot.unexpectedError ?? "agents.meta.json is missing."
+    };
+  }
+  if (snapshot.driftCount > 0 || snapshot.missingFiles.length > 0) {
+    const parts = [
+      `${snapshot.driftCount} tracked AGENTS file drift`,
+      snapshot.missingFiles.length > 0 ? `${snapshot.missingFiles.length} missing tracked file` : null
+    ].filter((part) => part !== null);
+    return {
+      name: "Meta revision",
+      status: "error",
+      message: `agents.meta.json revision ${snapshot.revision} is stale: ${parts.join(" \xB7 ")}.`
+    };
+  }
+  return {
+    name: "Meta revision",
+    status: "ok",
+    message: `agents.meta.json revision ${snapshot.revision} matches ${snapshot.nodeCount} tracked AGENTS file${snapshot.nodeCount === 1 ? "" : "s"}.`
+  };
+}
+function createProtectedPathsCheck(snapshot) {
+  if (!snapshot.present) {
+    return {
+      name: "Protected paths",
+      status: "warn",
+      message: snapshot.reason
+    };
+  }
+  if (snapshot.driftCount > 0) {
+    return {
+      name: "Protected paths",
+      status: "warn",
+      message: `${snapshot.driftCount} of ${snapshot.protectedPathCount} protected path${snapshot.protectedPathCount === 1 ? "" : "s"} drifted from approved hashes.`
+    };
+  }
+  return {
+    name: "Protected paths",
+    status: "ok",
+    message: `${snapshot.protectedPathCount} protected path${snapshot.protectedPathCount === 1 ? "" : "s"} intact with zero hash drift.`
+  };
+}
+function createLedgerCheck(snapshot) {
+  if (snapshot.lastEntryTs === null || snapshot.lastEntryAgeMs === null) {
+    return {
+      name: "Intent ledger",
+      status: "warn",
+      message: "No ledger entries recorded yet."
+    };
+  }
+  if (snapshot.lastEntryAgeMs >= LEDGER_ERROR_AFTER_MS) {
+    return {
+      name: "Intent ledger",
+      status: "error",
+      message: `Last ledger entry is ${formatAge(snapshot.lastEntryAgeMs)} old (${new Date(snapshot.lastEntryTs).toISOString()}).`
+    };
+  }
+  if (snapshot.lastEntryAgeMs >= LEDGER_WARN_AFTER_MS) {
+    return {
+      name: "Intent ledger",
+      status: "warn",
+      message: `Last ledger entry is ${formatAge(snapshot.lastEntryAgeMs)} old (${new Date(snapshot.lastEntryTs).toISOString()}).`
+    };
+  }
+  return {
+    name: "Intent ledger",
+    status: "ok",
+    message: `Last ledger entry is ${formatAge(snapshot.lastEntryAgeMs)} old (${snapshot.count} total entr${snapshot.count === 1 ? "y" : "ies"}).`
+  };
+}
+function createAuditCheck(report) {
+  if (report.checkedPathCount === 0) {
+    return {
+      name: "Rules fetch audit",
+      status: "warn",
+      message: "No AI edit intents recorded yet for compliance audit."
+    };
+  }
+  if (report.violationCount > 0) {
+    return {
+      name: "Rules fetch audit",
+      status: report.mode === "strict" ? "error" : "warn",
+      message: `${report.violationCount} edit path${report.violationCount === 1 ? "" : "s"} lack a preceding fab_get_rules call within ${formatDuration(report.windowMs)}.`
+    };
+  }
+  return {
+    name: "Rules fetch audit",
+    status: "ok",
+    message: `All ${report.checkedPathCount} audited edit path${report.checkedPathCount === 1 ? "" : "s"} have a preceding fab_get_rules call within ${formatDuration(report.windowMs)}.`
+  };
+}
+async function readSavedForensic(projectRoot) {
+  const forensicPath = join5(projectRoot, ".fabric", "forensic.json");
+  try {
+    const raw = await readFile4(forensicPath, "utf8");
+    const parsed = forensicReportSchema.safeParse(JSON.parse(raw));
+    if (!parsed.success) {
+      return {
+        present: false,
+        reason: "forensic.json is invalid."
+      };
+    }
+    return {
+      present: true,
+      report: parsed.data
+    };
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return {
+        present: false,
+        reason: ".fabric/forensic.json is missing."
+      };
+    }
+    return {
+      present: false,
+      reason: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+async function inspectMetaRevision(projectRoot) {
+  try {
+    const meta = readAgentsMeta(projectRoot);
+    const entries = Object.entries(meta.nodes).sort(([left], [right]) => left.localeCompare(right));
+    const missingFiles = [];
+    let driftCount = 0;
+    const revisionSource = entries.map(([, node]) => {
+      const absolutePath = join5(projectRoot, node.file);
+      if (!existsSync(absolutePath)) {
+        missingFiles.push(node.file);
+        driftCount += 1;
+        return "missing";
+      }
+      const actualHash = sha2562(readFileSync2(absolutePath, "utf8"));
+      if (actualHash !== node.hash) {
+        driftCount += 1;
+      }
+      return actualHash;
+    }).join("");
+    const revision = sha2562(revisionSource);
+    return {
+      present: true,
+      revision: meta.revision,
+      nodeCount: entries.length,
+      driftCount: revision === meta.revision ? driftCount : Math.max(driftCount, 1),
+      missingFiles
+    };
+  } catch (error) {
+    return {
+      present: false,
+      revision: null,
+      nodeCount: 0,
+      driftCount: 0,
+      missingFiles: [],
+      unexpectedError: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+async function inspectHumanLock(projectRoot) {
+  try {
+    const entries = await readHumanLock(projectRoot);
+    return {
+      present: true,
+      driftCount: entries.filter((entry) => entry.drift).length,
+      protectedPathCount: entries.length
+    };
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return {
+        present: false,
+        driftCount: 0,
+        protectedPathCount: 0,
+        reason: ".fabric/human-lock.json is missing; no protected paths are being tracked."
+      };
+    }
+    return {
+      present: false,
+      driftCount: 0,
+      protectedPathCount: 0,
+      reason: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+async function inspectLedger(projectRoot) {
+  const entries = await readLedger(projectRoot);
+  const lastEntry = entries.reduce(
+    (latest, entry) => latest === null || entry.ts > latest ? entry.ts : latest,
+    null
+  );
+  return {
+    count: entries.length,
+    lastEntryTs: lastEntry,
+    lastEntryAgeMs: lastEntry === null ? null : Math.max(Date.now() - lastEntry, 0)
+  };
+}
+function collectAuditViolations(projectRoot, ledgerEntries, getRulesEntries, windowMs) {
+  let checkedPathCount = 0;
+  const violations = [];
+  for (const entry of ledgerEntries) {
+    for (const affectedPath of entry.affected_paths) {
+      const normalizedPath = normalizeAuditPath(projectRoot, affectedPath);
+      const matched = findPrecedingGetRulesEvent(getRulesEntries, normalizedPath, entry.ts, windowMs);
+      checkedPathCount += 1;
+      if (matched !== null) {
+        continue;
+      }
+      violations.push({
+        editTs: entry.ts,
+        entryId: entry.id,
+        intent: entry.intent,
+        lastGetRulesTs: findLatestGetRulesTs(getRulesEntries, normalizedPath, entry.ts),
+        path: normalizedPath
+      });
+    }
+  }
+  return {
+    checkedPathCount,
+    violations
+  };
+}
+function findLatestGetRulesTs(entries, path, ts) {
+  let latest = null;
+  for (const entry of entries) {
+    if (entry.path !== path || entry.ts > ts) {
+      continue;
+    }
+    latest = latest === null || entry.ts > latest ? entry.ts : latest;
+  }
+  return latest;
+}
+function readDoctorAuditMode(projectRoot) {
+  const configPath = join5(projectRoot, "fabric.config.json");
+  try {
+    const parsed = JSON.parse(readFileSync2(configPath, "utf8"));
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return "off";
+    }
+    const configuredMode = readAuditModeValue(parsed.auditMode) ?? readAuditModeValue(parsed.audit_mode);
+    return configuredMode ?? "off";
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return "off";
+    }
+    return "off";
+  }
+}
+function normalizeTarget(targetInput) {
+  return isAbsolute2(targetInput) ? targetInput : resolve3(process.cwd(), targetInput);
+}
+function collectEntryPoints(root) {
+  if (!existsSync(root) || !statSync(root).isDirectory()) {
+    return [];
+  }
+  const entries = [];
+  const stack = [root];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (current === void 0) {
+      continue;
+    }
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      const absolutePath = join5(current, entry.name);
+      const relativePath = posix2.normalize(absolutePath.slice(root.length + 1).split("\\").join("/"));
+      if (relativePath.length === 0) {
+        continue;
+      }
+      if (entry.isDirectory()) {
+        if (IGNORED_DIRECTORIES.has(entry.name)) {
+          continue;
+        }
+        stack.push(absolutePath);
+        continue;
+      }
+      if (!entry.isFile()) {
+        continue;
+      }
+      const reason = getEntryPointReason(relativePath);
+      if (reason !== null) {
+        entries.push({
+          path: relativePath,
+          reason
+        });
+      }
+    }
+  }
+  return entries.sort((left, right) => left.path.localeCompare(right.path));
+}
+function getEntryPointReason(relativePath) {
+  const extension = relativePath.slice(relativePath.lastIndexOf("."));
+  if (!SCRIPT_EXTENSIONS.has(extension)) {
+    return null;
+  }
+  const directory = posix2.dirname(relativePath);
+  const fileName = posix2.basename(relativePath);
+  const fileBase = fileName.slice(0, Math.max(fileName.lastIndexOf("."), 0));
+  if (directory === "assets/scripts" || directory === "scripts") {
+    return "top-level script";
+  }
+  if (directory === "src" && /^(App|app|index|main)$/.test(fileBase)) {
+    return "application entry";
+  }
+  if ((directory === "app" || directory.startsWith("app/")) && /^(layout|page|route)$/.test(fileBase)) {
+    return "next app route";
+  }
+  if ((directory === "pages" || directory.startsWith("pages/")) && fileName !== "_app.d.ts") {
+    return "next page route";
+  }
+  return null;
+}
+function reduceStatus(statuses) {
+  if (statuses.includes("error")) {
+    return "error";
+  }
+  if (statuses.includes("warn")) {
+    return "warn";
+  }
+  return "ok";
+}
+function formatFramework(framework) {
+  const pieces = [framework.kind, framework.version !== "unknown" ? framework.version : null, framework.subkind].filter((piece) => piece !== null && piece !== "unknown");
+  return pieces.length > 0 ? pieces.join(" \xB7 ") : "unknown";
+}
+function formatAge(ageMs) {
+  const seconds = Math.floor(ageMs / 1e3);
+  if (seconds < 60) {
+    return `${seconds}s`;
+  }
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) {
+    return `${minutes}m`;
+  }
+  const hours = Math.floor(minutes / 60);
+  if (hours < 48) {
+    return `${hours}h`;
+  }
+  const days = Math.floor(hours / 24);
+  if (days < 14) {
+    return `${days}d`;
+  }
+  return `${Math.floor(days / 7)}w`;
+}
+function formatDuration(durationMs) {
+  const minutes = Math.floor(durationMs / (60 * 1e3));
+  if (minutes < 1) {
+    return `${Math.max(Math.floor(durationMs / 1e3), 1)}s`;
+  }
+  if (minutes < 60) {
+    return `${minutes}m`;
+  }
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) {
+    return `${hours}h`;
+  }
+  return `${Math.floor(hours / 24)}d`;
+}
+function readAuditModeValue(value) {
+  if (value === "strict" || value === "warn" || value === "off") {
+    return value;
+  }
+  return null;
+}
+function sha2562(content) {
+  return `sha256:${createHash2("sha256").update(content).digest("hex")}`;
+}
+function isMissingFileError(error) {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+
+export {
+  AgentsMetaFileMissingError,
+  AgentsMetaInvalidError,
+  resolveProjectRoot,
+  readAgentsMeta,
+  FABRIC_DIR,
+  atomicWriteText,
+  sha256,
+  assertPathWithinProjectRoot,
+  appendGetRulesAuditEvent,
+  appendEditIntentAuditEvents,
+  readLedger,
+  appendLedgerEntry,
+  readHumanLock,
+  readHumanLockEntry,
+  readHumanLockDocument,
+  hashHumanLockedContent,
+  runDoctorReport,
+  runDoctorAuditReport
+};