codetrellis 0.0.0-stage → 0.2.0

package/src/backend/services/system-docs-service.js

@@ -0,0 +1,701 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var system_docs_service_exports = {};
+__export(system_docs_service_exports, {
+  checkAllDocsFreshness: () => checkAllDocsFreshness,
+  createSystemDoc: () => createSystemDoc,
+  deleteSystemDoc: () => deleteSystemDoc,
+  findDocsByReferencedFile: () => findDocsByReferencedFile,
+  getFreshness: () => getFreshness,
+  getSystemDoc: () => getSystemDoc,
+  getSystemDocBySlug: () => getSystemDocBySlug,
+  indexProjectDocs: () => indexProjectDocs,
+  listSystemDocs: () => listSystemDocs,
+  searchSystemDocs: () => searchSystemDocs,
+  startSystemDocsWatcher: () => startSystemDocsWatcher,
+  stopSystemDocsWatcher: () => stopSystemDocsWatcher,
+  updateSystemDoc: () => updateSystemDoc,
+  verifySystemDoc: () => verifySystemDoc
+});
+module.exports = __toCommonJS(system_docs_service_exports);
+var _lazy____server = __toESM(require("../server"));
+var import_confined_fs = require("./confined-fs");
+var import_node_fs = __toESM(require("node:fs"));
+var import_node_path = __toESM(require("node:path"));
+var import_node_crypto = require("node:crypto");
+var import_node_child_process = require("node:child_process");
+var import_chokidar = __toESM(require("chokidar"));
+var import_yaml = require("yaml");
+var import_database = require("./database");
+var import_persistence = require("./persistence");
+var import_self_write_tracker = require("./self-write-tracker");
+var import_checkout_identity = require("./checkout-identity");
+const SAFE_SLUG = /^[a-z0-9][a-z0-9-]{0,127}$/i;
+function assertSafeSlug(slug) {
+  if (typeof slug !== "string" || !SAFE_SLUG.test(slug)) {
+    throw new import_confined_fs.ConfinementError(
+      `Invalid system-doc slug "${String(slug).slice(0, 64)}" \u2014 slugs may contain only letters, digits and hyphens.`
+    );
+  }
+  return slug;
+}
+const SYSTEM_DOCS_DIR_SEGMENT = ".codetrellis/docs";
+function listSystemDocs(projectPath) {
+  const db = (0, import_database.getDb)();
+  const result = db.exec(
+    `SELECT uid, slug, title, owner, tags, updated_at, last_verified_at, captured_against_commit
+       FROM system_docs WHERE project_path = ? ORDER BY updated_at DESC`,
+    [normalisePath(projectPath)]
+  );
+  if (!result[0]) return [];
+  return result[0].values.map((r) => ({
+    uid: r[0],
+    slug: r[1],
+    title: r[2],
+    owner: r[3] ?? null,
+    tags: safeParseJsonArray(r[4]),
+    updatedAt: r[5],
+    lastVerifiedAt: r[6] ?? null,
+    capturedAgainstCommit: r[7] ?? null
+  }));
+}
+function searchSystemDocs(projectPath, query) {
+  if (!query.trim()) return listSystemDocs(projectPath);
+  const db = (0, import_database.getDb)();
+  const like = `%${query.toLowerCase()}%`;
+  const result = db.exec(
+    `SELECT uid, slug, title, owner, tags, updated_at, last_verified_at, captured_against_commit
+       FROM system_docs
+       WHERE project_path = ?
+         AND (LOWER(title) LIKE ? OR LOWER(body) LIKE ?)
+       ORDER BY updated_at DESC`,
+    [normalisePath(projectPath), like, like]
+  );
+  if (!result[0]) return [];
+  return result[0].values.map((r) => ({
+    uid: r[0],
+    slug: r[1],
+    title: r[2],
+    owner: r[3] ?? null,
+    tags: safeParseJsonArray(r[4]),
+    updatedAt: r[5],
+    lastVerifiedAt: r[6] ?? null,
+    capturedAgainstCommit: r[7] ?? null
+  }));
+}
+function getSystemDoc(uid) {
+  const db = (0, import_database.getDb)();
+  const result = db.exec(`SELECT ${ALL_COLUMNS} FROM system_docs WHERE uid = ?`, [uid]);
+  if (!result[0]?.values[0]) return null;
+  return rowToDoc(result[0].values[0]);
+}
+function getSystemDocBySlug(projectPath, slug) {
+  const db = (0, import_database.getDb)();
+  const result = db.exec(
+    `SELECT ${ALL_COLUMNS} FROM system_docs WHERE project_path = ? AND slug = ?`,
+    [normalisePath(projectPath), slug]
+  );
+  if (!result[0]?.values[0]) return null;
+  return rowToDoc(result[0].values[0]);
+}
+function createSystemDoc(input) {
+  const projectPath = normalisePath(input.projectPath);
+  const uid = (0, import_node_crypto.randomUUID)();
+  const now = Date.now();
+  const author = input.author ?? "human";
+  const authorType = input.authorType ?? "human";
+  const body = input.body ?? "";
+  const tags = input.tags ?? [];
+  const references = input.references ?? {};
+  const owner = input.owner ?? null;
+  let slug = assertSafeSlug((input.slug ?? slugify(input.title)) || "doc");
+  if (getSystemDocBySlug(projectPath, slug)) {
+    slug = `${slug}-${uid.split("-")[0]}`;
+  }
+  const db = (0, import_database.getDb)();
+  db.run(
+    `INSERT INTO system_docs (uid, project_path, slug, title, body, owner, tags, "references",
+                              captured_against_commit, last_verified_at,
+                              author, author_type, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL, NULL, ?, ?, ?, ?)`,
+    [
+      uid,
+      projectPath,
+      slug,
+      input.title,
+      body,
+      owner,
+      JSON.stringify(tags),
+      JSON.stringify(references),
+      author,
+      authorType,
+      now,
+      now
+    ]
+  );
+  const doc = {
+    uid,
+    projectPath,
+    slug,
+    title: input.title,
+    body,
+    owner,
+    tags,
+    references,
+    capturedAgainstCommit: null,
+    lastVerifiedAt: null,
+    author,
+    authorType,
+    createdAt: now,
+    updatedAt: now
+  };
+  writeDocFile(doc);
+  (0, import_persistence.markDirty)();
+  return doc;
+}
+function updateSystemDoc(uid, updates) {
+  const existing = getSystemDoc(uid);
+  if (!existing) return null;
+  const now = Date.now();
+  const title = updates.title ?? existing.title;
+  const body = updates.body ?? existing.body;
+  const owner = updates.owner !== void 0 ? updates.owner : existing.owner;
+  const tags = updates.tags ?? existing.tags;
+  const references = updates.references ?? existing.references;
+  const author = updates.author ?? existing.author;
+  const authorType = updates.authorType ?? existing.authorType;
+  let slug = existing.slug;
+  if (updates.title && updates.title !== existing.title) {
+    const candidate = slugify(updates.title) || "doc";
+    if (candidate !== slug) {
+      const clash = getSystemDocBySlug(existing.projectPath, candidate);
+      slug = clash && clash.uid !== uid ? `${candidate}-${uid.split("-")[0]}` : candidate;
+    }
+  }
+  const db = (0, import_database.getDb)();
+  db.run(
+    `UPDATE system_docs SET slug = ?, title = ?, body = ?, owner = ?, tags = ?, "references" = ?,
+                            author = ?, author_type = ?, updated_at = ?
+     WHERE uid = ?`,
+    [
+      slug,
+      title,
+      body,
+      owner,
+      JSON.stringify(tags),
+      JSON.stringify(references),
+      author,
+      authorType,
+      now,
+      uid
+    ]
+  );
+  if (slug !== existing.slug) {
+    const oldPath = import_node_path.default.join(existing.projectPath, SYSTEM_DOCS_DIR_SEGMENT, `${existing.slug}.md`);
+    try {
+      if (import_node_fs.default.existsSync(oldPath)) {
+        (0, import_self_write_tracker.stampSelfWrite)(oldPath);
+        import_node_fs.default.unlinkSync(oldPath);
+      }
+    } catch {
+    }
+  }
+  const updated = {
+    ...existing,
+    slug,
+    title,
+    body,
+    owner,
+    tags,
+    references,
+    author,
+    authorType,
+    updatedAt: now
+  };
+  writeDocFile(updated);
+  (0, import_persistence.markDirty)();
+  return updated;
+}
+function deleteSystemDoc(uid) {
+  const existing = getSystemDoc(uid);
+  if (!existing) return false;
+  const db = (0, import_database.getDb)();
+  db.run(`DELETE FROM system_docs WHERE uid = ?`, [uid]);
+  const filePath = import_node_path.default.join(existing.projectPath, SYSTEM_DOCS_DIR_SEGMENT, `${existing.slug}.md`);
+  try {
+    if (import_node_fs.default.existsSync(filePath)) {
+      (0, import_self_write_tracker.stampSelfWrite)(filePath);
+      import_node_fs.default.unlinkSync(filePath);
+    }
+  } catch {
+  }
+  (0, import_persistence.markDirty)();
+  return true;
+}
+function verifySystemDoc(uid) {
+  const existing = getSystemDoc(uid);
+  if (!existing) return null;
+  const head = gitHeadSha(existing.projectPath);
+  if (!head) {
+    return existing;
+  }
+  const now = Date.now();
+  const db = (0, import_database.getDb)();
+  db.run(
+    `UPDATE system_docs SET captured_against_commit = ?, last_verified_at = ?, updated_at = ?
+     WHERE uid = ?`,
+    [head, now, now, uid]
+  );
+  const updated = {
+    ...existing,
+    capturedAgainstCommit: head,
+    lastVerifiedAt: now,
+    updatedAt: now
+  };
+  writeDocFile(updated);
+  (0, import_persistence.markDirty)();
+  return updated;
+}
+function getFreshness(uid) {
+  const doc = getSystemDoc(uid);
+  if (!doc) return null;
+  const currentCommit = gitHeadSha(doc.projectPath);
+  const capturedCommit = doc.capturedAgainstCommit;
+  if (!capturedCommit) {
+    return {
+      uid,
+      status: "current",
+      currentCommit,
+      capturedCommit: null,
+      changedReferencedFiles: []
+    };
+  }
+  if (!currentCommit || currentCommit === capturedCommit) {
+    return {
+      uid,
+      status: "current",
+      currentCommit,
+      capturedCommit,
+      changedReferencedFiles: []
+    };
+  }
+  const refFiles = doc.references.files ?? [];
+  if (refFiles.length === 0) {
+    return {
+      uid,
+      status: "moved",
+      currentCommit,
+      capturedCommit,
+      changedReferencedFiles: []
+    };
+  }
+  const changed = gitChangedFiles(doc.projectPath, capturedCommit, currentCommit);
+  const changedSet = new Set(changed);
+  const intersect = refFiles.filter((f) => changedSet.has(normaliseRelPath(f)));
+  const status = intersect.length > 0 ? "stale" : "moved";
+  return {
+    uid,
+    status,
+    currentCommit,
+    capturedCommit,
+    changedReferencedFiles: intersect
+  };
+}
+function findDocsByReferencedFile(projectPath, relativePath) {
+  const db = (0, import_database.getDb)();
+  const normalised = normalisePath(projectPath);
+  const jsonPath = JSON.stringify(relativePath);
+  const likePattern = `%${jsonPath}%`;
+  const result = db.exec(
+    `SELECT uid, slug, title, "references"
+       FROM system_docs
+       WHERE project_path = ? AND "references" LIKE ?`,
+    [normalised, likePattern]
+  );
+  if (!result[0]) return [];
+  return result[0].values.map((r) => {
+    const refs = safeParseJsonObject(r[3]);
+    return {
+      uid: r[0],
+      slug: r[1],
+      title: r[2],
+      plans: refs.plans ?? []
+    };
+  });
+}
+function checkAllDocsFreshness(projectPath) {
+  const docs = listSystemDocs(projectPath);
+  const stale = [];
+  for (const doc of docs) {
+    const report = getFreshness(doc.uid);
+    if (report && report.status === "stale") {
+      stale.push(report);
+    }
+  }
+  return stale;
+}
+function indexProjectDocs(projectPath) {
+  const dir = import_node_path.default.join(normalisePath(projectPath), SYSTEM_DOCS_DIR_SEGMENT);
+  if (!import_node_fs.default.existsSync(dir)) return { imported: 0, skipped: 0, errors: [] };
+  const result = { imported: 0, skipped: 0, errors: [] };
+  for (const entry of import_node_fs.default.readdirSync(dir)) {
+    if (!entry.endsWith(".md")) continue;
+    const fullPath = import_node_path.default.join(dir, entry);
+    try {
+      const ok = importDocFile(fullPath, projectPath);
+      if (ok) result.imported++;
+      else result.skipped++;
+    } catch (err) {
+      result.errors.push(`${entry}: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+  return result;
+}
+const watchersByProject = /* @__PURE__ */ new Map();
+function startSystemDocsWatcher(projectRoot) {
+  const key = normalisePath(projectRoot);
+  if (watchersByProject.has(key)) return;
+  const dir = import_node_path.default.join(key, SYSTEM_DOCS_DIR_SEGMENT);
+  try {
+    import_node_fs.default.mkdirSync(dir, { recursive: true });
+  } catch {
+  }
+  const watcher = import_chokidar.default.watch(dir, {
+    ignoreInitial: true,
+    persistent: true,
+    depth: 0,
+    awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 }
+  });
+  watcher.on("all", (event, filePath) => {
+    if (!filePath || !filePath.endsWith(".md")) return;
+    if (event !== "add" && event !== "change" && event !== "unlink") return;
+    if ((0, import_self_write_tracker.wasJustWrittenByUs)(filePath)) return;
+    try {
+      if (event === "unlink") {
+        const slug = import_node_path.default.basename(filePath, ".md");
+        const existing = getSystemDocBySlug(key, slug);
+        if (existing) {
+          (0, import_database.getDb)().run(`DELETE FROM system_docs WHERE uid = ?`, [existing.uid]);
+          (0, import_persistence.markDirty)();
+          tryBroadcast("system-doc-removed", { uid: existing.uid, slug, projectPath: key });
+        }
+        return;
+      }
+      const ok = importDocFile(filePath, key);
+      if (ok) {
+        tryBroadcast("system-doc-changed", { filePath, projectPath: key, event });
+      }
+    } catch (err) {
+      console.warn("[SystemDocs] Watcher handler failed:", err);
+    }
+  });
+  watcher.on("error", (err) => {
+    console.warn("[SystemDocs] Watcher error:", err);
+  });
+  watchersByProject.set(key, watcher);
+}
+async function stopSystemDocsWatcher(projectRoot) {
+  const key = normalisePath(projectRoot);
+  const watcher = watchersByProject.get(key);
+  if (!watcher) return;
+  watchersByProject.delete(key);
+  try {
+    await watcher.close();
+  } catch {
+  }
+}
+const ALL_COLUMNS = `uid, project_path, slug, title, body, owner, tags, "references",
+        captured_against_commit, last_verified_at,
+        author, author_type, created_at, updated_at`;
+function rowToDoc(r) {
+  return {
+    uid: r[0],
+    projectPath: r[1],
+    slug: r[2],
+    title: r[3],
+    body: r[4],
+    owner: r[5] ?? null,
+    tags: safeParseJsonArray(r[6]),
+    references: safeParseJsonObject(r[7]),
+    capturedAgainstCommit: r[8] ?? null,
+    lastVerifiedAt: r[9] ?? null,
+    author: r[10],
+    authorType: r[11],
+    createdAt: r[12],
+    updatedAt: r[13]
+  };
+}
+function writeDocFile(doc) {
+  const dir = import_node_path.default.join(doc.projectPath, SYSTEM_DOCS_DIR_SEGMENT);
+  if (!import_node_fs.default.existsSync(dir)) import_node_fs.default.mkdirSync(dir, { recursive: true });
+  const filePath = import_node_path.default.join(dir, `${doc.slug}.md`);
+  const frontmatter = {
+    uid: doc.uid,
+    title: doc.title,
+    owner: doc.owner ?? null,
+    tags: doc.tags,
+    references: doc.references,
+    capturedAgainstCommit: doc.capturedAgainstCommit ?? null,
+    lastVerifiedAt: doc.lastVerifiedAt ? new Date(doc.lastVerifiedAt).toISOString() : null,
+    author: doc.author,
+    authorType: doc.authorType,
+    createdAt: new Date(doc.createdAt).toISOString(),
+    updatedAt: new Date(doc.updatedAt).toISOString()
+  };
+  const out = `---
+${(0, import_yaml.stringify)(frontmatter)}---
+
+${doc.body}`;
+  const tmp = `${filePath}.tmp`;
+  import_node_fs.default.writeFileSync(tmp, out, "utf-8");
+  import_node_fs.default.renameSync(tmp, filePath);
+  (0, import_self_write_tracker.stampSelfWrite)(filePath);
+}
+function importDocFile(filePath, projectPath) {
+  if (!import_node_fs.default.existsSync(filePath)) return false;
+  const raw = import_node_fs.default.readFileSync(filePath, "utf-8");
+  const { meta, body, hasFrontmatter, parseError } = parseFrontMatter(raw);
+  if (hasFrontmatter && parseError) {
+    console.warn(
+      `[SystemDocs] Skipping ${filePath} \u2014 malformed YAML frontmatter (${parseError}). Fix the syntax and save again; no changes were applied to the index.`
+    );
+    return false;
+  }
+  let uid = typeof meta.uid === "string" ? meta.uid : null;
+  const title = typeof meta.title === "string" && meta.title.trim() ? meta.title.trim() : import_node_path.default.basename(filePath, ".md").replace(/[-_]+/g, " ");
+  const projPath = normalisePath(projectPath);
+  const slug = import_node_path.default.basename(filePath, ".md");
+  const now = Date.now();
+  const stamped = !!uid;
+  if (!uid) uid = (0, import_node_crypto.randomUUID)();
+  const owner = typeof meta.owner === "string" ? meta.owner : null;
+  const tags = Array.isArray(meta.tags) ? meta.tags.filter((t) => typeof t === "string") : [];
+  const references = isReferencesObject(meta.references) ? sanitiseReferences(meta.references) : {};
+  const capturedAgainstCommit = typeof meta.capturedAgainstCommit === "string" ? meta.capturedAgainstCommit : null;
+  const lastVerifiedAt = parseEpoch(meta.lastVerifiedAt);
+  const author = typeof meta.author === "string" ? meta.author : "human";
+  const authorType = typeof meta.authorType === "string" ? meta.authorType : "human";
+  const createdAt = parseEpoch(meta.createdAt) ?? now;
+  const db = (0, import_database.getDb)();
+  const exists = db.exec(`SELECT uid, project_path FROM system_docs WHERE uid = ?`, [uid]);
+  if (exists[0]?.values[0] && (0, import_checkout_identity.heldByAnotherCheckout)(exists[0].values[0][1], projPath)) {
+    return false;
+  }
+  if (exists[0]?.values[0]) {
+    db.run(
+      `UPDATE system_docs SET project_path = ?, slug = ?, title = ?, body = ?, owner = ?,
+                              tags = ?, "references" = ?, captured_against_commit = ?,
+                              last_verified_at = ?, author = ?, author_type = ?, updated_at = ?
+       WHERE uid = ?`,
+      [
+        projPath,
+        slug,
+        title,
+        body,
+        owner,
+        JSON.stringify(tags),
+        JSON.stringify(references),
+        capturedAgainstCommit,
+        lastVerifiedAt,
+        author,
+        authorType,
+        now,
+        uid
+      ]
+    );
+  } else {
+    db.run(
+      `INSERT INTO system_docs (uid, project_path, slug, title, body, owner, tags, "references",
+                                captured_against_commit, last_verified_at,
+                                author, author_type, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        uid,
+        projPath,
+        slug,
+        title,
+        body,
+        owner,
+        JSON.stringify(tags),
+        JSON.stringify(references),
+        capturedAgainstCommit,
+        lastVerifiedAt,
+        author,
+        authorType,
+        createdAt,
+        now
+      ]
+    );
+  }
+  if (!stamped) {
+    const doc = {
+      uid,
+      projectPath: projPath,
+      slug,
+      title,
+      body,
+      owner,
+      tags,
+      references,
+      capturedAgainstCommit,
+      lastVerifiedAt,
+      author,
+      authorType,
+      createdAt,
+      updatedAt: now
+    };
+    writeDocFile(doc);
+  }
+  (0, import_persistence.markDirty)();
+  return true;
+}
+function parseFrontMatter(source) {
+  if (!source.startsWith("---")) {
+    return { meta: {}, body: source, hasFrontmatter: false, parseError: null };
+  }
+  const end = source.indexOf("\n---", 3);
+  if (end < 0) {
+    return { meta: {}, body: source, hasFrontmatter: true, parseError: "missing closing ---" };
+  }
+  const yamlBlock = source.slice(3, end).replace(/^\n/, "");
+  const body = source.slice(end + 4).replace(/^\n+/, "");
+  let meta = {};
+  let parseError = null;
+  try {
+    meta = (0, import_yaml.parse)(yamlBlock) ?? {};
+  } catch (err) {
+    parseError = err instanceof Error ? err.message : String(err);
+    meta = {};
+  }
+  return { meta, body, hasFrontmatter: true, parseError };
+}
+function isReferencesObject(v) {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+function sanitiseReferences(r) {
+  const out = {};
+  const stringArray = (v) => {
+    if (!Array.isArray(v)) return void 0;
+    const arr = v.filter((x) => typeof x === "string");
+    return arr.length ? arr : void 0;
+  };
+  const files = stringArray(r.files);
+  if (files) out.files = files;
+  const symbols = stringArray(r.symbols);
+  if (symbols) out.symbols = symbols;
+  const items = stringArray(r.items);
+  if (items) out.items = items;
+  const plans = stringArray(r.plans);
+  if (plans) out.plans = plans;
+  const urls = stringArray(r.urls);
+  if (urls) out.urls = urls;
+  return out;
+}
+function parseEpoch(v) {
+  if (typeof v === "number") return v;
+  if (typeof v === "string") {
+    const t = Date.parse(v);
+    return Number.isFinite(t) ? t : null;
+  }
+  return null;
+}
+function safeParseJsonArray(s) {
+  if (!s) return [];
+  try {
+    const v = JSON.parse(s);
+    return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+  } catch {
+    return [];
+  }
+}
+function safeParseJsonObject(s) {
+  if (!s) return {};
+  try {
+    const v = JSON.parse(s);
+    return isReferencesObject(v) ? sanitiseReferences(v) : {};
+  } catch {
+    return {};
+  }
+}
+function normalisePath(p) {
+  return import_node_path.default.resolve(p).replace(/[/\\]+$/, "");
+}
+function normaliseRelPath(p) {
+  return p.replace(/\\/g, "/").replace(/^\.\/+/, "");
+}
+function slugify(s) {
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60);
+}
+function gitHeadSha(projectPath) {
+  try {
+    if (!import_node_fs.default.existsSync(import_node_path.default.join(projectPath, ".git"))) return null;
+    return (0, import_node_child_process.execFileSync)("git", ["rev-parse", "HEAD"], {
+      cwd: projectPath,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+function gitChangedFiles(projectPath, fromSha, toSha) {
+  try {
+    const out = (0, import_node_child_process.execFileSync)("git", ["diff", "--name-only", `${fromSha}..${toSha}`], {
+      cwd: projectPath,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    return out.split("\n").map((s) => s.trim()).filter(Boolean).map(normaliseRelPath);
+  } catch {
+    return [];
+  }
+}
+function tryBroadcast(type, payload) {
+  try {
+    const { broadcast } = _lazy____server;
+    broadcast(type, payload);
+  } catch {
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  checkAllDocsFreshness,
+  createSystemDoc,
+  deleteSystemDoc,
+  findDocsByReferencedFile,
+  getFreshness,
+  getSystemDoc,
+  getSystemDocBySlug,
+  indexProjectDocs,
+  listSystemDocs,
+  searchSystemDocs,
+  startSystemDocsWatcher,
+  stopSystemDocsWatcher,
+  updateSystemDoc,
+  verifySystemDoc
+});