diffwiki 0.16.0 → 0.17.0-rc.202608201146.531910e

package/dist/bin.js

@@ -1,9 +1,12 @@
 #!/usr/bin/env node
 
+// src/bin.ts
+import { ensureHome } from "diffwiki-core";
+
 // src/cli.ts
 import { spawn as spawn4 } from "child_process";
-import path4 from "path";
-import { fileURLToPath as fileURLToPath4 } from "url";
+import path5 from "path";
+import { fileURLToPath as fileURLToPath3 } from "url";
 import { Command, Option } from "commander";
 import {
   addExternalCollection,
@@ -72,12 +75,40 @@ var splitTags = (raw) => raw.flatMap((t) => t.split(",")).map((t) => t.trim()).f
 import { spawn } from "child_process";
 import { platform } from "os";
 import fs from "fs/promises";
-import path from "path";
+import path2 from "path";
 import http from "http";
 import { resolveHome } from "diffwiki-core";
+
+// src/app.ts
+import { existsSync } from "fs";
+import path from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+var APP_SPEC = `diffwiki-app@${version}`;
+function workspaceAppBin(localBin) {
+  const candidates = [
+    path.resolve(path.dirname(fileURLToPath2(import.meta.url)), "../../../apps/wiki/bin", localBin),
+    path.resolve(process.cwd(), "apps/wiki/bin", localBin)
+  ];
+  return candidates.find((p) => existsSync(p));
+}
+function resolveAppLaunch(opts = {}) {
+  const localBin = opts.localBin ?? "wiki-server.mjs";
+  const override = process.env.DIFFWIKI_APP_CMD;
+  if (override) {
+    const [cmd, ...args] = override.split(" ");
+    return { cmd, args, source: "override", spec: override };
+  }
+  const spec = process.env.DIFFWIKI_APP_SPEC;
+  if (spec) return { cmd: "npx", args: ["-y", spec], source: "spec", spec };
+  const local = workspaceAppBin(localBin);
+  if (local) return { cmd: "node", args: [local], source: "local", spec: local };
+  return { cmd: "npx", args: ["-y", APP_SPEC], source: "npx", spec: APP_SPEC };
+}
+
+// src/ui-server.ts
 var DEFAULT_PORT = 4321;
 function statePath() {
-  return path.join(resolveHome(), "ui.json");
+  return path2.join(resolveHome(), "ui.json");
 }
 async function readState() {
   try {
@@ -133,7 +164,8 @@ function waitForServer(url, timeoutMs = 3e4) {
   });
 }
 async function startUi(port = DEFAULT_PORT) {
-  const child = spawn("npx", ["-y", "diffwiki-app@latest", "--port", String(port)], {
+  const { cmd, args } = resolveAppLaunch();
+  const child = spawn(cmd, [...args, "--port", String(port)], {
     env: { ...process.env, PORT: String(port), HOST: "127.0.0.1" },
     detached: true,
     stdio: "ignore"
@@ -168,20 +200,11 @@ async function stopUi() {
 
 // src/exporter.ts
 import { spawn as spawn2 } from "child_process";
-import fs2 from "fs";
-import path2 from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
+import path3 from "path";
 import { listCollections, resolveCollectionSelection, InvalidExportSelectionError } from "diffwiki-core";
 var splitGlobs = (v) => (v ?? "").split(",").map((s) => s.trim()).filter(Boolean);
-function localAppExporter() {
-  const candidates = [
-    path2.resolve(path2.dirname(fileURLToPath2(import.meta.url)), "../../../apps/wiki/bin/export.mjs"),
-    path2.resolve(process.cwd(), "apps/wiki/bin/export.mjs")
-  ];
-  return candidates.find((p) => fs2.existsSync(p));
-}
 async function runExport(opts) {
-  const out = path2.resolve(opts.out);
+  const out = path3.resolve(opts.out);
   const filter = splitGlobs(opts.filter);
   const exclude = splitGlobs(opts.exclude);
   if (!opts.project && (filter.length > 0 || exclude.length > 0)) {
@@ -189,19 +212,17 @@ async function runExport(opts) {
     const { errors } = resolveCollectionSelection(names, { filter, exclude });
     if (errors.length > 0) throw new InvalidExportSelectionError(errors);
   }
-  const local = localAppExporter();
-  const override = process.env.DIFFWIKI_APP_CMD ?? (local ? `node ${local}` : void 0);
-  const [cmd, ...prefix] = override ? override.split(" ") : ["npx", "-y", "diffwiki-app@latest"];
-  const args = [...prefix, "export", "--out", out, "--base", opts.base];
-  if (opts.filter) args.push("--filter", opts.filter);
-  if (opts.exclude) args.push("--exclude", opts.exclude);
+  const { cmd, args, source, spec } = resolveAppLaunch({ localBin: "export.mjs" });
+  const appArgs = [...args, "export", "--out", out, "--base", opts.base];
+  if (opts.filter) appArgs.push("--filter", opts.filter);
+  if (opts.exclude) appArgs.push("--exclude", opts.exclude);
   if (opts.project) {
-    args.push("--project");
-    if (typeof opts.project === "string") args.push(opts.project);
+    appArgs.push("--project");
+    if (typeof opts.project === "string") appArgs.push(opts.project);
   }
-  if (override) console.log(`Exporting via ${override}`);
+  if (source === "override") console.log(`Exporting via ${spec}`);
   await new Promise((resolve, reject) => {
-    const child = spawn2(cmd, args, { stdio: "inherit", env: process.env });
+    const child = spawn2(cmd, appArgs, { stdio: "inherit", env: process.env });
     child.on("error", reject);
     child.on("close", (code) => code === 0 ? resolve() : reject(new Error(`export failed (exit ${code})`)));
   });
@@ -209,12 +230,10 @@ async function runExport(opts) {
 }
 
 // src/preview.ts
-import { existsSync } from "fs";
-import fs3 from "fs/promises";
+import fs2 from "fs/promises";
 import net from "net";
-import path3 from "path";
+import path4 from "path";
 import { spawn as spawn3 } from "child_process";
-import { fileURLToPath as fileURLToPath3 } from "url";
 import { seedProjectHome } from "diffwiki-core";
 async function findFreePort(start, host = "127.0.0.1") {
   const isFree = (port) => new Promise((resolve) => {
@@ -228,29 +247,16 @@ async function findFreePort(start, host = "127.0.0.1") {
   }
   throw new Error(`No free port available in ${start}..${start + 99}`);
 }
-function launchCommand() {
-  const override = process.env.DIFFWIKI_APP_CMD;
-  if (override) {
-    const [cmd, ...prefix] = override.split(" ");
-    return { cmd, prefix };
-  }
-  const candidates = [
-    path3.resolve(path3.dirname(fileURLToPath3(import.meta.url)), "../../../apps/wiki/bin/wiki-server.mjs"),
-    path3.resolve(process.cwd(), "apps/wiki/bin/wiki-server.mjs")
-  ];
-  const local = candidates.find((p) => existsSync(p));
-  return local ? { cmd: "node", prefix: [local] } : { cmd: "npx", prefix: ["-y", "diffwiki-app@latest"] };
-}
 async function runPreview(opts) {
-  const root = path3.resolve(opts.cwd);
+  const root = path4.resolve(opts.cwd);
   const { home, entries } = await seedProjectHome(root);
-  const { cmd, prefix } = launchCommand();
+  const { cmd, args } = resolveAppLaunch();
   const port = await findFreePort(opts.port);
   const url = `http://127.0.0.1:${port}`;
-  console.log(`Previewing ${entries.length} collection(s) from ${path3.join(root, "diffwiki.yaml")}`);
+  console.log(`Previewing ${entries.length} collection(s) from ${path4.join(root, "diffwiki.yaml")}`);
   if (port !== opts.port) console.log(`Port ${opts.port} is in use \u2014 using ${port} instead.`);
   console.log(`Starting UI at ${url} \u2026  (Ctrl-C to stop)`);
-  const child = spawn3(cmd, [...prefix, "--port", String(port)], {
+  const child = spawn3(cmd, [...args, "--port", String(port)], {
     env: {
       ...process.env,
       DIFFWIKI_HOME: home,
@@ -289,7 +295,7 @@ async function runPreview(opts) {
     const finish = () => {
       process.off("SIGINT", stop);
       process.off("SIGTERM", stop);
-      void fs3.rm(home, { recursive: true, force: true });
+      void fs2.rm(home, { recursive: true, force: true });
       resolve();
     };
     child.on("close", finish);
@@ -493,7 +499,7 @@ async function doctorAction(opts) {
   }
 }
 function bundledTemplatesDir() {
-  return path4.resolve(path4.dirname(fileURLToPath4(import.meta.url)), "..", "templates");
+  return path5.resolve(path5.dirname(fileURLToPath3(import.meta.url)), "..", "templates");
 }
 async function templatesInitAction() {
   const { seeded, skipped, dir } = await seedTemplates(bundledTemplatesDir());
@@ -686,7 +692,7 @@ function createProgram() {
   );
   site.command("preview").description("Preview the site from the repo diffwiki.yaml (ignores global collections)").option("-p, --port <port>", "port to serve on", "4321").action(withErrors((opts) => previewAction(opts)));
   const ui = program.command("ui").description("Run the local diffwiki app server");
-  ui.command("up").description("Start the diffwiki UI (latest published diffwiki-app)").option("-p, --port <port>", "port to serve on", "4321").action(withErrors((opts) => upAction(opts)));
+  ui.command("up").description("Start the diffwiki UI (runs the matching published diffwiki-app)").option("-p, --port <port>", "port to serve on", "4321").action(withErrors((opts) => upAction(opts)));
   ui.command("down").description("Stop the running diffwiki UI").action(withErrors(downAction));
   ui.command("status").description("Show whether the diffwiki UI is running").action(withErrors(statusAction));
   ui.command("open").description("Open the diffwiki UI in the browser (starting it if needed)").option("-p, --port <port>", "port to serve on", "4321").action(withErrors((opts) => openAction(opts)));
@@ -709,14 +715,14 @@ function createProgram() {
 // src/logging.ts
 import { mkdirSync } from "fs";
 import os from "os";
-import path5 from "path";
+import path6 from "path";
 import { configureSync, getConfig } from "@logtape/logtape";
 import { getRotatingFileSink } from "@logtape/file";
 import { resolveLogLevel } from "diffwiki-core";
 var configured = false;
 function diffwikiHome() {
   const override = process.env.DIFFWIKI_HOME;
-  return override && override.length > 0 ? override : path5.join(os.homedir(), ".diffwiki");
+  return override && override.length > 0 ? override : path6.join(os.homedir(), ".diffwiki");
 }
 function resolveCliLevel(argv) {
   if (argv.includes("-v") || argv.includes("--verbose")) return "debug";
@@ -733,9 +739,9 @@ function configureCliLogging(argv = process.argv) {
   if (configured || getConfig() != null) return;
   configured = true;
   const level = resolveCliLevel(argv);
-  const logsDir = path5.join(diffwikiHome(), "logs");
+  const logsDir = path6.join(diffwikiHome(), "logs");
   mkdirSync(logsDir, { recursive: true });
-  const logFile = path5.join(logsDir, "diffwiki.log");
+  const logFile = path6.join(logsDir, "diffwiki.log");
   const stderrSink = (record) => {
     process.stderr.write(formatLine(record) + "\n");
   };
@@ -754,4 +760,5 @@ function configureCliLogging(argv = process.argv) {
 
 // src/bin.ts
 configureCliLogging(process.argv);
-createProgram().parseAsync(process.argv);
+await ensureHome();
+await createProgram().parseAsync(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diffwiki",
-  "version": "0.16.0",
+  "version": "0.17.0-rc.202608201146.531910e",
   "description": "diffwiki command-line interface",
   "license": "MIT",
   "type": "module",
@@ -18,7 +18,7 @@
     "@logtape/logtape": "^2.2.4",
     "@logtape/file": "^2.2.4",
     "commander": "^13.0.0",
-    "diffwiki-core": "0.16.0"
+    "diffwiki-core": "0.17.0-rc.202608201146.531910e"
   },
   "devDependencies": {
     "@types/node": "^22.0.0"

package/templates/collection-index-template.md

@@ -7,11 +7,15 @@ budget: [100, 500]
 <!--
 Use this shape for a collection's root index file. An index groups articles into topics, provides a one-line description for each, and links to them. It does not teach, demonstrate, or narrate.
 
+Pick an organisation pattern:
+  - Subtopic headers — use when the collection spans multiple distinct subjects. One H2 per subject.
+  - Shape-based sections — use when the collection covers a single topic but mixes article types. Use H2s: Guides, Recipes, References (omit any that are empty).
+
 Authoring rules:
   - Adhere to the template structure
   - One H2 per topic group; keep the group label short (2–4 words)
   - One bullet per article: [Title](./slug.md) — one-line description
-  - No prose paragraphs, no examples, no code blocks, no References section
+  - No prose paragraphs, no examples, no code blocks
   - Keep descriptions to a single clause — enough to distinguish siblings
   - Do not copy over html comments or the template specific yaml frontmatter above this section. Write a diffwiki article yaml frontmatter as shown below this comment.
   - Use concise descriptive titles in article frontmatter
@@ -26,18 +30,33 @@ tags:
 
 - collection-index
 - TAG1
-- TAG2
   audience: public
   status: published
 
 ---
 
-## <Topic Group>
+<!-- Pattern A: subtopic headers — use when the collection spans multiple subjects -->
+
+## <Subject Area>
+
+- [Article Title](./slug.md) — one-line description.
+- [Article Title](./slug.md) — one-line description.
+
+## <Second Subject Area>
+
+- [Article Title](./slug.md) — one-line description.
+
+<!-- Pattern B: shape-based sections — use when the collection is single-topic with mixed article types -->
+
+## Guides
+
+- [Article Title](./slug.md) — one-line description.
+
+## Recipes
 
-- [Article Title](./slug.md) — one-line description of what this article covers.
-- [Article Title](./slug.md) — one-line description of what this article covers.
+- [Article Title](./slug.md) — one-line description.
+- [Article Title](./slug.md) — one-line description.
 
-## <Second Topic Group>
+## References
 
-- [Article Title](./slug.md) — one-line description of what this article covers.
-- [Article Title](./slug.md) — one-line description of what this article covers.
+- [Article Title](./slug.md) — one-line description.