diffwiki-core 0.17.0 → 0.17.1

package/dist/index.cjs

@@ -137,7 +137,7 @@ function isMissing(err) {
 }
 async function readRegistry() {
   try {
-    const parsed = JSON.parse(await import_promises2.default.readFile(registryPath(), "utf8"));
+    const parsed = JSON.parse(await import_promises3.default.readFile(registryPath(), "utf8"));
     return { version: parsed.version ?? 1, collections: parsed.collections ?? [] };
   } catch (err) {
     if (isMissing(err)) return { version: 1, collections: [] };
@@ -145,8 +145,8 @@ async function readRegistry() {
   }
 }
 async function writeRegistry(registry) {
-  await import_promises2.default.mkdir(resolveHome(), { recursive: true });
-  await import_promises2.default.writeFile(registryPath(), `${JSON.stringify(registry, null, 2)}
+  await import_promises3.default.mkdir(resolveHome(), { recursive: true });
+  await import_promises3.default.writeFile(registryPath(), `${JSON.stringify(registry, null, 2)}
 `, "utf8");
 }
 async function registerCollection(entry) {
@@ -164,11 +164,11 @@ async function unregisterCollection(name) {
   registry.collections = registry.collections.filter((c) => c.name !== name);
   await writeRegistry(registry);
 }
-var import_promises2;
+var import_promises3;
 var init_registry = __esm({
   "src/registry.ts"() {
     "use strict";
-    import_promises2 = __toESM(require("fs/promises"), 1);
+    import_promises3 = __toESM(require("fs/promises"), 1);
     init_paths();
   }
 });
@@ -179,7 +179,7 @@ function isMissing2(err) {
 }
 async function readPluginRegistry() {
   try {
-    const parsed = JSON.parse(await import_promises3.default.readFile(pluginsRegistryPath(), "utf8"));
+    const parsed = JSON.parse(await import_promises4.default.readFile(pluginsRegistryPath(), "utf8"));
     return { version: parsed.version ?? 1, plugins: parsed.plugins ?? [] };
   } catch (err) {
     if (isMissing2(err)) return { version: 1, plugins: [] };
@@ -187,8 +187,8 @@ async function readPluginRegistry() {
   }
 }
 async function writePluginRegistry(registry) {
-  await import_promises3.default.mkdir(resolveHome(), { recursive: true });
-  await import_promises3.default.writeFile(pluginsRegistryPath(), `${JSON.stringify(registry, null, 2)}
+  await import_promises4.default.mkdir(resolveHome(), { recursive: true });
+  await import_promises4.default.writeFile(pluginsRegistryPath(), `${JSON.stringify(registry, null, 2)}
 `, "utf8");
 }
 async function upsertPlugin(record) {
@@ -219,11 +219,11 @@ async function findPluginRecord(name) {
   const registry = await readPluginRegistry();
   return registry.plugins.find((p) => p.name === name);
 }
-var import_promises3;
+var import_promises4;
 var init_registry2 = __esm({
   "src/plugins/registry.ts"() {
     "use strict";
-    import_promises3 = __toESM(require("fs/promises"), 1);
+    import_promises4 = __toESM(require("fs/promises"), 1);
     init_paths();
   }
 });
@@ -534,7 +534,7 @@ async function findCollectionById(id) {
 async function createCollection(name, opts) {
   if (await findCollection(name)) throw new CollectionExistsError(name);
   const dir = collectionDir(name);
-  await import_promises4.default.mkdir(dir, { recursive: true });
+  await import_promises5.default.mkdir(dir, { recursive: true });
   const entry = {
     name,
     type: "global",
@@ -551,16 +551,16 @@ async function removeCollection(name) {
   if (!entry) throw new CollectionNotFoundError(name);
   await unregisterCollection(name);
   if (entry.type === "global") {
-    await import_promises4.default.rm(entry.path, { recursive: true, force: true });
+    await import_promises5.default.rm(entry.path, { recursive: true, force: true });
   }
   void fireHook("collection-removed", name);
   return entry;
 }
-var import_promises4;
+var import_promises5;
 var init_collections = __esm({
   "src/collections.ts"() {
     "use strict";
-    import_promises4 = __toESM(require("fs/promises"), 1);
+    import_promises5 = __toESM(require("fs/promises"), 1);
     init_paths();
     init_registry();
     init_errors();
@@ -603,6 +603,7 @@ __export(index_exports, {
   doctor: () => doctor,
   emitPluginEvent: () => emitPluginEvent,
   ensureGitRepo: () => ensureGitRepo,
+  ensureHome: () => ensureHome,
   ensurePluginRoot: () => ensurePluginRoot,
   fileTimestamps: () => fileTimestamps,
   findCollection: () => findCollection,
@@ -693,8 +694,30 @@ init_types();
 init_errors();
 init_paths();
 
-// src/templates.ts
+// src/home.ts
 var import_promises = __toESM(require("fs/promises"), 1);
+init_paths();
+async function seedIfAbsent(file, contents) {
+  try {
+    await import_promises.default.writeFile(file, contents(), { encoding: "utf8", flag: "wx" });
+  } catch (err) {
+    if (err.code !== "EEXIST") throw err;
+  }
+}
+async function ensureHome() {
+  await import_promises.default.mkdir(resolveHome(), { recursive: true });
+  await Promise.all([
+    import_promises.default.mkdir(collectionsDir(), { recursive: true }),
+    import_promises.default.mkdir(pluginsDir(), { recursive: true }),
+    import_promises.default.mkdir(templatesDir(), { recursive: true })
+  ]);
+  await seedIfAbsent(registryPath(), () => `${JSON.stringify({ version: 1, collections: [] }, null, 2)}
+`);
+  await seedIfAbsent(configPath(), () => "{}\n");
+}
+
+// src/templates.ts
+var import_promises2 = __toESM(require("fs/promises"), 1);
 var import_node_path2 = __toESM(require("path"), 1);
 init_paths();
 
@@ -778,34 +801,34 @@ function serializeArticle(article) {
 // src/templates.ts
 async function seedTemplates(srcDir) {
   const dir = templatesDir();
-  await import_promises.default.mkdir(dir, { recursive: true });
-  const files = (await import_promises.default.readdir(srcDir)).filter((f) => f.endsWith(".md")).sort();
+  await import_promises2.default.mkdir(dir, { recursive: true });
+  const files = (await import_promises2.default.readdir(srcDir)).filter((f) => f.endsWith(".md")).sort();
   const seeded = [];
   const skipped = [];
   for (const file of files) {
     const dest = import_node_path2.default.join(dir, file);
     try {
-      await import_promises.default.access(dest);
+      await import_promises2.default.access(dest);
       skipped.push(file);
       continue;
     } catch {
     }
-    await import_promises.default.copyFile(import_node_path2.default.join(srcDir, file), dest);
+    await import_promises2.default.copyFile(import_node_path2.default.join(srcDir, file), dest);
     seeded.push(file);
   }
   return { seeded, skipped, dir };
 }
 async function listTemplateShapes(srcDir) {
-  const files = await import_promises.default.readdir(srcDir);
+  const files = await import_promises2.default.readdir(srcDir);
   return files.filter((f) => f.endsWith("-template.md")).map((f) => f.replace(/-template\.md$/, "")).sort();
 }
 async function listTemplates(srcDir) {
-  const files = (await import_promises.default.readdir(srcDir)).filter((f) => f.endsWith("-template.md")).sort();
+  const files = (await import_promises2.default.readdir(srcDir)).filter((f) => f.endsWith("-template.md")).sort();
   const out = [];
   for (const file of files) {
     let data = {};
     try {
-      ({ data } = parseFrontmatter(await import_promises.default.readFile(import_node_path2.default.join(srcDir, file), "utf8")));
+      ({ data } = parseFrontmatter(await import_promises2.default.readFile(import_node_path2.default.join(srcDir, file), "utf8")));
     } catch {
     }
     const shape = typeof data.shape === "string" && data.shape ? data.shape : file.replace(/-template\.md$/, "");
@@ -817,7 +840,7 @@ async function listTemplates(srcDir) {
 }
 
 // src/config.ts
-var import_promises5 = __toESM(require("fs/promises"), 1);
+var import_promises6 = __toESM(require("fs/promises"), 1);
 init_paths();
 init_collections();
 init_errors();
@@ -828,15 +851,15 @@ function isMissing3(err) {
 }
 async function readConfig() {
   try {
-    return JSON.parse(await import_promises5.default.readFile(configPath(), "utf8"));
+    return JSON.parse(await import_promises6.default.readFile(configPath(), "utf8"));
   } catch (err) {
     if (isMissing3(err)) return {};
     throw err;
   }
 }
 async function writeConfig(config) {
-  await import_promises5.default.mkdir(resolveHome(), { recursive: true });
-  await import_promises5.default.writeFile(configPath(), `${JSON.stringify(config, null, 2)}
+  await import_promises6.default.mkdir(resolveHome(), { recursive: true });
+  await import_promises6.default.writeFile(configPath(), `${JSON.stringify(config, null, 2)}
 `, "utf8");
 }
 async function setConfigValue(key, value) {
@@ -885,7 +908,7 @@ function slugifyPath(input) {
 init_collections();
 
 // src/articles.ts
-var import_promises6 = __toESM(require("fs/promises"), 1);
+var import_promises7 = __toESM(require("fs/promises"), 1);
 var import_node_path4 = __toESM(require("path"), 1);
 init_collections();
 init_errors();
@@ -936,8 +959,8 @@ async function createArticle(opts) {
   const filePath = import_node_path4.default.join(dir, `${slugifyPath(title)}.md`);
   const body = opts.body ?? `# ${title}
 `;
-  await import_promises6.default.mkdir(import_node_path4.default.dirname(filePath), { recursive: true });
-  await import_promises6.default.writeFile(
+  await import_promises7.default.mkdir(import_node_path4.default.dirname(filePath), { recursive: true });
+  await import_promises7.default.writeFile(
     filePath,
     serializeArticle({ title, tags: opts.tags, body, audience: opts.audience, status: opts.status }),
     "utf8"
@@ -950,7 +973,7 @@ async function loadArticle(target) {
   const { dir } = await resolveCollectionDir(collection);
   const filePath = import_node_path4.default.join(dir, ensureMdPath(file));
   try {
-    return { filePath, dir, raw: await import_promises6.default.readFile(filePath, "utf8"), collection };
+    return { filePath, dir, raw: await import_promises7.default.readFile(filePath, "utf8"), collection };
   } catch (err) {
     if (err.code === "ENOENT") throw new ArticleNotFoundError(target);
     throw err;
@@ -959,7 +982,7 @@ async function loadArticle(target) {
 async function updateArticleBody(target, body) {
   const { filePath, dir, raw, collection } = await loadArticle(target);
   const parsed = parseArticle(raw);
-  await import_promises6.default.writeFile(
+  await import_promises7.default.writeFile(
     filePath,
     serializeArticle({
       title: parsed.title,
@@ -977,7 +1000,7 @@ async function mutateTags(target, fn) {
   const { filePath, dir, raw, collection } = await loadArticle(target);
   const parsed = parseArticle(raw);
   const tags = fn(parsed.tags);
-  await import_promises6.default.writeFile(
+  await import_promises7.default.writeFile(
     filePath,
     serializeArticle({
       title: parsed.title,
@@ -1006,7 +1029,7 @@ async function setArticleMeta(target, meta) {
   const parsed = parseArticle(raw);
   const audience = meta.audience ?? parsed.audience;
   const status = meta.status ?? parsed.status;
-  await import_promises6.default.writeFile(
+  await import_promises7.default.writeFile(
     filePath,
     serializeArticle({ title: parsed.title, tags: parsed.tags, audience, status, body: parsed.body }),
     "utf8"
@@ -1016,13 +1039,13 @@ async function setArticleMeta(target, meta) {
 }
 async function removeArticle(target) {
   const { filePath, dir, collection } = await loadArticle(target);
-  await import_promises6.default.rm(filePath);
+  await import_promises7.default.rm(filePath);
   void fireHook2("article-removed", collection, import_node_path4.default.relative(dir, filePath));
   return filePath;
 }
 
 // src/repo.ts
-var import_promises8 = __toESM(require("fs/promises"), 1);
+var import_promises9 = __toESM(require("fs/promises"), 1);
 var import_node_path6 = __toESM(require("path"), 1);
 var import_node_child_process3 = require("child_process");
 var import_node_util2 = require("util");
@@ -1031,7 +1054,7 @@ init_collections();
 init_registry();
 
 // src/git.ts
-var import_promises7 = __toESM(require("fs/promises"), 1);
+var import_promises8 = __toESM(require("fs/promises"), 1);
 var import_node_path5 = __toESM(require("path"), 1);
 var import_node_child_process2 = require("child_process");
 var import_node_util = require("util");
@@ -1113,7 +1136,7 @@ async function fileTimestamps(absPath) {
   let updated = gitUpdated;
   if (!created || !updated) {
     try {
-      const st = await import_promises7.default.stat(absPath);
+      const st = await import_promises8.default.stat(absPath);
       if (!updated) updated = st.mtime.toISOString();
       if (!created) created = isEpochish(st.birthtime) ? st.mtime.toISOString() : st.birthtime.toISOString();
     } catch {
@@ -1138,7 +1161,7 @@ async function detectRepoName(cwd) {
 }
 async function readRepoConfig(cwd) {
   try {
-    const raw = await import_promises8.default.readFile(import_node_path6.default.join(cwd, REPO_CONFIG_FILE), "utf8");
+    const raw = await import_promises9.default.readFile(import_node_path6.default.join(cwd, REPO_CONFIG_FILE), "utf8");
     const parsed = (0, import_yaml2.parse)(raw) ?? {};
     if (!parsed.path) return void 0;
     return {
@@ -1168,9 +1191,9 @@ async function initRepoWiki(opts) {
       n += 1;
     }
   }
-  await import_promises8.default.mkdir(absWiki, { recursive: true });
+  await import_promises9.default.mkdir(absWiki, { recursive: true });
   const config = { collection: name, path: wikiPath };
-  await import_promises8.default.writeFile(import_node_path6.default.join(cwd, REPO_CONFIG_FILE), (0, import_yaml2.stringify)(config), "utf8");
+  await import_promises9.default.writeFile(import_node_path6.default.join(cwd, REPO_CONFIG_FILE), (0, import_yaml2.stringify)(config), "utf8");
   const entry = {
     name,
     type: "repo",
@@ -1239,7 +1262,7 @@ async function collectionGitStatus(entry) {
 }
 
 // src/project.ts
-var import_promises9 = __toESM(require("fs/promises"), 1);
+var import_promises10 = __toESM(require("fs/promises"), 1);
 var import_node_os2 = __toESM(require("os"), 1);
 var import_node_path7 = __toESM(require("path"), 1);
 var import_yaml3 = require("yaml");
@@ -1296,7 +1319,7 @@ function normaliseContext(raw) {
 async function readProjectConfig(dir) {
   let raw;
   try {
-    raw = await import_promises9.default.readFile(import_node_path7.default.join(dir, PROJECT_CONFIG_FILE), "utf8");
+    raw = await import_promises10.default.readFile(import_node_path7.default.join(dir, PROJECT_CONFIG_FILE), "utf8");
   } catch (err) {
     if (err.code === "ENOENT") return void 0;
     throw err;
@@ -1331,13 +1354,13 @@ async function setContextCollections(dir, collections) {
   const file = import_node_path7.default.join(dir, PROJECT_CONFIG_FILE);
   let raw = "";
   try {
-    raw = await import_promises9.default.readFile(file, "utf8");
+    raw = await import_promises10.default.readFile(file, "utf8");
   } catch (err) {
     if (err.code !== "ENOENT") throw err;
   }
   const doc = (0, import_yaml3.parseDocument)(raw);
   doc.setIn(["context", "collections"], collections);
-  await import_promises9.default.writeFile(file, doc.toString(), "utf8");
+  await import_promises10.default.writeFile(file, doc.toString(), "utf8");
   return file;
 }
 async function resolveProjectCollections(dir) {
@@ -1360,8 +1383,8 @@ async function seedProjectHome(dir) {
   if (entries.length === 0) {
     throw new Error(`No collections to render from diffwiki.yaml in ${import_node_path7.default.resolve(dir)}`);
   }
-  const home = await import_promises9.default.mkdtemp(import_node_path7.default.join(import_node_os2.default.tmpdir(), "diffwiki-project-"));
-  await import_promises9.default.writeFile(
+  const home = await import_promises10.default.mkdtemp(import_node_path7.default.join(import_node_os2.default.tmpdir(), "diffwiki-project-"));
+  await import_promises10.default.writeFile(
     import_node_path7.default.join(home, "registry.json"),
     `${JSON.stringify({ version: 1, collections: entries }, null, 2)}
 `,
@@ -1374,7 +1397,7 @@ async function seedProjectHome(dir) {
 init_collections();
 
 // src/browse.ts
-var import_promises10 = __toESM(require("fs/promises"), 1);
+var import_promises11 = __toESM(require("fs/promises"), 1);
 var import_node_path8 = __toESM(require("path"), 1);
 init_collections();
 init_errors();
@@ -1421,7 +1444,7 @@ function buildArticleTree(relPaths) {
 async function collectRelPaths(dir, rel = "") {
   let dirents;
   try {
-    dirents = await import_promises10.default.readdir(dir, { withFileTypes: true });
+    dirents = await import_promises11.default.readdir(dir, { withFileTypes: true });
   } catch {
     return [];
   }
@@ -1439,7 +1462,7 @@ async function collectRelPaths(dir, rel = "") {
 }
 async function readdirSafe(dir) {
   try {
-    return await import_promises10.default.readdir(dir);
+    return await import_promises11.default.readdir(dir);
   } catch {
     return [];
   }
@@ -1457,7 +1480,7 @@ var CHEAP_META_BYTES = 8192;
 async function cheapMeta(absPath) {
   let handle;
   try {
-    handle = await import_promises10.default.open(absPath, "r");
+    handle = await import_promises11.default.open(absPath, "r");
     const buf = Buffer.alloc(CHEAP_META_BYTES);
     const { bytesRead } = await handle.read(buf, 0, CHEAP_META_BYTES, 0);
     const snippet = buf.subarray(0, bytesRead).toString("utf8");
@@ -1548,7 +1571,7 @@ async function readArticle(coll, slug) {
     const candidate = import_node_path8.default.resolve(collDir, rel);
     if (!inJail(candidate)) throw new InvalidTargetError(slug, "path traversal detected");
     try {
-      await import_promises10.default.access(candidate);
+      await import_promises11.default.access(candidate);
       abs = candidate;
       break;
     } catch {
@@ -1565,7 +1588,7 @@ async function readArticle(coll, slug) {
     }
   }
   if (!abs) throw new ArticleNotFoundError(`${coll}/${safeSlug}`);
-  const parsed = parseArticle(await import_promises10.default.readFile(abs, "utf8"));
+  const parsed = parseArticle(await import_promises11.default.readFile(abs, "utf8"));
   const title = parsed.title?.trim() || (safeSlug ? safeSlug.split("/").pop() ?? safeSlug : coll);
   return {
     coll,
@@ -2012,7 +2035,7 @@ function resolveCollectionSelection(all, sel = {}) {
 }
 
 // src/query.ts
-var import_promises11 = __toESM(require("fs/promises"), 1);
+var import_promises12 = __toESM(require("fs/promises"), 1);
 var import_node_path10 = __toESM(require("path"), 1);
 init_collections();
 init_errors();
@@ -2088,7 +2111,7 @@ var log2 = getLogger("query");
 async function collectMarkdownFiles(dir) {
   let entries;
   try {
-    entries = await import_promises11.default.readdir(dir, { withFileTypes: true });
+    entries = await import_promises12.default.readdir(dir, { withFileTypes: true });
   } catch {
     return [];
   }
@@ -2126,7 +2149,7 @@ async function nativeSearch(term, collections, collection, hideSystem = false) {
       let tags = [];
       let body = "";
       try {
-        const parsed = parseArticle(await import_promises11.default.readFile(full, "utf8"));
+        const parsed = parseArticle(await import_promises12.default.readFile(full, "utf8"));
         if (hideSystem && parsed.audience === "system") continue;
         if (parsed.title) title = parsed.title;
         tags = parsed.tags;
@@ -2184,7 +2207,7 @@ async function dropSystemHits(hits) {
   const kept = [];
   for (const hit of hits) {
     try {
-      if (parseArticle(await import_promises11.default.readFile(hit.path, "utf8")).audience === "system") continue;
+      if (parseArticle(await import_promises12.default.readFile(hit.path, "utf8")).audience === "system") continue;
     } catch {
     }
     kept.push(hit);
@@ -2232,14 +2255,14 @@ async function query(term, opts) {
 }
 
 // src/search.ts
-var import_promises12 = __toESM(require("fs/promises"), 1);
+var import_promises13 = __toESM(require("fs/promises"), 1);
 var import_node_path11 = __toESM(require("path"), 1);
 init_collections();
 var isStatic2 = () => process.env.DIFFWIKI_STATIC === "1";
 async function readArticleParts(collDir, slug) {
   for (const ext of [".mdx", ".md"]) {
     try {
-      const parsed = parseArticle(await import_promises12.default.readFile(import_node_path11.default.join(collDir, `${slug}${ext}`), "utf8"));
+      const parsed = parseArticle(await import_promises13.default.readFile(import_node_path11.default.join(collDir, `${slug}${ext}`), "utf8"));
       return { tags: parsed.tags, body: parsed.body };
     } catch {
     }
@@ -2289,13 +2312,13 @@ async function buildSearchIndex(collection) {
 }
 
 // src/doctor.ts
-var import_promises14 = __toESM(require("fs/promises"), 1);
+var import_promises15 = __toESM(require("fs/promises"), 1);
 init_paths();
 init_registry();
 init_collections();
 
 // src/plugins/manager.ts
-var import_promises13 = __toESM(require("fs/promises"), 1);
+var import_promises14 = __toESM(require("fs/promises"), 1);
 var import_node_os3 = __toESM(require("os"), 1);
 var import_node_path13 = __toESM(require("path"), 1);
 init_paths();
@@ -2324,7 +2347,7 @@ async function runProcess(file, args, opts) {
 // src/plugins/manager.ts
 async function readPackageJson(file) {
   try {
-    return JSON.parse(await import_promises13.default.readFile(file, "utf8"));
+    return JSON.parse(await import_promises14.default.readFile(file, "utf8"));
   } catch {
     return null;
   }
@@ -2340,7 +2363,7 @@ function binOf(manifest) {
 async function pluginManifestDirs(nodeModules) {
   let entries;
   try {
-    entries = await import_promises13.default.readdir(nodeModules);
+    entries = await import_promises14.default.readdir(nodeModules);
   } catch {
     return [];
   }
@@ -2350,7 +2373,7 @@ async function pluginManifestDirs(nodeModules) {
     if (entry.startsWith("@")) {
       let scoped;
       try {
-        scoped = await import_promises13.default.readdir(import_node_path13.default.join(nodeModules, entry));
+        scoped = await import_promises14.default.readdir(import_node_path13.default.join(nodeModules, entry));
       } catch {
         continue;
       }
@@ -2366,11 +2389,11 @@ async function pluginManifestDirs(nodeModules) {
 }
 async function ensurePluginRoot() {
   const dir = pluginsDir();
-  await import_promises13.default.mkdir(dir, { recursive: true });
+  await import_promises14.default.mkdir(dir, { recursive: true });
   const pkgPath = import_node_path13.default.join(dir, "package.json");
   if (await readPackageJson(pkgPath) === null) {
     const pkg = { name: "diffwiki-plugins", private: true, version: "0.0.0" };
-    await import_promises13.default.writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}
+    await import_promises14.default.writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}
 `, "utf8");
   }
   return dir;
@@ -2541,7 +2564,7 @@ init_host();
 init_types();
 async function exists(target) {
   try {
-    await import_promises14.default.access(target);
+    await import_promises15.default.access(target);
     return true;
   } catch {
     return false;
@@ -2647,7 +2670,7 @@ async function appendPluginDiagnostics(out, config) {
 }
 
 // src/lint.ts
-var import_promises15 = __toESM(require("fs/promises"), 1);
+var import_promises16 = __toESM(require("fs/promises"), 1);
 var import_node_path14 = __toESM(require("path"), 1);
 init_collections();
 init_errors();
@@ -2742,7 +2765,7 @@ function lintArticle(article) {
 async function walkMarkdown(dir) {
   let entries;
   try {
-    entries = await import_promises15.default.readdir(dir, { withFileTypes: true });
+    entries = await import_promises16.default.readdir(dir, { withFileTypes: true });
   } catch {
     return [];
   }
@@ -2782,7 +2805,7 @@ async function lintCollections(scope) {
       const label = `${coll.name}/${rel}`;
       let findings = [];
       try {
-        const parsed = parseArticle(await import_promises15.default.readFile(full, "utf8"));
+        const parsed = parseArticle(await import_promises16.default.readFile(full, "utf8"));
         findings = lintArticle(parsed);
       } catch (err) {
         findings = [{ level: "error", rule: "parse", message: `could not parse: ${err.message}` }];
@@ -2888,6 +2911,7 @@ init_registry2();
   doctor,
   emitPluginEvent,
   ensureGitRepo,
+  ensureHome,
   ensurePluginRoot,
   fileTimestamps,
   findCollection,

package/dist/index.d.cts

@@ -46,6 +46,18 @@ declare function collectionDir(name: string): string;
 declare function pluginsDir(): string;
 declare function pluginsRegistryPath(): string;
 
+/**
+ * Initialize the global diffwiki home (`~/.diffwiki`, or `DIFFWIKI_HOME`).
+ * Creates the directory tree (`collections/`, `plugins/`, `templates/`) and
+ * seeds empty-but-valid `registry.json` and `config.json` when absent.
+ * Idempotent — never overwrites existing files or user data.
+ *
+ * The CLI calls this at startup so the FIRST command a user runs — e.g.
+ * `npx diffwiki collection add` — leaves a fully initialized home behind, not
+ * just the one file that command happened to write.
+ */
+declare function ensureHome(): Promise<void>;
+
 /**
  * Authoring-template seeding.
  *
@@ -795,4 +807,4 @@ declare function findEnabledPlugin(kind: PluginKind, name?: string): Promise<Plu
 /** Find a plugin record by name (regardless of enabled state). */
 declare function findPluginRecord(name: string): Promise<PluginRecord | undefined>;
 
-export { type AddExternalOptions, Article, ArticleContent, ArticleNode, ArticleNotFoundError, Audience, CollectionAlreadyAddedError, CollectionEntry, CollectionExistsError, type CollectionGitStatus, CollectionInfo, CollectionNotFoundError, type CollectionSelection, type CollectionSelectionResult, CollectionTree, Config, Diagnostic, DiffwikiError, type DiffwikiLogLevel, type EditTarget, type FileTimestamps, type InitOptions, type InstallOutcome, InvalidExportSelectionError, InvalidTargetError, type KnownPlugin, LinkGraph, type LintFileResult, type LintFinding, type LintLevel, type LintResult, LocalGraph, NoDefaultCollectionError, PROJECT_CONFIG_FILE, PageData, ParsedArticle, PluginError, PluginEvent, PluginKind, PluginRecord, PluginRegistryFile, ProjectConfig, PublishStatus, QueryHit, QueryOptions, REPO_CONFIG_FILE, Registry, type RenderContext, type RenderedArticle, RepoConfig, SearchDoc, SearchMode, type SearchOutcome, SearchProvider, type SeedResult, type SetupOutcome, type SetupStep, SiteConfig, type TemplateInfo, TocItem, TreeNode, type UpstreamStatus, WorktreeNotAllowedError, addExternalCollection, addTags, buildArticleTree, buildCollections, buildLinkGraph, buildNavTree, buildSearchIndex, buildSiteConfig, collectionDir, collectionGitStatus, collectionMeta, collectionsDir, configPath, createArticle, createCollection, currentBranch, deregisterPlugin, doctor, emitPluginEvent, ensureGitRepo, ensurePluginRoot, fileTimestamps, findCollection, findCollectionById, findEnabledPlugin, findPluginRecord, getConfigValue, getLogger, gitToplevel, initRepoWiki, installPlugin, invalidateLinkGraph, isLinkedWorktree, lintArticle, lintCollections, listArticleTree, listAvailablePlugins, listCollections, listEnabledPlugins, listPlugins, listSearchModes, listTemplateShapes, listTemplates, loadSearchProvider, localGraph, nativeSearch, parseAddTarget, parsePathTarget, pluginsDir, pluginsRegistryPath, query, readArticle, readConfig, readContextCollections, readPluginRegistry, readProjectConfig, readRegistry, readRepoConfig, readSiteConfig, registerCollection, registerPlugin, registryPath, removeArticle, removeCollection, removePlugin, removeTags, renderArticle, repairPlugins, repoId, repoRemoteName, resolveCollectionSelection, resolveCwdCollection, resolveDefaultSearchMode, resolveEditTarget, resolveEditorCommand, resolveHome, resolveLogLevel, resolvePage, resolveProjectCollections, search, seedProjectHome, seedTemplates, setArticleMeta, setConfigValue, setContextCollections, setTags, showSystemEnabled, slugify, slugifyPath, templatesDir, toTreeNodes, unregisterCollection, updateArticleBody, upsertPlugin, upstreamStatus, writeConfig, writePluginRegistry, writeRegistry };
+export { type AddExternalOptions, Article, ArticleContent, ArticleNode, ArticleNotFoundError, Audience, CollectionAlreadyAddedError, CollectionEntry, CollectionExistsError, type CollectionGitStatus, CollectionInfo, CollectionNotFoundError, type CollectionSelection, type CollectionSelectionResult, CollectionTree, Config, Diagnostic, DiffwikiError, type DiffwikiLogLevel, type EditTarget, type FileTimestamps, type InitOptions, type InstallOutcome, InvalidExportSelectionError, InvalidTargetError, type KnownPlugin, LinkGraph, type LintFileResult, type LintFinding, type LintLevel, type LintResult, LocalGraph, NoDefaultCollectionError, PROJECT_CONFIG_FILE, PageData, ParsedArticle, PluginError, PluginEvent, PluginKind, PluginRecord, PluginRegistryFile, ProjectConfig, PublishStatus, QueryHit, QueryOptions, REPO_CONFIG_FILE, Registry, type RenderContext, type RenderedArticle, RepoConfig, SearchDoc, SearchMode, type SearchOutcome, SearchProvider, type SeedResult, type SetupOutcome, type SetupStep, SiteConfig, type TemplateInfo, TocItem, TreeNode, type UpstreamStatus, WorktreeNotAllowedError, addExternalCollection, addTags, buildArticleTree, buildCollections, buildLinkGraph, buildNavTree, buildSearchIndex, buildSiteConfig, collectionDir, collectionGitStatus, collectionMeta, collectionsDir, configPath, createArticle, createCollection, currentBranch, deregisterPlugin, doctor, emitPluginEvent, ensureGitRepo, ensureHome, ensurePluginRoot, fileTimestamps, findCollection, findCollectionById, findEnabledPlugin, findPluginRecord, getConfigValue, getLogger, gitToplevel, initRepoWiki, installPlugin, invalidateLinkGraph, isLinkedWorktree, lintArticle, lintCollections, listArticleTree, listAvailablePlugins, listCollections, listEnabledPlugins, listPlugins, listSearchModes, listTemplateShapes, listTemplates, loadSearchProvider, localGraph, nativeSearch, parseAddTarget, parsePathTarget, pluginsDir, pluginsRegistryPath, query, readArticle, readConfig, readContextCollections, readPluginRegistry, readProjectConfig, readRegistry, readRepoConfig, readSiteConfig, registerCollection, registerPlugin, registryPath, removeArticle, removeCollection, removePlugin, removeTags, renderArticle, repairPlugins, repoId, repoRemoteName, resolveCollectionSelection, resolveCwdCollection, resolveDefaultSearchMode, resolveEditTarget, resolveEditorCommand, resolveHome, resolveLogLevel, resolvePage, resolveProjectCollections, search, seedProjectHome, seedTemplates, setArticleMeta, setConfigValue, setContextCollections, setTags, showSystemEnabled, slugify, slugifyPath, templatesDir, toTreeNodes, unregisterCollection, updateArticleBody, upsertPlugin, upstreamStatus, writeConfig, writePluginRegistry, writeRegistry };

package/dist/index.d.ts

@@ -46,6 +46,18 @@ declare function collectionDir(name: string): string;
 declare function pluginsDir(): string;
 declare function pluginsRegistryPath(): string;
 
+/**
+ * Initialize the global diffwiki home (`~/.diffwiki`, or `DIFFWIKI_HOME`).
+ * Creates the directory tree (`collections/`, `plugins/`, `templates/`) and
+ * seeds empty-but-valid `registry.json` and `config.json` when absent.
+ * Idempotent — never overwrites existing files or user data.
+ *
+ * The CLI calls this at startup so the FIRST command a user runs — e.g.
+ * `npx diffwiki collection add` — leaves a fully initialized home behind, not
+ * just the one file that command happened to write.
+ */
+declare function ensureHome(): Promise<void>;
+
 /**
  * Authoring-template seeding.
  *
@@ -795,4 +807,4 @@ declare function findEnabledPlugin(kind: PluginKind, name?: string): Promise<Plu
 /** Find a plugin record by name (regardless of enabled state). */
 declare function findPluginRecord(name: string): Promise<PluginRecord | undefined>;
 
-export { type AddExternalOptions, Article, ArticleContent, ArticleNode, ArticleNotFoundError, Audience, CollectionAlreadyAddedError, CollectionEntry, CollectionExistsError, type CollectionGitStatus, CollectionInfo, CollectionNotFoundError, type CollectionSelection, type CollectionSelectionResult, CollectionTree, Config, Diagnostic, DiffwikiError, type DiffwikiLogLevel, type EditTarget, type FileTimestamps, type InitOptions, type InstallOutcome, InvalidExportSelectionError, InvalidTargetError, type KnownPlugin, LinkGraph, type LintFileResult, type LintFinding, type LintLevel, type LintResult, LocalGraph, NoDefaultCollectionError, PROJECT_CONFIG_FILE, PageData, ParsedArticle, PluginError, PluginEvent, PluginKind, PluginRecord, PluginRegistryFile, ProjectConfig, PublishStatus, QueryHit, QueryOptions, REPO_CONFIG_FILE, Registry, type RenderContext, type RenderedArticle, RepoConfig, SearchDoc, SearchMode, type SearchOutcome, SearchProvider, type SeedResult, type SetupOutcome, type SetupStep, SiteConfig, type TemplateInfo, TocItem, TreeNode, type UpstreamStatus, WorktreeNotAllowedError, addExternalCollection, addTags, buildArticleTree, buildCollections, buildLinkGraph, buildNavTree, buildSearchIndex, buildSiteConfig, collectionDir, collectionGitStatus, collectionMeta, collectionsDir, configPath, createArticle, createCollection, currentBranch, deregisterPlugin, doctor, emitPluginEvent, ensureGitRepo, ensurePluginRoot, fileTimestamps, findCollection, findCollectionById, findEnabledPlugin, findPluginRecord, getConfigValue, getLogger, gitToplevel, initRepoWiki, installPlugin, invalidateLinkGraph, isLinkedWorktree, lintArticle, lintCollections, listArticleTree, listAvailablePlugins, listCollections, listEnabledPlugins, listPlugins, listSearchModes, listTemplateShapes, listTemplates, loadSearchProvider, localGraph, nativeSearch, parseAddTarget, parsePathTarget, pluginsDir, pluginsRegistryPath, query, readArticle, readConfig, readContextCollections, readPluginRegistry, readProjectConfig, readRegistry, readRepoConfig, readSiteConfig, registerCollection, registerPlugin, registryPath, removeArticle, removeCollection, removePlugin, removeTags, renderArticle, repairPlugins, repoId, repoRemoteName, resolveCollectionSelection, resolveCwdCollection, resolveDefaultSearchMode, resolveEditTarget, resolveEditorCommand, resolveHome, resolveLogLevel, resolvePage, resolveProjectCollections, search, seedProjectHome, seedTemplates, setArticleMeta, setConfigValue, setContextCollections, setTags, showSystemEnabled, slugify, slugifyPath, templatesDir, toTreeNodes, unregisterCollection, updateArticleBody, upsertPlugin, upstreamStatus, writeConfig, writePluginRegistry, writeRegistry };
+export { type AddExternalOptions, Article, ArticleContent, ArticleNode, ArticleNotFoundError, Audience, CollectionAlreadyAddedError, CollectionEntry, CollectionExistsError, type CollectionGitStatus, CollectionInfo, CollectionNotFoundError, type CollectionSelection, type CollectionSelectionResult, CollectionTree, Config, Diagnostic, DiffwikiError, type DiffwikiLogLevel, type EditTarget, type FileTimestamps, type InitOptions, type InstallOutcome, InvalidExportSelectionError, InvalidTargetError, type KnownPlugin, LinkGraph, type LintFileResult, type LintFinding, type LintLevel, type LintResult, LocalGraph, NoDefaultCollectionError, PROJECT_CONFIG_FILE, PageData, ParsedArticle, PluginError, PluginEvent, PluginKind, PluginRecord, PluginRegistryFile, ProjectConfig, PublishStatus, QueryHit, QueryOptions, REPO_CONFIG_FILE, Registry, type RenderContext, type RenderedArticle, RepoConfig, SearchDoc, SearchMode, type SearchOutcome, SearchProvider, type SeedResult, type SetupOutcome, type SetupStep, SiteConfig, type TemplateInfo, TocItem, TreeNode, type UpstreamStatus, WorktreeNotAllowedError, addExternalCollection, addTags, buildArticleTree, buildCollections, buildLinkGraph, buildNavTree, buildSearchIndex, buildSiteConfig, collectionDir, collectionGitStatus, collectionMeta, collectionsDir, configPath, createArticle, createCollection, currentBranch, deregisterPlugin, doctor, emitPluginEvent, ensureGitRepo, ensureHome, ensurePluginRoot, fileTimestamps, findCollection, findCollectionById, findEnabledPlugin, findPluginRecord, getConfigValue, getLogger, gitToplevel, initRepoWiki, installPlugin, invalidateLinkGraph, isLinkedWorktree, lintArticle, lintCollections, listArticleTree, listAvailablePlugins, listCollections, listEnabledPlugins, listPlugins, listSearchModes, listTemplateShapes, listTemplates, loadSearchProvider, localGraph, nativeSearch, parseAddTarget, parsePathTarget, pluginsDir, pluginsRegistryPath, query, readArticle, readConfig, readContextCollections, readPluginRegistry, readProjectConfig, readRegistry, readRepoConfig, readSiteConfig, registerCollection, registerPlugin, registryPath, removeArticle, removeCollection, removePlugin, removeTags, renderArticle, repairPlugins, repoId, repoRemoteName, resolveCollectionSelection, resolveCwdCollection, resolveDefaultSearchMode, resolveEditTarget, resolveEditorCommand, resolveHome, resolveLogLevel, resolvePage, resolveProjectCollections, search, seedProjectHome, seedTemplates, setArticleMeta, setConfigValue, setContextCollections, setTags, showSystemEnabled, slugify, slugifyPath, templatesDir, toTreeNodes, unregisterCollection, updateArticleBody, upsertPlugin, upstreamStatus, writeConfig, writePluginRegistry, writeRegistry };

package/dist/index.js

@@ -54,39 +54,60 @@ import {
   writeRegistry
 } from "./chunk-TXM4OGBA.js";
 
-// src/templates.ts
+// src/home.ts
 import fs from "fs/promises";
+async function seedIfAbsent(file, contents) {
+  try {
+    await fs.writeFile(file, contents(), { encoding: "utf8", flag: "wx" });
+  } catch (err) {
+    if (err.code !== "EEXIST") throw err;
+  }
+}
+async function ensureHome() {
+  await fs.mkdir(resolveHome(), { recursive: true });
+  await Promise.all([
+    fs.mkdir(collectionsDir(), { recursive: true }),
+    fs.mkdir(pluginsDir(), { recursive: true }),
+    fs.mkdir(templatesDir(), { recursive: true })
+  ]);
+  await seedIfAbsent(registryPath(), () => `${JSON.stringify({ version: 1, collections: [] }, null, 2)}
+`);
+  await seedIfAbsent(configPath(), () => "{}\n");
+}
+
+// src/templates.ts
+import fs2 from "fs/promises";
 import path from "path";
 async function seedTemplates(srcDir) {
   const dir = templatesDir();
-  await fs.mkdir(dir, { recursive: true });
-  const files = (await fs.readdir(srcDir)).filter((f) => f.endsWith(".md")).sort();
+  await fs2.mkdir(dir, { recursive: true });
+  const files = (await fs2.readdir(srcDir)).filter((f) => f.endsWith(".md")).sort();
   const seeded = [];
   const skipped = [];
   for (const file of files) {
     const dest = path.join(dir, file);
     try {
-      await fs.access(dest);
+      await fs2.access(dest);
       skipped.push(file);
       continue;
     } catch {
     }
-    await fs.copyFile(path.join(srcDir, file), dest);
+    await fs2.copyFile(path.join(srcDir, file), dest);
     seeded.push(file);
   }
   return { seeded, skipped, dir };
 }
 async function listTemplateShapes(srcDir) {
-  const files = await fs.readdir(srcDir);
+  const files = await fs2.readdir(srcDir);
   return files.filter((f) => f.endsWith("-template.md")).map((f) => f.replace(/-template\.md$/, "")).sort();
 }
 async function listTemplates(srcDir) {
-  const files = (await fs.readdir(srcDir)).filter((f) => f.endsWith("-template.md")).sort();
+  const files = (await fs2.readdir(srcDir)).filter((f) => f.endsWith("-template.md")).sort();
   const out = [];
   for (const file of files) {
     let data = {};
     try {
-      ({ data } = parseFrontmatter(await fs.readFile(path.join(srcDir, file), "utf8")));
+      ({ data } = parseFrontmatter(await fs2.readFile(path.join(srcDir, file), "utf8")));
     } catch {
     }
     const shape = typeof data.shape === "string" && data.shape ? data.shape : file.replace(/-template\.md$/, "");
@@ -98,21 +119,21 @@ async function listTemplates(srcDir) {
 }
 
 // src/config.ts
-import fs2 from "fs/promises";
+import fs3 from "fs/promises";
 function isMissing(err) {
   return err?.code === "ENOENT";
 }
 async function readConfig() {
   try {
-    return JSON.parse(await fs2.readFile(configPath(), "utf8"));
+    return JSON.parse(await fs3.readFile(configPath(), "utf8"));
   } catch (err) {
     if (isMissing(err)) return {};
     throw err;
   }
 }
 async function writeConfig(config) {
-  await fs2.mkdir(resolveHome(), { recursive: true });
-  await fs2.writeFile(configPath(), `${JSON.stringify(config, null, 2)}
+  await fs3.mkdir(resolveHome(), { recursive: true });
+  await fs3.writeFile(configPath(), `${JSON.stringify(config, null, 2)}
 `, "utf8");
 }
 async function setConfigValue(key, value) {
@@ -155,7 +176,7 @@ function slugifyPath(input) {
 }
 
 // src/articles.ts
-import fs3 from "fs/promises";
+import fs4 from "fs/promises";
 import path2 from "path";
 async function fireHook(event, collection, relPath) {
   try {
@@ -204,8 +225,8 @@ async function createArticle(opts) {
   const filePath = path2.join(dir, `${slugifyPath(title)}.md`);
   const body = opts.body ?? `# ${title}
 `;
-  await fs3.mkdir(path2.dirname(filePath), { recursive: true });
-  await fs3.writeFile(
+  await fs4.mkdir(path2.dirname(filePath), { recursive: true });
+  await fs4.writeFile(
     filePath,
     serializeArticle({ title, tags: opts.tags, body, audience: opts.audience, status: opts.status }),
     "utf8"
@@ -218,7 +239,7 @@ async function loadArticle(target) {
   const { dir } = await resolveCollectionDir(collection);
   const filePath = path2.join(dir, ensureMdPath(file));
   try {
-    return { filePath, dir, raw: await fs3.readFile(filePath, "utf8"), collection };
+    return { filePath, dir, raw: await fs4.readFile(filePath, "utf8"), collection };
   } catch (err) {
     if (err.code === "ENOENT") throw new ArticleNotFoundError(target);
     throw err;
@@ -227,7 +248,7 @@ async function loadArticle(target) {
 async function updateArticleBody(target, body) {
   const { filePath, dir, raw, collection } = await loadArticle(target);
   const parsed = parseArticle(raw);
-  await fs3.writeFile(
+  await fs4.writeFile(
     filePath,
     serializeArticle({
       title: parsed.title,
@@ -245,7 +266,7 @@ async function mutateTags(target, fn) {
   const { filePath, dir, raw, collection } = await loadArticle(target);
   const parsed = parseArticle(raw);
   const tags = fn(parsed.tags);
-  await fs3.writeFile(
+  await fs4.writeFile(
     filePath,
     serializeArticle({
       title: parsed.title,
@@ -274,7 +295,7 @@ async function setArticleMeta(target, meta) {
   const parsed = parseArticle(raw);
   const audience = meta.audience ?? parsed.audience;
   const status = meta.status ?? parsed.status;
-  await fs3.writeFile(
+  await fs4.writeFile(
     filePath,
     serializeArticle({ title: parsed.title, tags: parsed.tags, audience, status, body: parsed.body }),
     "utf8"
@@ -284,20 +305,20 @@ async function setArticleMeta(target, meta) {
 }
 async function removeArticle(target) {
   const { filePath, dir, collection } = await loadArticle(target);
-  await fs3.rm(filePath);
+  await fs4.rm(filePath);
   void fireHook("article-removed", collection, path2.relative(dir, filePath));
   return filePath;
 }
 
 // src/repo.ts
-import fs5 from "fs/promises";
+import fs6 from "fs/promises";
 import path4 from "path";
 import { execFile as execFile2 } from "child_process";
 import { promisify as promisify2 } from "util";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 
 // src/git.ts
-import fs4 from "fs/promises";
+import fs5 from "fs/promises";
 import path3 from "path";
 import { execFile } from "child_process";
 import { promisify } from "util";
@@ -378,7 +399,7 @@ async function fileTimestamps(absPath) {
   let updated = gitUpdated;
   if (!created || !updated) {
     try {
-      const st = await fs4.stat(absPath);
+      const st = await fs5.stat(absPath);
       if (!updated) updated = st.mtime.toISOString();
       if (!created) created = isEpochish(st.birthtime) ? st.mtime.toISOString() : st.birthtime.toISOString();
     } catch {
@@ -402,7 +423,7 @@ async function detectRepoName(cwd) {
 }
 async function readRepoConfig(cwd) {
   try {
-    const raw = await fs5.readFile(path4.join(cwd, REPO_CONFIG_FILE), "utf8");
+    const raw = await fs6.readFile(path4.join(cwd, REPO_CONFIG_FILE), "utf8");
     const parsed = parseYaml(raw) ?? {};
     if (!parsed.path) return void 0;
     return {
@@ -432,9 +453,9 @@ async function initRepoWiki(opts) {
       n += 1;
     }
   }
-  await fs5.mkdir(absWiki, { recursive: true });
+  await fs6.mkdir(absWiki, { recursive: true });
   const config = { collection: name, path: wikiPath };
-  await fs5.writeFile(path4.join(cwd, REPO_CONFIG_FILE), stringifyYaml(config), "utf8");
+  await fs6.writeFile(path4.join(cwd, REPO_CONFIG_FILE), stringifyYaml(config), "utf8");
   const entry = {
     name,
     type: "repo",
@@ -503,7 +524,7 @@ async function collectionGitStatus(entry) {
 }
 
 // src/project.ts
-import fs6 from "fs/promises";
+import fs7 from "fs/promises";
 import os from "os";
 import path5 from "path";
 import { parse as parseYaml2, parseDocument } from "yaml";
@@ -560,7 +581,7 @@ function normaliseContext(raw) {
 async function readProjectConfig(dir) {
   let raw;
   try {
-    raw = await fs6.readFile(path5.join(dir, PROJECT_CONFIG_FILE), "utf8");
+    raw = await fs7.readFile(path5.join(dir, PROJECT_CONFIG_FILE), "utf8");
   } catch (err) {
     if (err.code === "ENOENT") return void 0;
     throw err;
@@ -595,13 +616,13 @@ async function setContextCollections(dir, collections) {
   const file = path5.join(dir, PROJECT_CONFIG_FILE);
   let raw = "";
   try {
-    raw = await fs6.readFile(file, "utf8");
+    raw = await fs7.readFile(file, "utf8");
   } catch (err) {
     if (err.code !== "ENOENT") throw err;
   }
   const doc = parseDocument(raw);
   doc.setIn(["context", "collections"], collections);
-  await fs6.writeFile(file, doc.toString(), "utf8");
+  await fs7.writeFile(file, doc.toString(), "utf8");
   return file;
 }
 async function resolveProjectCollections(dir) {
@@ -624,8 +645,8 @@ async function seedProjectHome(dir) {
   if (entries.length === 0) {
     throw new Error(`No collections to render from diffwiki.yaml in ${path5.resolve(dir)}`);
   }
-  const home = await fs6.mkdtemp(path5.join(os.tmpdir(), "diffwiki-project-"));
-  await fs6.writeFile(
+  const home = await fs7.mkdtemp(path5.join(os.tmpdir(), "diffwiki-project-"));
+  await fs7.writeFile(
     path5.join(home, "registry.json"),
     `${JSON.stringify({ version: 1, collections: entries }, null, 2)}
 `,
@@ -635,7 +656,7 @@ async function seedProjectHome(dir) {
 }
 
 // src/browse.ts
-import fs7 from "fs/promises";
+import fs8 from "fs/promises";
 import path6 from "path";
 var INDEX_RE = /^(index|readme)\.mdx?$/i;
 function buildArticleTree(relPaths) {
@@ -680,7 +701,7 @@ function buildArticleTree(relPaths) {
 async function collectRelPaths(dir, rel = "") {
   let dirents;
   try {
-    dirents = await fs7.readdir(dir, { withFileTypes: true });
+    dirents = await fs8.readdir(dir, { withFileTypes: true });
   } catch {
     return [];
   }
@@ -698,7 +719,7 @@ async function collectRelPaths(dir, rel = "") {
 }
 async function readdirSafe(dir) {
   try {
-    return await fs7.readdir(dir);
+    return await fs8.readdir(dir);
   } catch {
     return [];
   }
@@ -716,7 +737,7 @@ var CHEAP_META_BYTES = 8192;
 async function cheapMeta(absPath) {
   let handle;
   try {
-    handle = await fs7.open(absPath, "r");
+    handle = await fs8.open(absPath, "r");
     const buf = Buffer.alloc(CHEAP_META_BYTES);
     const { bytesRead } = await handle.read(buf, 0, CHEAP_META_BYTES, 0);
     const snippet = buf.subarray(0, bytesRead).toString("utf8");
@@ -807,7 +828,7 @@ async function readArticle(coll, slug) {
     const candidate = path6.resolve(collDir, rel);
     if (!inJail(candidate)) throw new InvalidTargetError(slug, "path traversal detected");
     try {
-      await fs7.access(candidate);
+      await fs8.access(candidate);
       abs = candidate;
       break;
     } catch {
@@ -824,7 +845,7 @@ async function readArticle(coll, slug) {
     }
   }
   if (!abs) throw new ArticleNotFoundError(`${coll}/${safeSlug}`);
-  const parsed = parseArticle(await fs7.readFile(abs, "utf8"));
+  const parsed = parseArticle(await fs8.readFile(abs, "utf8"));
   const title = parsed.title?.trim() || (safeSlug ? safeSlug.split("/").pop() ?? safeSlug : coll);
   return {
     coll,
@@ -1268,13 +1289,13 @@ function resolveCollectionSelection(all, sel = {}) {
 }
 
 // src/query.ts
-import fs8 from "fs/promises";
+import fs9 from "fs/promises";
 import path8 from "path";
 var log2 = getLogger("query");
 async function collectMarkdownFiles(dir) {
   let entries;
   try {
-    entries = await fs8.readdir(dir, { withFileTypes: true });
+    entries = await fs9.readdir(dir, { withFileTypes: true });
   } catch {
     return [];
   }
@@ -1312,7 +1333,7 @@ async function nativeSearch(term, collections, collection, hideSystem = false) {
       let tags = [];
       let body = "";
       try {
-        const parsed = parseArticle(await fs8.readFile(full, "utf8"));
+        const parsed = parseArticle(await fs9.readFile(full, "utf8"));
         if (hideSystem && parsed.audience === "system") continue;
         if (parsed.title) title = parsed.title;
         tags = parsed.tags;
@@ -1370,7 +1391,7 @@ async function dropSystemHits(hits) {
   const kept = [];
   for (const hit of hits) {
     try {
-      if (parseArticle(await fs8.readFile(hit.path, "utf8")).audience === "system") continue;
+      if (parseArticle(await fs9.readFile(hit.path, "utf8")).audience === "system") continue;
     } catch {
     }
     kept.push(hit);
@@ -1418,13 +1439,13 @@ async function query(term, opts) {
 }
 
 // src/search.ts
-import fs9 from "fs/promises";
+import fs10 from "fs/promises";
 import path9 from "path";
 var isStatic2 = () => process.env.DIFFWIKI_STATIC === "1";
 async function readArticleParts(collDir, slug) {
   for (const ext of [".mdx", ".md"]) {
     try {
-      const parsed = parseArticle(await fs9.readFile(path9.join(collDir, `${slug}${ext}`), "utf8"));
+      const parsed = parseArticle(await fs10.readFile(path9.join(collDir, `${slug}${ext}`), "utf8"));
       return { tags: parsed.tags, body: parsed.body };
     } catch {
     }
@@ -1474,15 +1495,15 @@ async function buildSearchIndex(collection) {
 }
 
 // src/doctor.ts
-import fs11 from "fs/promises";
+import fs12 from "fs/promises";
 
 // src/plugins/manager.ts
-import fs10 from "fs/promises";
+import fs11 from "fs/promises";
 import os2 from "os";
 import path10 from "path";
 async function readPackageJson(file) {
   try {
-    return JSON.parse(await fs10.readFile(file, "utf8"));
+    return JSON.parse(await fs11.readFile(file, "utf8"));
   } catch {
     return null;
   }
@@ -1498,7 +1519,7 @@ function binOf(manifest) {
 async function pluginManifestDirs(nodeModules) {
   let entries;
   try {
-    entries = await fs10.readdir(nodeModules);
+    entries = await fs11.readdir(nodeModules);
   } catch {
     return [];
   }
@@ -1508,7 +1529,7 @@ async function pluginManifestDirs(nodeModules) {
     if (entry.startsWith("@")) {
       let scoped;
       try {
-        scoped = await fs10.readdir(path10.join(nodeModules, entry));
+        scoped = await fs11.readdir(path10.join(nodeModules, entry));
       } catch {
         continue;
       }
@@ -1524,11 +1545,11 @@ async function pluginManifestDirs(nodeModules) {
 }
 async function ensurePluginRoot() {
   const dir = pluginsDir();
-  await fs10.mkdir(dir, { recursive: true });
+  await fs11.mkdir(dir, { recursive: true });
   const pkgPath = path10.join(dir, "package.json");
   if (await readPackageJson(pkgPath) === null) {
     const pkg = { name: "diffwiki-plugins", private: true, version: "0.0.0" };
-    await fs10.writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}
+    await fs11.writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}
 `, "utf8");
   }
   return dir;
@@ -1697,7 +1718,7 @@ async function listPlugins() {
 // src/doctor.ts
 async function exists(target) {
   try {
-    await fs11.access(target);
+    await fs12.access(target);
     return true;
   } catch {
     return false;
@@ -1803,7 +1824,7 @@ async function appendPluginDiagnostics(out, config) {
 }
 
 // src/lint.ts
-import fs12 from "fs/promises";
+import fs13 from "fs/promises";
 import path11 from "path";
 var BUDGETS = {
   recipe: { min: 50, max: 1e3 },
@@ -1896,7 +1917,7 @@ function lintArticle(article) {
 async function walkMarkdown(dir) {
   let entries;
   try {
-    entries = await fs12.readdir(dir, { withFileTypes: true });
+    entries = await fs13.readdir(dir, { withFileTypes: true });
   } catch {
     return [];
   }
@@ -1936,7 +1957,7 @@ async function lintCollections(scope) {
       const label = `${coll.name}/${rel}`;
       let findings = [];
       try {
-        const parsed = parseArticle(await fs12.readFile(full, "utf8"));
+        const parsed = parseArticle(await fs13.readFile(full, "utf8"));
         findings = lintArticle(parsed);
       } catch (err) {
         findings = [{ level: "error", rule: "parse", message: `could not parse: ${err.message}` }];
@@ -2028,6 +2049,7 @@ export {
   doctor,
   emitPluginEvent,
   ensureGitRepo,
+  ensureHome,
   ensurePluginRoot,
   fileTimestamps,
   findCollection,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diffwiki-core",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "description": "Core configuration, registry, and article management for diffwiki",
   "license": "MIT",
   "type": "module",