diffwiki-core 0.3.0 → 0.4.0-rc.202607220518.0ade9d3

package/dist/index.js

@@ -1,148 +1,72 @@
-// src/errors.ts
-var DiffwikiError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = new.target.name;
-  }
-};
-var CollectionExistsError = class extends DiffwikiError {
-  constructor(name) {
-    super(`collection "${name}" already exists`);
-  }
-};
-var CollectionNotFoundError = class extends DiffwikiError {
-  constructor(name) {
-    super(`collection "${name}" not found`);
-  }
-};
-var NoDefaultCollectionError = class extends DiffwikiError {
-  constructor() {
-    super("no default collection set (use: diffwiki config-set defaultCollection <name>)");
-  }
-};
-var ArticleNotFoundError = class extends DiffwikiError {
-  constructor(target) {
-    super(`article "${target}" not found`);
-  }
-};
-var InvalidTargetError = class extends DiffwikiError {
-  constructor(target, expected) {
-    super(`invalid target "${target}" \u2014 ${expected}`);
-  }
-};
-
-// src/paths.ts
-import os from "os";
-import path from "path";
-function resolveHome() {
-  const override = process.env.DIFFWIKI_HOME;
-  return override && override.length > 0 ? override : path.join(os.homedir(), ".diffwiki");
-}
-function registryPath() {
-  return path.join(resolveHome(), "registry.json");
-}
-function configPath() {
-  return path.join(resolveHome(), "config.json");
-}
-function collectionsDir() {
-  return path.join(resolveHome(), "collections");
-}
-function collectionDir(name) {
-  return path.join(collectionsDir(), name);
-}
+import {
+  ArticleNotFoundError,
+  CollectionExistsError,
+  CollectionNotFoundError,
+  DiffwikiError,
+  InvalidTargetError,
+  NATIVE_ENGINE,
+  NoDefaultCollectionError,
+  PluginError,
+  collectionDir,
+  collectionsDir,
+  configPath,
+  createCollection,
+  deregisterPlugin,
+  emitPluginEvent,
+  findCollection,
+  findEnabledPlugin,
+  listCollections,
+  listEnabledPlugins,
+  listSearchModes,
+  loadSearchProvider,
+  pluginsDir,
+  pluginsRegistryPath,
+  readPluginRegistry,
+  readRegistry,
+  registerCollection,
+  registryPath,
+  removeCollection,
+  resolveHome,
+  spawnPluginClient,
+  unregisterCollection,
+  upsertPlugin,
+  writePluginRegistry,
+  writeRegistry
+} from "./chunk-I3PPUXYY.js";
 
 // src/config.ts
-import fs3 from "fs/promises";
-
-// src/collections.ts
-import fs2 from "fs/promises";
-
-// src/registry.ts
 import fs from "fs/promises";
 function isMissing(err) {
   return err?.code === "ENOENT";
 }
