diffwiki-core 0.14.0 → 0.15.0

package/dist/plugin.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/plugin.ts
@@ -22,9 +32,12 @@ var plugin_exports = {};
 __export(plugin_exports, {
   commandExists: () => commandExists,
   definePlugin: () => definePlugin,
+  ensureTool: () => ensureTool,
+  parseArticle: () => parseArticle,
   resolveDependency: () => resolveDependency,
   runProcess: () => runProcess,
-  runProcessJson: () => runProcessJson
+  runProcessJson: () => runProcessJson,
+  stripFrontmatter: () => stripFrontmatter
 });
 module.exports = __toCommonJS(plugin_exports);
 
@@ -34,6 +47,71 @@ var import_node_util = require("util");
 var import_node_fs = require("fs");
 var import_node_path = require("path");
 var import_node_url = require("url");
+
+// src/frontmatter.ts
+var import_gray_matter = __toESM(require("gray-matter"), 1);
+var import_yaml = require("yaml");
+var YAML_ENGINE = {
+  parse: (input) => {
+    const data = (0, import_yaml.parse)(input);
+    return data && typeof data === "object" ? data : {};
+  },
+  stringify: (data) => (0, import_yaml.stringify)(data)
+};
+var MATTER_OPTS = { engines: { yaml: YAML_ENGINE } };
+function coerceAudience(value) {
+  return value === "private" || value === "system" ? value : "public";
+}
+function coerceStatus(value) {
+  return value === "draft" || value === "deprecated" ? value : "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 = 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: [], audience, status, body: body.replace(/^\n+/, "") };
+}
+var FRONTMATTER_BLOCK_RE = /^\uFEFF?[ \t]*---\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/;
+function stripFrontmatter(raw) {
+  return raw.replace(FRONTMATTER_BLOCK_RE, "");
+}
+function parseArticle(raw) {
+  try {
+    const { data, content } = (0, import_gray_matter.default)(raw, MATTER_OPTS);
+    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;
+    const audience = coerceAudience(data.audience);
+    const status = coerceStatus(data.status);
+    return { title, tags, created, audience, status, body: content.replace(/^\n+/, "") };
+  } catch {
+    return parseFallback(raw);
+  }
+}
+
+// src/plugins/sdk.ts
 var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.execFile);
 async function runProcess(file, args, opts) {
   const { stdout, stderr } = await execFileAsync(file, args, {
@@ -90,6 +168,57 @@ async function resolveDependency(dep, fromUrl) {
   }
   return { dependency: dep, command: null, source: "missing" };
 }
+async function ensureTool(spec, opts) {
+  const exists = opts?.exists ?? commandExists;
+  const run = opts?.run ?? ((file, args) => runProcess(file, args));
+  const log = opts?.log;
+  if (await exists(spec.command)) {
+    return { command: spec.command, present: true, installed: false, message: `${spec.command} present` };
+  }
+  if (!opts?.install) {
+    return {
+      command: spec.command,
+      present: false,
+      installed: false,
+      message: `${spec.command} not found \u2014 ${spec.manual}`
+    };
+  }
+  const attempts = [];
+  if (spec.mise && await exists("mise"))
+    attempts.push({ method: "mise", bin: "mise", args: ["use", "-g", spec.mise] });
+  if (spec.brew && await exists("brew")) attempts.push({ method: "brew", bin: "brew", args: ["install", spec.brew] });
+  for (const a of attempts) {
+    try {
+      log?.("info", `installing ${spec.command} via ${a.method}\u2026`);
+      await run(a.bin, a.args);
+      if (await exists(spec.command)) {
+        return {
+          command: spec.command,
+          present: true,
+          installed: true,
+          method: a.method,
+          message: `installed ${spec.command} via ${a.method}`
+        };
+      }
+      return {
+        command: spec.command,
+        present: false,
+        installed: true,
+        method: a.method,
+        message: `installed ${spec.command} via ${a.method}, but it isn't on PATH yet \u2014 restart your shell (or activate ${a.method}) and retry`
+      };
+    } catch (err) {
+      log?.("warn", `${a.method} could not install ${spec.command}: ${err.message}`);
+    }
+  }
+  const aptHint = spec.apt ? ` (Debian/Ubuntu: sudo apt-get install -y ${spec.apt})` : "";
+  return {
+    command: spec.command,
+    present: false,
+    installed: false,
+    message: `could not auto-install ${spec.command} \u2014 ${spec.manual}${aptHint}`
+  };
+}
 function definePlugin(def) {
   const { name, kind, version, capabilities, dependencies, handlers } = def;
   const describeResult = {
@@ -169,7 +298,10 @@ function definePlugin(def) {
 0 && (module.exports = {
   commandExists,
   definePlugin,
+  ensureTool,
+  parseArticle,
   resolveDependency,
   runProcess,
-  runProcessJson
+  runProcessJson,
+  stripFrontmatter
 });

package/dist/plugin.d.cts

@@ -1,179 +1,5 @@
-/**
- * Wire-protocol and SDK types shared by the plugin authoring SDK (`sdk.ts`) and
- * re-exported to plugin authors via the `diffwiki-core/plugin` subpath.
- *
- * @module
- */
-/** Log severity levels for plugin diagnostic messages. */
-type LogLevel = 'info' | 'warn' | 'error';
-/** A logging function that plugins use to emit diagnostic messages to stderr. */
-type PluginLogFn = (level: LogLevel, message: string) => void;
-/** A wire-format collection as received in handler params. */
-interface WireCollection {
-    name: string;
-    path: string;
-}
-/** Diagnostic entry returned by the health handler. */
-interface WireDiagnostic {
-    level: 'ok' | 'warn' | 'error';
-    message: string;
-}
-/** Readiness details returned by the health handler. */
-interface WireReadiness {
-    toolInstalled: boolean;
-    modelsPresent: boolean;
-    indexBuilt: boolean;
-    docsIndexed: number;
-    embeddingsPending: number;
-    firstSearchCost: 'instant' | 'model-load' | 'model-download';
-}
-/** A single search hit returned by the search handler. */
-interface SearchHandlerHit {
-    collection: string;
-    relPath: string;
-    title: string;
-    snippet?: string;
-    score?: number;
-    docid?: string;
-    tags?: string[];
-}
-/** Result shape returned by the search handler. */
-interface SearchHandlerResult {
-    hits: SearchHandlerHit[];
-}
-/** Result shape returned by the index handler. */
-interface IndexHandlerResult {
-    indexed: number;
-}
-/** Result shape returned by the health handler. */
-interface HealthHandlerResult {
-    ready: boolean;
-    readiness?: WireReadiness;
-    diagnostics: WireDiagnostic[];
-}
-/** Result shape returned by the setup handler. */
-interface SetupHandlerResult {
-    ready: boolean;
-    steps?: Array<{
-        step: string;
-        ok: boolean;
-        message?: string;
-    }>;
-}
-/** Result shape returned by the onEvent handler. */
-interface EventHandlerResult {
-    accepted: boolean;
-}
-/** Parameters passed to the search handler. */
-interface SearchParams {
-    term: string;
-    collections: WireCollection[];
-    collection?: string;
-    type?: string;
-    limit?: number;
-}
-/** Parameters passed to the index handler. */
-interface IndexParams {
-    collections: WireCollection[];
-    embed?: boolean;
-}
-/** Parameters passed to the setup handler. */
-interface SetupParams {
-    collections: WireCollection[];
-    embed?: boolean;
-    prefetchModels?: boolean;
-}
-/** Parameters passed to the onEvent handler. */
-interface EventParams {
-    event: string;
-    collection: WireCollection;
-    relPath?: string;
-    collections: WireCollection[];
-}
-/** Parameters passed to the health handler. */
-interface HealthParams {
-    collections: WireCollection[];
-}
-/** Plugin capabilities advertised during describe. */
-interface PluginCapabilities {
-    searchTypes: string[];
-    collectionFilter: boolean;
-    events: boolean;
-}
-/**
- * An external executable a plugin needs at runtime (e.g. `qmd`, `rg`).
- *
- * Declaring a dependency lets the plugin resolve the binary uniformly and lets
- * `setup`/`health` report it. When `npm` is set, the package is expected to be a
- * regular dependency in the plugin's own `package.json`, so `diffwiki plugin
- * install` pulls it transitively and {@link ResolvedDependency} finds its bin in
- * the plugin's `node_modules` — no global install required.
- */
-interface PluginDependency {
-    /** The executable name, e.g. `'qmd'` or `'rg'`. */
-    command: string;
-    /** npm package that provides the executable; when set, the local bin is preferred over PATH. */
-    npm?: string;
-    /** Human-facing manual install hint, shown when the dependency is unresolved. */
-    hint?: string;
-}
-/**
- * The outcome of resolving a {@link PluginDependency}: the argv prefix to invoke
- * it, plus where it was found. `command` is null when unresolved.
- */
-interface ResolvedDependency {
-    dependency: PluginDependency;
-    /** Argv prefix to spawn the tool, or null if unresolved. */
-    command: string[] | null;
-    /** How it resolved: the npm-provided local bin, the system PATH, or nowhere. */
-    source: 'npm' | 'path' | 'missing';
-}
-/** The handler functions a plugin provides. */
-interface PluginHandlers {
-    /** Handle a search request. Required for search plugins. */
-    search: (params: SearchParams, log: PluginLogFn) => Promise<SearchHandlerResult> | SearchHandlerResult;
-    /** Handle a reindex request. Optional -- defaults to `{ indexed: 0 }`. */
-    index?: (params: IndexParams, log: PluginLogFn) => Promise<IndexHandlerResult> | IndexHandlerResult;
-    /** Handle an initial setup/provisioning request. Optional -- defaults to `{ ready: true }`. */
-    setup?: (params: SetupParams, log: PluginLogFn) => Promise<SetupHandlerResult> | SetupHandlerResult;
-    /** Handle a lifecycle event (article/collection add/update/remove). Optional. */
-    onEvent?: (params: EventParams, log: PluginLogFn) => Promise<EventHandlerResult> | EventHandlerResult;
-    /** Report plugin health and readiness. Optional. */
-    health?: (params: HealthParams, log: PluginLogFn) => Promise<HealthHandlerResult> | HealthHandlerResult;
-}
-/** The definition object passed to `definePlugin()`. */
-interface PluginDefinition {
-    /** Plugin name (must match the name used in `diffwiki plugin register`). */
-    name: string;
-    /** Plugin kind. Currently only `'search'` is supported. */
-    kind: 'search';
-    /** Semantic version string. */
-    version?: string;
-    /** Plugin capabilities advertised to the host. */
-    capabilities: PluginCapabilities;
-    /** External executables the plugin needs. Reported via `describe` and resolvable via {@link ResolvedDependency}. */
-    dependencies?: PluginDependency[];
-    /** Handler functions for each operation. */
-    handlers: PluginHandlers;
-}
-/** The object returned by `definePlugin()`. Call `.run()` to serve one request. */
-interface DefinedPlugin {
-    /** The plugin definition. */
-    definition: PluginDefinition;
-    /**
-     * Read one JSON request from stdin, dispatch to the matching handler, write
-     * the JSON response to stdout, and exit. Exit code 0 on success, 1 on
-     * handler error. Logs go to stderr.
-     */
-    run: () => void;
-}
-/** Options for `runProcess` and `runProcessJson`. */
-interface RunProcessOptions {
-    /** Environment variables for the child process. Defaults to `process.env`. */
-    env?: NodeJS.ProcessEnv;
-    /** Timeout in milliseconds. No timeout by default. */
-    timeout?: number;
-}
+import { Y as PluginDefinition, Z as DefinedPlugin, _ as PluginDependency, $ as ResolvedDependency, a0 as RunProcessOptions } from './frontmatter-ghMCpLNf.cjs';
+export { a1 as EventHandlerResult, a2 as EventParams, a3 as HealthHandlerResult, a4 as HealthParams, a5 as IndexHandlerResult, a6 as IndexParams, a7 as LogLevel, j as ParsedArticle, a8 as PluginCapabilities, a9 as PluginHandlers, aa as PluginLogFn, J as SearchExpansion, ab as SearchHandlerHit, ac as SearchHandlerResult, ad as SearchParams, ae as SetupHandlerResult, af as SetupParams, ag as WireCollection, ah as WireDiagnostic, ai as WireReadiness, U as parseArticle, X as stripFrontmatter } from './frontmatter-ghMCpLNf.cjs';
 
 /**
  * diffwiki plugin authoring SDK — the public surface for plugin authors, imported
@@ -207,6 +33,57 @@ declare function commandExists(name: string): Promise<boolean>;
  * @param fromUrl The plugin bin's `import.meta.url`, used to anchor node resolution.
  */
 declare function resolveDependency(dep: PluginDependency, fromUrl: string): Promise<ResolvedDependency>;
+/** Per-package-manager identifiers for a tool ensureTool can install. */
+interface ToolInstallers {
+    /** mise tool id (installed with `mise use -g`), e.g. `'fzf'` or `'npm:@tobilu/qmd'`. */
+    mise?: string;
+    /** Homebrew formula (installed with `brew install`), e.g. `'fzf'`. */
+    brew?: string;
+    /** apt package name. NOT auto-run (needs sudo) — surfaced as guidance only. */
+    apt?: string;
+}
+/** A tool to ensure is on PATH, with the package ids + a manual fallback hint. */
+interface EnsureToolSpec extends ToolInstallers {
+    /** Executable checked on PATH, e.g. `'fzf'`. */
+    command: string;
+    /** Manual instruction (URL or command) shown when auto-install can't proceed. */
+    manual: string;
+}
+/** The outcome of an {@link ensureTool} call. */
+interface EnsureToolResult {
+    command: string;
+    /** True if the tool is on PATH after ensureTool ran. */
+    present: boolean;
+    /** True if ensureTool installed it during this call. */
+    installed: boolean;
+    /** The manager used, when an install was attempted and succeeded. */
+    method?: 'mise' | 'brew';
+    /** A human-facing message describing the outcome. */
+    message: string;
+}
+/** Injectable seams for {@link ensureTool} (defaults hit the real system). */
+interface EnsureToolOptions {
+    /** Attempt installation when the tool is missing (default: false — check only). */
+    install?: boolean;
+    /** Diagnostic sink. */
+    log?: (level: 'info' | 'warn' | 'error', message: string) => void;
+    /** Existence probe (injected in tests). Defaults to {@link commandExists}. */
+    exists?: (command: string) => Promise<boolean>;
+    /** Command runner (injected in tests). Defaults to {@link runProcess}. */
+    run?: (file: string, args: readonly string[]) => Promise<unknown>;
+}
+/**
+ * Ensure a system tool is on PATH, optionally installing it via a detected
+ * package manager. Detection order: **mise**, then **Homebrew**. `apt` is
+ * intentionally never auto-run (it needs `sudo`, which would hang or prompt) —
+ * it is included in the guidance message instead. Safe to call when the tool
+ * already exists (returns immediately) and never throws.
+ *
+ * Note: a tool installed via mise may not be on PATH in the current process
+ * until mise's shims are active; that case is reported as `installed:true,
+ * present:false` with a message telling the user to restart their shell.
+ */
+declare function ensureTool(spec: EnsureToolSpec, opts?: EnsureToolOptions): Promise<EnsureToolResult>;
 /**
  * Define a diffwiki plugin. The required entry point for all plugins: accepts a
  * {@link PluginDefinition} and returns a {@link DefinedPlugin} whose `.run()`
@@ -226,4 +103,4 @@ declare function resolveDependency(dep: PluginDependency, fromUrl: string): Prom
  */
 declare function definePlugin(def: PluginDefinition): DefinedPlugin;
 
-export { type DefinedPlugin, type EventHandlerResult, type EventParams, type HealthHandlerResult, type HealthParams, type IndexHandlerResult, type IndexParams, type LogLevel, type PluginCapabilities, type PluginDefinition, type PluginDependency, type PluginHandlers, type PluginLogFn, type ResolvedDependency, type RunProcessOptions, type SearchHandlerHit, type SearchHandlerResult, type SearchParams, type SetupHandlerResult, type SetupParams, type WireCollection, type WireDiagnostic, type WireReadiness, commandExists, definePlugin, resolveDependency, runProcess, runProcessJson };
+export { DefinedPlugin, type EnsureToolOptions, type EnsureToolResult, type EnsureToolSpec, PluginDefinition, PluginDependency, ResolvedDependency, RunProcessOptions, type ToolInstallers, commandExists, definePlugin, ensureTool, resolveDependency, runProcess, runProcessJson };

package/dist/plugin.d.ts

@@ -1,179 +1,5 @@
-/**
- * Wire-protocol and SDK types shared by the plugin authoring SDK (`sdk.ts`) and
- * re-exported to plugin authors via the `diffwiki-core/plugin` subpath.
- *
- * @module
- */
-/** Log severity levels for plugin diagnostic messages. */
-type LogLevel = 'info' | 'warn' | 'error';
-/** A logging function that plugins use to emit diagnostic messages to stderr. */
-type PluginLogFn = (level: LogLevel, message: string) => void;
-/** A wire-format collection as received in handler params. */
-interface WireCollection {
-    name: string;
-    path: string;
-}
-/** Diagnostic entry returned by the health handler. */
-interface WireDiagnostic {
-    level: 'ok' | 'warn' | 'error';
-    message: string;
-}
-/** Readiness details returned by the health handler. */
-interface WireReadiness {
-    toolInstalled: boolean;
-    modelsPresent: boolean;
-    indexBuilt: boolean;
-    docsIndexed: number;
-    embeddingsPending: number;
-    firstSearchCost: 'instant' | 'model-load' | 'model-download';
-}
-/** A single search hit returned by the search handler. */
-interface SearchHandlerHit {
-    collection: string;
-    relPath: string;
-    title: string;
-    snippet?: string;
-    score?: number;
-    docid?: string;
-    tags?: string[];
-}
-/** Result shape returned by the search handler. */
-interface SearchHandlerResult {
-    hits: SearchHandlerHit[];
-}
-/** Result shape returned by the index handler. */
-interface IndexHandlerResult {
-    indexed: number;
-}
-/** Result shape returned by the health handler. */
-interface HealthHandlerResult {
-    ready: boolean;
-    readiness?: WireReadiness;
-    diagnostics: WireDiagnostic[];
-}
-/** Result shape returned by the setup handler. */
-interface SetupHandlerResult {
-    ready: boolean;
-    steps?: Array<{
-        step: string;
-        ok: boolean;
-        message?: string;
-    }>;
-}
-/** Result shape returned by the onEvent handler. */
-interface EventHandlerResult {
-    accepted: boolean;
-}
-/** Parameters passed to the search handler. */
-interface SearchParams {
-    term: string;
-    collections: WireCollection[];
-    collection?: string;
-    type?: string;
-    limit?: number;
-}
-/** Parameters passed to the index handler. */
-interface IndexParams {
-    collections: WireCollection[];
-    embed?: boolean;
-}
-/** Parameters passed to the setup handler. */
-interface SetupParams {
-    collections: WireCollection[];
-    embed?: boolean;
-    prefetchModels?: boolean;
-}
-/** Parameters passed to the onEvent handler. */
-interface EventParams {
-    event: string;
-    collection: WireCollection;
-    relPath?: string;
-    collections: WireCollection[];
-}
-/** Parameters passed to the health handler. */
-interface HealthParams {
-    collections: WireCollection[];
-}
-/** Plugin capabilities advertised during describe. */
-interface PluginCapabilities {
-    searchTypes: string[];
-    collectionFilter: boolean;
-    events: boolean;
-}
-/**
- * An external executable a plugin needs at runtime (e.g. `qmd`, `rg`).
- *
- * Declaring a dependency lets the plugin resolve the binary uniformly and lets
- * `setup`/`health` report it. When `npm` is set, the package is expected to be a
- * regular dependency in the plugin's own `package.json`, so `diffwiki plugin
- * install` pulls it transitively and {@link ResolvedDependency} finds its bin in
- * the plugin's `node_modules` — no global install required.
- */
-interface PluginDependency {
-    /** The executable name, e.g. `'qmd'` or `'rg'`. */
-    command: string;
-    /** npm package that provides the executable; when set, the local bin is preferred over PATH. */
-    npm?: string;
-    /** Human-facing manual install hint, shown when the dependency is unresolved. */
-    hint?: string;
-}
-/**
- * The outcome of resolving a {@link PluginDependency}: the argv prefix to invoke
- * it, plus where it was found. `command` is null when unresolved.
- */
-interface ResolvedDependency {
-    dependency: PluginDependency;
-    /** Argv prefix to spawn the tool, or null if unresolved. */
-    command: string[] | null;
-    /** How it resolved: the npm-provided local bin, the system PATH, or nowhere. */
-    source: 'npm' | 'path' | 'missing';
-}
-/** The handler functions a plugin provides. */
-interface PluginHandlers {
-    /** Handle a search request. Required for search plugins. */
-    search: (params: SearchParams, log: PluginLogFn) => Promise<SearchHandlerResult> | SearchHandlerResult;
-    /** Handle a reindex request. Optional -- defaults to `{ indexed: 0 }`. */
-    index?: (params: IndexParams, log: PluginLogFn) => Promise<IndexHandlerResult> | IndexHandlerResult;
-    /** Handle an initial setup/provisioning request. Optional -- defaults to `{ ready: true }`. */
-    setup?: (params: SetupParams, log: PluginLogFn) => Promise<SetupHandlerResult> | SetupHandlerResult;
-    /** Handle a lifecycle event (article/collection add/update/remove). Optional. */
-    onEvent?: (params: EventParams, log: PluginLogFn) => Promise<EventHandlerResult> | EventHandlerResult;
-    /** Report plugin health and readiness. Optional. */
-    health?: (params: HealthParams, log: PluginLogFn) => Promise<HealthHandlerResult> | HealthHandlerResult;
-}
-/** The definition object passed to `definePlugin()`. */
-interface PluginDefinition {
-    /** Plugin name (must match the name used in `diffwiki plugin register`). */
-    name: string;
-    /** Plugin kind. Currently only `'search'` is supported. */
-    kind: 'search';
-    /** Semantic version string. */
-    version?: string;
-    /** Plugin capabilities advertised to the host. */
-    capabilities: PluginCapabilities;
-    /** External executables the plugin needs. Reported via `describe` and resolvable via {@link ResolvedDependency}. */
-    dependencies?: PluginDependency[];
-    /** Handler functions for each operation. */
-    handlers: PluginHandlers;
-}
-/** The object returned by `definePlugin()`. Call `.run()` to serve one request. */
-interface DefinedPlugin {
-    /** The plugin definition. */
-    definition: PluginDefinition;
-    /**
-     * Read one JSON request from stdin, dispatch to the matching handler, write
-     * the JSON response to stdout, and exit. Exit code 0 on success, 1 on
-     * handler error. Logs go to stderr.
-     */
-    run: () => void;
-}
-/** Options for `runProcess` and `runProcessJson`. */
-interface RunProcessOptions {
-    /** Environment variables for the child process. Defaults to `process.env`. */
-    env?: NodeJS.ProcessEnv;
-    /** Timeout in milliseconds. No timeout by default. */
-    timeout?: number;
-}
+import { Y as PluginDefinition, Z as DefinedPlugin, _ as PluginDependency, $ as ResolvedDependency, a0 as RunProcessOptions } from './frontmatter-ghMCpLNf.js';
+export { a1 as EventHandlerResult, a2 as EventParams, a3 as HealthHandlerResult, a4 as HealthParams, a5 as IndexHandlerResult, a6 as IndexParams, a7 as LogLevel, j as ParsedArticle, a8 as PluginCapabilities, a9 as PluginHandlers, aa as PluginLogFn, J as SearchExpansion, ab as SearchHandlerHit, ac as SearchHandlerResult, ad as SearchParams, ae as SetupHandlerResult, af as SetupParams, ag as WireCollection, ah as WireDiagnostic, ai as WireReadiness, U as parseArticle, X as stripFrontmatter } from './frontmatter-ghMCpLNf.js';
 
 /**
  * diffwiki plugin authoring SDK — the public surface for plugin authors, imported
@@ -207,6 +33,57 @@ declare function commandExists(name: string): Promise<boolean>;
  * @param fromUrl The plugin bin's `import.meta.url`, used to anchor node resolution.
  */
 declare function resolveDependency(dep: PluginDependency, fromUrl: string): Promise<ResolvedDependency>;
+/** Per-package-manager identifiers for a tool ensureTool can install. */
+interface ToolInstallers {
+    /** mise tool id (installed with `mise use -g`), e.g. `'fzf'` or `'npm:@tobilu/qmd'`. */
+    mise?: string;
+    /** Homebrew formula (installed with `brew install`), e.g. `'fzf'`. */
+    brew?: string;
+    /** apt package name. NOT auto-run (needs sudo) — surfaced as guidance only. */
+    apt?: string;
+}
+/** A tool to ensure is on PATH, with the package ids + a manual fallback hint. */
+interface EnsureToolSpec extends ToolInstallers {
+    /** Executable checked on PATH, e.g. `'fzf'`. */
+    command: string;
+    /** Manual instruction (URL or command) shown when auto-install can't proceed. */
+    manual: string;
+}
+/** The outcome of an {@link ensureTool} call. */
+interface EnsureToolResult {
+    command: string;
+    /** True if the tool is on PATH after ensureTool ran. */
+    present: boolean;
+    /** True if ensureTool installed it during this call. */
+    installed: boolean;
+    /** The manager used, when an install was attempted and succeeded. */
+    method?: 'mise' | 'brew';
+    /** A human-facing message describing the outcome. */
+    message: string;
+}
+/** Injectable seams for {@link ensureTool} (defaults hit the real system). */
+interface EnsureToolOptions {
+    /** Attempt installation when the tool is missing (default: false — check only). */
+    install?: boolean;
+    /** Diagnostic sink. */
+    log?: (level: 'info' | 'warn' | 'error', message: string) => void;
+    /** Existence probe (injected in tests). Defaults to {@link commandExists}. */
+    exists?: (command: string) => Promise<boolean>;
+    /** Command runner (injected in tests). Defaults to {@link runProcess}. */
+    run?: (file: string, args: readonly string[]) => Promise<unknown>;
+}
+/**
+ * Ensure a system tool is on PATH, optionally installing it via a detected
+ * package manager. Detection order: **mise**, then **Homebrew**. `apt` is
+ * intentionally never auto-run (it needs `sudo`, which would hang or prompt) —
+ * it is included in the guidance message instead. Safe to call when the tool
+ * already exists (returns immediately) and never throws.
+ *
+ * Note: a tool installed via mise may not be on PATH in the current process
+ * until mise's shims are active; that case is reported as `installed:true,
+ * present:false` with a message telling the user to restart their shell.
+ */
+declare function ensureTool(spec: EnsureToolSpec, opts?: EnsureToolOptions): Promise<EnsureToolResult>;
 /**
  * Define a diffwiki plugin. The required entry point for all plugins: accepts a
  * {@link PluginDefinition} and returns a {@link DefinedPlugin} whose `.run()`
@@ -226,4 +103,4 @@ declare function resolveDependency(dep: PluginDependency, fromUrl: string): Prom
  */
 declare function definePlugin(def: PluginDefinition): DefinedPlugin;
 
-export { type DefinedPlugin, type EventHandlerResult, type EventParams, type HealthHandlerResult, type HealthParams, type IndexHandlerResult, type IndexParams, type LogLevel, type PluginCapabilities, type PluginDefinition, type PluginDependency, type PluginHandlers, type PluginLogFn, type ResolvedDependency, type RunProcessOptions, type SearchHandlerHit, type SearchHandlerResult, type SearchParams, type SetupHandlerResult, type SetupParams, type WireCollection, type WireDiagnostic, type WireReadiness, commandExists, definePlugin, resolveDependency, runProcess, runProcessJson };
+export { DefinedPlugin, type EnsureToolOptions, type EnsureToolResult, type EnsureToolSpec, PluginDefinition, PluginDependency, ResolvedDependency, RunProcessOptions, type ToolInstallers, commandExists, definePlugin, ensureTool, resolveDependency, runProcess, runProcessJson };