@navbook/cli 0.3.0 → 0.5.0

package/dist/plugins/host.d.ts

@@ -0,0 +1,125 @@
+/**
+ * What a plugin's entry module is handed — spec 05 §5.2.
+ *
+ * Each entry exports `activate(host)`. The host carries three things: the
+ * running core, the settings the repository declared, and the hooks for
+ * registering what this layer accepts.
+ *
+ * `core` is the host's own module object, not something the plugin imported.
+ * That is the single most important line in this file. A plugin resolving its
+ * own `@navbook/core` would get a second copy, and then `instanceof
+ * WorkspaceError` would be false across the boundary, two YAML parsers would
+ * sit on the startup path, and two `Repo` types that are structurally
+ * identical would be nominally different. The store installs with
+ * `--omit=peer` so that copy cannot exist; this is how the plugin gets the
+ * real one instead.
+ */
+import type { CorePluginHost, EntityRecord, Repo } from "@navbook/core";
+import type { Composed, ComposeOptions } from "../commands/compose.ts";
+import type { ExtraColumn } from "../commands/entity.ts";
+import type { Ctx } from "../context.ts";
+/** What every entry module exports. */
+export interface PluginEntry<H> {
+    activate(host: H): void | Promise<void>;
+}
+export type { CorePluginHost };
+/**
+ * What a plugin adds to a command that already exists.
+ *
+ * Every field here has a seam in the CLI that predates plugins: `columns` and
+ * `jsonExtra` are what `nav pr list --all-refs` already uses to add its `refs`
+ * column, and `showSection` is the same idea for a detail view. A plugin
+ * contributing through them renders identically to a built-in, which is the
+ * point — `nav issue list` should not look like it has a bolt-on.
+ */
+export interface VerbHandlers {
+    /**
+     * Frontmatter for a newly created entity, read off this verb's options.
+     *
+     * Returns what `NewEntityInput.ext` takes, so the plugin's keys are written
+     * by the same composer that writes the format's own.
+     */
+    openFields?(opts: Record<string, unknown>): Record<string, string | readonly string[]>;
+    /** Columns appended to this listing, after the built-in ones. */
+    columns?: ExtraColumn[];
+    /** Keys merged into this command's `--json` object, per entity. */
+    jsonExtra?(entity: EntityRecord): Record<string, unknown>;
+    /** Lines appended to this `show`, after the built-in detail. */
+    showSection?(entity: EntityRecord, repo: Repo): string[];
+    /** Candidates offered for this command's query terms, e.g. `feature:auth`. */
+    listCompletions?(): string[];
+}
+/** What the `./cli` entry is given: the core host, plus the terminal. */
+export interface CliPluginHost extends CorePluginHost {
+    /** Where output goes, who is acting, and where the repository is. */
+    ctx: Ctx;
+    /**
+     * Implement a command the manifest declared.
+     *
+     * `path` is the command as typed, without `nav`: `"feature open"`, or
+     * `"feature spec add"`. A path the manifest does not declare is refused,
+     * because the manifest is what built the help and the completions, and a
+     * command that runs but is not in either would be worse than one that does
+     * not run.
+     */
+    command(path: string, run: (args: string[], opts: Record<string, unknown>) => void | Promise<void>): void;
+    /** Implement contributions to an existing verb the manifest declared. */
+    contribute(on: string, handlers: VerbHandlers): void;
+    /** Answer completion for an argument whose spec names this completer. */
+    completer(id: string, complete: (words: string[]) => string[]): void;
+    /** The terminal conveniences, so a plugin's output matches a built-in's. */
+    ui: CliPluginUi;
+}
+/**
+ * The parts of the CLI a plugin may use to talk to the terminal.
+ *
+ * Named rather than handed the modules wholesale: this is the surface the
+ * plugin API version promises, and a plugin reaching past it into the CLI's
+ * internals would break on a refactor nobody thought was a breaking change.
+ */
+export interface CliPluginUi {
+    /** Stop with an operational error (exit 1), as every built-in verb does. */
+    fail(message: string, details?: string[]): never;
+    /** Stop with a format violation (exit 2), as `doctor` does. */
+    failFormat(message: string, details?: string[]): never;
+    /** Ask a yes/no question; anything but yes is a no. */
+    askYesNo(question: string): boolean;
+    /** Print what will happen, ask once, then do it — the `nav install` shape. */
+    confirmAndPerform(opts: {
+        title: string;
+        actions: readonly {
+            description: string;
+            perform: () => void;
+        }[];
+        assumeYes?: boolean;
+    }): boolean;
+    /**
+     * Produce the text of a new file, from `-m` or from `$EDITOR`.
+     *
+     * The whole composing path rather than the editor alone, because what makes
+     * a hand-edited buffer safe is that it is parsed and validated before
+     * anything is written — and a plugin opening `$EDITOR` itself would have to
+     * reproduce that, and would eventually reproduce it slightly differently.
+     */
+    composeFile(opts: ComposeOptions): Composed;
+    /** Open `$EDITOR` on a file already in the tree, as `nav issue edit` does. */
+    editFile(absolutePath: string): void;
+    /** Render a table sized to the terminal, the way every listing does. */
+    renderTable(columns: readonly {
+        header: string;
+        flexible?: boolean;
+        minWidth?: number;
+    }[], rows: readonly string[][]): string;
+    /**
+     * Pad text with spaces to `width` terminal columns, measured as a listing
+     * measures its cells — so a wide or combining character lines up.
+     */
+    pad(text: string, width: number): string;
+    /** The one-line report printed after a `--commit` run. */
+    commitReport(result: {
+        committed: boolean;
+        subject: string;
+    }): string;
+    /** Collect a repeatable option's values, for a manifest that declares one. */
+    collect(value: string, previous: string[]): string[];
+}