-async function readRegistry() {
-  try {
-    const parsed = JSON.parse(await fs.readFile(registryPath(), "utf8"));
-    return { version: parsed.version ?? 1, collections: parsed.collections ?? [] };
-  } catch (err) {
-    if (isMissing(err)) return { version: 1, collections: [] };
-    throw err;
-  }
-}
-async function writeRegistry(registry) {
-  await fs.mkdir(resolveHome(), { recursive: true });
-  await fs.writeFile(registryPath(), `${JSON.stringify(registry, null, 2)}
-`, "utf8");
-}
-async function registerCollection(entry) {
-  const registry = await readRegistry();
-  const index = registry.collections.findIndex((c) => c.name === entry.name);
-  if (index >= 0) {
-    registry.collections[index] = entry;
-  } else {
-    registry.collections.push(entry);
-  }
-  await writeRegistry(registry);
-}
-async function unregisterCollection(name) {
-  const registry = await readRegistry();
-  registry.collections = registry.collections.filter((c) => c.name !== name);
-  await writeRegistry(registry);
-}
-
-// src/collections.ts
-async function listCollections() {
-  return (await readRegistry()).collections;
-}
-async function findCollection(name) {
-  return (await readRegistry()).collections.find((c) => c.name === name);
-}
-async function createCollection(name) {
-  if (await findCollection(name)) throw new CollectionExistsError(name);
-  const dir = collectionDir(name);
-  await fs2.mkdir(dir, { recursive: true });
-  const entry = {
-    name,
-    type: "global",
-    path: dir,
-    createdAt: (/* @__PURE__ */ new Date()).toISOString()
-  };
-  await registerCollection(entry);
-  return entry;
-}
-async function removeCollection(name) {
-  const entry = await findCollection(name);
-  if (!entry) throw new CollectionNotFoundError(name);
-  await unregisterCollection(name);
-  if (entry.type === "global") {
-    await fs2.rm(entry.path, { recursive: true, force: true });
-  }
-  return entry;
-}
-
-// src/config.ts
-function isMissing2(err) {
-  return err?.code === "ENOENT";
-}
 async function readConfig() {
   try {
-    return JSON.parse(await fs3.readFile(configPath(), "utf8"));
+    return JSON.parse(await fs.readFile(configPath(), "utf8"));
   } catch (err) {
-    if (isMissing2(err)) return {};
+    if (isMissing(err)) return {};
     throw err;
   }
 }
 async function writeConfig(config) {
-  await fs3.mkdir(resolveHome(), { recursive: true });
-  await fs3.writeFile(configPath(), `${JSON.stringify(config, null, 2)}
+  await fs.mkdir(resolveHome(), { recursive: true });
+  await fs.writeFile(configPath(), `${JSON.stringify(config, null, 2)}
 `, "utf8");
 }
 async function setConfigValue(key, value) {
   if (key === "defaultCollection" && !await findCollection(value)) {
     throw new CollectionNotFoundError(value);
   }
+  if (key === "defaultSearch") {
+    const engine = value.split(":")[0];
+    if (engine !== NATIVE_ENGINE) {
+      const enabled = await listEnabledPlugins("search");
+      if (!enabled.some((p) => p.name === engine)) {
+        console.warn(
+          `! defaultSearch "${value}" names an engine that is not installed/enabled \u2014 native will be used until it is`
+        );
+      }
+    }
+  }
   const config = await readConfig();
   config[key] = value;
   await writeConfig(config);
@@ -161,23 +85,60 @@ function slugify(input) {
 
 // src/frontmatter.ts
 import matter from "gray-matter";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+var YAML_ENGINE = {
+  parse: (input) => {
+    const data = parseYaml(input);
+    return data && typeof data === "object" ? data : {};
+  },
+  stringify: (data) => stringifyYaml(data)
+};
+var MATTER_OPTS = { engines: { yaml: YAML_ENGINE } };
+function parseFallback(raw) {
+  const fenceRe = /^---[ \t]*\n([\s\S]*?)\n---[ \t]*\n/;
+  const fenceMatch = fenceRe.exec(raw);
+  let title = "";
+  let body;
+  if (fenceMatch) {
+    const inner = fenceMatch[1];
+    const titleMatch = /^title:\s*(.+)$/m.exec(inner);
+    if (titleMatch) {
+      title = titleMatch[1].trim().replace(/^["']|["']$/g, "");
+    }
+    body = raw.slice(fenceMatch[0].length);
+  } else {
+    body = raw;
+  }
+  return { title, tags: [], body: body.replace(/^\n+/, "") };
+}
 function parseArticle(raw) {
-  const { data, content } = matter(raw);
-  const title = typeof data.title === "string" ? data.title : "";
-  const tags = Array.isArray(data.tags) ? data.tags.map((t) => String(t)) : [];
-  const created = typeof data.created === "string" ? data.created : void 0;
-  return { title, tags, created, body: content.replace(/^\n+/, "") };
+  try {
+    const { data, content } = matter(raw, MATTER_OPTS);
+    const title = typeof data.title === "string" ? data.title : "";
+    const tags = Array.isArray(data.tags) ? data.tags.map((t) => String(t)) : [];
+    const created = typeof data.created === "string" ? data.created : void 0;
+    return { title, tags, created, body: content.replace(/^\n+/, "") };
+  } catch {
+    return parseFallback(raw);
+  }
 }
 function serializeArticle(article) {
   const front = { title: article.title, tags: article.tags };
   if (article.created) front.created = article.created;
   if (article.updated) front.updated = article.updated;
-  return matter.stringify(article.body, front);
+  return matter.stringify(article.body, front, MATTER_OPTS);
 }
 
 // src/articles.ts
-import fs4 from "fs/promises";
-import path2 from "path";
+import fs2 from "fs/promises";
+import path from "path";
+async function fireHook(event, collection, relPath) {
+  try {
+    const { emitPluginEvent: emitPluginEvent2 } = await import("./events-656CR64Q.js");
+    await emitPluginEvent2(event, collection, relPath);
+  } catch {
+  }
+}
 function parseAddTarget(target) {
   const idx = target.indexOf(":");
   if (idx === -1) {
@@ -210,37 +171,38 @@ async function resolveCollectionDir(name) {
 }
 function ensureMdPath(file) {
   if (/\.mdx?$/.test(file)) return file;
-  const dir = path2.dirname(file);
-  const base = slugify(path2.basename(file));
-  const rel = dir === "." ? `${base}.md` : path2.join(dir, `${base}.md`);
+  const dir = path.dirname(file);
+  const base = slugify(path.basename(file));
+  const rel = dir === "." ? `${base}.md` : path.join(dir, `${base}.md`);
   return rel;
 }
 async function createArticle(opts) {
   const { collection, title } = parseAddTarget(opts.target);
   const { name, dir } = await resolveCollectionDir(collection);
-  const filePath = path2.join(dir, `${slugify(title)}.md`);
+  const filePath = path.join(dir, `${slugify(title)}.md`);
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const body = opts.body ?? `# ${title}
 `;
-  await fs4.mkdir(dir, { recursive: true });
-  await fs4.writeFile(filePath, serializeArticle({ title, tags: opts.tags, created: now, updated: now, body }), "utf8");
+  await fs2.mkdir(dir, { recursive: true });
+  await fs2.writeFile(filePath, serializeArticle({ title, tags: opts.tags, created: now, updated: now, body }), "utf8");
+  void fireHook("article-created", name, path.relative(dir, filePath));
   return { title, tags: opts.tags, path: filePath, collection: name };
 }
 async function loadArticle(target) {
   const { collection, file } = parsePathTarget(target);
   const { dir } = await resolveCollectionDir(collection);
-  const filePath = path2.join(dir, ensureMdPath(file));
+  const filePath = path.join(dir, ensureMdPath(file));
   try {
-    return { filePath, raw: await fs4.readFile(filePath, "utf8"), collection };
+    return { filePath, dir, raw: await fs2.readFile(filePath, "utf8"), collection };
   } catch (err) {
     if (err.code === "ENOENT") throw new ArticleNotFoundError(target);
     throw err;
   }
 }
 async function updateArticleBody(target, body) {
-  const { filePath, raw, collection } = await loadArticle(target);
+  const { filePath, dir, raw, collection } = await loadArticle(target);
   const parsed = parseArticle(raw);
-  await fs4.writeFile(
+  await fs2.writeFile(
     filePath,
     serializeArticle({
       title: parsed.title,
@@ -251,13 +213,14 @@ async function updateArticleBody(target, body) {
     }),
     "utf8"
   );
+  void fireHook("article-updated", collection, path.relative(dir, filePath));
   return { title: parsed.title, tags: parsed.tags, path: filePath, collection };
 }
 async function mutateTags(target, fn) {
-  const { filePath, raw, collection } = await loadArticle(target);
+  const { filePath, dir, raw, collection } = await loadArticle(target);
   const parsed = parseArticle(raw);
   const tags = fn(parsed.tags);
-  await fs4.writeFile(
+  await fs2.writeFile(
     filePath,
     serializeArticle({
       title: parsed.title,
@@ -268,6 +231,7 @@ async function mutateTags(target, fn) {
     }),
     "utf8"
   );
+  void fireHook("article-updated", collection, path.relative(dir, filePath));
   return { title: parsed.title, tags, path: filePath, collection };
 }
 function addTags(target, tags) {
@@ -281,34 +245,35 @@ function setTags(target, tags) {
   return mutateTags(target, () => Array.from(new Set(tags)));
 }
 async function removeArticle(target) {
-  const { filePath } = await loadArticle(target);
-  await fs4.rm(filePath);
+  const { filePath, dir, collection } = await loadArticle(target);
+  await fs2.rm(filePath);
+  void fireHook("article-removed", collection, path.relative(dir, filePath));
   return filePath;
 }
 
 // src/repo.ts
-import fs5 from "fs/promises";
-import path3 from "path";
+import fs3 from "fs/promises";
+import path2 from "path";
 import { execFile } from "child_process";
 import { promisify } from "util";
-import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { parse as parseYaml2, stringify as stringifyYaml2 } from "yaml";
 var execFileAsync = promisify(execFile);
 var REPO_CONFIG_FILE = "diffwiki.yaml";
 async function detectRepoName(cwd) {
   try {
     const { stdout } = await execFileAsync("git", ["rev-parse", "--show-toplevel"], { cwd });
-    return path3.basename(stdout.trim());
+    return path2.basename(stdout.trim());
   } catch {
-    return path3.basename(path3.resolve(cwd));
+    return path2.basename(path2.resolve(cwd));
   }
 }
 async function readRepoConfig(cwd) {
   try {
-    const raw = await fs5.readFile(path3.join(cwd, REPO_CONFIG_FILE), "utf8");
-    const parsed = parseYaml(raw) ?? {};
+    const raw = await fs3.readFile(path2.join(cwd, REPO_CONFIG_FILE), "utf8");
+    const parsed = parseYaml2(raw) ?? {};
     if (!parsed.path) return void 0;
     return {
-      collection: parsed.collection ?? path3.basename(path3.resolve(cwd)),
+      collection: parsed.collection ?? path2.basename(path2.resolve(cwd)),
       path: parsed.path
     };
   } catch (err) {
@@ -317,9 +282,9 @@ async function readRepoConfig(cwd) {
   }
 }
 async function initRepoWiki(opts) {
-  const cwd = path3.resolve(opts.cwd);
+  const cwd = path2.resolve(opts.cwd);
   const wikiPath = opts.wikiPath ?? "wiki";
-  const absWiki = path3.join(cwd, wikiPath);
+  const absWiki = path2.join(cwd, wikiPath);
   let name = opts.collection ?? await detectRepoName(cwd);
   const existing = await findCollection(name);
   if (existing && existing.path !== absWiki) {
@@ -334,9 +299,9 @@ async function initRepoWiki(opts) {
       n += 1;
     }
   }
-  await fs5.mkdir(absWiki, { recursive: true });
+  await fs3.mkdir(absWiki, { recursive: true });
   const config = { collection: name, path: wikiPath };
-  await fs5.writeFile(path3.join(cwd, REPO_CONFIG_FILE), stringifyYaml(config), "utf8");
+  await fs3.writeFile(path2.join(cwd, REPO_CONFIG_FILE), stringifyYaml2(config), "utf8");
   const entry = {
     name,
     type: "repo",
@@ -348,44 +313,356 @@ async function initRepoWiki(opts) {
 }
 
 // src/query.ts
-import fs6 from "fs/promises";
-import path4 from "path";
-async function query(term, collection) {
-  let targets;
+import fs4 from "fs/promises";
+import path3 from "path";
+async function collectMarkdownFiles(dir) {
+  let entries;
+  try {
+    entries = await fs4.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const entry of entries) {
+    const full = path3.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await collectMarkdownFiles(full));
+    } else if (entry.isFile() && /\.mdx?$/.test(entry.name)) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+var K1 = 1.5;
+var B = 0.75;
+var FIELD_WEIGHTS = { title: 3, tags: 2, collection: 1.5, body: 1 };
+function tokenize(text) {
+  return text.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 0);
+}
+function termFreqs(tokens) {
+  const freqs = /* @__PURE__ */ new Map();
+  for (const t of tokens) {
+    freqs.set(t, (freqs.get(t) ?? 0) + 1);
+  }
+  return freqs;
+}
+function bm25FieldScore(queryTerms, fieldTokens, avgFieldLen, idf) {
+  const tf = termFreqs(fieldTokens);
+  const dl = fieldTokens.length;
+  const avgDl = avgFieldLen || 1;
+  let score = 0;
+  for (const term of queryTerms) {
+    const freq = tf.get(term) ?? 0;
+    if (freq === 0) continue;
+    const termIdf = idf.get(term) ?? 0;
+    const numerator = freq * (K1 + 1);
+    const denominator = freq + K1 * (1 - B + B * (dl / avgDl));
+    score += termIdf * (numerator / denominator);
+  }
+  return score;
+}
+async function nativeSearch(term, collections, collection) {
+  let targets = collections;
   if (collection) {
-    const one = await findCollection(collection);
+    const one = collections.find((c) => c.name === collection);
     if (!one) throw new CollectionNotFoundError(collection);
     targets = [one];
-  } else {
-    targets = await listCollections();
   }
-  const needle = term.toLowerCase();
-  const hits = [];
+  const docs = [];
   for (const entry of targets) {
-    let files;
-    try {
-      files = await fs6.readdir(entry.path);
-    } catch {
-      continue;
+    for (const full of await collectMarkdownFiles(entry.path)) {
+      const fallbackTitle = path3.basename(full).replace(/\.mdx?$/, "");
+      let title = fallbackTitle;
+      let tags = [];
+      let body = "";
+      try {
+        const parsed = parseArticle(await fs4.readFile(full, "utf8"));
+        if (parsed.title) title = parsed.title;
+        tags = parsed.tags;
+        body = parsed.body;
+      } catch {
+      }
+      docs.push({
+        collectionName: entry.name,
+        filePath: full,
+        title,
+        tags,
+        fields: {
+          title: tokenize(title),
+          tags: tokenize(tags.join(" ")),
+          collection: tokenize(entry.name),
+          body: tokenize(body)
+        }
+      });
+    }
+  }
+  if (!term.trim()) {
+    return docs.map((d) => ({
+      collection: d.collectionName,
+      path: d.filePath,
+      title: d.title,
+      tags: d.tags
+    }));
+  }
+  const queryTerms = tokenize(term);
+  if (queryTerms.length === 0) {
+    return docs.map((d) => ({
+      collection: d.collectionName,
+      path: d.filePath,
+      title: d.title,
+      tags: d.tags
+    }));
+  }
+  const docTokenSets = docs.map(
+    (doc) => /* @__PURE__ */ new Set([...doc.fields.title, ...doc.fields.tags, ...doc.fields.collection, ...doc.fields.body])
+  );
+  const N = docs.length;
+  const idf = /* @__PURE__ */ new Map();
+  for (const qt of queryTerms) {
+    let docFreq = 0;
+    for (const tokenSet of docTokenSets) {
+      if (tokenSet.has(qt)) docFreq++;
+    }
+    idf.set(qt, Math.log((N - docFreq + 0.5) / (docFreq + 0.5) + 1));
+  }
+  const avgLens = {
+    title: docs.reduce((sum, d) => sum + d.fields.title.length, 0) / (N || 1),
+    tags: docs.reduce((sum, d) => sum + d.fields.tags.length, 0) / (N || 1),
+    collection: docs.reduce((sum, d) => sum + d.fields.collection.length, 0) / (N || 1),
+    body: docs.reduce((sum, d) => sum + d.fields.body.length, 0) / (N || 1)
+  };
+  const scored = [];
+  for (const doc of docs) {
+    const titleScore = bm25FieldScore(queryTerms, doc.fields.title, avgLens.title, idf) * FIELD_WEIGHTS.title;
+    const tagsScore = bm25FieldScore(queryTerms, doc.fields.tags, avgLens.tags, idf) * FIELD_WEIGHTS.tags;
+    const collScore = bm25FieldScore(queryTerms, doc.fields.collection, avgLens.collection, idf) * FIELD_WEIGHTS.collection;
+    const bodyScore = bm25FieldScore(queryTerms, doc.fields.body, avgLens.body, idf) * FIELD_WEIGHTS.body;
+    const total = titleScore + tagsScore + collScore + bodyScore;
+    if (total > 0) {
+      scored.push({ doc, score: total });
     }
-    for (const file of files) {
-      if (!/\.mdx?$/.test(file)) continue;
-      const full = path4.join(entry.path, file);
-      const parsed = parseArticle(await fs6.readFile(full, "utf8"));
-      const haystack = [parsed.title, file, ...parsed.tags].join(" ").toLowerCase();
-      if (!needle || haystack.includes(needle)) {
-        hits.push({ collection: entry.name, path: full, title: parsed.title, tags: parsed.tags });
+  }
+  scored.sort((a, b) => b.score - a.score);
+  return scored.map((s) => ({
+    collection: s.doc.collectionName,
+    path: s.doc.filePath,
+    title: s.doc.title,
+    tags: s.doc.tags,
+    score: s.score
+  }));
+}
+async function resolveDefaultEngine() {
+  const config = await readConfig();
+  const enabled = await listEnabledPlugins("search");
+  const configured = config.defaultSearch?.split(":")[0];
+  if (configured && enabled.some((p) => p.name === configured)) return configured;
+  if (enabled.length > 0) return enabled[0].name;
+  return NATIVE_ENGINE;
+}
+async function resolveDefaultSearchMode() {
+  const config = await readConfig();
+  const enabled = await listEnabledPlugins("search");
+  const configured = config.defaultSearch?.split(":")[0];
+  const configuredType = config.defaultSearch?.split(":")[1];
+  let engine = NATIVE_ENGINE;
+  if (configured && enabled.some((p) => p.name === configured)) engine = configured;
+  else if (enabled.length > 0) engine = enabled[0].name;
+  if (engine === NATIVE_ENGINE) return { engine, type: "basic" };
+  const modes = await listSearchModes();
+  const engineModes = modes.filter((m) => m.plugin === engine);
+  if (engineModes.length === 0) return { engine: NATIVE_ENGINE, type: "basic" };
+  if (configuredType && engineModes.some((m) => m.type === configuredType)) {
+    return { engine, type: configuredType };
+  }
+  return { engine, type: engineModes[0].type };
+}
+async function query(term, opts) {
+  const collections = await listCollections();
+  const engine = opts?.engine ?? await resolveDefaultEngine();
+  if (engine === NATIVE_ENGINE) return nativeSearch(term, collections, opts?.collection);
+  const provider = await loadSearchProvider(engine);
+  if (!provider) return nativeSearch(term, collections, opts?.collection);
+  try {
+    return await provider.search(term, collections, opts);
+  } catch {
+    return nativeSearch(term, collections, opts?.collection);
+  } finally {
+    await provider.close();
+  }
+}
+
+// src/doctor.ts
+import fs6 from "fs/promises";
+
+// src/plugins/manager.ts
+import fs5 from "fs/promises";
+import path4 from "path";
+import { execFile as execFile2 } from "child_process";
+import { promisify as promisify2 } from "util";
+var run = promisify2(execFile2);
+async function readPackageJson(file) {
+  try {
+    return JSON.parse(await fs5.readFile(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function binOf(manifest) {
+  if (typeof manifest.bin === "string") return manifest.bin;
+  if (manifest.bin && typeof manifest.bin === "object") {
+    const first = Object.values(manifest.bin)[0];
+    return typeof first === "string" ? first : null;
+  }
+  return null;
+}
+async function pluginManifestDirs(nodeModules) {
+  let entries;
+  try {
+    entries = await fs5.readdir(nodeModules);
+  } catch {
+    return [];
+  }
+  const dirs = [];
+  for (const entry of entries) {
+    if (entry.startsWith(".")) continue;
+    if (entry.startsWith("@")) {
+      let scoped;
+      try {
+        scoped = await fs5.readdir(path4.join(nodeModules, entry));
+      } catch {
+        continue;
       }
+      for (const pkg of scoped) {
+        if (pkg.startsWith(".")) continue;
+        dirs.push(path4.join(nodeModules, entry, pkg));
+      }
+    } else {
+      dirs.push(path4.join(nodeModules, entry));
     }
   }
-  return hits;
+  return dirs;
+}
+async function ensurePluginRoot() {
+  const dir = pluginsDir();
+  await fs5.mkdir(dir, { recursive: true });
+  const pkgPath = path4.join(dir, "package.json");
+  if (await readPackageJson(pkgPath) === null) {
+    const pkg = { name: "diffwiki-plugins", private: true, version: "0.0.0" };
+    await fs5.writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}
+`, "utf8");
+  }
+  return dir;
+}
+async function discoverSearchPackage(dir) {
+  const nodeModules = path4.join(dir, "node_modules");
+  for (const pkgDir of await pluginManifestDirs(nodeModules)) {
+    const manifest = await readPackageJson(path4.join(pkgDir, "package.json"));
+    if (!manifest?.name || manifest.diffwiki?.kind !== "search") continue;
+    const bin = binOf(manifest);
+    if (!bin) continue;
+    return { name: manifest.name, version: manifest.version, binAbs: path4.resolve(pkgDir, bin) };
+  }
+  return null;
+}
+async function bestEffortClose(provider) {
+  try {
+    await provider?.close();
+  } catch {
+  }
+}
+async function runSetup(name, prefetchModels) {
+  let provider = null;
+  try {
+    provider = await loadSearchProvider(name);
+    if (provider) {
+      await provider.setup(await listCollections(), { embed: false, prefetchModels });
+    }
+  } catch {
+  } finally {
+    await bestEffortClose(provider);
+  }
+}
+async function installPlugin(spec, opts) {
+  const dir = await ensurePluginRoot();
+  try {
+    await run("npm", ["install", spec, "--prefix", dir]);
+  } catch (err) {
+    throw new PluginError(`npm install ${spec} failed: ${err.message}`);
+  }
+  const discovered = await discoverSearchPackage(dir);
+  if (!discovered) {
+    throw new PluginError(
+      `no diffwiki search plugin found in "${spec}" (need package.json diffwiki.kind === "search" + bin)`
+    );
+  }
+  const record = {
+    name: discovered.name,
+    kind: "search",
+    command: ["node", discovered.binAbs],
+    version: discovered.version,
+    enabled: true,
+    managed: true
+  };
+  await upsertPlugin(record);
+  if (opts?.setup !== false) {
+    await runSetup(record.name, !!opts?.prefetchModels);
+  }
+  return record;
+}
+async function registerPlugin(name, command) {
+  if (command.length === 0) throw new PluginError(`register "${name}": --command must not be empty`);
+  const record = { name, kind: "search", command, enabled: true, managed: false };
+  await upsertPlugin(record);
+  const provider = await loadSearchProvider(name);
+  if (!provider) {
+    await deregisterPlugin(name);
+    throw new PluginError(`plugin "${name}" did not spawn as a search plugin (command: ${command.join(" ")})`);
+  }
+  try {
+    await provider.setup(await listCollections(), { embed: false, prefetchModels: false });
+  } catch {
+  } finally {
+    await bestEffortClose(provider);
+  }
+  return record;
+}
+async function removePlugin(name) {
+  const record = (await readPluginRegistry()).plugins.find((p) => p.name === name);
+  if (!record) throw new PluginError(`plugin "${name}" is not registered`);
+  if (record.managed) {
+    const dir = await ensurePluginRoot();
+    try {
+      await run("npm", ["uninstall", name, "--prefix", dir]);
+    } catch {
+    }
+  }
+  await deregisterPlugin(name);
+}
+async function probeSpawnable(name) {
+  let provider = null;
+  try {
+    provider = await loadSearchProvider(name);
+    return provider !== null;
+  } catch {
+    return false;
+  } finally {
+    await bestEffortClose(provider);
+  }
+}
+async function listPlugins() {
+  const registry = await readPluginRegistry();
+  const out = [];
+  for (const record of registry.plugins) {
+    const spawnable = record.enabled ? await probeSpawnable(record.name) : false;
+    out.push({ ...record, spawnable });
+  }
+  return out;
 }
 
 // src/doctor.ts
