diffwiki-core 0.2.0-rc.f44d17c → 0.3.0-rc.202607211217.f5290fa

package/dist/index.cjs

@@ -38,6 +38,7 @@ __export(index_exports, {
   NoDefaultCollectionError: () => NoDefaultCollectionError,
   REPO_CONFIG_FILE: () => REPO_CONFIG_FILE,
   addTags: () => addTags,
+  buildArticleTree: () => buildArticleTree,
   collectionDir: () => collectionDir,
   collectionsDir: () => collectionsDir,
   configPath: () => configPath,
@@ -47,11 +48,13 @@ __export(index_exports, {
   findCollection: () => findCollection,
   getConfigValue: () => getConfigValue,
   initRepoWiki: () => initRepoWiki,
+  listArticleTree: () => listArticleTree,
   listCollections: () => listCollections,
   parseAddTarget: () => parseAddTarget,
   parseArticle: () => parseArticle,
   parsePathTarget: () => parsePathTarget,
   query: () => query,
+  readArticle: () => readArticle,
   readConfig: () => readConfig,
   readRegistry: () => readRegistry,
   readRepoConfig: () => readRepoConfig,
@@ -126,51 +129,28 @@ function collectionDir(name) {
 }
 
 // src/config.ts
-var import_promises = __toESM(require("fs/promises"), 1);
-function isMissing(err) {
-  return err?.code === "ENOENT";
-}
-async function readConfig() {
-  try {
-    return JSON.parse(await import_promises.default.readFile(configPath(), "utf8"));
-  } catch (err) {
-    if (isMissing(err)) return {};
-    throw err;
-  }
-}
-async function writeConfig(config) {
-  await import_promises.default.mkdir(resolveHome(), { recursive: true });
-  await import_promises.default.writeFile(configPath(), `${JSON.stringify(config, null, 2)}
-`, "utf8");
-}
-async function setConfigValue(key, value) {
-  const config = await readConfig();
-  config[key] = value;
-  await writeConfig(config);
-}
-async function getConfigValue(key) {
-  const config = await readConfig();
-  const value = config[key];
-  return typeof value === "string" ? value : void 0;
-}
+var import_promises3 = __toESM(require("fs/promises"), 1);
 
-// src/registry.ts
+// src/collections.ts
 var import_promises2 = __toESM(require("fs/promises"), 1);
-function isMissing2(err) {
+
+// src/registry.ts
+var import_promises = __toESM(require("fs/promises"), 1);
+function isMissing(err) {
   return err?.code === "ENOENT";
 }
 async function readRegistry() {
   try {
-    const parsed = JSON.parse(await import_promises2.default.readFile(registryPath(), "utf8"));
+    const parsed = JSON.parse(await import_promises.default.readFile(registryPath(), "utf8"));
     return { version: parsed.version ?? 1, collections: parsed.collections ?? [] };
   } catch (err) {
-    if (isMissing2(err)) return { version: 1, collections: [] };
+    if (isMissing(err)) return { version: 1, collections: [] };
     throw err;
   }
 }
 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_promises.default.mkdir(resolveHome(), { recursive: true });
+  await import_promises.default.writeFile(registryPath(), `${JSON.stringify(registry, null, 2)}
 `, "utf8");
 }
 async function registerCollection(entry) {
@@ -189,29 +169,7 @@ async function unregisterCollection(name) {
   await writeRegistry(registry);
 }
 
-// src/slugify.ts
-function slugify(input) {
-  const slug = input.toLowerCase().replace(/^#+\s*/, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80).replace(/-+$/g, "");
-  return slug.length > 0 ? slug : "untitled";
-}
-
-// src/frontmatter.ts
-var import_gray_matter = __toESM(require("gray-matter"), 1);
-function parseArticle(raw) {
-  const { data, content } = (0, import_gray_matter.default)(raw);
-  const title = typeof data.title === "string" ? data.title : "";
-  const tags = Array.isArray(data.tags) ? data.tags.map((t) => String(t)) : [];
-  return { title, tags, body: content.replace(/^\n+/, "") };
-}
-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 import_gray_matter.default.stringify(article.body, front);
-}
-
 // src/collections.ts
-var import_promises3 = __toESM(require("fs/promises"), 1);
 async function listCollections() {
   return (await readRegistry()).collections;
 }
@@ -221,7 +179,7 @@ async function findCollection(name) {
 async function createCollection(name) {
   if (await findCollection(name)) throw new CollectionExistsError(name);
   const dir = collectionDir(name);
-  await import_promises3.default.mkdir(dir, { recursive: true });
+  await import_promises2.default.mkdir(dir, { recursive: true });
   const entry = {
     name,
     type: "global",
@@ -236,11 +194,64 @@ async function removeCollection(name) {
   if (!entry) throw new CollectionNotFoundError(name);
   await unregisterCollection(name);
   if (entry.type === "global") {
-    await import_promises3.default.rm(entry.path, { recursive: true, force: true });
+    await import_promises2.default.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 import_promises3.default.readFile(configPath(), "utf8"));
+  } catch (err) {
+    if (isMissing2(err)) return {};
+    throw err;
+  }
+}
+async function writeConfig(config) {
+  await import_promises3.default.mkdir(resolveHome(), { recursive: true });
+  await import_promises3.default.writeFile(configPath(), `${JSON.stringify(config, null, 2)}
+`, "utf8");
+}
+async function setConfigValue(key, value) {
+  if (key === "defaultCollection" && !await findCollection(value)) {
+    throw new CollectionNotFoundError(value);
+  }
+  const config = await readConfig();
+  config[key] = value;
+  await writeConfig(config);
+}
+async function getConfigValue(key) {
+  const config = await readConfig();
+  const value = config[key];
+  return typeof value === "string" ? value : void 0;
+}
+
+// src/slugify.ts
+function slugify(input) {
+  const slug = input.toLowerCase().replace(/^#+\s*/, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80).replace(/-+$/g, "");
+  return slug.length > 0 ? slug : "untitled";
+}
+
+// src/frontmatter.ts
+var import_gray_matter = __toESM(require("gray-matter"), 1);
+function parseArticle(raw) {
+  const { data, content } = (0, import_gray_matter.default)(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+/, "") };
+}
+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 import_gray_matter.default.stringify(article.body, front);
+}
+
 // src/articles.ts
 var import_promises4 = __toESM(require("fs/promises"), 1);
 var import_node_path2 = __toESM(require("path"), 1);
@@ -275,7 +286,11 @@ async function resolveCollectionDir(name) {
   return { name: coll, dir: entry.path };
 }
 function ensureMdPath(file) {
-  return /\.mdx?$/.test(file) ? file : `${file}.md`;
+  if (/\.mdx?$/.test(file)) return file;
+  const dir = import_node_path2.default.dirname(file);
+  const base = slugify(import_node_path2.default.basename(file));
+  const rel = dir === "." ? `${base}.md` : import_node_path2.default.join(dir, `${base}.md`);
+  return rel;
 }
 async function createArticle(opts) {
   const { collection, title } = parseAddTarget(opts.target);
@@ -307,6 +322,7 @@ async function updateArticleBody(target, body) {
     serializeArticle({
       title: parsed.title,
       tags: parsed.tags,
+      created: parsed.created,
       updated: (/* @__PURE__ */ new Date()).toISOString(),
       body
     }),
@@ -323,6 +339,7 @@ async function mutateTags(target, fn) {
     serializeArticle({
       title: parsed.title,
       tags,
+      created: parsed.created,
       updated: (/* @__PURE__ */ new Date()).toISOString(),
       body: parsed.body
     }),
@@ -414,7 +431,8 @@ async function query(term, collection) {
   let targets;
   if (collection) {
     const one = await findCollection(collection);
-    targets = one ? [one] : [];
+    if (!one) throw new CollectionNotFoundError(collection);
+    targets = [one];
   } else {
     targets = await listCollections();
   }
@@ -479,6 +497,128 @@ async function doctor() {
   }
   return out;
 }
+
+// src/browse.ts
+var import_promises8 = __toESM(require("fs/promises"), 1);
+var import_node_path5 = __toESM(require("path"), 1);
+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);
+    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,
+      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 import_promises8.default.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(import_node_path5.default.join(dir, d.name), childRel));
+    } else if (/\.(mdx?)$/.test(d.name)) {
+      out.push(childRel);
+    }
+  }
+  return out;
+}
+async function cheapTitle(absPath) {
+  let handle;
+  try {
+    handle = await import_promises8.default.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) {
+        return { ...node, children: await enrichTitles(node.children, collDir) };
+      }
+      for (const ext of [".mdx", ".md"]) {
+        const title = await cheapTitle(import_node_path5.default.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), import_node_path5.default.resolve(entry.path));
+}
+async function readArticle(coll, slug) {
+  const entry = await findCollection(coll);
+  if (!entry) throw new CollectionNotFoundError(coll);
+  const collDir = import_node_path5.default.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("/");
+  if (!safeSlug) throw new InvalidTargetError(slug, "expected a non-empty article slug");
+  let abs;
+  for (const ext of [".mdx", ".md"]) {
+    const candidate = import_node_path5.default.resolve(collDir, `${safeSlug}${ext}`);
+    if (candidate !== collDir && !candidate.startsWith(collDir + import_node_path5.default.sep)) {
+      throw new InvalidTargetError(slug, "path traversal detected");
+    }
+    try {
+      await import_promises8.default.access(candidate);
+      abs = candidate;
+      break;
+    } catch {
+    }
+  }
+  if (!abs) throw new ArticleNotFoundError(`${coll}/${safeSlug}`);
+  const parsed = parseArticle(await import_promises8.default.readFile(abs, "utf8"));
+  const title = parsed.title?.trim() || (safeSlug.split("/").pop() ?? safeSlug);
+  return { coll, slug: safeSlug, title, tags: parsed.tags, body: parsed.body, path: abs };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ArticleNotFoundError,
@@ -489,6 +629,7 @@ async function doctor() {
   NoDefaultCollectionError,
   REPO_CONFIG_FILE,
   addTags,
+  buildArticleTree,
   collectionDir,
   collectionsDir,
   configPath,
@@ -498,11 +639,13 @@ async function doctor() {
   findCollection,
   getConfigValue,
   initRepoWiki,
+  listArticleTree,
   listCollections,
   parseAddTarget,
   parseArticle,
   parsePathTarget,
   query,
+  readArticle,
   readConfig,
   readRegistry,
   readRepoConfig,

package/dist/index.d.cts

@@ -25,6 +25,28 @@ interface RepoConfig {
     /** Path to the wiki directory, relative to the repo root. */
     path: string;
 }
+/** A node in a collection's article tree. Branches have `children`; leaves have `slug`. */
+interface ArticleNode {
+    /** Segment label — dir name for branches, filename-without-ext for leaves. */
+    name: string;
+    /** Display title — frontmatter `title` for leaves when available, else `name`. */
+    title?: string;
+    /** Leaf only: article path within the collection, without extension, e.g. "guide/setup". */
+    slug?: string;
+    /** Branch only: nested nodes. */
+    children?: ArticleNode[];
+}
+/** A resolved article's content, returned by `readArticle`. */
+interface ArticleContent {
+    coll: string;
+    slug: string;
+    title: string;
+    tags: string[];
+    /** Frontmatter-stripped body (md/mdx). */
+    body: string;
+    /** Absolute path to the file on disk. */
+    path: string;
+}
 
 /** Base class for all expected, user-facing diffwiki failures. */
 declare class DiffwikiError extends Error {
@@ -70,6 +92,7 @@ declare function slugify(input: string): string;
 interface ParsedArticle {
     title: string;
     tags: string[];
+    created?: string;
     body: string;
 }
 interface SerializableArticle {
@@ -141,4 +164,23 @@ interface Diagnostic {
 }
 declare function doctor(): Promise<Diagnostic[]>;
 
-export { type Article, ArticleNotFoundError, type CollectionEntry, CollectionExistsError, CollectionNotFoundError, type CollectionType, type Config, type Diagnostic, type DiagnosticLevel, DiffwikiError, type InitOptions, InvalidTargetError, NoDefaultCollectionError, type ParsedArticle, type QueryHit, REPO_CONFIG_FILE, type Registry, type RepoConfig, type SerializableArticle, addTags, collectionDir, collectionsDir, configPath, createArticle, createCollection, doctor, findCollection, getConfigValue, initRepoWiki, listCollections, parseAddTarget, parseArticle, parsePathTarget, query, readConfig, readRegistry, readRepoConfig, registerCollection, registryPath, removeArticle, removeCollection, removeTags, resolveHome, serializeArticle, setConfigValue, setTags, slugify, unregisterCollection, updateArticleBody, writeConfig, writeRegistry };
+/**
+ * Build a nested ArticleNode[] from a flat list of relative file paths.
+ * Pure — no I/O. Directories become branches; files become leaves whose `slug`
+ * is the relative path without extension. Dirs-first, then alpha (case-insensitive).
+ */
+declare function buildArticleTree(relPaths: string[]): ArticleNode[];
+/**
+ * List the article tree of a collection. Walks the collection's registered
+ * `entry.path` — so collections living OUTSIDE `~/.diffwiki/collections`
+ * (e.g. in-repo wikis registered via `diffwiki init`) work unchanged.
+ */
+declare function listArticleTree(coll: string): Promise<ArticleNode[]>;
+/**
+ * Read and resolve a single article by collection + slug (relative path without
+ * extension). Tries `.mdx` then `.md`, guards against path traversal, and splits
+ * frontmatter. Throws CollectionNotFoundError / ArticleNotFoundError / InvalidTargetError.
+ */
+declare function readArticle(coll: string, slug: string): Promise<ArticleContent>;
+
+export { type Article, type ArticleContent, type ArticleNode, ArticleNotFoundError, type CollectionEntry, CollectionExistsError, CollectionNotFoundError, type CollectionType, type Config, type Diagnostic, type DiagnosticLevel, DiffwikiError, type InitOptions, InvalidTargetError, NoDefaultCollectionError, type ParsedArticle, type QueryHit, REPO_CONFIG_FILE, type Registry, type RepoConfig, type SerializableArticle, addTags, buildArticleTree, collectionDir, collectionsDir, configPath, createArticle, createCollection, doctor, findCollection, getConfigValue, initRepoWiki, listArticleTree, listCollections, parseAddTarget, parseArticle, parsePathTarget, query, readArticle, readConfig, readRegistry, readRepoConfig, registerCollection, registryPath, removeArticle, removeCollection, removeTags, resolveHome, serializeArticle, setConfigValue, setTags, slugify, unregisterCollection, updateArticleBody, writeConfig, writeRegistry };

package/dist/index.d.ts

@@ -25,6 +25,28 @@ interface RepoConfig {
     /** Path to the wiki directory, relative to the repo root. */
     path: string;
 }
+/** A node in a collection's article tree. Branches have `children`; leaves have `slug`. */
+interface ArticleNode {
+    /** Segment label — dir name for branches, filename-without-ext for leaves. */
+    name: string;
+    /** Display title — frontmatter `title` for leaves when available, else `name`. */
+    title?: string;
+    /** Leaf only: article path within the collection, without extension, e.g. "guide/setup". */
+    slug?: string;
+    /** Branch only: nested nodes. */
+    children?: ArticleNode[];
+}
+/** A resolved article's content, returned by `readArticle`. */
+interface ArticleContent {
+    coll: string;
+    slug: string;
+    title: string;
+    tags: string[];
+    /** Frontmatter-stripped body (md/mdx). */
+    body: string;
+    /** Absolute path to the file on disk. */
+    path: string;
+}
 
 /** Base class for all expected, user-facing diffwiki failures. */
 declare class DiffwikiError extends Error {
@@ -70,6 +92,7 @@ declare function slugify(input: string): string;
 interface ParsedArticle {
     title: string;
     tags: string[];
+    created?: string;
     body: string;
 }
 interface SerializableArticle {
@@ -141,4 +164,23 @@ interface Diagnostic {
 }
 declare function doctor(): Promise<Diagnostic[]>;
 
-export { type Article, ArticleNotFoundError, type CollectionEntry, CollectionExistsError, CollectionNotFoundError, type CollectionType, type Config, type Diagnostic, type DiagnosticLevel, DiffwikiError, type InitOptions, InvalidTargetError, NoDefaultCollectionError, type ParsedArticle, type QueryHit, REPO_CONFIG_FILE, type Registry, type RepoConfig, type SerializableArticle, addTags, collectionDir, collectionsDir, configPath, createArticle, createCollection, doctor, findCollection, getConfigValue, initRepoWiki, listCollections, parseAddTarget, parseArticle, parsePathTarget, query, readConfig, readRegistry, readRepoConfig, registerCollection, registryPath, removeArticle, removeCollection, removeTags, resolveHome, serializeArticle, setConfigValue, setTags, slugify, unregisterCollection, updateArticleBody, writeConfig, writeRegistry };
+/**
+ * Build a nested ArticleNode[] from a flat list of relative file paths.
+ * Pure — no I/O. Directories become branches; files become leaves whose `slug`
+ * is the relative path without extension. Dirs-first, then alpha (case-insensitive).
+ */
+declare function buildArticleTree(relPaths: string[]): ArticleNode[];
+/**
+ * List the article tree of a collection. Walks the collection's registered
+ * `entry.path` — so collections living OUTSIDE `~/.diffwiki/collections`
+ * (e.g. in-repo wikis registered via `diffwiki init`) work unchanged.
+ */
+declare function listArticleTree(coll: string): Promise<ArticleNode[]>;
+/**
+ * Read and resolve a single article by collection + slug (relative path without
+ * extension). Tries `.mdx` then `.md`, guards against path traversal, and splits
+ * frontmatter. Throws CollectionNotFoundError / ArticleNotFoundError / InvalidTargetError.
+ */
+declare function readArticle(coll: string, slug: string): Promise<ArticleContent>;
+
+export { type Article, type ArticleContent, type ArticleNode, ArticleNotFoundError, type CollectionEntry, CollectionExistsError, CollectionNotFoundError, type CollectionType, type Config, type Diagnostic, type DiagnosticLevel, DiffwikiError, type InitOptions, InvalidTargetError, NoDefaultCollectionError, type ParsedArticle, type QueryHit, REPO_CONFIG_FILE, type Registry, type RepoConfig, type SerializableArticle, addTags, buildArticleTree, collectionDir, collectionsDir, configPath, createArticle, createCollection, doctor, findCollection, getConfigValue, initRepoWiki, listArticleTree, listCollections, parseAddTarget, parseArticle, parsePathTarget, query, readArticle, readConfig, readRegistry, readRepoConfig, registerCollection, registryPath, removeArticle, removeCollection, removeTags, resolveHome, serializeArticle, setConfigValue, setTags, slugify, unregisterCollection, updateArticleBody, writeConfig, writeRegistry };

package/dist/index.js

@@ -52,51 +52,28 @@ function collectionDir(name) {
 }
 
 // src/config.ts
-import fs from "fs/promises";
-function isMissing(err) {
-  return err?.code === "ENOENT";
-}
-async function readConfig() {
-  try {
-    return JSON.parse(await fs.readFile(configPath(), "utf8"));
-  } catch (err) {
-    if (isMissing(err)) return {};
-    throw err;
-  }
-}
-async function writeConfig(config) {
-  await fs.mkdir(resolveHome(), { recursive: true });
-  await fs.writeFile(configPath(), `${JSON.stringify(config, null, 2)}
-`, "utf8");
-}
-async function setConfigValue(key, value) {
-  const config = await readConfig();
-  config[key] = value;
-  await writeConfig(config);
-}
-async function getConfigValue(key) {
-  const config = await readConfig();
-  const value = config[key];
-  return typeof value === "string" ? value : void 0;
-}
+import fs3 from "fs/promises";
 
-// src/registry.ts
+// src/collections.ts
 import fs2 from "fs/promises";
-function isMissing2(err) {
+
+// src/registry.ts
+import fs from "fs/promises";
+function isMissing(err) {
   return err?.code === "ENOENT";
 }
 async function readRegistry() {
   try {
-    const parsed = JSON.parse(await fs2.readFile(registryPath(), "utf8"));
+    const parsed = JSON.parse(await fs.readFile(registryPath(), "utf8"));
     return { version: parsed.version ?? 1, collections: parsed.collections ?? [] };
   } catch (err) {
-    if (isMissing2(err)) return { version: 1, collections: [] };
+    if (isMissing(err)) return { version: 1, collections: [] };
     throw err;
   }
 }
 async function writeRegistry(registry) {
-  await fs2.mkdir(resolveHome(), { recursive: true });
-  await fs2.writeFile(registryPath(), `${JSON.stringify(registry, null, 2)}
+  await fs.mkdir(resolveHome(), { recursive: true });
+  await fs.writeFile(registryPath(), `${JSON.stringify(registry, null, 2)}
 `, "utf8");
 }
 async function registerCollection(entry) {
@@ -115,29 +92,7 @@ async function unregisterCollection(name) {
   await writeRegistry(registry);
 }
 
-// src/slugify.ts
-function slugify(input) {
-  const slug = input.toLowerCase().replace(/^#+\s*/, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80).replace(/-+$/g, "");
-  return slug.length > 0 ? slug : "untitled";
-}
-
-// src/frontmatter.ts
-import matter from "gray-matter";
-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)) : [];
-  return { title, tags, body: content.replace(/^\n+/, "") };
-}
-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);
-}
-
 // src/collections.ts
-import fs3 from "fs/promises";
 async function listCollections() {
   return (await readRegistry()).collections;
 }
@@ -147,7 +102,7 @@ async function findCollection(name) {
 async function createCollection(name) {
   if (await findCollection(name)) throw new CollectionExistsError(name);
   const dir = collectionDir(name);
-  await fs3.mkdir(dir, { recursive: true });
+  await fs2.mkdir(dir, { recursive: true });
   const entry = {
     name,
     type: "global",
@@ -162,11 +117,64 @@ async function removeCollection(name) {
   if (!entry) throw new CollectionNotFoundError(name);
   await unregisterCollection(name);
   if (entry.type === "global") {
-    await fs3.rm(entry.path, { recursive: true, force: true });
+    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"));
+  } catch (err) {
+    if (isMissing2(err)) return {};
+    throw err;
+  }
+}
+async function writeConfig(config) {
+  await fs3.mkdir(resolveHome(), { recursive: true });
+  await fs3.writeFile(configPath(), `${JSON.stringify(config, null, 2)}
+`, "utf8");
+}
+async function setConfigValue(key, value) {
+  if (key === "defaultCollection" && !await findCollection(value)) {
+    throw new CollectionNotFoundError(value);
+  }
+  const config = await readConfig();
+  config[key] = value;
+  await writeConfig(config);
+}
+async function getConfigValue(key) {
+  const config = await readConfig();
+  const value = config[key];
+  return typeof value === "string" ? value : void 0;
+}
+
+// src/slugify.ts
+function slugify(input) {
+  const slug = input.toLowerCase().replace(/^#+\s*/, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80).replace(/-+$/g, "");
+  return slug.length > 0 ? slug : "untitled";
+}
+
+// src/frontmatter.ts
+import matter from "gray-matter";
+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+/, "") };
+}
+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);
+}
+
 // src/articles.ts
 import fs4 from "fs/promises";
 import path2 from "path";
@@ -201,7 +209,11 @@ async function resolveCollectionDir(name) {
   return { name: coll, dir: entry.path };
 }
 function ensureMdPath(file) {
-  return /\.mdx?$/.test(file) ? file : `${file}.md`;
+  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`);
+  return rel;
 }
 async function createArticle(opts) {
   const { collection, title } = parseAddTarget(opts.target);
@@ -233,6 +245,7 @@ async function updateArticleBody(target, body) {
     serializeArticle({
       title: parsed.title,
       tags: parsed.tags,
+      created: parsed.created,
       updated: (/* @__PURE__ */ new Date()).toISOString(),
       body
     }),
@@ -249,6 +262,7 @@ async function mutateTags(target, fn) {
     serializeArticle({
       title: parsed.title,
       tags,
+      created: parsed.created,
       updated: (/* @__PURE__ */ new Date()).toISOString(),
       body: parsed.body
     }),
@@ -340,7 +354,8 @@ async function query(term, collection) {
   let targets;
   if (collection) {
     const one = await findCollection(collection);
-    targets = one ? [one] : [];
+    if (!one) throw new CollectionNotFoundError(collection);
+    targets = [one];
   } else {
     targets = await listCollections();
   }
@@ -405,6 +420,128 @@ async function doctor() {
   }
   return out;
 }
+
+// src/browse.ts
+import fs8 from "fs/promises";
+import path5 from "path";
+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);
+    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,
+      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 fs8.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 cheapTitle(absPath) {
+  let handle;
+  try {
+    handle = await fs8.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) {
+        return { ...node, children: await enrichTitles(node.children, collDir) };
+      }
+      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("/");
+  if (!safeSlug) throw new InvalidTargetError(slug, "expected a non-empty article slug");
+  let abs;
+  for (const ext of [".mdx", ".md"]) {
+    const candidate = path5.resolve(collDir, `${safeSlug}${ext}`);
+    if (candidate !== collDir && !candidate.startsWith(collDir + path5.sep)) {
+      throw new InvalidTargetError(slug, "path traversal detected");
+    }
+    try {
+      await fs8.access(candidate);
+      abs = candidate;
+      break;
+    } catch {
+    }
+  }
+  if (!abs) throw new ArticleNotFoundError(`${coll}/${safeSlug}`);
+  const parsed = parseArticle(await fs8.readFile(abs, "utf8"));
+  const title = parsed.title?.trim() || (safeSlug.split("/").pop() ?? safeSlug);
+  return { coll, slug: safeSlug, title, tags: parsed.tags, body: parsed.body, path: abs };
+}
 export {
   ArticleNotFoundError,
   CollectionExistsError,
@@ -414,6 +551,7 @@ export {
   NoDefaultCollectionError,
   REPO_CONFIG_FILE,
   addTags,
+  buildArticleTree,
   collectionDir,
   collectionsDir,
   configPath,
@@ -423,11 +561,13 @@ export {
   findCollection,
   getConfigValue,
   initRepoWiki,
+  listArticleTree,
   listCollections,
   parseAddTarget,
   parseArticle,
   parsePathTarget,
   query,
+  readArticle,
   readConfig,
   readRegistry,
   readRepoConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diffwiki-core",
-  "version": "0.2.0-rc.f44d17c",
+  "version": "0.3.0-rc.202607211217.f5290fa",
   "description": "Core configuration, registry, and article management for diffwiki",
   "license": "MIT",
   "type": "module",