package/dist/plugins/host.js

@@ -0,0 +1,18 @@
+/**
+ * What a plugin's entry module is handed — spec 05 §5.2.
+ *
+ * Each entry exports `activate(host)`. The host carries three things: the
+ * running core, the settings the repository declared, and the hooks for
+ * registering what this layer accepts.
+ *
+ * `core` is the host's own module object, not something the plugin imported.
+ * That is the single most important line in this file. A plugin resolving its
+ * own `@navbook/core` would get a second copy, and then `instanceof
+ * WorkspaceError` would be false across the boundary, two YAML parsers would
+ * sit on the startup path, and two `Repo` types that are structurally
+ * identical would be nominally different. The store installs with
+ * `--omit=peer` so that copy cannot exist; this is how the plugin gets the
+ * real one instead.
+ */
+export {};
+//# sourceMappingURL=host.js.map

package/dist/plugins/host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.js","sourceRoot":"","sources":["../../src/plugins/host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}

package/dist/plugins/loader.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Importing a plugin's code, as late as possible — spec 04 §4.3, 05 §5.2.
+ *
+ * The rule this file exists to keep: nothing here runs for a command whose
+ * manifest does not name it. `nav issue list` on a machine with five plugins
+ * installed imports none of them, and `nav --help` imports none of them
+ * either, because the help was built from manifests. An `import()` of one
+ * plugin costs more than the whole of `nav issue list`'s budget, so this is
+ * not a micro-optimisation: it is the difference between plugins being
+ * affordable and not.
+ *
+ * What triggers a load is therefore always a *declaration* — a command the
+ * plugin declared being run, a contribution it declared being reached, a
+ * query term it declared being typed.
+ */
+import { type CoreExtensions } from "@navbook/core";
+import type { PluginEntry } from "./host.ts";
+import type { LoadedPlugin } from "./resolve.ts";
+/** Which part of a plugin to import; the `exports` subpath, without the dot. */
+export type PluginPart = "core" | "cli" | "server" | "web";
+/**
+ * The file a plugin's `exports` maps a subpath to.
+ *
+ * Read from the package's own `package.json` rather than guessed, because the
+ * whole point of `exports` is that a package decides its own layout — and a
+ * published plugin's `./cli` points into `dist/` while the same plugin in a
+ * checkout points into `src/`.
+ *
+ * Null only when the plugin has no such part, which is a plugin's choice. A
+ * package that is gone, or an entry it declares that is not on disk, throws:
+ * the index still lists the plugin, and "declares a command but does not
+ * implement it" would send its author looking for a bug that is not theirs.
+ */
+export declare function entryPath(plugin: LoadedPlugin, part: PluginPart): string | null;
+/** Import one part of one plugin, memoised. */
+export declare function importEntry<H>(plugin: LoadedPlugin, part: PluginPart): Promise<PluginEntry<H> | null>;
+/** Clear the memo. For tests that load the same plugin under two settings. */
+export declare function forgetLoaded(): void;
+/** A plugin's `./core` part, activated, with whatever went wrong. */
+export interface CoreLoad {
+    ext: CoreExtensions;
+    /** One line per plugin that could not contribute, for stderr. */
+    problems: string[];
+}
+/**
+ * Activate every plugin's `./core` entry and merge what they registered.
+ *
+ * A plugin that throws while activating, or that collides with one already
+ * merged, is dropped and reported — the run continues with the plugins that
+ * worked. Dropping one plugin loses that plugin's data; refusing to start
+ * loses the user's whole tracker, and the second is not a better answer to a
+ * bad `package.json` somebody published.
+ */
+export declare function loadCoreExtensions(plugins: readonly LoadedPlugin[]): Promise<CoreLoad>;