-import fs7 from "fs/promises";
 async function exists(target) {
   try {
-    await fs7.access(target);
+    await fs6.access(target);
     return true;
   } catch {
     return false;
@@ -418,46 +695,364 @@ async function doctor() {
   } else {
     out.push({ level: "warn", message: "no default collection set" });
   }
+  await appendPluginDiagnostics(out, config);
   return out;
 }
+function readinessLine(name, health) {
+  const r = health.readiness;
+  if (!r) {
+    return { level: health.ready ? "ok" : "warn", message: `plugin "${name}" ${health.ready ? "ready" : "not ready"}` };
+  }
+  if (r.firstSearchCost === "model-download") {
+    return {
+      level: "warn",
+      message: `plugin "${name}": ${r.docsIndexed} doc(s) indexed \u2014 first search will download models (~2GB)`
+    };
+  }
+  if (r.firstSearchCost === "model-load") {
+    return {
+      level: "warn",
+      message: `plugin "${name}": ${r.docsIndexed} doc(s) indexed \u2014 first search loads models (a few seconds)`
+    };
+  }
+  return { level: "ok", message: `plugin "${name}": ${r.docsIndexed} doc(s) indexed \u2014 first search is instant` };
+}
+async function appendPluginDiagnostics(out, config) {
+  let plugins = [];
+  try {
+    plugins = await listPlugins();
+  } catch (err) {
+    out.push({ level: "error", message: `failed to read plugin registry: ${err.message}` });
+    return;
+  }
+  if (plugins.length === 0) {
+    out.push({ level: "warn", message: "no search plugins installed \u2014 using built-in native search" });
+  }
+  const collections = await listCollections();
+  for (const p of plugins) {
+    if (!p.enabled) {
+      out.push({ level: "warn", message: `plugin "${p.name}" registered but disabled` });
+      continue;
+    }
+    if (!p.spawnable) {
+      out.push({
+        level: "error",
+        message: `plugin "${p.name}" registered but its command is not spawnable: ${p.command.join(" ")}`
+      });
+      continue;
+    }
+    out.push({ level: "ok", message: `plugin "${p.name}" enabled and spawnable` });
+    let provider = null;
+    try {
+      provider = await loadSearchProvider(p.name);
+      if (!provider) {
+        out.push({ level: "error", message: `plugin "${p.name}" failed to load for a health check` });
+        continue;
+      }
+      const health = await provider.health(collections);
+      for (const d of health.diagnostics) out.push({ level: d.level, message: `${p.name} \xB7 ${d.message}` });
+      out.push(readinessLine(p.name, health));
+    } catch (err) {
+      out.push({ level: "error", message: `plugin "${p.name}" health check failed: ${err.message}` });
+    } finally {
+      try {
+        await provider?.close();
+      } catch {
+      }
+    }
+  }
+  if (config.defaultSearch) {
+    const engine = config.defaultSearch.split(":")[0];
+    const known = engine === NATIVE_ENGINE || plugins.some((p) => p.name === engine && p.enabled);
+    if (!known) {
+      out.push({
+        level: "warn",
+        message: `defaultSearch "${config.defaultSearch}" is not installed/enabled \u2014 using native`
+      });
+    }
+  }
+}
+
+// src/browse.ts
+import fs7 from "fs/promises";
+import path5 from "path";
+var INDEX_RE = /^(index|readme)\.mdx?$/i;
+function buildArticleTree(relPaths) {
+  const root = {};
+  for (const raw of relPaths) {
+    const rel = raw.replace(/\\/g, "/").replace(/^\/+/, "");
+    if (!rel) continue;
+    const segs = rel.split("/");
+    let cur = root;
+    segs.forEach((seg, i) => {
+      if (i === segs.length - 1) {
+        if (!(seg in cur)) cur[seg] = null;
+      } else {
+        if (cur[seg] === null || !(seg in cur)) cur[seg] = {};
+        cur = cur[seg];
+      }
+    });
+  }
+  const stripExt = (f) => f.replace(/\.(mdx?)$/, "");
+  const walk = (trie, parents) => {
+    const entries = Object.entries(trie);
+    const branches = entries.filter(([, v]) => v !== null);
+    const leaves = entries.filter(([, v]) => v === null).map(([k]) => k).filter((f) => !INDEX_RE.test(f));
+    branches.sort(([a], [b]) => a.toLowerCase().localeCompare(b.toLowerCase()));
+    leaves.sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
+    const branchNodes = branches.map(([seg, sub]) => ({
+      name: seg,
+      title: seg,
+      // Folders are navigable to their index page (an authored index.md/README,
+      // else a generated listing).
+      slug: [...parents, seg].join("/"),
+      children: walk(sub, [...parents, seg])
+    }));
+    const leafNodes = leaves.map((file) => {
+      const nameNoExt = stripExt(file);
+      return { name: nameNoExt, title: nameNoExt, slug: [...parents, nameNoExt].join("/") };
+    });
+    return [...branchNodes, ...leafNodes];
+  };
+  return walk(root, []);
+}
+async function collectRelPaths(dir, rel = "") {
+  let dirents;
+  try {
+    dirents = await fs7.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const d of dirents) {
+    if (d.name.startsWith(".")) continue;
+    const childRel = rel ? `${rel}/${d.name}` : d.name;
+    if (d.isDirectory()) {
+      out.push(...await collectRelPaths(path5.join(dir, d.name), childRel));
+    } else if (/\.(mdx?)$/.test(d.name)) {
+      out.push(childRel);
+    }
+  }
+  return out;
+}
+async function readdirSafe(dir) {
+  try {
+    return await fs7.readdir(dir);
+  } catch {
+    return [];
+  }
+}
+function pickIndexFile(names) {
+  const rank = (n) => {
+    const lower = n.toLowerCase();
+    const base = lower.startsWith("index") ? 0 : 1;
+    const ext = lower.endsWith(".mdx") ? 0 : 1;
+    return base * 2 + ext;
+  };
+  return names.filter((n) => INDEX_RE.test(n)).sort((a, b) => rank(a) - rank(b))[0];
+}
+async function cheapTitle(absPath) {
+  let handle;
+  try {
+    handle = await fs7.open(absPath, "r");
+    const buf = Buffer.alloc(512);
+    const { bytesRead } = await handle.read(buf, 0, 512, 0);
+    const snippet = buf.subarray(0, bytesRead).toString("utf8");
+    const m = snippet.match(/^---[\s\S]*?^title:\s*(.+)$/m);
+    if (m) return m[1].trim().replace(/^["']|["']$/g, "");
+  } catch {
+  } finally {
+    await handle?.close();
+  }
+  return void 0;
+}
+async function enrichTitles(nodes, collDir) {
+  return Promise.all(
+    nodes.map(async (node) => {
+      if (node.children) {
+        const children = await enrichTitles(node.children, collDir);
+        let title = node.title;
+        if (node.slug) {
+          const dir = path5.join(collDir, node.slug);
+          const idx = pickIndexFile(await readdirSafe(dir));
+          if (idx) title = await cheapTitle(path5.join(dir, idx)) ?? title;
+        }
+        return { ...node, title, children };
+      }
+      for (const ext of [".mdx", ".md"]) {
+        const title = await cheapTitle(path5.join(collDir, `${node.slug}${ext}`));
+        if (title) return { ...node, title };
+      }
+      return node;
+    })
+  );
+}
+async function listArticleTree(coll) {
+  const entry = await findCollection(coll);
+  if (!entry) throw new CollectionNotFoundError(coll);
+  const rels = await collectRelPaths(entry.path);
+  return enrichTitles(buildArticleTree(rels), path5.resolve(entry.path));
+}
+async function readArticle(coll, slug) {
+  const entry = await findCollection(coll);
+  if (!entry) throw new CollectionNotFoundError(coll);
+  const collDir = path5.resolve(entry.path);
+  const normalized = slug.replace(/\\/g, "/");
+  if (normalized.split("/").some((s) => s === "..")) {
+    throw new InvalidTargetError(slug, "path traversal detected");
+  }
+  const safeSlug = normalized.split("/").filter((s) => s !== "" && s !== ".").join("/");
+  const inJail = (p) => p === collDir || p.startsWith(collDir + path5.sep);
+  let abs;
+  for (const rel of safeSlug ? [`${safeSlug}.mdx`, `${safeSlug}.md`] : []) {
+    const candidate = path5.resolve(collDir, rel);
+    if (!inJail(candidate)) throw new InvalidTargetError(slug, "path traversal detected");
+    try {
+      await fs7.access(candidate);
+      abs = candidate;
+      break;
+    } catch {
+    }
+  }
+  if (!abs) {
+    const dir = path5.resolve(collDir, safeSlug);
+    if (inJail(dir)) {
+      const idx = pickIndexFile(await readdirSafe(dir));
+      if (idx) abs = path5.join(dir, idx);
+    }
+  }
+  if (!abs) throw new ArticleNotFoundError(`${coll}/${safeSlug}`);
+  const parsed = parseArticle(await fs7.readFile(abs, "utf8"));
+  const title = parsed.title?.trim() || (safeSlug ? safeSlug.split("/").pop() ?? safeSlug : coll);
+  return { coll, slug: safeSlug, title, tags: parsed.tags, body: parsed.body, path: abs };
+}
+
+// src/render.ts
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import remarkGfm from "remark-gfm";
+import remarkRehype from "remark-rehype";
+import rehypeSlug from "rehype-slug";
+import rehypeShiki from "@shikijs/rehype";
+import rehypeStringify from "rehype-stringify";
+import { visit, SKIP } from "unist-util-visit";
+import { toString as hastToString } from "hast-util-to-string";
+var LANG_ALIASES = {
+  "c#": "csharp",
+  cs: "csharp",
+  "c++": "cpp",
+  cxx: "cpp",
+  hs: "haskell",
+  ex: "elixir"
+};
+function rehypeCollectToc(toc) {
+  return (tree) => {
+    visit(tree, "element", (node) => {
+      if (node.tagName !== "h2" && node.tagName !== "h3") return;
+      const id = node.properties?.id;
+      if (!id) return;
+      toc.push({ slug: String(id), text: hastToString(node), depth: node.tagName === "h2" ? 2 : 3 });
+    });
+  };
+}
+function rehypeStripLeadingH1() {
+  return (tree) => {
+    let removed = false;
+    visit(tree, "element", (node, index, parent) => {
+      if (!removed && node.tagName === "h1" && parent && index != null) {
+        parent.children.splice(index, 1);
+        removed = true;
+        return [SKIP, index];
+      }
+    });
+  };
+}
+function rehypeMarkMermaid() {
+  return (tree) => {
+    visit(tree, "element", (node) => {
+      if (node.tagName !== "pre") return;
+      const code = node.children.find((c) => c.type === "element" && c.tagName === "code");
+      const cls = code?.properties?.className ?? [];
+      if (!code || !cls.includes("language-mermaid")) return;
+      const source = hastToString(code);
+      node.properties = { className: ["mermaid"] };
+      node.children = [{ type: "text", value: source }];
+    });
+  };
+}
+async function renderArticle(body) {
+  const toc = [];
+  const file = await unified().use(remarkParse).use(remarkGfm).use(remarkRehype).use(rehypeSlug).use(rehypeCollectToc, toc).use(rehypeStripLeadingH1).use(rehypeMarkMermaid).use(rehypeShiki, {
+    themes: { light: "github-light", dark: "github-dark" },
+    defaultColor: false,
+    langAlias: LANG_ALIASES,
+    fallbackLanguage: "plaintext"
+  }).use(rehypeStringify).process(body);
+  return { html: String(file), toc };
+}
 export {
   ArticleNotFoundError,
   CollectionExistsError,
   CollectionNotFoundError,
   DiffwikiError,
   InvalidTargetError,
+  NATIVE_ENGINE,
   NoDefaultCollectionError,
+  PluginError,
   REPO_CONFIG_FILE,
   addTags,
+  buildArticleTree,
   collectionDir,
   collectionsDir,
   configPath,
   createArticle,
   createCollection,
+  deregisterPlugin,
   doctor,
+  emitPluginEvent,
+  ensurePluginRoot,
   findCollection,
+  findEnabledPlugin,
   getConfigValue,
   initRepoWiki,
+  installPlugin,
+  listArticleTree,
   listCollections,
+  listEnabledPlugins,
+  listPlugins,
+  listSearchModes,
+  loadSearchProvider,
+  nativeSearch,
   parseAddTarget,
   parseArticle,
   parsePathTarget,
+  pluginsDir,
+  pluginsRegistryPath,
   query,
+  readArticle,
   readConfig,
+  readPluginRegistry,
   readRegistry,
   readRepoConfig,
   registerCollection,
+  registerPlugin,
   registryPath,
   removeArticle,
   removeCollection,
+  removePlugin,
   removeTags,
+  renderArticle,
+  resolveDefaultSearchMode,
   resolveHome,
   serializeArticle,
   setConfigValue,
   setTags,
   slugify,
+  spawnPluginClient,
   unregisterCollection,
   updateArticleBody,
+  upsertPlugin,
   writeConfig,
+  writePluginRegistry,
   writeRegistry
 };