diffwiki 0.8.0 → 0.9.0-rc.202607291532.69c042c

package/dist/bin.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
+import { spawn as spawn4 } from "child_process";
 import { Command } from "commander";
 import {
   addExternalCollection,
@@ -23,6 +24,8 @@ import {
   removePlugin,
   removeTags,
   resolveCwdCollection,
+  resolveEditorCommand,
+  resolveEditTarget,
   setConfigValue,
   setTags,
   updateArticleBody
@@ -54,6 +57,9 @@ function withErrors(fn) {
 }
 var collect = (value, previous) => previous.concat([value]);
 var splitTags = (raw) => raw.flatMap((t) => t.split(",")).map((t) => t.trim()).filter((t) => t.length > 0);
+var deprecated = (oldForm, newForm) => {
+  console.error(`\u26A0 "diffwiki ${oldForm}" is deprecated; use "diffwiki ${newForm}".`);
+};
 
 // src/ui-server.ts
 import { spawn } from "child_process";
@@ -171,7 +177,7 @@ async function runExport(opts) {
   const out = path2.resolve(opts.out);
   const filter = splitGlobs(opts.filter);
   const exclude = splitGlobs(opts.exclude);
-  if (filter.length > 0 || exclude.length > 0) {
+  if (!opts.project && (filter.length > 0 || exclude.length > 0)) {
     const names = (await listCollections()).map((c) => c.name);
     const { errors } = resolveCollectionSelection(names, { filter, exclude });
     if (errors.length > 0) throw new InvalidExportSelectionError(errors);
@@ -182,6 +188,10 @@ async function runExport(opts) {
   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);
+  if (opts.project) {
+    args.push("--project");
+    if (typeof opts.project === "string") args.push(opts.project);
+  }
   if (override) console.log(`Exporting via ${override}`);
   await new Promise((resolve, reject) => {
     const child = spawn2(cmd, args, { stdio: "inherit", env: process.env });
@@ -191,261 +201,512 @@ async function runExport(opts) {
   console.log(`Static site written to ${out}`);
 }
 
+// src/preview.ts
+import { existsSync } from "fs";
+import fs3 from "fs/promises";
+import net from "net";
+import path3 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) => {
+    const srv = net.createServer();
+    srv.once("error", () => resolve(false));
+    srv.once("listening", () => srv.close(() => resolve(true)));
+    srv.listen(port, host);
+  });
+  for (let port = start; port < start + 100; port += 1) {
+    if (await isFree(port)) return port;
+  }
+  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 { home, entries } = await seedProjectHome(root);
+  const { cmd, prefix } = launchCommand();
+  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")}`);
+  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)], {
+    env: {
+      ...process.env,
+      DIFFWIKI_HOME: home,
+      DIFFWIKI_PROJECT_DIR: root,
+      PORT: String(port),
+      HOST: "127.0.0.1"
+    },
+    stdio: "inherit",
+    // Own process group so a terminal Ctrl-C doesn't double-signal the child (which
+    // triggers its slow graceful-shutdown countdown). We drive shutdown ourselves.
+    detached: true
+  });
+  const signalTree = (sig) => {
+    if (child.pid === void 0) return;
+    try {
+      process.kill(-child.pid, sig);
+    } catch {
+      try {
+        child.kill(sig);
+      } catch {
+      }
+    }
+  };
+  let forcing = false;
+  const stop = () => {
+    if (forcing) return signalTree("SIGKILL");
+    forcing = true;
+    signalTree("SIGTERM");
+    setTimeout(() => signalTree("SIGKILL"), 1e3).unref();
+  };
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+  const ready = await waitForServer(url);
+  if (ready) openBrowser(url);
+  await new Promise((resolve) => {
+    const finish = () => {
+      process.off("SIGINT", stop);
+      process.off("SIGTERM", stop);
+      void fs3.rm(home, { recursive: true, force: true });
+      resolve();
+    };
+    child.on("close", finish);
+    child.on("error", (err) => {
+      console.error(`Failed to start preview: ${err.message}`);
+      finish();
+    });
+  });
+}
+
 // src/cli.ts
 var icon = (level) => level === "ok" ? "\u2713" : level === "warn" ? "!" : "\u2716";
+async function listCollectionsAction() {
+  const collections = await listCollections2();
+  if (collections.length === 0) {
+    console.log("No collections yet. Create one with: diffwiki collection create <name>");
+    return;
+  }
+  for (const c of collections) {
+    const status = await collectionGitStatus(c);
+    const branch = status?.branch ? `	(${status.branch})` : "";
+    console.log(`${c.name}	[${c.type}]	${c.path}${branch}`);
+  }
+}
+async function addExternalAction(opts) {
+  const entry = await addExternalCollection({ cwd: process.cwd(), docsDir: opts.docs });
+  const status = await collectionGitStatus(entry);
+  const branch = status?.branch ? ` (${status.branch})` : "";
+  console.log(`Added "${entry.name}"${branch} \u2192 ${entry.path}`);
+  console.log("Registered globally \u2014 discoverable via: diffwiki collection list");
+}
+async function createCollectionAction(name) {
+  const entry = await createCollection(name);
+  console.log(`Created collection "${entry.name}" at ${entry.path}`);
+}
+async function createArticleAction(target, body, tags) {
+  const article = await createArticle({
+    target,
+    tags: splitTags(tags),
+    body
+  });
+  console.log(article.path);
+}
+async function updateArticleAction(target, body) {
+  const article = await updateArticleBody(target, body);
+  console.log(`Updated ${article.path}`);
+}
+async function removeArticleAction(target) {
+  const removed = await removeArticle(target);
+  console.log(`Removed ${removed}`);
+}
+async function tagsAction(fn, target, tags) {
+  const article = await fn(target, splitTags([tags]));
+  console.log(`${article.path} \u2192 tags: ${article.tags.join(", ") || "(none)"}`);
+}
+async function indexAction(opts) {
+  const provider = await loadSearchProvider();
+  if (!provider) {
+    const installable = (await listSearchModes()).filter((m) => m.plugin !== "native");
+    console.log(
+      installable.length > 0 ? `No index-backed plugin active. Available modes: ${installable.map((m) => `${m.plugin}\xB7${m.type}`).join(", ")}` : "No search plugin installed \u2014 using native search (nothing to index). Install one with: diffwiki plugin install <spec>"
+    );
+    return;
+  }
+  const indexed = await provider.reindex(await listCollections2(), { embed: !!opts.embed });
+  console.log(`Indexed ${indexed} document(s).`);
+}
+async function queryAction(term, opts) {
+  const queryOpts = { engine: opts.engine, collection: opts.collection, type: opts.type };
+  const outcome = await search(term, queryOpts);
+  const hits = outcome.hits;
+  console.log(`${hits.length} result(s)`);
+  for (const hit of hits) {
+    const score = typeof hit.score === "number" ? hit.score.toFixed(3) : "-";
+    const line = `${score}	${hit.collection}	${hit.title}	${hit.path}`;
+    console.log(hit.snippet ? `${line}	${hit.snippet}` : line);
+  }
+  if (outcome.error) {
+    console.error(`\u26A0 engine "${outcome.engine}" failed: ${outcome.error} \u2014 used native (${hits.length} results)`);
+  }
+}
+async function pluginInstallAction(spec, opts) {
+  const { record, setup, defaulted } = await installPlugin(spec, {
+    setup: opts.setup,
+    setDefault: opts.default,
+    prefetchModels: opts.prefetchModels
+  });
+  console.log(`Installed "${record.name}"${record.version ? ` v${record.version}` : ""}`);
+  if (!opts.setup) {
+    console.log("Skipped setup (--no-setup) \u2014 run: diffwiki search index");
+  } else if (setup && !setup.ready) {
+    const reason = setup.steps.find((s) => !s.ok)?.message ?? "setup did not complete";
+    console.log(`\u26A0 Not ready: ${reason}`);
+    console.log("  \u2192 run: diffwiki doctor");
+  }
+  if (defaulted) {
+    console.log(
+      `Set "${record.name}" as the default search engine (change: diffwiki config set defaultSearch <engine[:type]>)`
+    );
+  }
+}
+async function pluginRegisterAction(name, opts) {
+  const record = await registerPlugin(name, opts.command);
+  console.log(`Registered "${record.name}" \u2192 ${record.command.join(" ")}`);
+}
+async function pluginListAction() {
+  const installed = await listPlugins();
+  const installedNames = new Set(installed.map((p) => p.name));
+  console.log("Installed:");
+  if (installed.length === 0) {
+    console.log("  (none)");
+  } else {
+    for (const p of installed) {
+      console.log(
+        `  ${p.name}	${p.kind}	${p.version ?? "-"}	enabled=${p.enabled}	managed=${!!p.managed}	spawnable=${p.spawnable}`
+      );
+    }
+  }
+  const available = listAvailablePlugins().filter((k) => !installedNames.has(k.name));
+  if (available.length > 0) {
+    console.log("\nAvailable (install with: diffwiki plugin install <name>):");
+    for (const k of available) {
+      console.log(`  ${k.name}	[${k.kind}]	${k.description}`);
+      console.log(`    requires ${k.requires ?? "nothing"}`);
+    }
+  }
+}
+async function pluginRemoveAction(name) {
+  await removePlugin(name);
+  console.log(`Removed "${name}"`);
+}
+async function initAction(opts) {
+  const entry = await initRepoWiki({
+    cwd: process.cwd(),
+    collection: opts.collection,
+    wikiPath: opts.path
+  });
+  console.log(`Initialized repo wiki "${entry.name}" at ${entry.path}`);
+  console.log("Registered globally \u2014 discoverable via: diffwiki collection list");
+}
+async function exportAction(opts) {
+  await runExport({
+    out: opts.out,
+    base: opts.base,
+    filter: opts.filter,
+    exclude: opts.exclude,
+    project: opts.project
+  });
+}
+async function configSetAction(key, value) {
+  await setConfigValue(key, value);
+  console.log(`Set ${key} = ${value}`);
+}
+async function configGetAction(key) {
+  const value = await getConfigValue(key);
+  console.log(value ?? "(unset)");
+}
+async function doctorAction() {
+  const diagnostics = await doctor();
+  for (const d of diagnostics) {
+    console.log(`${icon(d.level)} ${d.message}`);
+  }
+  if (diagnostics.some((d) => d.level === "error")) {
+    process.exitCode = 1;
+  }
+}
+async function upAction(opts) {
+  const existing = await readState();
+  if (existing && isAlive(existing.pid)) {
+    console.log(`UI already running at ${existing.url} (pid ${existing.pid})`);
+    return;
+  }
+  const state = await startUi(Number(opts.port));
+  const ok = await waitForServer(state.url);
+  console.log(
+    ok ? `UI started at ${state.url} (pid ${state.pid})` : `Launched (pid ${state.pid}) but ${state.url} did not respond yet \u2014 check \`diffwiki ui status\``
+  );
+}
+async function downAction() {
+  const stopped = await stopUi();
+  console.log(stopped ? `Stopped UI (pid ${stopped.pid})` : "UI is not running.");
+}
+async function statusAction() {
+  const state = await readState();
+  if (state && isAlive(state.pid)) {
+    console.log(`running \xB7 ${state.url} \xB7 pid ${state.pid} \xB7 since ${state.startedAt}`);
+  } else {
+    console.log("stopped");
+  }
+}
+async function openAction(opts) {
+  let state = await readState();
+  if (!state || !isAlive(state.pid)) {
+    state = await startUi(Number(opts.port));
+    await waitForServer(state.url);
+  }
+  const coll = await resolveCwdCollection(process.cwd());
+  const target = coll ? `${state.url}/${encodeURIComponent(coll.name)}` : state.url;
+  openBrowser(target);
+  console.log(`Opening ${target}`);
+}
+async function editAction(target, editorFlag) {
+  const argv = await resolveEditorCommand(editorFlag);
+  if (!argv) {
+    console.error(
+      'No editor set. Configure one: diffwiki config set editor "<cmd>" \u2014 or set $EDITOR, or pass --editor.'
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const { path: dest, kind } = await resolveEditTarget(target, process.cwd());
+  const [cmd, ...args] = argv;
+  console.log(`Opening ${kind} ${dest} with ${argv.join(" ")}`);
+  const code = await new Promise((resolve) => {
+    const child = spawn4(cmd, [...args, dest], { stdio: "inherit" });
+    child.on("error", (err) => {
+      console.error(`Could not launch editor "${cmd}": ${err.message}`);
+      resolve(127);
+    });
+    child.on("exit", (c) => resolve(c ?? 0));
+  });
+  if (code !== 0) process.exitCode = code;
+}
+async function previewAction(opts) {
+  await runPreview({ cwd: process.cwd(), port: Number(opts.port) });
+}
 function createProgram() {
   const program = new Command();
   program.name("diffwiki").description("A git-based knowledge base").version(version).showHelpAfterError().option("-v, --verbose", "verbose logging (sets the log level to debug)").option("--log <level>", "log level: trace|debug|info|warning|error|fatal");
   program.action(() => {
     program.outputHelp();
   });
-  program.command("list").description("List all collections").action(
-    withErrors(async () => {
-      const collections = await listCollections2();
-      if (collections.length === 0) {
-        console.log("No collections yet. Create one with: diffwiki create <name>");
-        return;
-      }
-      for (const c of collections) {
-        const status = await collectionGitStatus(c);
-        const branch = status?.branch ? `	(${status.branch})` : "";
-        console.log(`${c.name}	[${c.type}]	${c.path}${branch}`);
-      }
+  const collection = program.command("collection").description("Manage collections (containers)");
+  collection.command("list").description("List all collections").action(withErrors(listCollectionsAction));
+  collection.command("create").description("Create a new global collection").argument("<name>", "collection name").action(withErrors((name) => createCollectionAction(name)));
+  collection.command("add").description("Add the current git repo as an external collection (docs dir, no diffwiki.yaml)").option("-d, --docs <dir>", "content dir relative to repo root", "docs").action(withErrors((opts) => addExternalAction(opts)));
+  collection.command("init").description("Initialize an in-repo wiki and register it globally").option("-c, --collection <name>", "collection name (default: repo name)").option("-p, --path <path>", "wiki path within the repo (default: wiki)").action(withErrors((opts) => initAction(opts)));
+  collection.command("edit").description("Open a collection in your editor \u2014 GUI not required").argument("[name]", "collection (default: the current repo collection)").option("--editor <cmd>", "editor command (overrides config `editor`, $VISUAL, $EDITOR)").action(withErrors((name, opts) => editAction(name, opts.editor)));
+  const article = program.command("article").description("Manage articles (documents)");
+  article.command("create").description("Add an article to a collection").argument("<target>", '"[collection:]title"').argument("[body]", "markdown body").option("-t, --tag <tag>", "tag (repeatable, comma-separated)", collect, []).action(
+    withErrors(
+      (target, body, opts) => createArticleAction(target, body, opts.tag)
+    )
+  );
+  article.command("update").description("Replace an article's body").argument("<target>", '"collection:slug"').argument("<body>", "new markdown body").action(withErrors((target, body) => updateArticleAction(target, body)));
+  article.command("remove").description("Delete an article").argument("<target>", '"collection:slug"').action(withErrors((target) => removeArticleAction(target)));
+  article.command("edit").description("Open an article in your editor \u2014 GUI not required").argument("<target>", '"collection:slug"').option("--editor <cmd>", "editor command (overrides config `editor`, $VISUAL, $EDITOR)").action(withErrors((target, opts) => editAction(target, opts.editor)));
+  const tags = program.command("tags").description("Manage an article's tags");
+  const registerTagsSub = (name, description, fn) => {
+    tags.command(name).description(description).argument("<target>", '"collection:slug"').argument("<tags>", "comma-separated tags").action(withErrors((target, tagList) => tagsAction(fn, target, tagList)));
+  };
+  registerTagsSub("add", "Add to an article's tags", addTags);
+  registerTagsSub("remove", "Remove from an article's tags", removeTags);
+  registerTagsSub("set", "Replace an article's tags", setTags);
+  const searchCmd = program.command("search").description("Search articles and manage the index");
+  searchCmd.command("query").alias("q").description("Search articles via the resolved search engine (native fallback if none)").option("--engine <name>", "search engine/plugin (default: config defaultSearch, else native)").option("-c, --collection <name>", "limit to a collection").option("-t, --type <type>", "search type (engine-defined, e.g. keyword|semantic|hybrid)").argument("[term]", "search term", "").action(
+    withErrors(
+      (term, opts) => queryAction(term, opts)
+    )
+  );
+  searchCmd.command("index").description("Rebuild the search index via the active plugin").option("--embed", "also build vector embeddings (may download models on first run)").action(withErrors((opts) => indexAction(opts)));
+  const plugin = program.command("plugin").description("Manage search plugins");
+  plugin.command("install").description("Install a search plugin from an npm spec and provision it (setup)").argument("<spec>", "npm package spec (name, name@version, or path)").option("--no-setup", "skip the end-to-end setup after install").option("--no-default", "do not make this the default search engine").option("--prefetch-models", "pre-download models during setup (heavy)").action(
+    withErrors(
+      (spec, opts) => pluginInstallAction(spec, opts)
+    )
+  );
+  plugin.command("register").description("Register an existing executable as a search plugin").argument("<name>", "plugin name").requiredOption("--command <cmd...>", "command argv to spawn the plugin (e.g. node /abs/adapter.js)").action(withErrors((name, opts) => pluginRegisterAction(name, opts)));
+  plugin.command("list").description("List installed and available search plugins").action(withErrors(pluginListAction));
+  plugin.command("remove").description("Remove a search plugin").argument("<name>", "plugin name").action(withErrors((name) => pluginRemoveAction(name)));
+  const site = program.command("site").description("Build and preview the published site");
+  site.command("export").description("Generate a static site (deployable to GitHub Pages)").requiredOption("-o, --out <dir>", "output directory").option("-b, --base <path>", "base URL path (e.g. /my-repo/ for GitHub Pages)", "/").option("-f, --filter <globs>", "only export collections matching these globs (comma-separated)").option("-e, --exclude <globs>", "exclude collections matching these globs (comma-separated)").option("--project [dir]", "build only the repo project from its diffwiki.yaml (default: cwd)").action(
+    withErrors(
+      (opts) => exportAction(opts)
+    )
+  );
+  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("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)));
+  const config = program.command("config").description("Read and write diffwiki config");
+  config.command("set").description("Set a config value (e.g. defaultCollection, or defaultSearch <engine[:type]>)").argument("<key>", "config key").argument("<value>", "config value").action(withErrors((key, value) => configSetAction(key, value)));
+  config.command("get").description("Read a config value").argument("<key>", "config key").action(withErrors((key) => configGetAction(key)));
+  program.command("doctor").description("Diagnose configuration issues").action(withErrors(doctorAction));
+  registerDeprecatedAliases(program);
+  return program;
+}
+function registerDeprecatedAliases(program) {
+  program.command("list", { hidden: true }).action(
+    withErrors(() => {
+      deprecated("list", "collection list");
+      return listCollectionsAction();
     })
   );
-  program.command("add").description("Add the current git repo as an external collection (docs dir, no diffwiki.yaml)").option("-d, --docs <dir>", "content dir relative to repo root", "docs").action(
-    withErrors(async (opts) => {
-      const entry = await addExternalCollection({ cwd: process.cwd(), docsDir: opts.docs });
-      const status = await collectionGitStatus(entry);
-      const branch = status?.branch ? ` (${status.branch})` : "";
-      console.log(`Added "${entry.name}"${branch} \u2192 ${entry.path}`);
-      console.log("Registered globally \u2014 discoverable via: diffwiki list");
+  program.command("add", { hidden: true }).option("-d, --docs <dir>", "content dir relative to repo root", "docs").action(
+    withErrors((opts) => {
+      deprecated("add", "collection add");
+      return addExternalAction(opts);
     })
   );
-  program.command("create").description("Create a new global collection").argument("<name>", "collection name").action(
-    withErrors(async (name) => {
-      const entry = await createCollection(name);
-      console.log(`Created collection "${entry.name}" at ${entry.path}`);
+  program.command("create", { hidden: true }).argument("<name>", "collection name").action(
+    withErrors((name) => {
+      deprecated("create", "collection create");
+      return createCollectionAction(name);
     })
   );
-  program.command("add-article").description("Add an article to a collection").requiredOption("-p, --path <target>", '"[collection:]title"').option("-t, --tag <tag>", "tag (repeatable, comma-separated)", collect, []).argument("[body]", "markdown body").action(
-    withErrors(async (body, opts) => {
-      const article = await createArticle({
-        target: opts.path,
-        tags: splitTags(opts.tag),
-        body
-      });
-      console.log(article.path);
+  program.command("add-article", { hidden: true }).requiredOption("-p, --path <target>", '"[collection:]title"').option("-t, --tag <tag>", "tag (repeatable, comma-separated)", collect, []).argument("[body]", "markdown body").action(
+    withErrors((body, opts) => {
+      deprecated("add-article", "article create");
+      return createArticleAction(opts.path, body, opts.tag);
     })
   );
-  program.command("update-article").description("Replace an article's body").requiredOption("-p, --path <target>", '"collection:path"').argument("<body>", "new markdown body").action(
-    withErrors(async (body, opts) => {
-      const article = await updateArticleBody(opts.path, body);
-      console.log(`Updated ${article.path}`);
+  program.command("update-article", { hidden: true }).requiredOption("-p, --path <target>", '"collection:path"').argument("<body>", "new markdown body").action(
+    withErrors((body, opts) => {
+      deprecated("update-article", "article update");
+      return updateArticleAction(opts.path, body);
     })
   );
-  program.command("remove-article").description("Delete an article").requiredOption("-p, --path <target>", '"collection:path"').action(
-    withErrors(async (opts) => {
-      const removed = await removeArticle(opts.path);
-      console.log(`Removed ${removed}`);
+  program.command("remove-article", { hidden: true }).requiredOption("-p, --path <target>", '"collection:path"').action(
+    withErrors((opts) => {
+      deprecated("remove-article", "article remove");
+      return removeArticleAction(opts.path);
     })
   );
-  const registerTagCommand = (name, fn) => {
-    program.command(name).requiredOption("-p, --path <target>", '"collection:path"').argument("<tags>", "comma-separated tags").action(
-      withErrors(async (tags, opts) => {
-        const article = await fn(opts.path, splitTags([tags]));
-        console.log(`${article.path} \u2192 tags: ${article.tags.join(", ") || "(none)"}`);
+  const registerDeprecatedTag = (name, newForm, fn) => {
+    program.command(name, { hidden: true }).requiredOption("-p, --path <target>", '"collection:path"').argument("<tags>", "comma-separated tags").action(
+      withErrors((tagList, opts) => {
+        deprecated(name, newForm);
+        return tagsAction(fn, opts.path, tagList);
       })
     );
   };
-  registerTagCommand("add-tags", addTags);
-  registerTagCommand("remove-tags", removeTags);
-  registerTagCommand("update-tags", setTags);
-  program.command("index").description("Rebuild the search index via the active plugin").option("--embed", "also build vector embeddings (may download models on first run)").action(
-    withErrors(async (opts) => {
-      const provider = await loadSearchProvider();
-      if (!provider) {
-        const installable = (await listSearchModes()).filter((m) => m.plugin !== "native");
-        console.log(
-          installable.length > 0 ? `No index-backed plugin active. Available modes: ${installable.map((m) => `${m.plugin}\xB7${m.type}`).join(", ")}` : "No search plugin installed \u2014 using native search (nothing to index). Install one with: diffwiki plugin install <spec>"
-        );
-        return;
-      }
-      const indexed = await provider.reindex(await listCollections2(), { embed: !!opts.embed });
-      console.log(`Indexed ${indexed} document(s).`);
+  registerDeprecatedTag("add-tags", "tags add", addTags);
+  registerDeprecatedTag("remove-tags", "tags remove", removeTags);
+  registerDeprecatedTag("update-tags", "tags set", setTags);
+  program.command("index", { hidden: true }).option("--embed", "also build vector embeddings (may download models on first run)").action(
+    withErrors((opts) => {
+      deprecated("index", "search index");
+      return indexAction(opts);
     })
   );
-  program.command("query").description("Search articles via the resolved search engine (native fallback if none)").option("--engine <name>", "search engine/plugin (default: config defaultSearch, else native)").option("-c, --collection <name>", "limit to a collection").option("-t, --type <type>", "search type (engine-defined, e.g. keyword|semantic|hybrid)").argument("[term]", "search term", "").action(
-    withErrors(async (term, opts) => {
-      const queryOpts = { engine: opts.engine, collection: opts.collection, type: opts.type };
-      const outcome = await search(term, queryOpts);
-      const hits = outcome.hits;
-      console.log(`${hits.length} result(s)`);
-      for (const hit of hits) {
-        const score = typeof hit.score === "number" ? hit.score.toFixed(3) : "-";
-        const line = `${score}	${hit.collection}	${hit.title}	${hit.path}`;
-        console.log(hit.snippet ? `${line}	${hit.snippet}` : line);
-      }
-      if (outcome.error) {
-        console.error(`\u26A0 engine "${outcome.engine}" failed: ${outcome.error} \u2014 used native (${hits.length} results)`);
-      }
-    })
-  );
-  const plugin = program.command("plugin").description("Manage search plugins");
-  plugin.command("install").description("Install a search plugin from an npm spec and provision it (setup)").argument("<spec>", "npm package spec (name, name@version, or path)").option("--no-setup", "skip the end-to-end setup after install").option("--no-default", "do not make this the default search engine").option("--prefetch-models", "pre-download models during setup (heavy)").action(
-    withErrors(async (spec, opts) => {
-      const { record, setup, defaulted } = await installPlugin(spec, {
-        setup: opts.setup,
-        setDefault: opts.default,
-        prefetchModels: opts.prefetchModels
-      });
-      console.log(`Installed "${record.name}"${record.version ? ` v${record.version}` : ""}`);
-      if (!opts.setup) {
-        console.log("Skipped setup (--no-setup) \u2014 run: diffwiki index");
-      } else if (setup && !setup.ready) {
-        const reason = setup.steps.find((s) => !s.ok)?.message ?? "setup did not complete";
-        console.log(`\u26A0 Not ready: ${reason}`);
-        console.log("  \u2192 run: diffwiki doctor");
-      }
-      if (defaulted) {
-        console.log(
-          `Set "${record.name}" as the default search engine (change: diffwiki config-set defaultSearch <engine[:type]>)`
-        );
-      }
+  program.command("query", { hidden: true }).option("--engine <name>", "search engine/plugin (default: config defaultSearch, else native)").option("-c, --collection <name>", "limit to a collection").option("-t, --type <type>", "search type (engine-defined, e.g. keyword|semantic|hybrid)").argument("[term]", "search term", "").action(
+    withErrors((term, opts) => {
+      deprecated("query", "search query");
+      return queryAction(term, opts);
     })
   );
-  plugin.command("register").description("Register an existing executable as a search plugin").argument("<name>", "plugin name").requiredOption("--command <cmd...>", "command argv to spawn the plugin (e.g. node /abs/adapter.js)").action(
-    withErrors(async (name, opts) => {
-      const record = await registerPlugin(name, opts.command);
-      console.log(`Registered "${record.name}" \u2192 ${record.command.join(" ")}`);
+  program.command("init", { hidden: true }).option("-c, --collection <name>", "collection name (default: repo name)").option("-p, --path <path>", "wiki path within the repo (default: wiki)").action(
+    withErrors((opts) => {
+      deprecated("init", "collection init");
+      return initAction(opts);
     })
   );
-  plugin.command("list").description("List installed and available search plugins").action(
-    withErrors(async () => {
-      const installed = await listPlugins();
-      const installedNames = new Set(installed.map((p) => p.name));
-      console.log("Installed:");
-      if (installed.length === 0) {
-        console.log("  (none)");
-      } else {
-        for (const p of installed) {
-          console.log(
-            `  ${p.name}	${p.kind}	${p.version ?? "-"}	enabled=${p.enabled}	managed=${!!p.managed}	spawnable=${p.spawnable}`
-          );
-        }
-      }
-      const available = listAvailablePlugins().filter((k) => !installedNames.has(k.name));
-      if (available.length > 0) {
-        console.log("\nAvailable (install with: diffwiki plugin install <name>):");
-        for (const k of available) {
-          console.log(`  ${k.name}	[${k.kind}]	${k.description}`);
-          console.log(`    requires ${k.requires ?? "nothing"}`);
-        }
+  program.command("export", { hidden: true }).requiredOption("-o, --out <dir>", "output directory").option("-b, --base <path>", "base URL path (e.g. /my-repo/ for GitHub Pages)", "/").option("-f, --filter <globs>", "only export collections matching these globs (comma-separated)").option("-e, --exclude <globs>", "exclude collections matching these globs (comma-separated)").option("--project [dir]", "build only the repo project from its diffwiki.yaml (default: cwd)").action(
+    withErrors(
+      (opts) => {
+        deprecated("export", "site export");
+        return exportAction(opts);
       }
-    })
-  );
-  plugin.command("remove").description("Remove a search plugin").argument("<name>", "plugin name").action(
-    withErrors(async (name) => {
-      await removePlugin(name);
-      console.log(`Removed "${name}"`);
-    })
+    )
   );
-  program.command("init").description("Initialize an in-repo wiki and register it globally").option("-c, --collection <name>", "collection name (default: repo name)").option("-p, --path <path>", "wiki path within the repo (default: wiki)").action(
-    withErrors(async (opts) => {
-      const entry = await initRepoWiki({
-        cwd: process.cwd(),
-        collection: opts.collection,
-        wikiPath: opts.path
-      });
-      console.log(`Initialized repo wiki "${entry.name}" at ${entry.path}`);
-      console.log("Registered globally \u2014 discoverable via: diffwiki list");
+  program.command("config-set", { hidden: true }).argument("<key>", "config key").argument("<value>", "config value").action(
+    withErrors((key, value) => {
+      deprecated("config-set", "config set");
+      return configSetAction(key, value);
     })
   );
-  program.command("export").description("Generate a static site (deployable to GitHub Pages)").requiredOption("-o, --out <dir>", "output directory").option("-b, --base <path>", "base URL path (e.g. /my-repo/ for GitHub Pages)", "/").option("-f, --filter <globs>", "only export collections matching these globs (comma-separated)").option("-e, --exclude <globs>", "exclude collections matching these globs (comma-separated)").action(
-    withErrors(async (opts) => {
-      await runExport({ out: opts.out, base: opts.base, filter: opts.filter, exclude: opts.exclude });
+  program.command("config-get", { hidden: true }).argument("<key>", "config key").action(
+    withErrors((key) => {
+      deprecated("config-get", "config get");
+      return configGetAction(key);
     })
   );
-  program.command("config-set").description("Set a config value (e.g. defaultCollection, or defaultSearch <engine[:type]>)").argument("<key>", "config key").argument("<value>", "config value").action(
-    withErrors(async (key, value) => {
-      await setConfigValue(key, value);
-      console.log(`Set ${key} = ${value}`);
+  program.command("up", { hidden: true }).option("-p, --port <port>", "port to serve on", "4321").action(
+    withErrors((opts) => {
+      deprecated("up", "ui up");
+      return upAction(opts);
     })
   );
-  program.command("config-get").description("Read a config value").argument("<key>", "config key").action(
-    withErrors(async (key) => {
-      const value = await getConfigValue(key);
-      console.log(value ?? "(unset)");
+  program.command("down", { hidden: true }).action(
+    withErrors(() => {
+      deprecated("down", "ui down");
+      return downAction();
     })
   );
-  program.command("doctor").description("Diagnose configuration issues").action(
-    withErrors(async () => {
-      const diagnostics = await doctor();
-      for (const d of diagnostics) {
-        console.log(`${icon(d.level)} ${d.message}`);
-      }
-      if (diagnostics.some((d) => d.level === "error")) {
-        process.exitCode = 1;
-      }
-    })
-  );
-  program.command("up").description("Start the diffwiki UI (latest published diffwiki-app)").option("-p, --port <port>", "port to serve on", "4321").action(
-    withErrors(async (opts) => {
-      const existing = await readState();
-      if (existing && isAlive(existing.pid)) {
-        console.log(`UI already running at ${existing.url} (pid ${existing.pid})`);
-        return;
-      }
-      const state = await startUi(Number(opts.port));
-      const ok = await waitForServer(state.url);
-      console.log(
-        ok ? `UI started at ${state.url} (pid ${state.pid})` : `Launched (pid ${state.pid}) but ${state.url} did not respond yet \u2014 check \`diffwiki status\``
-      );
+  program.command("status", { hidden: true }).action(
+    withErrors(() => {
+      deprecated("status", "ui status");
+      return statusAction();
     })
   );
-  program.command("down").description("Stop the running diffwiki UI").action(
-    withErrors(async () => {
-      const stopped = await stopUi();
-      console.log(stopped ? `Stopped UI (pid ${stopped.pid})` : "UI is not running.");
+  program.command("open", { hidden: true }).option("-p, --port <port>", "port to serve on", "4321").action(
+    withErrors((opts) => {
+      deprecated("open", "ui open");
+      return openAction(opts);
     })
   );
-  program.command("status").description("Show whether the diffwiki UI is running").action(
-    withErrors(async () => {
-      const state = await readState();
-      if (state && isAlive(state.pid)) {
-        console.log(`running \xB7 ${state.url} \xB7 pid ${state.pid} \xB7 since ${state.startedAt}`);
-      } else {
-        console.log("stopped");
-      }
+  program.command("edit", { hidden: true }).argument("[target]", 'collection or "collection:slug" (default: the current repo collection)').option("--editor <cmd>", "editor command (overrides config `editor`, $VISUAL, $EDITOR)").action(
+    withErrors((target, opts) => {
+      deprecated("edit", "collection edit / article edit");
+      return editAction(target, opts.editor);
     })
   );
-  program.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(async (opts) => {
-      let state = await readState();
-      if (!state || !isAlive(state.pid)) {
-        state = await startUi(Number(opts.port));
-        await waitForServer(state.url);
-      }
-      const coll = await resolveCwdCollection(process.cwd());
-      const target = coll ? `${state.url}/${encodeURIComponent(coll.name)}` : state.url;
-      openBrowser(target);
-      console.log(`Opening ${target}`);
+  program.command("preview", { hidden: true }).option("-p, --port <port>", "port to serve on", "4321").action(
+    withErrors((opts) => {
+      deprecated("preview", "site preview");
+      return previewAction(opts);
     })
   );
-  return program;
 }
 
 // src/logging.ts
 import { mkdirSync } from "fs";
 import os from "os";
-import path3 from "path";
+import path4 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 : path3.join(os.homedir(), ".diffwiki");
+  return override && override.length > 0 ? override : path4.join(os.homedir(), ".diffwiki");
 }
 function resolveCliLevel(argv) {
   if (argv.includes("-v") || argv.includes("--verbose")) return "debug";
@@ -462,9 +723,9 @@ function configureCliLogging(argv = process.argv) {
   if (configured || getConfig() != null) return;
   configured = true;
   const level = resolveCliLevel(argv);
-  const logsDir = path3.join(diffwikiHome(), "logs");
+  const logsDir = path4.join(diffwikiHome(), "logs");
   mkdirSync(logsDir, { recursive: true });
-  const logFile = path3.join(logsDir, "diffwiki.log");
+  const logFile = path4.join(logsDir, "diffwiki.log");
   const stderrSink = (record) => {
     process.stderr.write(formatLine(record) + "\n");
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diffwiki",
-  "version": "0.8.0",
+  "version": "0.9.0-rc.202607291532.69c042c",
   "description": "diffwiki command-line interface",
   "license": "MIT",
   "type": "module",
@@ -17,7 +17,7 @@
     "@logtape/logtape": "^2.2.4",
     "@logtape/file": "^2.2.4",
     "commander": "^13.0.0",
-    "diffwiki-core": "0.8.0"
+    "diffwiki-core": "0.9.0-rc.202607291532.69c042c"
   },
   "devDependencies": {
     "@types/node": "^22.0.0"