diffwiki 0.9.0-rc.202607291540.2b773e4 → 0.9.0

package/dist/bin.js

@@ -57,9 +57,6 @@ 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";
@@ -295,405 +292,283 @@ async function runPreview(opts) {
 
 // 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();
   });
-  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)
-    )
+  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}`);
+      }
+    })
   );
-  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)
-    )
+  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");
+    })
   );
-  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)
-    )
+  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}`);
+    })
   );
-  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)
-    )
+  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);
+    })
   );
-  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("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("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("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("create", { hidden: true }).argument("<name>", "collection name").action(
-    withErrors((name) => {
-      deprecated("create", "collection create");
-      return createCollectionAction(name);
+  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)"}`);
+      })
+    );
+  };
+  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).`);
     })
   );
-  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("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)`);
+      }
     })
   );
-  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);
+  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("remove-article", { hidden: true }).requiredOption("-p, --path <target>", '"collection:path"').action(
-    withErrors((opts) => {
-      deprecated("remove-article", "article remove");
-      return removeArticleAction(opts.path);
+  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(" ")}`);
     })
   );
-  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);
-      })
-    );
-  };
-  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);
+  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("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("remove").description("Remove a search plugin").argument("<name>", "plugin name").action(
+    withErrors(async (name) => {
+      await removePlugin(name);
+      console.log(`Removed "${name}"`);
     })
   );
-  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);
+  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("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(
+  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)").option("--project [dir]", "build only the repo project from its diffwiki.yaml (default: cwd)").action(
     withErrors(
-      (opts) => {
-        deprecated("export", "site export");
-        return exportAction(opts);
+      async (opts) => {
+        await runExport({
+          out: opts.out,
+          base: opts.base,
+          filter: opts.filter,
+          exclude: opts.exclude,
+          project: opts.project
+        });
       }
     )
   );
-  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("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("config-get", { hidden: true }).argument("<key>", "config key").action(
-    withErrors((key) => {
-      deprecated("config-get", "config get");
-      return configGetAction(key);
+  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("up", { hidden: true }).option("-p, --port <port>", "port to serve on", "4321").action(
-    withErrors((opts) => {
-      deprecated("up", "ui up");
-      return upAction(opts);
+  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("down", { hidden: true }).action(
-    withErrors(() => {
-      deprecated("down", "ui down");
-      return downAction();
+  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);
+  program.command("edit").description("Open a collection (or article) in your editor \u2014 GUI not required").argument("[target]", 'collection or "collection:slug" (default: the current repo collection)').option("--editor <cmd>", "editor command (overrides config `editor`, $VISUAL, $EDITOR)").action(
+    withErrors(async (target, opts) => {
+      const argv = await resolveEditorCommand(opts.editor);
+      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;
     })
   );
+  program.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(async (opts) => {
+      await runPreview({ cwd: process.cwd(), port: Number(opts.port) });
+    })
+  );
+  return program;
 }
 
 // src/logging.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diffwiki",
-  "version": "0.9.0-rc.202607291540.2b773e4",
+  "version": "0.9.0",
   "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.9.0-rc.202607291540.2b773e4"
+    "diffwiki-core": "0.9.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0"