diffwiki-core 0.7.0 → 0.8.0

package/dist/index.cjs

@@ -582,6 +582,7 @@ __export(index_exports, {
   buildSearchIndex: () => buildSearchIndex,
   collectionDir: () => collectionDir,
   collectionGitStatus: () => collectionGitStatus,
+  collectionMeta: () => collectionMeta,
   collectionsDir: () => collectionsDir,
   configPath: () => configPath,
   createArticle: () => createArticle,
@@ -729,22 +730,39 @@ var YAML_ENGINE = {
   stringify: (data) => (0, import_yaml.stringify)(data)
 };
 var MATTER_OPTS = { engines: { yaml: YAML_ENGINE } };
+function coerceAudience(value) {
+  return value === "private" ? "private" : "public";
+}
+function coerceStatus(value) {
+  return value === "draft" ? "draft" : "published";
+}
 function parseFallback(raw) {
   const fenceRe = /^---[ \t]*\n([\s\S]*?)\n---[ \t]*\n/;
   const fenceMatch = fenceRe.exec(raw);
   let title = "";
+  let audience = "public";
+  let status = "published";
   let body;
+  const clean = (s) => s.trim().replace(/^["']|["']$/g, "");
   if (fenceMatch) {
     const inner = fenceMatch[1];
     const titleMatch = /^title:\s*(.+)$/m.exec(inner);
     if (titleMatch) {
-      title = titleMatch[1].trim().replace(/^["']|["']$/g, "");
+      title = clean(titleMatch[1]);
+    }
+    const audienceMatch = /^audience:\s*(.+)$/m.exec(inner);
+    if (audienceMatch) {
+      audience = coerceAudience(clean(audienceMatch[1]));
+    }
+    const statusMatch = /^status:\s*(.+)$/m.exec(inner);
+    if (statusMatch) {
+      status = coerceStatus(clean(statusMatch[1]));
     }
     body = raw.slice(fenceMatch[0].length);
   } else {
     body = raw;
   }
-  return { title, tags: [], body: body.replace(/^\n+/, "") };
+  return { title, tags: [], audience, status, body: body.replace(/^\n+/, "") };
 }
 function parseArticle(raw) {
   try {
@@ -752,13 +770,17 @@ function parseArticle(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+/, "") };
+    const audience = coerceAudience(data.audience);
+    const status = coerceStatus(data.status);
+    return { title, tags, created, audience, status, body: content.replace(/^\n+/, "") };
   } catch {
     return parseFallback(raw);
   }
 }
 function serializeArticle(article) {
   const front = { title: article.title, tags: article.tags };
+  if (article.audience === "private") front.audience = "private";
+  if (article.status === "draft") front.status = "draft";
   return import_gray_matter.default.stringify(article.body, front, MATTER_OPTS);
 }
 
@@ -839,7 +861,17 @@ async function loadArticle(target) {
 async function updateArticleBody(target, body) {
   const { filePath, dir, raw, collection } = await loadArticle(target);
   const parsed = parseArticle(raw);
-  await import_promises5.default.writeFile(filePath, serializeArticle({ title: parsed.title, tags: parsed.tags, body }), "utf8");
+  await import_promises5.default.writeFile(
+    filePath,
+    serializeArticle({
+      title: parsed.title,
+      tags: parsed.tags,
+      audience: parsed.audience,
+      status: parsed.status,
+      body
+    }),
+    "utf8"
+  );
   void fireHook2("article-updated", collection, import_node_path3.default.relative(dir, filePath));
   return { title: parsed.title, tags: parsed.tags, path: filePath, collection };
 }
@@ -847,7 +879,17 @@ async function mutateTags(target, fn) {
   const { filePath, dir, raw, collection } = await loadArticle(target);
   const parsed = parseArticle(raw);
   const tags = fn(parsed.tags);
-  await import_promises5.default.writeFile(filePath, serializeArticle({ title: parsed.title, tags, body: parsed.body }), "utf8");
+  await import_promises5.default.writeFile(
+    filePath,
+    serializeArticle({
+      title: parsed.title,
+      tags,
+      audience: parsed.audience,
+      status: parsed.status,
+      body: parsed.body
+    }),
+    "utf8"
+  );
   void fireHook2("article-updated", collection, import_node_path3.default.relative(dir, filePath));
   return { title: parsed.title, tags, path: filePath, collection };
 }
@@ -1168,20 +1210,30 @@ function pickIndexFile(names) {
   };
   return names.filter((n) => INDEX_RE.test(n)).sort((a, b) => rank(a) - rank(b))[0];
 }
-async function cheapTitle(absPath) {
+var CHEAP_META_BYTES = 8192;
+async function cheapMeta(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 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");
-    const m = snippet.match(/^---[\s\S]*?^title:\s*(.+)$/m);
-    if (m) return m[1].trim().replace(/^["']|["']$/g, "");
+    const fence = /^---[ \t]*\n([\s\S]*?)(?:\n---[ \t]*\n|$)/.exec(snippet);
+    if (!fence) return {};
+    const inner = fence[1];
+    const clean = (s) => s.trim().replace(/^["']|["']$/g, "");
+    const titleM = /^title:\s*(.+)$/m.exec(inner);
+    const audienceM = /^audience:\s*(.+)$/m.exec(inner);
+    const statusM = /^status:\s*(.+)$/m.exec(inner);
+    const title = titleM ? clean(titleM[1]) : void 0;
+    const audience = audienceM && clean(audienceM[1]) === "private" ? "private" : void 0;
+    const status = statusM && clean(statusM[1]) === "draft" ? "draft" : void 0;
+    return { title, audience, status };
   } catch {
   } finally {
     await handle?.close();
   }
-  return void 0;
+  return {};
 }
 async function enrichTitles(nodes, collDir) {
   return Promise.all(
@@ -1189,21 +1241,41 @@ async function enrichTitles(nodes, collDir) {
       if (node.children) {
         const children = await enrichTitles(node.children, collDir);
         let title = node.title;
+        let audience = node.audience;
+        let status = node.status;
         if (node.slug) {
           const dir = import_node_path6.default.join(collDir, node.slug);
           const idx = pickIndexFile(await readdirSafe(dir));
-          if (idx) title = await cheapTitle(import_node_path6.default.join(dir, idx)) ?? title;
+          if (idx) {
+            const meta = await cheapMeta(import_node_path6.default.join(dir, idx));
+            title = meta.title ?? title;
+            audience = meta.audience ?? audience;
+            status = meta.status ?? status;
+          }
         }
-        return { ...node, title, children };
+        return { ...node, title, audience, status, children };
       }
       for (const ext of [".mdx", ".md"]) {
-        const title = await cheapTitle(import_node_path6.default.join(collDir, `${node.slug}${ext}`));
-        if (title) return { ...node, title };
+        const meta = await cheapMeta(import_node_path6.default.join(collDir, `${node.slug}${ext}`));
+        if (meta.title || meta.audience || meta.status) {
+          return {
+            ...node,
+            title: meta.title ?? node.title,
+            audience: meta.audience ?? node.audience,
+            status: meta.status ?? node.status
+          };
+        }
       }
       return node;
     })
   );
 }
+async function collectionMeta(collDir) {
+  const idx = pickIndexFile(await readdirSafe(collDir));
+  if (!idx) return {};
+  const meta = await cheapMeta(import_node_path6.default.join(collDir, idx));
+  return { audience: meta.audience, status: meta.status };
+}
 async function listArticleTree(coll) {
   const entry = await findCollection(coll);
   if (!entry) throw new CollectionNotFoundError(coll);
@@ -1245,7 +1317,17 @@ async function readArticle(coll, slug) {
   if (!abs) throw new ArticleNotFoundError(`${coll}/${safeSlug}`);
   const parsed = parseArticle(await import_promises8.default.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, isIndex };
+  return {
+    coll,
+    slug: safeSlug,
+    title,
+    tags: parsed.tags,
+    audience: parsed.audience,
+    status: parsed.status,
+    body: parsed.body,
+    path: abs,
+    isIndex
+  };
 }
 
 // src/render.ts
@@ -1278,10 +1360,15 @@ function rehypeRewriteLinks(ctx) {
       if (pathPart === "") return;
       const joined = import_node_path7.default.posix.join(slugDir === "." ? "" : slugDir, pathPart);
       const normalized = import_node_path7.default.posix.normalize(joined);
+      const toRoute = (p) => p.replace(/\.(mdx?)$/i, "").replace(/(^|\/)(index|readme)$/i, "$1").replace(/\/+$/, "").replace(/^\/+/, "");
+      if (normalized.startsWith("../")) {
+        const sibling = normalized.slice(3);
+        if (sibling === "" || sibling.startsWith("..")) return;
+        node.properties = { ...node.properties, href: `/${toRoute(sibling)}${suffix}` };
+        return;
+      }
       if (normalized.startsWith("..")) return;
-      let resolved = normalized.replace(/\.(mdx?)$/i, "");
-      resolved = resolved.replace(/(^|\/)(index|readme)$/i, "$1");
-      resolved = resolved.replace(/\/+$/, "").replace(/^\/+/, "");
+      const resolved = toRoute(normalized);
       node.properties = {
         ...node.properties,
         href: `/${ctx.coll}${resolved ? `/${resolved}` : ""}${suffix}`
@@ -1496,13 +1583,22 @@ function localGraph(graph, focusId, include, siblingCap = 12) {
 init_errors();
 var isStatic = () => process.env.DIFFWIKI_STATIC === "1";
 function toTreeNodes(coll, nodes) {
-  return nodes.map(
+  const visible = isStatic() ? nodes.filter((n) => n.audience !== "private" && n.status !== "draft") : nodes;
+  return visible.map(
     (n) => n.children ? {
       name: n.name,
       title: n.title ?? n.name,
       path: n.slug ? `/${coll}/${n.slug}` : void 0,
+      ...n.audience ? { audience: n.audience } : {},
+      ...n.status ? { status: n.status } : {},
       children: toTreeNodes(coll, n.children)
-    } : { name: n.name, title: n.title ?? n.name, path: `/${coll}/${n.slug}` }
+    } : {
+      name: n.name,
+      title: n.title ?? n.name,
+      path: `/${coll}/${n.slug}`,
+      ...n.audience ? { audience: n.audience } : {},
+      ...n.status ? { status: n.status } : {}
+    }
   );
 }
 async function gitInfo(e) {
@@ -1515,23 +1611,40 @@ async function gitInfo(e) {
 }
 async function buildCollections() {
   const entries = await listCollections();
-  return Promise.all(
-    entries.map(async (e) => ({
-      name: e.name,
-      type: e.type,
-      path: e.path,
-      ...await gitInfo(e)
-    }))
+  const infos = await Promise.all(
+    entries.map(async (e) => {
+      const { audience, status } = await collectionMeta(e.path);
+      return {
+        name: e.name,
+        type: e.type,
+        path: e.path,
+        ...await gitInfo(e),
+        ...audience ? { audience } : {},
+        ...status ? { status } : {}
+      };
+    })
   );
+  return isStatic() ? infos.filter((c) => c.audience !== "private" && c.status !== "draft") : infos;
 }
 async function buildNavTree() {
   const entries = await listCollections();
-  return Promise.all(
-    entries.map(async (e) => ({
-      collection: { name: e.name, type: e.type, path: e.path, ...await gitInfo(e) },
-      nodes: toTreeNodes(e.name, await listArticleTree(e.name))
-    }))
+  const trees = await Promise.all(
+    entries.map(async (e) => {
+      const { audience, status } = await collectionMeta(e.path);
+      return {
+        collection: {
+          name: e.name,
+          type: e.type,
+          path: e.path,
+          ...await gitInfo(e),
+          ...audience ? { audience } : {},
+          ...status ? { status } : {}
+        },
+        nodes: toTreeNodes(e.name, await listArticleTree(e.name))
+      };
+    })
   );
+  return isStatic() ? trees.filter((t) => t.collection.audience !== "private" && t.collection.status !== "draft") : trees;
 }
 function findNode(nodes, slug) {
   for (const n of nodes) {
@@ -1559,6 +1672,8 @@ async function resolvePage(coll, slug, opts) {
       slug: art.slug,
       title: art.title,
       tags: art.tags,
+      ...art.audience === "private" ? { audience: art.audience } : {},
+      ...art.status === "draft" ? { status: art.status } : {},
       html,
       toc,
       path: `/${art.coll}/${art.slug}`,
@@ -1808,6 +1923,7 @@ async function query(term, opts) {
 var import_promises10 = __toESM(require("fs/promises"), 1);
 var import_node_path9 = __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 {
@@ -1820,6 +1936,7 @@ async function readArticleParts(collDir, slug) {
 }
 async function flatten(coll, collDir, nodes, out) {
   for (const n of nodes) {
+    if (isStatic2() && (n.audience === "private" || n.status === "draft")) continue;
     if (n.slug && !n.children) {
       const title = n.title ?? n.name;
       const { tags, body } = await readArticleParts(collDir, n.slug);
@@ -1846,6 +1963,10 @@ async function buildSearchIndex(collection) {
     try {
       const collEntry = await findCollection(e.name);
       const collDir = import_node_path9.default.resolve(collEntry?.path ?? e.path);
+      if (isStatic2()) {
+        const cm = await collectionMeta(collDir);
+        if (cm.audience === "private" || cm.status === "draft") continue;
+      }
       await flatten(e.name, collDir, await listArticleTree(e.name), out);
     } catch {
     }
@@ -2256,6 +2377,7 @@ init_registry2();
   buildSearchIndex,
   collectionDir,
   collectionGitStatus,
+  collectionMeta,
   collectionsDir,
   configPath,
   createArticle,

package/dist/index.d.cts

@@ -2,6 +2,10 @@ import { SearchDoc } from './bm25.cjs';
 export { RankableFields, rankDocs, tokenize } from './bm25.cjs';
 import { LogLevel, Logger } from '@logtape/logtape';
 
+/** Audience axis — who an article is for. Private is never published. Missing/invalid → 'public'. */
+type Audience = 'public' | 'private';
+/** Lifecycle axis — readiness. Draft is not yet published. Missing/invalid → 'published'. */
+type PublishStatus = 'draft' | 'published';
 type CollectionType = 'global' | 'repo' | 'external';
 interface CollectionEntry {
     name: string;
@@ -47,6 +51,10 @@ interface ArticleNode {
      * leaves (the article) and on branches (the folder, navigable to its index).
      */
     slug?: string;
+    /** Audience, set only when 'private' (omitted for 'public'). */
+    audience?: Audience;
+    /** Lifecycle status, set only when 'draft' (omitted for 'published'). */
+    status?: PublishStatus;
     /** Branch only: nested nodes. */
     children?: ArticleNode[];
 }
@@ -56,6 +64,10 @@ interface ArticleContent {
     slug: string;
     title: string;
     tags: string[];
+    /** Audience from frontmatter ('public' when absent). */
+    audience: Audience;
+    /** Lifecycle status from frontmatter ('published' when absent). */
+    status: PublishStatus;
     /** Frontmatter-stripped body (md/mdx). */
     body: string;
     /** Absolute path to the file on disk. */
@@ -160,6 +172,10 @@ interface TreeNode {
     name: string;
     title?: string;
     path?: string;
+    /** Audience; present only when 'private' (drives the sidebar lock). */
+    audience?: Audience;
+    /** Lifecycle status; present only when 'draft' (drives the sidebar DRAFT tag). */
+    status?: PublishStatus;
     children?: TreeNode[];
     /** Set only on top-level collection rows: git branch/behind badge data. */
     meta?: NodeMeta;
@@ -170,6 +186,10 @@ interface CollectionInfo {
     path: string;
     branch?: string;
     behind?: number;
+    /** Audience from the collection's root index page; present only when 'private'. */
+    audience?: Audience;
+    /** Lifecycle status from the collection's root index page; present only when 'draft'. */
+    status?: PublishStatus;
 }
 interface CollectionTree {
     collection: CollectionInfo;
@@ -185,6 +205,10 @@ interface DocData {
     slug: string;
     title: string;
     tags: string[];
+    /** Audience; present only when 'private'. */
+    audience?: Audience;
+    /** Lifecycle status; present only when 'draft'. */
+    status?: PublishStatus;
     html: string;
     toc: TocItem[];
     path: string;
@@ -307,11 +331,15 @@ interface ParsedArticle {
     title: string;
     tags: string[];
     created?: string;
+    audience: Audience;
+    status: PublishStatus;
     body: string;
 }
 interface SerializableArticle {
     title: string;
     tags: string[];
+    audience?: Audience;
+    status?: PublishStatus;
     body: string;
 }
 declare function parseArticle(raw: string): ParsedArticle;
@@ -436,7 +464,10 @@ interface FileTimestamps {
  */
 declare function fileTimestamps(absPath: string): Promise<FileTimestamps>;
 
-/** Map core article nodes to UI nav nodes, assigning each its route path. */
+/** Map core article nodes to UI nav nodes, assigning each its route path.
+ *  In static builds, private (audience) or draft (status) articles are dropped
+ *  entirely (no nav row, and — since routes + per-doc JSON derive from this tree
+ *  — no route/JSON). */
 declare function toTreeNodes(coll: string, nodes: ArticleNode[]): TreeNode[];
 declare function buildCollections(): Promise<CollectionInfo[]>;
 declare function buildNavTree(): Promise<CollectionTree[]>;
@@ -640,6 +671,16 @@ declare function resolveLogLevel(env?: NodeJS.ProcessEnv): DiffwikiLogLevel;
  * is the relative path without extension. Dirs-first, then alpha (case-insensitive).
  */
 declare function buildArticleTree(relPaths: string[]): ArticleNode[];
+/**
+ * Read a collection's (or any directory's) audience + status from its index page
+ * (index.md / README). Each axis is present only at its non-default value
+ * (audience:'private' / status:'draft'), else absent. Cheap partial read — used
+ * to mark/skip whole collections the same way leaf articles are.
+ */
+declare function collectionMeta(collDir: string): Promise<{
+    audience?: Audience;
+    status?: PublishStatus;
+}>;
 /**
  * List the article tree of a collection. Walks the collection's registered
  * `entry.path` — so collections living OUTSIDE `~/.diffwiki/collections`
@@ -890,4 +931,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, type Article, type ArticleContent, type ArticleNode, ArticleNotFoundError, CollectionAlreadyAddedError, type CollectionEntry, CollectionExistsError, type CollectionGitStatus, type CollectionInfo, CollectionNotFoundError, type CollectionSelection, type CollectionSelectionResult, type CollectionTree, type CollectionType, type Config, type Diagnostic, type DiagnosticLevel, DiffwikiError, type DiffwikiLogLevel, type DocData, type FileTimestamps, type GraphEdge, type GraphNode, type InitOptions, type InstallOutcome, InvalidExportSelectionError, InvalidTargetError, type KnownPlugin, type LinkGraph, type ListingEntry, type LocalGraph, NATIVE_ENGINE, NoDefaultCollectionError, type NodeMeta, type PageData, type ParsedArticle, type PluginCapabilities, PluginError, type PluginEvent, type PluginHealth, type PluginKind, type PluginReadiness, type PluginRecord, type PluginRegistryFile, type QueryHit, type QueryOptions, REPO_CONFIG_FILE, type Registry, type RenderContext, type RenderedArticle, type RepoConfig, SearchDoc, type SearchMode, type SearchOutcome, type SearchProvider, type SerializableArticle, type SetupOutcome, type SetupStep, type TocItem, type TreeNode, type UpstreamStatus, WorktreeNotAllowedError, addExternalCollection, addTags, buildArticleTree, buildCollections, buildLinkGraph, buildNavTree, buildSearchIndex, collectionDir, collectionGitStatus, collectionsDir, configPath, createArticle, createCollection, currentBranch, deregisterPlugin, doctor, emitPluginEvent, ensureGitRepo, ensurePluginRoot, fileTimestamps, findCollection, findCollectionById, findEnabledPlugin, findPluginRecord, getConfigValue, getLogger, gitToplevel, initRepoWiki, installPlugin, invalidateLinkGraph, isLinkedWorktree, listArticleTree, listAvailablePlugins, listCollections, listEnabledPlugins, listPlugins, listSearchModes, loadSearchProvider, localGraph, nativeSearch, parseAddTarget, parseArticle, parsePathTarget, pluginsDir, pluginsRegistryPath, query, readArticle, readConfig, readPluginRegistry, readRegistry, readRepoConfig, registerCollection, registerPlugin, registryPath, removeArticle, removeCollection, removePlugin, removeTags, renderArticle, repoId, repoRemoteName, resolveCollectionSelection, resolveCwdCollection, resolveDefaultSearchMode, resolveHome, resolveLogLevel, resolvePage, search, serializeArticle, setConfigValue, setTags, slugify, toTreeNodes, unregisterCollection, updateArticleBody, upsertPlugin, upstreamStatus, writeConfig, writePluginRegistry, writeRegistry };
+export { type AddExternalOptions, type Article, type ArticleContent, type ArticleNode, ArticleNotFoundError, type Audience, CollectionAlreadyAddedError, type CollectionEntry, CollectionExistsError, type CollectionGitStatus, type CollectionInfo, CollectionNotFoundError, type CollectionSelection, type CollectionSelectionResult, type CollectionTree, type CollectionType, type Config, type Diagnostic, type DiagnosticLevel, DiffwikiError, type DiffwikiLogLevel, type DocData, type FileTimestamps, type GraphEdge, type GraphNode, type InitOptions, type InstallOutcome, InvalidExportSelectionError, InvalidTargetError, type KnownPlugin, type LinkGraph, type ListingEntry, type LocalGraph, NATIVE_ENGINE, NoDefaultCollectionError, type NodeMeta, type PageData, type ParsedArticle, type PluginCapabilities, PluginError, type PluginEvent, type PluginHealth, type PluginKind, type PluginReadiness, type PluginRecord, type PluginRegistryFile, type PublishStatus, type QueryHit, type QueryOptions, REPO_CONFIG_FILE, type Registry, type RenderContext, type RenderedArticle, type RepoConfig, SearchDoc, type SearchMode, type SearchOutcome, type SearchProvider, type SerializableArticle, type SetupOutcome, type SetupStep, type TocItem, type TreeNode, type UpstreamStatus, WorktreeNotAllowedError, addExternalCollection, addTags, buildArticleTree, buildCollections, buildLinkGraph, buildNavTree, buildSearchIndex, 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, listArticleTree, listAvailablePlugins, listCollections, listEnabledPlugins, listPlugins, listSearchModes, loadSearchProvider, localGraph, nativeSearch, parseAddTarget, parseArticle, parsePathTarget, pluginsDir, pluginsRegistryPath, query, readArticle, readConfig, readPluginRegistry, readRegistry, readRepoConfig, registerCollection, registerPlugin, registryPath, removeArticle, removeCollection, removePlugin, removeTags, renderArticle, repoId, repoRemoteName, resolveCollectionSelection, resolveCwdCollection, resolveDefaultSearchMode, resolveHome, resolveLogLevel, resolvePage, search, serializeArticle, setConfigValue, setTags, slugify, toTreeNodes, unregisterCollection, updateArticleBody, upsertPlugin, upstreamStatus, writeConfig, writePluginRegistry, writeRegistry };

package/dist/index.d.ts

@@ -2,6 +2,10 @@ import { SearchDoc } from './bm25.js';
 export { RankableFields, rankDocs, tokenize } from './bm25.js';
 import { LogLevel, Logger } from '@logtape/logtape';
 
+/** Audience axis — who an article is for. Private is never published. Missing/invalid → 'public'. */
+type Audience = 'public' | 'private';
+/** Lifecycle axis — readiness. Draft is not yet published. Missing/invalid → 'published'. */
+type PublishStatus = 'draft' | 'published';
 type CollectionType = 'global' | 'repo' | 'external';
 interface CollectionEntry {
     name: string;
@@ -47,6 +51,10 @@ interface ArticleNode {
      * leaves (the article) and on branches (the folder, navigable to its index).
      */
     slug?: string;
+    /** Audience, set only when 'private' (omitted for 'public'). */
+    audience?: Audience;
+    /** Lifecycle status, set only when 'draft' (omitted for 'published'). */
+    status?: PublishStatus;
     /** Branch only: nested nodes. */
     children?: ArticleNode[];
 }
@@ -56,6 +64,10 @@ interface ArticleContent {
     slug: string;
     title: string;
     tags: string[];
+    /** Audience from frontmatter ('public' when absent). */
+    audience: Audience;
+    /** Lifecycle status from frontmatter ('published' when absent). */
+    status: PublishStatus;
     /** Frontmatter-stripped body (md/mdx). */
     body: string;
     /** Absolute path to the file on disk. */
@@ -160,6 +172,10 @@ interface TreeNode {
     name: string;
     title?: string;
     path?: string;
+    /** Audience; present only when 'private' (drives the sidebar lock). */
+    audience?: Audience;
+    /** Lifecycle status; present only when 'draft' (drives the sidebar DRAFT tag). */
+    status?: PublishStatus;
     children?: TreeNode[];
     /** Set only on top-level collection rows: git branch/behind badge data. */
     meta?: NodeMeta;
@@ -170,6 +186,10 @@ interface CollectionInfo {
     path: string;
     branch?: string;
     behind?: number;
+    /** Audience from the collection's root index page; present only when 'private'. */
+    audience?: Audience;
+    /** Lifecycle status from the collection's root index page; present only when 'draft'. */
+    status?: PublishStatus;
 }
 interface CollectionTree {
     collection: CollectionInfo;
@@ -185,6 +205,10 @@ interface DocData {
     slug: string;
     title: string;
     tags: string[];
+    /** Audience; present only when 'private'. */
+    audience?: Audience;
+    /** Lifecycle status; present only when 'draft'. */
+    status?: PublishStatus;
     html: string;
     toc: TocItem[];
     path: string;
@@ -307,11 +331,15 @@ interface ParsedArticle {
     title: string;
     tags: string[];
     created?: string;
+    audience: Audience;
+    status: PublishStatus;
     body: string;
 }
 interface SerializableArticle {
     title: string;
     tags: string[];
+    audience?: Audience;
+    status?: PublishStatus;
     body: string;
 }
 declare function parseArticle(raw: string): ParsedArticle;
@@ -436,7 +464,10 @@ interface FileTimestamps {
  */
 declare function fileTimestamps(absPath: string): Promise<FileTimestamps>;
 
-/** Map core article nodes to UI nav nodes, assigning each its route path. */
+/** Map core article nodes to UI nav nodes, assigning each its route path.
+ *  In static builds, private (audience) or draft (status) articles are dropped
+ *  entirely (no nav row, and — since routes + per-doc JSON derive from this tree
+ *  — no route/JSON). */
 declare function toTreeNodes(coll: string, nodes: ArticleNode[]): TreeNode[];
 declare function buildCollections(): Promise<CollectionInfo[]>;
 declare function buildNavTree(): Promise<CollectionTree[]>;
@@ -640,6 +671,16 @@ declare function resolveLogLevel(env?: NodeJS.ProcessEnv): DiffwikiLogLevel;
  * is the relative path without extension. Dirs-first, then alpha (case-insensitive).
  */
 declare function buildArticleTree(relPaths: string[]): ArticleNode[];
+/**
+ * Read a collection's (or any directory's) audience + status from its index page
+ * (index.md / README). Each axis is present only at its non-default value
+ * (audience:'private' / status:'draft'), else absent. Cheap partial read — used
+ * to mark/skip whole collections the same way leaf articles are.
+ */
+declare function collectionMeta(collDir: string): Promise<{
+    audience?: Audience;
+    status?: PublishStatus;
+}>;
 /**
  * List the article tree of a collection. Walks the collection's registered
  * `entry.path` — so collections living OUTSIDE `~/.diffwiki/collections`
@@ -890,4 +931,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, type Article, type ArticleContent, type ArticleNode, ArticleNotFoundError, CollectionAlreadyAddedError, type CollectionEntry, CollectionExistsError, type CollectionGitStatus, type CollectionInfo, CollectionNotFoundError, type CollectionSelection, type CollectionSelectionResult, type CollectionTree, type CollectionType, type Config, type Diagnostic, type DiagnosticLevel, DiffwikiError, type DiffwikiLogLevel, type DocData, type FileTimestamps, type GraphEdge, type GraphNode, type InitOptions, type InstallOutcome, InvalidExportSelectionError, InvalidTargetError, type KnownPlugin, type LinkGraph, type ListingEntry, type LocalGraph, NATIVE_ENGINE, NoDefaultCollectionError, type NodeMeta, type PageData, type ParsedArticle, type PluginCapabilities, PluginError, type PluginEvent, type PluginHealth, type PluginKind, type PluginReadiness, type PluginRecord, type PluginRegistryFile, type QueryHit, type QueryOptions, REPO_CONFIG_FILE, type Registry, type RenderContext, type RenderedArticle, type RepoConfig, SearchDoc, type SearchMode, type SearchOutcome, type SearchProvider, type SerializableArticle, type SetupOutcome, type SetupStep, type TocItem, type TreeNode, type UpstreamStatus, WorktreeNotAllowedError, addExternalCollection, addTags, buildArticleTree, buildCollections, buildLinkGraph, buildNavTree, buildSearchIndex, collectionDir, collectionGitStatus, collectionsDir, configPath, createArticle, createCollection, currentBranch, deregisterPlugin, doctor, emitPluginEvent, ensureGitRepo, ensurePluginRoot, fileTimestamps, findCollection, findCollectionById, findEnabledPlugin, findPluginRecord, getConfigValue, getLogger, gitToplevel, initRepoWiki, installPlugin, invalidateLinkGraph, isLinkedWorktree, listArticleTree, listAvailablePlugins, listCollections, listEnabledPlugins, listPlugins, listSearchModes, loadSearchProvider, localGraph, nativeSearch, parseAddTarget, parseArticle, parsePathTarget, pluginsDir, pluginsRegistryPath, query, readArticle, readConfig, readPluginRegistry, readRegistry, readRepoConfig, registerCollection, registerPlugin, registryPath, removeArticle, removeCollection, removePlugin, removeTags, renderArticle, repoId, repoRemoteName, resolveCollectionSelection, resolveCwdCollection, resolveDefaultSearchMode, resolveHome, resolveLogLevel, resolvePage, search, serializeArticle, setConfigValue, setTags, slugify, toTreeNodes, unregisterCollection, updateArticleBody, upsertPlugin, upstreamStatus, writeConfig, writePluginRegistry, writeRegistry };
+export { type AddExternalOptions, type Article, type ArticleContent, type ArticleNode, ArticleNotFoundError, type Audience, CollectionAlreadyAddedError, type CollectionEntry, CollectionExistsError, type CollectionGitStatus, type CollectionInfo, CollectionNotFoundError, type CollectionSelection, type CollectionSelectionResult, type CollectionTree, type CollectionType, type Config, type Diagnostic, type DiagnosticLevel, DiffwikiError, type DiffwikiLogLevel, type DocData, type FileTimestamps, type GraphEdge, type GraphNode, type InitOptions, type InstallOutcome, InvalidExportSelectionError, InvalidTargetError, type KnownPlugin, type LinkGraph, type ListingEntry, type LocalGraph, NATIVE_ENGINE, NoDefaultCollectionError, type NodeMeta, type PageData, type ParsedArticle, type PluginCapabilities, PluginError, type PluginEvent, type PluginHealth, type PluginKind, type PluginReadiness, type PluginRecord, type PluginRegistryFile, type PublishStatus, type QueryHit, type QueryOptions, REPO_CONFIG_FILE, type Registry, type RenderContext, type RenderedArticle, type RepoConfig, SearchDoc, type SearchMode, type SearchOutcome, type SearchProvider, type SerializableArticle, type SetupOutcome, type SetupStep, type TocItem, type TreeNode, type UpstreamStatus, WorktreeNotAllowedError, addExternalCollection, addTags, buildArticleTree, buildCollections, buildLinkGraph, buildNavTree, buildSearchIndex, 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, listArticleTree, listAvailablePlugins, listCollections, listEnabledPlugins, listPlugins, listSearchModes, loadSearchProvider, localGraph, nativeSearch, parseAddTarget, parseArticle, parsePathTarget, pluginsDir, pluginsRegistryPath, query, readArticle, readConfig, readPluginRegistry, readRegistry, readRepoConfig, registerCollection, registerPlugin, registryPath, removeArticle, removeCollection, removePlugin, removeTags, renderArticle, repoId, repoRemoteName, resolveCollectionSelection, resolveCwdCollection, resolveDefaultSearchMode, resolveHome, resolveLogLevel, resolvePage, search, serializeArticle, setConfigValue, setTags, slugify, toTreeNodes, unregisterCollection, updateArticleBody, upsertPlugin, upstreamStatus, writeConfig, writePluginRegistry, writeRegistry };

package/dist/index.js

@@ -109,22 +109,39 @@ var YAML_ENGINE = {
   stringify: (data) => stringifyYaml(data)
 };
 var MATTER_OPTS = { engines: { yaml: YAML_ENGINE } };
+function coerceAudience(value) {
+  return value === "private" ? "private" : "public";
+}
+function coerceStatus(value) {
+  return value === "draft" ? "draft" : "published";
+}
 function parseFallback(raw) {
   const fenceRe = /^---[ \t]*\n([\s\S]*?)\n---[ \t]*\n/;
   const fenceMatch = fenceRe.exec(raw);
   let title = "";
+  let audience = "public";
+  let status = "published";
   let body;
+  const clean = (s) => s.trim().replace(/^["']|["']$/g, "");
   if (fenceMatch) {
     const inner = fenceMatch[1];
     const titleMatch = /^title:\s*(.+)$/m.exec(inner);
     if (titleMatch) {
-      title = titleMatch[1].trim().replace(/^["']|["']$/g, "");
+      title = clean(titleMatch[1]);
+    }
+    const audienceMatch = /^audience:\s*(.+)$/m.exec(inner);
+    if (audienceMatch) {
+      audience = coerceAudience(clean(audienceMatch[1]));
+    }
+    const statusMatch = /^status:\s*(.+)$/m.exec(inner);
+    if (statusMatch) {
+      status = coerceStatus(clean(statusMatch[1]));
     }
     body = raw.slice(fenceMatch[0].length);
   } else {
     body = raw;
   }
-  return { title, tags: [], body: body.replace(/^\n+/, "") };
+  return { title, tags: [], audience, status, body: body.replace(/^\n+/, "") };
 }
 function parseArticle(raw) {
   try {
@@ -132,13 +149,17 @@ function parseArticle(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+/, "") };
+    const audience = coerceAudience(data.audience);
+    const status = coerceStatus(data.status);
+    return { title, tags, created, audience, status, body: content.replace(/^\n+/, "") };
   } catch {
     return parseFallback(raw);
   }
 }
 function serializeArticle(article) {
   const front = { title: article.title, tags: article.tags };
+  if (article.audience === "private") front.audience = "private";
+  if (article.status === "draft") front.status = "draft";
   return matter.stringify(article.body, front, MATTER_OPTS);
 }
 
@@ -214,7 +235,17 @@ async function loadArticle(target) {
 async function updateArticleBody(target, body) {
   const { filePath, dir, raw, collection } = await loadArticle(target);
   const parsed = parseArticle(raw);
-  await fs2.writeFile(filePath, serializeArticle({ title: parsed.title, tags: parsed.tags, body }), "utf8");
+  await fs2.writeFile(
+    filePath,
+    serializeArticle({
+      title: parsed.title,
+      tags: parsed.tags,
+      audience: parsed.audience,
+      status: parsed.status,
+      body
+    }),
+    "utf8"
+  );
   void fireHook("article-updated", collection, path.relative(dir, filePath));
   return { title: parsed.title, tags: parsed.tags, path: filePath, collection };
 }
@@ -222,7 +253,17 @@ async function mutateTags(target, fn) {
   const { filePath, dir, raw, collection } = await loadArticle(target);
   const parsed = parseArticle(raw);
   const tags = fn(parsed.tags);
-  await fs2.writeFile(filePath, serializeArticle({ title: parsed.title, tags, body: parsed.body }), "utf8");
+  await fs2.writeFile(
+    filePath,
+    serializeArticle({
+      title: parsed.title,
+      tags,
+      audience: parsed.audience,
+      status: parsed.status,
+      body: parsed.body
+    }),
+    "utf8"
+  );
   void fireHook("article-updated", collection, path.relative(dir, filePath));
   return { title: parsed.title, tags, path: filePath, collection };
 }
@@ -534,20 +575,30 @@ function pickIndexFile(names) {
   };
   return names.filter((n) => INDEX_RE.test(n)).sort((a, b) => rank(a) - rank(b))[0];
 }
-async function cheapTitle(absPath) {
+var CHEAP_META_BYTES = 8192;
+async function cheapMeta(absPath) {
   let handle;
   try {
     handle = await fs5.open(absPath, "r");
-    const buf = Buffer.alloc(512);
-    const { bytesRead } = await handle.read(buf, 0, 512, 0);
+    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");
-    const m = snippet.match(/^---[\s\S]*?^title:\s*(.+)$/m);
-    if (m) return m[1].trim().replace(/^["']|["']$/g, "");
+    const fence = /^---[ \t]*\n([\s\S]*?)(?:\n---[ \t]*\n|$)/.exec(snippet);
+    if (!fence) return {};
+    const inner = fence[1];
+    const clean = (s) => s.trim().replace(/^["']|["']$/g, "");
+    const titleM = /^title:\s*(.+)$/m.exec(inner);
+    const audienceM = /^audience:\s*(.+)$/m.exec(inner);
+    const statusM = /^status:\s*(.+)$/m.exec(inner);
+    const title = titleM ? clean(titleM[1]) : void 0;
+    const audience = audienceM && clean(audienceM[1]) === "private" ? "private" : void 0;
+    const status = statusM && clean(statusM[1]) === "draft" ? "draft" : void 0;
+    return { title, audience, status };
   } catch {
   } finally {
     await handle?.close();
   }
-  return void 0;
+  return {};
 }
 async function enrichTitles(nodes, collDir) {
   return Promise.all(
@@ -555,21 +606,41 @@ async function enrichTitles(nodes, collDir) {
       if (node.children) {
         const children = await enrichTitles(node.children, collDir);
         let title = node.title;
+        let audience = node.audience;
+        let status = node.status;
         if (node.slug) {
           const dir = path4.join(collDir, node.slug);
           const idx = pickIndexFile(await readdirSafe(dir));
-          if (idx) title = await cheapTitle(path4.join(dir, idx)) ?? title;
+          if (idx) {
+            const meta = await cheapMeta(path4.join(dir, idx));
+            title = meta.title ?? title;
+            audience = meta.audience ?? audience;
+            status = meta.status ?? status;
+          }
         }
-        return { ...node, title, children };
+        return { ...node, title, audience, status, children };
       }
       for (const ext of [".mdx", ".md"]) {
-        const title = await cheapTitle(path4.join(collDir, `${node.slug}${ext}`));
-        if (title) return { ...node, title };
+        const meta = await cheapMeta(path4.join(collDir, `${node.slug}${ext}`));
+        if (meta.title || meta.audience || meta.status) {
+          return {
+            ...node,
+            title: meta.title ?? node.title,
+            audience: meta.audience ?? node.audience,
+            status: meta.status ?? node.status
+          };
+        }
       }
       return node;
     })
   );
 }
+async function collectionMeta(collDir) {
+  const idx = pickIndexFile(await readdirSafe(collDir));
+  if (!idx) return {};
+  const meta = await cheapMeta(path4.join(collDir, idx));
+  return { audience: meta.audience, status: meta.status };
+}
 async function listArticleTree(coll) {
   const entry = await findCollection(coll);
   if (!entry) throw new CollectionNotFoundError(coll);
@@ -611,7 +682,17 @@ async function readArticle(coll, slug) {
   if (!abs) throw new ArticleNotFoundError(`${coll}/${safeSlug}`);
   const parsed = parseArticle(await fs5.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, isIndex };
+  return {
+    coll,
+    slug: safeSlug,
+    title,
+    tags: parsed.tags,
+    audience: parsed.audience,
+    status: parsed.status,
+    body: parsed.body,
+    path: abs,
+    isIndex
+  };
 }
 
 // src/render.ts
@@ -644,10 +725,15 @@ function rehypeRewriteLinks(ctx) {
       if (pathPart === "") return;
       const joined = path5.posix.join(slugDir === "." ? "" : slugDir, pathPart);
       const normalized = path5.posix.normalize(joined);
+      const toRoute = (p) => p.replace(/\.(mdx?)$/i, "").replace(/(^|\/)(index|readme)$/i, "$1").replace(/\/+$/, "").replace(/^\/+/, "");
+      if (normalized.startsWith("../")) {
+        const sibling = normalized.slice(3);
+        if (sibling === "" || sibling.startsWith("..")) return;
+        node.properties = { ...node.properties, href: `/${toRoute(sibling)}${suffix}` };
+        return;
+      }
       if (normalized.startsWith("..")) return;
-      let resolved = normalized.replace(/\.(mdx?)$/i, "");
-      resolved = resolved.replace(/(^|\/)(index|readme)$/i, "$1");
-      resolved = resolved.replace(/\/+$/, "").replace(/^\/+/, "");
+      const resolved = toRoute(normalized);
       node.properties = {
         ...node.properties,
         href: `/${ctx.coll}${resolved ? `/${resolved}` : ""}${suffix}`
@@ -859,13 +945,22 @@ function localGraph(graph, focusId, include, siblingCap = 12) {
 // src/site.ts
 var isStatic = () => process.env.DIFFWIKI_STATIC === "1";
 function toTreeNodes(coll, nodes) {
-  return nodes.map(
+  const visible = isStatic() ? nodes.filter((n) => n.audience !== "private" && n.status !== "draft") : nodes;
+  return visible.map(
     (n) => n.children ? {
       name: n.name,
       title: n.title ?? n.name,
       path: n.slug ? `/${coll}/${n.slug}` : void 0,
+      ...n.audience ? { audience: n.audience } : {},
+      ...n.status ? { status: n.status } : {},
       children: toTreeNodes(coll, n.children)
-    } : { name: n.name, title: n.title ?? n.name, path: `/${coll}/${n.slug}` }
+    } : {
+      name: n.name,
+      title: n.title ?? n.name,
+      path: `/${coll}/${n.slug}`,
+      ...n.audience ? { audience: n.audience } : {},
+      ...n.status ? { status: n.status } : {}
+    }
   );
 }
 async function gitInfo(e) {
@@ -878,23 +973,40 @@ async function gitInfo(e) {
 }
 async function buildCollections() {
   const entries = await listCollections();
-  return Promise.all(
-    entries.map(async (e) => ({
-      name: e.name,
-      type: e.type,
-      path: e.path,
-      ...await gitInfo(e)
-    }))
+  const infos = await Promise.all(
+    entries.map(async (e) => {
+      const { audience, status } = await collectionMeta(e.path);
+      return {
+        name: e.name,
+        type: e.type,
+        path: e.path,
+        ...await gitInfo(e),
+        ...audience ? { audience } : {},
+        ...status ? { status } : {}
+      };
+    })
   );
+  return isStatic() ? infos.filter((c) => c.audience !== "private" && c.status !== "draft") : infos;
 }
 async function buildNavTree() {
   const entries = await listCollections();
-  return Promise.all(
-    entries.map(async (e) => ({
-      collection: { name: e.name, type: e.type, path: e.path, ...await gitInfo(e) },
-      nodes: toTreeNodes(e.name, await listArticleTree(e.name))
-    }))
+  const trees = await Promise.all(
+    entries.map(async (e) => {
+      const { audience, status } = await collectionMeta(e.path);
+      return {
+        collection: {
+          name: e.name,
+          type: e.type,
+          path: e.path,
+          ...await gitInfo(e),
+          ...audience ? { audience } : {},
+          ...status ? { status } : {}
+        },
+        nodes: toTreeNodes(e.name, await listArticleTree(e.name))
+      };
+    })
   );
+  return isStatic() ? trees.filter((t) => t.collection.audience !== "private" && t.collection.status !== "draft") : trees;
 }
 function findNode(nodes, slug) {
   for (const n of nodes) {
@@ -922,6 +1034,8 @@ async function resolvePage(coll, slug, opts) {
       slug: art.slug,
       title: art.title,
       tags: art.tags,
+      ...art.audience === "private" ? { audience: art.audience } : {},
+      ...art.status === "draft" ? { status: art.status } : {},
       html,
       toc,
       path: `/${art.coll}/${art.slug}`,
@@ -1106,6 +1220,7 @@ async function query(term, opts) {
 // src/search.ts
 import fs7 from "fs/promises";
 import path7 from "path";
+var isStatic2 = () => process.env.DIFFWIKI_STATIC === "1";
 async function readArticleParts(collDir, slug) {
   for (const ext of [".mdx", ".md"]) {
     try {
@@ -1118,6 +1233,7 @@ async function readArticleParts(collDir, slug) {
 }
 async function flatten(coll, collDir, nodes, out) {
   for (const n of nodes) {
+    if (isStatic2() && (n.audience === "private" || n.status === "draft")) continue;
     if (n.slug && !n.children) {
       const title = n.title ?? n.name;
       const { tags, body } = await readArticleParts(collDir, n.slug);
@@ -1144,6 +1260,10 @@ async function buildSearchIndex(collection) {
     try {
       const collEntry = await findCollection(e.name);
       const collDir = path7.resolve(collEntry?.path ?? e.path);
+      if (isStatic2()) {
+        const cm = await collectionMeta(collDir);
+        if (cm.audience === "private" || cm.status === "draft") continue;
+      }
       await flatten(e.name, collDir, await listArticleTree(e.name), out);
     } catch {
     }
@@ -1514,6 +1634,7 @@ export {
   buildSearchIndex,
   collectionDir,
   collectionGitStatus,
+  collectionMeta,
   collectionsDir,
   configPath,
   createArticle,

package/package.json

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