package/dist/plugins/loader.js

@@ -0,0 +1,165 @@
+/**
+ * Importing a plugin's code, as late as possible — spec 04 §4.3, 05 §5.2.
+ *
+ * The rule this file exists to keep: nothing here runs for a command whose
+ * manifest does not name it. `nav issue list` on a machine with five plugins
+ * installed imports none of them, and `nav --help` imports none of them
+ * either, because the help was built from manifests. An `import()` of one
+ * plugin costs more than the whole of `nav issue list`'s budget, so this is
+ * not a micro-optimisation: it is the difference between plugins being
+ * affordable and not.
+ *
+ * What triggers a load is therefore always a *declaration* — a command the
+ * plugin declared being run, a contribution it declared being reached, a
+ * query term it declared being typed.
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import * as core from "@navbook/core";
+import { ExtensionConflictError, mergeExtensions, NO_EXTENSIONS, } from "@navbook/core";
+/** One import per part per process, however many commands ask for it. */
+const loaded = new Map();
+/**
+ * The file a plugin's `exports` maps a subpath to.
+ *
+ * Read from the package's own `package.json` rather than guessed, because the
+ * whole point of `exports` is that a package decides its own layout — and a
+ * published plugin's `./cli` points into `dist/` while the same plugin in a
+ * checkout points into `src/`.
+ *
+ * Null only when the plugin has no such part, which is a plugin's choice. A
+ * package that is gone, or an entry it declares that is not on disk, throws:
+ * the index still lists the plugin, and "declares a command but does not
+ * implement it" would send its author looking for a bug that is not theirs.
+ */
+export function entryPath(plugin, part) {
+    let pkg;
+    try {
+        pkg = JSON.parse(readFileSync(join(plugin.dir, "package.json"), "utf8"));
+    }
+    catch (error) {
+        throw new Error(existsSync(plugin.dir)
+            ? `its package.json cannot be read: ${message(error)}`
+            : `its package is not at ${plugin.dir}; reinstall it with 'nav plugin install ${plugin.name}'`);
+    }
+    const entry = pkg.exports?.[`./${part}`];
+    const file = typeof entry === "string" ? entry : resolveConditions(entry);
+    if (file === null)
+        return null;
+    const path = join(plugin.dir, file);
+    if (!existsSync(path))
+        throw new Error(`its './${part}' entry ${path} does not exist`);
+    return path;
+}
+/** Pick a file out of a conditional exports object, preferring what Node runs. */
+function resolveConditions(entry) {
+    if (typeof entry !== "object" || entry === null)
+        return null;
+    const conditions = entry;
+    for (const key of ["node", "import", "default", "require"]) {
+        const value = conditions[key];
+        if (typeof value === "string")
+            return value;
+        if (typeof value === "object" && value !== null) {
+            const nested = resolveConditions(value);
+            if (nested !== null)
+                return nested;
+        }
+    }
+    return null;
+}
+/** Import one part of one plugin, memoised. */
+export async function importEntry(plugin, part) {
+    const key = `${plugin.name}#${part}`;
+    const existing = loaded.get(key);
+    if (existing !== undefined)
+        return (await existing);
+    // Outside the memo, so a throw here is reported by each caller that asks.
+    const path = entryPath(plugin, part);
+    if (path === null) {
+        loaded.set(key, Promise.resolve(null));
+        return null;
+    }
+    const pending = import(__rewriteRelativeImportExtension(pathToFileURL(path).href));
+    loaded.set(key, pending);
+    return (await pending);
+}
+/** Clear the memo. For tests that load the same plugin under two settings. */
+export function forgetLoaded() {
+    loaded.clear();
+}
+/**
+ * Activate every plugin's `./core` entry and merge what they registered.
+ *
+ * A plugin that throws while activating, or that collides with one already
+ * merged, is dropped and reported — the run continues with the plugins that
+ * worked. Dropping one plugin loses that plugin's data; refusing to start
+ * loses the user's whole tracker, and the second is not a better answer to a
+ * bad `package.json` somebody published.
+ */
+export async function loadCoreExtensions(plugins) {
+    if (plugins.length === 0)
+        return { ext: NO_EXTENSIONS, problems: [] };
+    const parts = [];
+    const problems = [];
+    for (const plugin of plugins) {
+        const entry = await importEntry(plugin, "core").catch((error) => {
+            problems.push(`nav: plugin ${plugin.name} could not be loaded: ${message(error)}`);
+            return null;
+        });
+        if (entry === null)
+            continue;
+        if (typeof entry.activate !== "function") {
+            problems.push(`nav: plugin ${plugin.name} exports no activate() from './core'`);
+            continue;
+        }
+        const registered = [];
+        try {
+            await entry.activate({
+                core,
+                manifest: plugin.manifest,
+                settings: plugin.settings,
+                register: (received) => void registered.push(received),
+            });
+        }
+        catch (error) {
+            problems.push(`nav: plugin ${plugin.name} failed to activate: ${message(error)}`);
+            continue;
+        }
+        parts.push({ name: plugin.name, registered });
+    }
+    // Merge one plugin at a time, so a collision names the plugin that lost and
+    // the ones before it survive. Merging everything at once would only be able
+    // to say that two plugins collided, which is true but not actionable.
+    const kept = [];
+    for (const part of parts) {
+        try {
+            mergeExtensions([...kept, ...part.registered]);
+            kept.push(...part.registered);
+        }
+        catch (error) {
+            // Any fault, not only a collision: a registration of the wrong shape
+            // (`treeLocations` as an object, say) throws a TypeError from deep in
+            // the merge, and rethrowing it would take down every command over one
+            // plugin — the outcome this function exists to prevent.
+            const why = error instanceof ExtensionConflictError
+                ? error.message
+                : `what it registered could not be used: ${message(error)}`;
+            problems.push(`nav: plugin ${part.name} skipped: ${why}`);
+        }
+    }
+    return { ext: kept.length === 0 ? NO_EXTENSIONS : mergeExtensions(kept), problems };
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=loader.js.map

package/dist/plugins/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/plugins/loader.ts"],"names":[],"mappings":"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"}

package/dist/plugins/resolve.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Which plugins this invocation has, and which it was told about but lacks.
+ *
+ * Two sources, in order: `NAVBOOK_PLUGIN_PATH`, for a plugin being written and
+ * not installed anywhere, and the store, for everything else. A path entry
+ * shadows an installed copy of the same package — otherwise developing a
+ * plugin you have also installed would silently test the installed one.
+ *
+ * The declaration (spec 02 §2.12) is read here, and read only to *report*:
+ * nothing in this file fetches anything. A plugin the repository names and the
+ * machine does not have is one line on stderr and a run that carries on, which
+ * is the rule that makes cloning a repository safe.
+ */
+import { type PluginDeclarationReading, type WsCtx } from "@navbook/core";
+import { type IndexedPlugin } from "./store.ts";
+export declare const PLUGIN_PATH_ENV = "NAVBOOK_PLUGIN_PATH";
+/** An installed plugin, with the settings the repository declares for it. */
+export interface LoadedPlugin extends IndexedPlugin {
+    /** What `navbook.json` declares under this name; empty when undeclared. */
+    settings: Record<string, unknown>;
+    /** True when the repository's marker names it (spec 02 §2.12). */
+    declared: boolean;
+    /** True when it came from `NAVBOOK_PLUGIN_PATH` rather than the store. */
+    fromPath: boolean;
+}
+export interface ResolvedPlugins {
+    /** Usable plugins, in the order their contributions should be applied. */
+    active: LoadedPlugin[];
+    /** Declared by the repository, absent from this machine. */
+    missing: string[];
+    /** Found but not used, each with the reason, for one line on stderr. */
+    skipped: {
+        name: string;
+        reason: string;
+    }[];
+    /** What the marker declared, for a caller that wants the settings or faults. */
+    declaration: PluginDeclarationReading;
+}
+/**
+ * Resolve the plugins for this invocation.
+ *
+ * Costs one `plugins.json` read in the common case, and one `package.json`
+ * read per `NAVBOOK_PLUGIN_PATH` entry, which is a development path. The
+ * marker is read too, but the workspace reads it anyway for the review policy.
+ */
+export declare function resolvePlugins(ws: WsCtx, env: NodeJS.ProcessEnv): ResolvedPlugins;
+/** The line printed for a plugin the repository declares and the machine lacks. */
+export declare function missingLine(name: string, navDir: string): string;
+/** The line printed for a plugin that was found but cannot be used. */
+export declare function skippedLine(name: string, reason: string): string;

package/dist/plugins/resolve.js

@@ -0,0 +1,134 @@
+/**
+ * Which plugins this invocation has, and which it was told about but lacks.
+ *
+ * Two sources, in order: `NAVBOOK_PLUGIN_PATH`, for a plugin being written and
+ * not installed anywhere, and the store, for everything else. A path entry
+ * shadows an installed copy of the same package — otherwise developing a
+ * plugin you have also installed would silently test the installed one.
+ *
+ * The declaration (spec 02 §2.12) is read here, and read only to *report*:
+ * nothing in this file fetches anything. A plugin the repository names and the
+ * machine does not have is one line on stderr and a run that carries on, which
+ * is the rule that makes cloning a repository safe.
+ */
+import { existsSync } from "node:fs";
+import { isAbsolute, resolve as resolvePath } from "node:path";
+import { PLUGIN_API_VERSION, readPluginDeclaration, satisfiesRange, } from "@navbook/core";
+import { readIndex, readPluginAt } from "./store.js";
+export const PLUGIN_PATH_ENV = "NAVBOOK_PLUGIN_PATH";
+const NOTHING = {
+    active: [],
+    missing: [],
+    skipped: [],
+    declaration: { plugins: new Map(), declared: false, problems: [] },
+};
+/**
+ * Resolve the plugins for this invocation.
+ *
+ * Costs one `plugins.json` read in the common case, and one `package.json`
+ * read per `NAVBOOK_PLUGIN_PATH` entry, which is a development path. The
+ * marker is read too, but the workspace reads it anyway for the review policy.
+ */
+export function resolvePlugins(ws, env) {
+    const fromPath = pathPlugins(env);
+    const index = readIndex(env);
+    if (fromPath.active.length === 0 && fromPath.skipped.length === 0 && index === null) {
+        // Nothing installed and nothing on the path: the overwhelmingly common
+        // case, and it must not cost a marker read of its own.
+        return ws.hasNavbook ? undeclaredOnly(ws) : NOTHING;
+    }
+    const declaration = ws.hasNavbook
+        ? readPluginDeclaration(ws)
+        : { plugins: new Map(), declared: false, problems: [] };
+    const active = [];
+    const skipped = [...fromPath.skipped];
+    const seen = new Set();
+    const admit = (plugin, viaPath) => {
+        if (seen.has(plugin.name))
+            return;
+        const problem = incompatible(plugin);
+        if (problem !== null) {
+            skipped.push({ name: plugin.name, reason: problem });
+            seen.add(plugin.name);
+            return;
+        }
+        seen.add(plugin.name);
+        active.push({
+            ...plugin,
+            settings: declaration.plugins.get(plugin.name) ?? {},
+            declared: declaration.plugins.has(plugin.name),
+            fromPath: viaPath,
+        });
+    };
+    // Path first, so a plugin being developed shadows an installed copy.
+    for (const plugin of fromPath.active)
+        admit(plugin, true);
+    for (const plugin of Object.values(index?.plugins ?? {}))
+        admit(plugin, false);
+    const missing = [...declaration.plugins.keys()].filter((name) => !seen.has(name));
+    return { active, missing, skipped, declaration };
+}
+/** The store is empty, so everything declared is missing. */
+function undeclaredOnly(ws) {
+    const declaration = readPluginDeclaration(ws);
+    return {
+        active: [],
+        missing: [...declaration.plugins.keys()],
+        skipped: [],
+        declaration,
+    };
+}
+/** Read every directory `NAVBOOK_PLUGIN_PATH` names. */
+function pathPlugins(env) {
+    const raw = env[PLUGIN_PATH_ENV];
+    if (raw === undefined || raw.trim() === "")
+        return { active: [], skipped: [] };
+    const active = [];
+    const skipped = [];
+    for (const entry of raw.split(":")) {
+        const dir = entry.trim();
+        if (dir === "")
+            continue;
+        const path = isAbsolute(dir) ? dir : resolvePath(dir);
+        if (!existsSync(path)) {
+            skipped.push({
+                name: path,
+                reason: `${PLUGIN_PATH_ENV} names a directory that is not there`,
+            });
+            continue;
+        }
+        const read = readPluginAt(path);
+        if ("error" in read) {
+            skipped.push({ name: path, reason: read.error });
+            continue;
+        }
+        active.push(read);
+    }
+    return { active, skipped };
+}
+/**
+ * Why a plugin cannot be used, or null when it can.
+ *
+ * A version mismatch is reported rather than risked. The alternative is
+ * loading it anyway and discovering the mismatch as a missing function in the
+ * middle of an operation, by which point the user is reading a stack trace
+ * about a tree that is perfectly sound.
+ */
+function incompatible(plugin) {
+    if (plugin.engines === null) {
+        return `it declares no 'engines.navbook', so there is nothing to check it against`;
+    }
+    if (!satisfiesRange(plugin.engines, PLUGIN_API_VERSION)) {
+        return `it needs a Navbook plugin API of ${plugin.engines}; this is ${PLUGIN_API_VERSION}`;
+    }
+    return null;
+}
+/** The line printed for a plugin the repository declares and the machine lacks. */
+export function missingLine(name, navDir) {
+    return `nav: ${name} is declared in ${navDir}/navbook.json but is not installed; run 'nav plugin install'`;
+}
+/** The line printed for a plugin that was found but cannot be used. */
+export function skippedLine(name, reason) {
+    return `nav: plugin ${name} skipped: ${reason}`;
+}
+//# sourceMappingURL=resolve.js.map

package/dist/plugins/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/plugins/resolve.ts"],"names":[],"mappings":"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"}

package/dist/plugins/runtime.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The CLI's plugin runtime: what is installed, what it contributes, and when
+ * its code is actually loaded.
+ *
+ * One of these is built per invocation and threaded through the program. It
+ * holds the resolution (cheap, always done) and memoises the loading
+ * (expensive, done only when a declaration says it is needed).
+ *
+ * The division of labour with `program.ts` is worth stating: the program asks
+ * this for *declarations* while building the command tree, and for
+ * *implementations* inside an action. Nothing in the build phase can trigger a
+ * load, which is how spec 04 §4.3's rule is kept structurally rather than by
+ * remembering to.
+ */
+import type { CoreExtensions, EntityKind, QueryKeySpec } from "@navbook/core";
+import type { Ctx } from "../context.ts";
+import { type PluginCommands } from "./commands.ts";
+import type { VerbHandlers } from "./host.ts";
+import type { LoadedPlugin, ResolvedPlugins } from "./resolve.ts";
+export declare class PluginRuntime {
+    #private;
+    readonly resolved: ResolvedPlugins;
+    readonly commands: PluginCommands;
+    /** Everything worth saying on stderr once, collected while resolving. */
+    readonly notices: string[];
+    constructor(resolved: ResolvedPlugins, builtinNouns: readonly string[]);
+    /** True when no plugin is installed, which is the common case. */
+    get empty(): boolean;
+    /**
+     * Whether this command line needs the format extensions loaded.
+     *
+     * Decided from the manifests and the words typed, before anything parses,
+     * because loading them means importing plugin code — and spec 04 §4.3 says
+     * no plugin code is loaded for a command whose declaration does not name it.
+     * `nav issue list` with five plugins installed answers false here and
+     * imports nothing.
+     *
+     * The four cases that answer true:
+     *
+     * - a plugin noun is the first word, and its declaration asks for core;
+     * - a plugin contributes to this exact `noun verb`;
+     * - a term on the line names a query key a plugin declared;
+     * - the command is `doctor`, which runs every registered check.
+     */
+    needsCoreFor(argv: readonly string[]): boolean;
+    /** Plugins whose commands are still usable after collision checking. */
+    get usable(): LoadedPlugin[];
+    /**
+     * The query terms usable plugins declared, for one noun or for either.
+     *
+     * From the manifests, so help and completion can offer them without loading
+     * a line of plugin code (spec 04 §4.3).
+     */
+    queryKeys(kind?: EntityKind): QueryKeySpec[];
+    /**
+     * The registered format extensions, loading the `./core` entries once.
+     *
+     * Everything that reads or validates a tree needs these; nothing else does.
+     * The caller decides whether this invocation is one of those, which is where
+     * the startup budget is actually spent or saved.
+     */
+    coreExtensions(ctx: Ctx): Promise<CoreExtensions>;
+    /** What a plugin registered for a verb, loading its `./cli` entry if needed. */
+    handlersFor(ctx: Ctx, verb: string): Promise<VerbHandlers[]>;
+    /** Run a plugin command, loading its `./cli` entry. */
+    run(ctx: Ctx, plugin: LoadedPlugin, path: string, args: string[], opts: Record<string, unknown>): Promise<void>;
+    /** Completion candidates a plugin offers for a declared completer. */
+    completions(ctx: Ctx, plugin: LoadedPlugin, id: string, words: string[]): Promise<string[]>;
+}