codealmanac 0.1.6 → 0.1.8

package/dist/chunk-3C5SY5SE.js

@@ -0,0 +1,1239 @@
+#!/usr/bin/env node
+import {
+  BLUE,
+  BOLD,
+  DIM,
+  GREEN,
+  RED,
+  RST
+} from "./chunk-FM3VRDK7.js";
+import {
+  findNearestAlmanacDir,
+  getGlobalAlmanacDir,
+  getRegistryPath
+} from "./chunk-7JUX4ADQ.js";
+
+// src/indexer/schema.ts
+import Database from "better-sqlite3";
+var SCHEMA_DDL = `
+CREATE TABLE IF NOT EXISTS pages (
+  slug          TEXT PRIMARY KEY,
+  title         TEXT,
+  file_path     TEXT NOT NULL,
+  content_hash  TEXT NOT NULL,
+  updated_at    INTEGER NOT NULL,
+  archived_at   INTEGER,
+  superseded_by TEXT
+);
+
+CREATE TABLE IF NOT EXISTS topics (
+  slug        TEXT PRIMARY KEY,
+  title       TEXT,
+  description TEXT
+);
+
+CREATE TABLE IF NOT EXISTS page_topics (
+  page_slug  TEXT NOT NULL REFERENCES pages(slug) ON DELETE CASCADE,
+  topic_slug TEXT NOT NULL,
+  PRIMARY KEY (page_slug, topic_slug)
+);
+
+CREATE TABLE IF NOT EXISTS topic_parents (
+  child_slug  TEXT NOT NULL,
+  parent_slug TEXT NOT NULL,
+  PRIMARY KEY (child_slug, parent_slug),
+  CHECK (child_slug != parent_slug)
+);
+
+CREATE TABLE IF NOT EXISTS file_refs (
+  page_slug     TEXT NOT NULL REFERENCES pages(slug) ON DELETE CASCADE,
+  path          TEXT NOT NULL,
+  original_path TEXT NOT NULL,
+  is_dir        INTEGER NOT NULL,
+  PRIMARY KEY (page_slug, path)
+);
+CREATE INDEX IF NOT EXISTS idx_file_refs_path ON file_refs(path);
+
+CREATE TABLE IF NOT EXISTS wikilinks (
+  source_slug TEXT NOT NULL REFERENCES pages(slug) ON DELETE CASCADE,
+  target_slug TEXT NOT NULL,
+  PRIMARY KEY (source_slug, target_slug)
+);
+
+CREATE TABLE IF NOT EXISTS cross_wiki_links (
+  source_slug TEXT NOT NULL REFERENCES pages(slug) ON DELETE CASCADE,
+  target_wiki TEXT NOT NULL,
+  target_slug TEXT NOT NULL,
+  PRIMARY KEY (source_slug, target_wiki, target_slug)
+);
+
+-- NOTE: virtual FTS5 table \u2014 ON DELETE CASCADE from pages does NOT apply.
+-- The indexer must explicitly DELETE FROM fts_pages whenever it removes
+-- or replaces a page row, or we leak orphaned FTS rows.
+CREATE VIRTUAL TABLE IF NOT EXISTS fts_pages USING fts5(slug, title, content);
+`;
+var SCHEMA_VERSION = 2;
+function openIndex(dbPath) {
+  const db = new Database(dbPath);
+  const mode = db.pragma("journal_mode", { simple: true });
+  if (typeof mode !== "string" || mode.toLowerCase() !== "wal") {
+    db.pragma("journal_mode = WAL");
+  }
+  db.pragma("foreign_keys = ON");
+  const rawVersion = db.pragma("user_version", { simple: true });
+  const currentVersion = typeof rawVersion === "number" ? rawVersion : 0;
+  if (currentVersion < SCHEMA_VERSION) {
+    db.exec("DROP TABLE IF EXISTS file_refs");
+    try {
+      db.exec("UPDATE pages SET content_hash = ''");
+    } catch {
+    }
+    db.pragma(`user_version = ${SCHEMA_VERSION}`);
+  }
+  db.exec(SCHEMA_DDL);
+  return db;
+}
+
+// src/indexer/index.ts
+import { createHash } from "crypto";
+import { existsSync as existsSync4, statSync as statSync2 } from "fs";
+import { readFile as readFile2, utimes } from "fs/promises";
+import { basename, join as join2 } from "path";
+import fg2 from "fast-glob";
+
+// src/slug.ts
+function toKebabCase(input) {
+  return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
+// src/topics/yaml.ts
+import { existsSync } from "fs";
+import { mkdir, readFile, rename, writeFile } from "fs/promises";
+import { dirname } from "path";
+import yaml from "js-yaml";
+async function loadTopicsFile(path) {
+  if (!existsSync(path)) {
+    return { topics: [] };
+  }
+  let raw;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (err) {
+    if (isNodeError(err) && err.code === "ENOENT") {
+      return { topics: [] };
+    }
+    throw err;
+  }
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    return { topics: [] };
+  }
+  let parsed;
+  try {
+    parsed = yaml.load(raw);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`topics.yaml at ${path} is not valid YAML: ${message}`);
+  }
+  if (parsed === null || parsed === void 0) {
+    return { topics: [] };
+  }
+  if (typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`topics.yaml at ${path} must be a mapping`);
+  }
+  const obj = parsed;
+  const rawTopics = obj.topics;
+  if (rawTopics === void 0 || rawTopics === null) {
+    return { topics: [] };
+  }
+  if (!Array.isArray(rawTopics)) {
+    throw new Error(`topics.yaml at ${path} \u2014 "topics" must be a list`);
+  }
+  const topics = [];
+  for (const item of rawTopics) {
+    if (typeof item !== "object" || item === null || Array.isArray(item)) {
+      continue;
+    }
+    const entry = item;
+    const slugRaw = entry.slug;
+    if (typeof slugRaw !== "string" || slugRaw.trim().length === 0) continue;
+    const slug = toKebabCase(slugRaw);
+    if (slug.length === 0) continue;
+    const title = typeof entry.title === "string" && entry.title.trim().length > 0 ? entry.title.trim() : titleCase(slug);
+    const description = typeof entry.description === "string" && entry.description.trim().length > 0 ? entry.description.trim() : null;
+    const parents = [];
+    if (Array.isArray(entry.parents)) {
+      for (const p of entry.parents) {
+        if (typeof p === "string" && p.trim().length > 0) {
+          const ps = toKebabCase(p);
+          if (ps.length > 0 && ps !== slug && !parents.includes(ps)) {
+            parents.push(ps);
+          }
+        }
+      }
+    }
+    topics.push({ slug, title, description, parents });
+  }
+  return { topics };
+}
+async function writeTopicsFile(path, file) {
+  const sorted = [...file.topics].sort((a, b) => a.slug.localeCompare(b.slug));
+  const doc = {
+    topics: sorted.map((t) => {
+      return {
+        slug: t.slug,
+        title: t.title,
+        description: t.description,
+        parents: t.parents
+      };
+    })
+  };
+  const header = `# .almanac/topics.yaml \u2014 source of truth for topic metadata.
+# Managed by \`almanac topics\` commands. User-added comments
+# between entries will be stripped on the next write (js-yaml
+# doesn't round-trip comments). Edit at your own risk \u2014 or use the
+# CLI (\`almanac topics create|link|describe|rename|delete\`)
+# which preserves the structure correctly.
+`;
+  const body = yaml.dump(doc, {
+    lineWidth: 100,
+    noRefs: true,
+    sortKeys: false
+  });
+  const content = `${header}${body}`;
+  const tmpPath = `${path}.tmp`;
+  const parent = dirname(path);
+  if (!existsSync(parent)) {
+    await mkdir(parent, { recursive: true });
+  }
+  await writeFile(tmpPath, content, "utf8");
+  await rename(tmpPath, path);
+}
+function findTopic(file, slug) {
+  for (const t of file.topics) {
+    if (t.slug === slug) return t;
+  }
+  return null;
+}
+function ensureTopic(file, slug) {
+  const existing = findTopic(file, slug);
+  if (existing !== null) return existing;
+  const entry = {
+    slug,
+    title: titleCase(slug),
+    description: null,
+    parents: []
+  };
+  file.topics.push(entry);
+  return entry;
+}
+function titleCase(slug) {
+  if (slug.length === 0) return slug;
+  return slug.split("-").filter((s) => s.length > 0).map((s) => `${s[0]?.toUpperCase() ?? ""}${s.slice(1)}`).join(" ");
+}
+function isNodeError(err) {
+  return err instanceof Error && "code" in err;
+}
+
+// src/indexer/frontmatter.ts
+import yaml2 from "js-yaml";
+function parseFrontmatter(raw) {
+  const empty = {
+    topics: [],
+    files: [],
+    archived_at: null,
+    superseded_by: null,
+    supersedes: null,
+    body: raw
+  };
+  if (!raw.startsWith("---")) {
+    return empty;
+  }
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (match === null) {
+    return empty;
+  }
+  const yamlBody = match[1] ?? "";
+  const body = match[2] ?? "";
+  let parsed;
+  try {
+    parsed = yaml2.load(yamlBody);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`almanac: malformed frontmatter (${message})
+`);
+    return empty;
+  }
+  if (parsed === null || parsed === void 0) {
+    return { ...empty, body };
+  }
+  if (typeof parsed !== "object" || Array.isArray(parsed)) {
+    return { ...empty, body };
+  }
+  const obj = parsed;
+  return {
+    title: coerceString(obj.title),
+    topics: coerceStringArray(obj.topics),
+    files: coerceStringArray(obj.files),
+    archived_at: coerceEpochSeconds(obj.archived_at),
+    superseded_by: coerceString(obj.superseded_by) ?? null,
+    supersedes: coerceString(obj.supersedes) ?? null,
+    body
+  };
+}
+function firstH1(body) {
+  const lines = body.split(/\r?\n/, 40);
+  for (const line of lines) {
+    const m = line.match(/^#\s+(.+?)\s*#*\s*$/);
+    if (m !== null) {
+      return m[1];
+    }
+  }
+  return void 0;
+}
+function coerceString(v) {
+  if (typeof v === "string" && v.trim().length > 0) return v.trim();
+  return void 0;
+}
+function coerceStringArray(v) {
+  if (!Array.isArray(v)) return [];
+  const out = [];
+  for (const item of v) {
+    if (typeof item === "string" && item.trim().length > 0) {
+      out.push(item.trim());
+    }
+  }
+  return out;
+}
+function coerceEpochSeconds(v) {
+  if (v instanceof Date) {
+    return Math.floor(v.getTime() / 1e3);
+  }
+  if (typeof v === "number" && Number.isFinite(v)) {
+    return Math.floor(v);
+  }
+  if (typeof v === "string" && v.trim().length > 0) {
+    const t = Date.parse(v.trim());
+    if (!Number.isNaN(t)) {
+      return Math.floor(t / 1e3);
+    }
+  }
+  return null;
+}
+
+// src/indexer/freshness.ts
+import { existsSync as existsSync2, statSync } from "fs";
+import { join } from "path";
+import fg from "fast-glob";
+var PAGES_GLOB = "**/*.md";
+function pagesNewerThan(pagesDir, dbPath) {
+  let dbMtime;
+  try {
+    dbMtime = statSync(dbPath).mtimeMs;
+  } catch {
+    return true;
+  }
+  const entries = fg.sync(PAGES_GLOB, {
+    cwd: pagesDir,
+    absolute: true,
+    onlyFiles: true,
+    stats: true
+  });
+  for (const entry of entries) {
+    const mtime = entry.stats?.mtimeMs;
+    if (mtime !== void 0 && mtime > dbMtime) return true;
+  }
+  return false;
+}
+function topicsYamlNewerThan(almanacDir, dbPath) {
+  const path = join(almanacDir, "topics.yaml");
+  if (!existsSync2(path)) return false;
+  let dbMtime;
+  try {
+    dbMtime = statSync(dbPath).mtimeMs;
+  } catch {
+    return true;
+  }
+  try {
+    const st = statSync(path);
+    return st.mtimeMs > dbMtime;
+  } catch {
+    return false;
+  }
+}
+
+// src/indexer/paths.ts
+function normalizePath(raw, isDir) {
+  const normalized = normalizeShape(raw, isDir);
+  return normalized.toLowerCase();
+}
+function normalizePathPreservingCase(raw, isDir) {
+  return normalizeShape(raw, isDir);
+}
+function normalizeShape(raw, isDir) {
+  let s = raw.trim();
+  s = s.replace(/\\+/g, "/");
+  while (s.startsWith("./")) s = s.slice(2);
+  s = s.replace(/\/+/g, "/");
+  s = s.replace(/\/+$/, "");
+  if (isDir) {
+    return `${s}/`;
+  }
+  return s;
+}
+function looksLikeDir(raw) {
+  const s = raw.trim().replace(/\\+/g, "/");
+  return s.endsWith("/");
+}
+
+// src/indexer/topics-yaml.ts
+import { existsSync as existsSync3 } from "fs";
+var TOPICS_YAML_FILENAME = "topics.yaml";
+async function applyTopicsYaml(db, topicsYamlPath) {
+  if (!existsSync3(topicsYamlPath)) return;
+  let file;
+  try {
+    file = await loadTopicsFile(topicsYamlPath);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`almanac: ${message}
+`);
+    return;
+  }
+  const upsertTopic = db.prepare(
+    `INSERT INTO topics (slug, title, description) VALUES (?, ?, ?)
+     ON CONFLICT(slug) DO UPDATE SET
+       title = excluded.title,
+       description = excluded.description`
+  );
+  const clearParents = db.prepare(
+    "DELETE FROM topic_parents WHERE child_slug = ?"
+  );
+  const insertParent = db.prepare(
+    "INSERT OR IGNORE INTO topic_parents (child_slug, parent_slug) VALUES (?, ?)"
+  );
+  const declared = /* @__PURE__ */ new Set();
+  for (const t of file.topics) declared.add(t.slug);
+  const adHoc = db.prepare(
+    "SELECT DISTINCT topic_slug FROM page_topics"
+  ).all();
+  for (const r of adHoc) declared.add(r.topic_slug);
+  const apply = db.transaction(() => {
+    for (const t of file.topics) {
+      upsertTopic.run(t.slug, t.title, t.description);
+      clearParents.run(t.slug);
+      for (const parent of t.parents) {
+        if (parent === t.slug) continue;
+        insertParent.run(t.slug, parent);
+      }
+    }
+    const existing = db.prepare("SELECT slug FROM topics").all();
+    const deleteTopic = db.prepare("DELETE FROM topics WHERE slug = ?");
+    const deleteEdgesByChild = db.prepare(
+      "DELETE FROM topic_parents WHERE child_slug = ?"
+    );
+    const deleteEdgesByParent = db.prepare(
+      "DELETE FROM topic_parents WHERE parent_slug = ?"
+    );
+    for (const r of existing) {
+      if (declared.has(r.slug)) continue;
+      deleteEdgesByChild.run(r.slug);
+      deleteEdgesByParent.run(r.slug);
+      deleteTopic.run(r.slug);
+    }
+  });
+  apply();
+}
+
+// src/indexer/wikilinks.ts
+function classifyWikilink(raw) {
+  const pipe = raw.indexOf("|");
+  let body = pipe === -1 ? raw : raw.slice(0, pipe);
+  body = body.trim();
+  if (body.length === 0) return null;
+  const firstColon = body.indexOf(":");
+  const firstSlash = body.indexOf("/");
+  if (firstColon !== -1 && (firstSlash === -1 || firstColon < firstSlash)) {
+    const wiki = body.slice(0, firstColon).trim();
+    const target2 = body.slice(firstColon + 1).trim();
+    if (wiki.length === 0 || target2.length === 0) return null;
+    return { kind: "xwiki", wiki, target: target2 };
+  }
+  if (firstSlash !== -1) {
+    const isDir = looksLikeDir(body);
+    const path = normalizePath(body, isDir);
+    const originalPath = normalizePathPreservingCase(body, isDir);
+    if (path.length === 0) return null;
+    return isDir ? { kind: "folder", path, originalPath } : { kind: "file", path, originalPath };
+  }
+  const target = toKebabCase(body);
+  if (target.length === 0) return null;
+  return { kind: "page", target };
+}
+function extractWikilinks(body) {
+  const out = [];
+  const re = /\[\[([^\]\n]+)\]\]/g;
+  let m;
+  while ((m = re.exec(body)) !== null) {
+    const ref = classifyWikilink(m[1] ?? "");
+    if (ref !== null) out.push(ref);
+  }
+  return out;
+}
+
+// src/indexer/index.ts
+async function ensureFreshIndex(ctx) {
+  const almanacDir = join2(ctx.repoRoot, ".almanac");
+  const dbPath = join2(almanacDir, "index.db");
+  const pagesDir = join2(almanacDir, "pages");
+  if (!existsSync4(pagesDir)) {
+    const db = openIndex(dbPath);
+    db.close();
+    return emptyResult();
+  }
+  if (!existsSync4(dbPath) || pagesNewerThan(pagesDir, dbPath) || topicsYamlNewerThan(almanacDir, dbPath)) {
+    return runIndexer(ctx);
+  }
+  return emptyResult();
+}
+function emptyResult() {
+  return {
+    changed: 0,
+    removed: 0,
+    total: 0,
+    pagesIndexed: 0,
+    filesSeen: 0,
+    filesSkipped: 0
+  };
+}
+async function runIndexer(ctx) {
+  const almanacDir = join2(ctx.repoRoot, ".almanac");
+  const dbPath = join2(almanacDir, "index.db");
+  const pagesDir = join2(almanacDir, "pages");
+  const db = openIndex(dbPath);
+  let result;
+  try {
+    result = await indexPagesInto(db, pagesDir);
+    await applyTopicsYaml(db, join2(almanacDir, TOPICS_YAML_FILENAME));
+  } finally {
+    db.close();
+  }
+  try {
+    const now = /* @__PURE__ */ new Date();
+    await utimes(dbPath, now, now);
+  } catch {
+  }
+  return result;
+}
+async function indexPagesInto(db, pagesDir) {
+  const files = await fg2(PAGES_GLOB, {
+    cwd: pagesDir,
+    absolute: false,
+    onlyFiles: true,
+    caseSensitiveMatch: true
+  });
+  const existingRows = db.prepare("SELECT slug, content_hash, file_path FROM pages").all();
+  const existingBySlug = /* @__PURE__ */ new Map();
+  for (const row of existingRows) existingBySlug.set(row.slug, row);
+  const planned = [];
+  const seenSlugs = /* @__PURE__ */ new Set();
+  let filesSkipped = 0;
+  for (const rel of files) {
+    const fullPath = join2(pagesDir, rel);
+    const base = basename(rel, ".md");
+    const slug = toKebabCase(base);
+    if (slug.length === 0) {
+      process.stderr.write(
+        `almanac: skipping "${rel}" \u2014 filename has no slug-able characters
+`
+      );
+      filesSkipped++;
+      continue;
+    }
+    if (slug !== base) {
+      process.stderr.write(
+        `almanac: warning \u2014 "${rel}" is not canonical; indexed as slug "${slug}"
+`
+      );
+    }
+    if (seenSlugs.has(slug)) {
+      process.stderr.write(
+        `almanac: warning \u2014 slug "${slug}" collides with an earlier file; skipping "${rel}"
+`
+      );
+      filesSkipped++;
+      continue;
+    }
+    let st;
+    let raw;
+    try {
+      st = statSync2(fullPath);
+      raw = await readFile2(fullPath, "utf8");
+    } catch (err) {
+      if (err instanceof Error && "code" in err && (err.code === "ENOENT" || err.code === "EACCES")) {
+        process.stderr.write(
+          `almanac: skipping "${rel}" \u2014 ${err.message}
+`
+        );
+        filesSkipped++;
+        continue;
+      }
+      throw err;
+    }
+    seenSlugs.add(slug);
+    const updatedAt = Math.floor(st.mtimeMs / 1e3);
+    const contentHash = hashContent(raw);
+    const existing = existingBySlug.get(slug);
+    if (existing !== void 0 && existing.content_hash === contentHash && existing.file_path === fullPath) {
+      continue;
+    }
+    const fm = parseFrontmatter(raw);
+    const title = fm.title ?? firstH1(fm.body) ?? base;
+    const links = extractWikilinks(fm.body);
+    planned.push({
+      slug,
+      title,
+      filePath: rel,
+      fullPath,
+      contentHash,
+      updatedAt,
+      archivedAt: fm.archived_at,
+      supersededBy: fm.superseded_by,
+      topics: fm.topics,
+      frontmatterFiles: fm.files,
+      wikilinks: links,
+      content: fm.body
+    });
+  }
+  const toDelete = [];
+  for (const slug of existingBySlug.keys()) {
+    if (!seenSlugs.has(slug)) toDelete.push(slug);
+  }
+  const deleteByPage = db.prepare("DELETE FROM pages WHERE slug = ?");
+  const deleteFtsByPage = db.prepare(
+    "DELETE FROM fts_pages WHERE slug = ?"
+  );
+  const replacePage = db.prepare(
+    `INSERT INTO pages (slug, title, file_path, content_hash, updated_at, archived_at, superseded_by)
+     VALUES (?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(slug) DO UPDATE SET
+       title         = excluded.title,
+       file_path     = excluded.file_path,
+       content_hash  = excluded.content_hash,
+       updated_at    = excluded.updated_at,
+       archived_at   = excluded.archived_at,
+       superseded_by = excluded.superseded_by`
+  );
+  const deletePageTopics = db.prepare(
+    "DELETE FROM page_topics WHERE page_slug = ?"
+  );
+  const insertPageTopic = db.prepare(
+    "INSERT OR IGNORE INTO page_topics (page_slug, topic_slug) VALUES (?, ?)"
+  );
+  const insertTopic = db.prepare(
+    "INSERT OR IGNORE INTO topics (slug, title) VALUES (?, ?)"
+  );
+  const deleteFileRefs = db.prepare(
+    "DELETE FROM file_refs WHERE page_slug = ?"
+  );
+  const insertFileRef = db.prepare(
+    "INSERT OR IGNORE INTO file_refs (page_slug, path, original_path, is_dir) VALUES (?, ?, ?, ?)"
+  );
+  const deleteWikilinks = db.prepare(
+    "DELETE FROM wikilinks WHERE source_slug = ?"
+  );
+  const insertWikilink = db.prepare(
+    "INSERT OR IGNORE INTO wikilinks (source_slug, target_slug) VALUES (?, ?)"
+  );
+  const deleteXwiki = db.prepare(
+    "DELETE FROM cross_wiki_links WHERE source_slug = ?"
+  );
+  const insertXwiki = db.prepare(
+    "INSERT OR IGNORE INTO cross_wiki_links (source_slug, target_wiki, target_slug) VALUES (?, ?, ?)"
+  );
+  const insertFts = db.prepare(
+    "INSERT INTO fts_pages (slug, title, content) VALUES (?, ?, ?)"
+  );
+  const apply = db.transaction(() => {
+    for (const slug of toDelete) {
+      deleteFtsByPage.run(slug);
+      deleteByPage.run(slug);
+    }
+    for (const p of planned) {
+      deletePageTopics.run(p.slug);
+      deleteFileRefs.run(p.slug);
+      deleteWikilinks.run(p.slug);
+      deleteXwiki.run(p.slug);
+      deleteFtsByPage.run(p.slug);
+      replacePage.run(
+        p.slug,
+        p.title,
+        p.fullPath,
+        p.contentHash,
+        p.updatedAt,
+        p.archivedAt,
+        p.supersededBy
+      );
+      for (const topic of p.topics) {
+        const topicSlug = toKebabCase(topic);
+        if (topicSlug.length === 0) continue;
+        insertTopic.run(topicSlug, titleCase(topicSlug));
+        insertPageTopic.run(p.slug, topicSlug);
+      }
+      for (const raw of p.frontmatterFiles) {
+        const isDir = looksLikeDir(raw);
+        const path = normalizePath(raw, isDir);
+        const originalPath = normalizePathPreservingCase(raw, isDir);
+        if (path.length === 0) continue;
+        insertFileRef.run(p.slug, path, originalPath, isDir ? 1 : 0);
+      }
+      for (const ref of p.wikilinks) {
+        switch (ref.kind) {
+          case "page":
+            insertWikilink.run(p.slug, ref.target);
+            break;
+          case "file":
+            insertFileRef.run(p.slug, ref.path, ref.originalPath, 0);
+            break;
+          case "folder":
+            insertFileRef.run(p.slug, ref.path, ref.originalPath, 1);
+            break;
+          case "xwiki":
+            insertXwiki.run(p.slug, ref.wiki, ref.target);
+            break;
+        }
+      }
+      insertFts.run(p.slug, p.title, p.content);
+    }
+  });
+  apply();
+  const pagesIndexed = seenSlugs.size;
+  return {
+    changed: planned.length,
+    removed: toDelete.length,
+    total: pagesIndexed,
+    pagesIndexed,
+    filesSeen: files.length,
+    filesSkipped
+  };
+}
+function hashContent(raw) {
+  return createHash("sha256").update(raw).digest("hex");
+}
+
+// src/registry/index.ts
+import { mkdir as mkdir2, readFile as readFile3, rename as rename2, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname2 } from "path";
+async function readRegistry() {
+  const path = getRegistryPath();
+  let raw;
+  try {
+    raw = await readFile3(path, "utf8");
+  } catch (err) {
+    if (isNodeError2(err) && err.code === "ENOENT") {
+      return [];
+    }
+    throw err;
+  }
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    return [];
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`registry at ${path} is not valid JSON: ${message}`);
+  }
+  if (!Array.isArray(parsed)) {
+    throw new Error(`registry at ${path} must be a JSON array`);
+  }
+  return parsed.map((item, idx) => {
+    if (typeof item !== "object" || item === null) {
+      throw new Error(`registry entry ${idx} is not an object`);
+    }
+    const e = item;
+    const name = typeof e.name === "string" ? e.name : "";
+    const path2 = typeof e.path === "string" ? e.path : "";
+    if (name.length === 0) {
+      throw new Error(`registry entry ${idx} is missing a non-empty "name"`);
+    }
+    if (path2.length === 0) {
+      throw new Error(`registry entry ${idx} is missing a non-empty "path"`);
+    }
+    return {
+      name,
+      description: typeof e.description === "string" ? e.description : "",
+      path: path2,
+      registered_at: typeof e.registered_at === "string" ? e.registered_at : ""
+    };
+  });
+}
+async function writeRegistry(entries) {
+  const path = getRegistryPath();
+  await mkdir2(dirname2(path), { recursive: true });
+  const body = `${JSON.stringify(entries, null, 2)}
+`;
+  const tmpPath = `${path}.tmp`;
+  await writeFile2(tmpPath, body, "utf8");
+  await rename2(tmpPath, path);
+}
+function pathsEqual(a, b) {
+  if (process.platform === "darwin" || process.platform === "win32") {
+    return a.toLowerCase() === b.toLowerCase();
+  }
+  return a === b;
+}
+async function addEntry(entry) {
+  const existing = await readRegistry();
+  const filtered = existing.filter(
+    (e) => e.name !== entry.name && !pathsEqual(e.path, entry.path)
+  );
+  filtered.push(entry);
+  await writeRegistry(filtered);
+  return filtered;
+}
+async function dropEntry(name) {
+  const existing = await readRegistry();
+  const idx = existing.findIndex((e) => e.name === name);
+  if (idx === -1) {
+    return null;
+  }
+  const [removed] = existing.splice(idx, 1);
+  await writeRegistry(existing);
+  return removed ?? null;
+}
+async function findEntry(params) {
+  const entries = await readRegistry();
+  for (const entry of entries) {
+    if (params.name !== void 0 && entry.name === params.name) return entry;
+    if (params.path !== void 0 && pathsEqual(entry.path, params.path)) {
+      return entry;
+    }
+  }
+  return null;
+}
+async function ensureGlobalDir() {
+  await mkdir2(getGlobalAlmanacDir(), { recursive: true });
+}
+function isNodeError2(err) {
+  return err instanceof Error && "code" in err;
+}
+
+// src/commands/health.ts
+import { existsSync as existsSync6 } from "fs";
+import { readFile as readFile4 } from "fs/promises";
+import { basename as basename2, join as join4 } from "path";
+import fg3 from "fast-glob";
+
+// src/indexer/duration.ts
+function parseDuration(input) {
+  const trimmed = input.trim();
+  const m = trimmed.match(/^(\d+)([mhdw])$/);
+  if (m === null) {
+    throw new Error(
+      `invalid duration "${input}" (expected Nw, Nd, Nh, or Nm \u2014 e.g. 2w, 30d)`
+    );
+  }
+  const n = Number.parseInt(m[1] ?? "0", 10);
+  const unit = m[2];
+  switch (unit) {
+    case "m":
+      return n * 60;
+    case "h":
+      return n * 60 * 60;
+    case "d":
+      return n * 60 * 60 * 24;
+    case "w":
+      return n * 60 * 60 * 24 * 7;
+    default:
+      throw new Error(`invalid duration unit "${unit ?? ""}"`);
+  }
+}
+
+// src/indexer/resolve-wiki.ts
+import { existsSync as existsSync5 } from "fs";
+import { join as join3 } from "path";
+async function resolveWikiRoot(params) {
+  if (params.wiki !== void 0) {
+    const entry = await findEntry({ name: params.wiki });
+    if (entry === null) {
+      throw new Error(`no registered wiki named "${params.wiki}"`);
+    }
+    if (!existsSync5(join3(entry.path, ".almanac"))) {
+      throw new Error(
+        `wiki "${params.wiki}" path is unreachable (${entry.path})`
+      );
+    }
+    return entry.path;
+  }
+  const nearest = findNearestAlmanacDir(params.cwd);
+  if (nearest === null) {
+    throw new Error(
+      "no .almanac/ found in this directory or any parent; run `almanac bootstrap` first"
+    );
+  }
+  return nearest;
+}
+
+// src/topics/dag.ts
+var DAG_DEPTH_CAP = 32;
+function ancestorsInFile(file, slug) {
+  const parentsOf = /* @__PURE__ */ new Map();
+  for (const t of file.topics) {
+    parentsOf.set(t.slug, t.parents);
+  }
+  const ancestors = /* @__PURE__ */ new Set();
+  let frontier = parentsOf.get(slug) ?? [];
+  let depth = 0;
+  while (frontier.length > 0 && depth < DAG_DEPTH_CAP) {
+    const next = [];
+    for (const node of frontier) {
+      if (ancestors.has(node)) continue;
+      ancestors.add(node);
+      const ps = parentsOf.get(node);
+      if (ps !== void 0) next.push(...ps);
+    }
+    frontier = next;
+    depth += 1;
+  }
+  return ancestors;
+}
+function descendantsInDb(db, slug) {
+  const rows = db.prepare(
+    `WITH RECURSIVE desc(slug, depth) AS (
+         SELECT child_slug, 1 FROM topic_parents WHERE parent_slug = ?
+         UNION
+         SELECT tp.child_slug, d.depth + 1
+         FROM topic_parents tp
+         JOIN desc d ON tp.parent_slug = d.slug
+         WHERE d.depth < ?
+       )
+       SELECT DISTINCT slug FROM desc ORDER BY slug`
+  ).all(slug, DAG_DEPTH_CAP).map((r) => r.slug);
+  return rows;
+}
+function subtreeInDb(db, slug) {
+  return [slug, ...descendantsInDb(db, slug)];
+}
+
+// src/commands/health.ts
+var DEFAULT_STALE_SECONDS = 90 * 24 * 60 * 60;
+async function runHealth(options) {
+  const repoRoot = await resolveWikiRoot({ cwd: options.cwd, wiki: options.wiki });
+  await ensureFreshIndex({ repoRoot });
+  const almanacDir = join4(repoRoot, ".almanac");
+  const pagesDir = join4(almanacDir, "pages");
+  const db = openIndex(join4(almanacDir, "index.db"));
+  try {
+    const staleSeconds = options.stale !== void 0 ? parseDuration(options.stale) : DEFAULT_STALE_SECONDS;
+    const scope = resolveScope(db, options);
+    const report = {
+      orphans: findOrphans(db, scope),
+      stale: findStale(db, scope, staleSeconds),
+      dead_refs: await findDeadRefs(db, scope, repoRoot),
+      broken_links: findBrokenLinks(db, scope),
+      broken_xwiki: await findBrokenXwiki(db, scope),
+      empty_topics: findEmptyTopics(db, scope),
+      empty_pages: await findEmptyPages(db, scope, pagesDir),
+      slug_collisions: await findSlugCollisions(pagesDir)
+    };
+    if (options.json === true) {
+      return {
+        stdout: `${JSON.stringify(report, null, 2)}
+`,
+        stderr: "",
+        exitCode: 0
+      };
+    }
+    return {
+      stdout: formatReport(report),
+      stderr: "",
+      exitCode: 0
+    };
+  } finally {
+    db.close();
+  }
+}
+function resolveScope(db, options) {
+  let pages = null;
+  let topics = null;
+  if (options.topic !== void 0) {
+    const rootSlug = toKebabCase(options.topic);
+    if (rootSlug.length > 0) {
+      const subtree = subtreeInDb(db, rootSlug);
+      topics = new Set(subtree);
+      const placeholders = subtree.map(() => "?").join(", ");
+      const rows = db.prepare(
+        `SELECT DISTINCT page_slug FROM page_topics
+           WHERE topic_slug IN (${placeholders})`
+      ).all(...subtree);
+      pages = new Set(rows.map((r) => r.page_slug));
+    }
+  }
+  if (options.stdin === true && options.stdinInput !== void 0) {
+    const stdinPages = /* @__PURE__ */ new Set();
+    for (const line of options.stdinInput.split(/\r?\n/)) {
+      const s = line.trim();
+      if (s.length > 0) stdinPages.add(s);
+    }
+    if (pages === null) pages = stdinPages;
+    else {
+      const out = /* @__PURE__ */ new Set();
+      for (const s of stdinPages) if (pages.has(s)) out.add(s);
+      pages = out;
+    }
+  }
+  return { pages, topics };
+}
+function inPageScope(scope, slug) {
+  if (scope.pages === null) return true;
+  return scope.pages.has(slug);
+}
+function findOrphans(db, scope) {
+  const rows = db.prepare(
+    `SELECT p.slug FROM pages p
+       WHERE p.archived_at IS NULL
+         AND NOT EXISTS (
+           SELECT 1 FROM page_topics pt WHERE pt.page_slug = p.slug
+         )
+       ORDER BY p.slug`
+  ).all();
+  return rows.filter((r) => inPageScope(scope, r.slug));
+}
+function findStale(db, scope, staleSeconds) {
+  const now = Math.floor(Date.now() / 1e3);
+  const threshold = now - staleSeconds;
+  const rows = db.prepare(
+    `SELECT slug, updated_at FROM pages
+       WHERE archived_at IS NULL AND updated_at < ?
+       ORDER BY updated_at ASC`
+  ).all(threshold);
+  return rows.filter((r) => inPageScope(scope, r.slug)).map((r) => ({
+    slug: r.slug,
+    days_since_update: Math.floor((now - r.updated_at) / (60 * 60 * 24))
+  }));
+}
+async function findDeadRefs(db, scope, repoRoot) {
+  const rows = db.prepare(
+    `SELECT p.slug, r.path, r.original_path, r.is_dir
+       FROM file_refs r
+       JOIN pages p ON p.slug = r.page_slug
+       WHERE p.archived_at IS NULL
+       ORDER BY p.slug, r.path`
+  ).all();
+  const out = [];
+  for (const r of rows) {
+    if (!inPageScope(scope, r.slug)) continue;
+    const abs = join4(repoRoot, r.original_path);
+    if (!existsSync6(abs)) {
+      out.push({ slug: r.slug, path: r.original_path });
+    }
+  }
+  return out;
+}
+function findBrokenLinks(db, scope) {
+  const rows = db.prepare(
+    `SELECT w.source_slug, w.target_slug
+       FROM wikilinks w
+       JOIN pages src ON src.slug = w.source_slug
+       LEFT JOIN pages tgt ON tgt.slug = w.target_slug
+       WHERE tgt.slug IS NULL AND src.archived_at IS NULL
+       ORDER BY w.source_slug, w.target_slug`
+  ).all();
+  return rows.filter((r) => inPageScope(scope, r.source_slug));
+}
+async function findBrokenXwiki(db, scope) {
+  const rows = db.prepare(
+    // Same archived-source filter as `findBrokenLinks`. Retired pages
+    // shouldn't spam the report with links to wikis that may have
+    // been intentionally retired too.
+    `SELECT x.source_slug, x.target_wiki, x.target_slug
+       FROM cross_wiki_links x
+       JOIN pages src ON src.slug = x.source_slug
+       WHERE src.archived_at IS NULL
+       ORDER BY x.source_slug, x.target_wiki, x.target_slug`
+  ).all();
+  const out = [];
+  const reachableCache = /* @__PURE__ */ new Map();
+  for (const r of rows) {
+    if (!inPageScope(scope, r.source_slug)) continue;
+    let ok = reachableCache.get(r.target_wiki);
+    if (ok === void 0) {
+      const entry = await findEntry({ name: r.target_wiki });
+      ok = entry !== null && existsSync6(join4(entry.path, ".almanac"));
+      reachableCache.set(r.target_wiki, ok);
+    }
+    if (!ok) {
+      out.push({
+        source_slug: r.source_slug,
+        target_wiki: r.target_wiki,
+        target_slug: r.target_slug
+      });
+    }
+  }
+  return out;
+}
+function findEmptyTopics(db, scope) {
+  const rows = db.prepare(
+    `SELECT t.slug FROM topics t
+       WHERE NOT EXISTS (
+         SELECT 1 FROM page_topics pt WHERE pt.topic_slug = t.slug
+       )
+       ORDER BY t.slug`
+  ).all();
+  if (scope.topics === null) return rows;
+  return rows.filter((r) => scope.topics.has(r.slug));
+}
+async function findEmptyPages(db, scope, pagesDir) {
+  const rows = db.prepare(
+    `SELECT slug, file_path FROM pages
+       WHERE archived_at IS NULL
+       ORDER BY slug`
+  ).all();
+  const out = [];
+  for (const r of rows) {
+    if (!inPageScope(scope, r.slug)) continue;
+    let raw;
+    try {
+      raw = await readFile4(r.file_path, "utf8");
+    } catch {
+      continue;
+    }
+    const m = raw.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?([\s\S]*)$/);
+    const body = m !== null ? m[1] ?? "" : raw;
+    void pagesDir;
+    const hasSubstance = body.split(/\r?\n/).some((l) => {
+      const t = l.trim();
+      if (t.length === 0) return false;
+      if (t.startsWith("#")) return false;
+      return true;
+    });
+    if (!hasSubstance) {
+      out.push({ slug: r.slug });
+    }
+  }
+  return out;
+}
+async function findSlugCollisions(pagesDir) {
+  if (!existsSync6(pagesDir)) return [];
+  const files = await fg3("**/*.md", {
+    cwd: pagesDir,
+    absolute: false,
+    onlyFiles: true,
+    caseSensitiveMatch: true
+  });
+  const bySlug = /* @__PURE__ */ new Map();
+  for (const rel of files) {
+    const slug = toKebabCase(basename2(rel, ".md"));
+    if (slug.length === 0) continue;
+    const list = bySlug.get(slug) ?? [];
+    list.push(rel);
+    bySlug.set(slug, list);
+  }
+  const out = [];
+  for (const [slug, paths] of bySlug.entries()) {
+    if (paths.length > 1) {
+      out.push({ slug, paths: paths.sort() });
+    }
+  }
+  out.sort((a, b) => a.slug.localeCompare(b.slug));
+  return out;
+}
+function formatReport(r) {
+  const sections = [];
+  sections.push(
+    section(
+      "orphans",
+      r.orphans.length,
+      r.orphans.map((o) => `  ${BLUE}${o.slug}${RST}`)
+    )
+  );
+  sections.push(
+    section(
+      "stale",
+      r.stale.length,
+      r.stale.map((s) => `  ${BLUE}${s.slug}${RST}     ${DIM}(${s.days_since_update} days)${RST}`)
+    )
+  );
+  sections.push(
+    section(
+      "dead-refs",
+      r.dead_refs.length,
+      r.dead_refs.map((d) => `  ${BLUE}${d.slug}${RST}  references ${d.path} ${DIM}(missing)${RST}`)
+    )
+  );
+  sections.push(
+    section(
+      "broken-links",
+      r.broken_links.length,
+      r.broken_links.map(
+        (b) => `  ${BLUE}${b.source_slug}${RST} \u2192 ${b.target_slug} ${DIM}(target does not exist)${RST}`
+      )
+    )
+  );
+  sections.push(
+    section(
+      "broken-xwiki",
+      r.broken_xwiki.length,
+      r.broken_xwiki.map(
+        (b) => `  ${BLUE}${b.source_slug}${RST} \u2192 ${b.target_wiki}:${b.target_slug} ${DIM}(wiki unregistered or unreachable)${RST}`
+      )
+    )
+  );
+  sections.push(
+    section(
+      "empty-topics",
+      r.empty_topics.length,
+      r.empty_topics.map((e) => `  ${BLUE}${e.slug}${RST}`)
+    )
+  );
+  sections.push(
+    section(
+      "empty-pages",
+      r.empty_pages.length,
+      r.empty_pages.map((e) => `  ${BLUE}${e.slug}${RST}`)
+    )
+  );
+  sections.push(
+    section(
+      "slug-collisions",
+      r.slug_collisions.length,
+      r.slug_collisions.map((c) => `  ${BLUE}${c.slug}${RST}: ${c.paths.join(", ")}`)
+    )
+  );
+  return `${sections.join("\n\n")}
+`;
+}
+function section(label, count, lines) {
+  if (count === 0) return `${BOLD}${label}${RST} ${GREEN}(0): (ok)${RST}`;
+  return `${BOLD}${label}${RST} ${RED}(${count})${RST}:
+${lines.join("\n")}`;
+}
+
+export {
+  toKebabCase,
+  loadTopicsFile,
+  writeTopicsFile,
+  findTopic,
+  ensureTopic,
+  titleCase,
+  parseFrontmatter,
+  normalizePath,
+  looksLikeDir,
+  openIndex,
+  ensureFreshIndex,
+  runIndexer,
+  readRegistry,
+  addEntry,
+  dropEntry,
+  findEntry,
+  ensureGlobalDir,
+  resolveWikiRoot,
+  ancestorsInFile,
+  descendantsInDb,
+  parseDuration,
+  runHealth
+};
+//# sourceMappingURL=chunk-3C5SY5SE.js.map