@navbook/cli 0.3.0 → 0.5.0

package/dist/plugins/runtime.js

@@ -0,0 +1,256 @@
+/**
+ * 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 { commitReport } from "@navbook/core";
+import { composeFile } from "../commands/compose.js";
+import { openInEditor } from "../editor.js";
+import { fail, failFormat } from "../errors.js";
+import { askYesNo, confirmAndPerform } from "../prompt.js";
+import { pad, renderTable, terminalWidth } from "../render/table.js";
+import { collectCommands } from "./commands.js";
+import { importEntry, loadCoreExtensions } from "./loader.js";
+export class PluginRuntime {
+    resolved;
+    commands;
+    /** Everything worth saying on stderr once, collected while resolving. */
+    notices;
+    #ext = null;
+    #activated = new Map();
+    constructor(resolved, builtinNouns) {
+        this.resolved = resolved;
+        this.commands = collectCommands(resolved.active, builtinNouns);
+        this.notices = [...this.commands.problems];
+    }
+    /** True when no plugin is installed, which is the common case. */
+    get empty() {
+        return this.resolved.active.length === 0;
+    }
+    /**
+     * 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) {
+        if (this.empty)
+            return false;
+        // `--help` runs no command: Commander prints what the manifests already
+        // built and exits, so there is nothing for an extension to be needed by.
+        if (argv.some((word) => word === "--help" || word === "-h"))
+            return false;
+        const words = argv.filter((word) => !word.startsWith("-"));
+        // `__complete` is a stand-in for whatever is being typed, so the decision
+        // is made about *that*: completing `nav issue list` must load whatever
+        // completing `nav issue list` would.
+        //
+        // With one exception. A plugin noun on its own — `nav probe <TAB>` — is
+        // answered with its verb names, which come from the manifest, so it costs
+        // nothing. Only once a verb is on the line can completion reach an
+        // argument completer or a query term, and only then is the tree needed.
+        const completing = words[0] === "__complete";
+        if (completing) {
+            words.shift();
+            if (words.length <= 1)
+                return false;
+        }
+        const [noun, verb] = words;
+        if (noun === undefined)
+            return false;
+        if (noun === "doctor")
+            return true;
+        const declared = this.commands.nouns.get(noun);
+        if (declared !== undefined) {
+            // A noun's own commands default to needing core: nearly all of them read
+            // the tree, and a plugin that does not can say so.
+            const leaf = (declared.spec.commands ?? []).find((child) => child.name === verb);
+            return (leaf ?? declared.spec).needsCore !== false;
+        }
+        if (verb !== undefined && this.commands.contributions.has(`${noun} ${verb}`))
+            return true;
+        const keys = new Set(this.queryKeys().map((key) => `${key.key}:`));
+        return argv.some((word) => {
+            const colon = word.indexOf(":");
+            return colon > 0 && keys.has(word.slice(0, colon + 1));
+        });
+    }
+    /** Plugins whose commands are still usable after collision checking. */
+    get usable() {
+        return this.resolved.active.filter((plugin) => !this.commands.skipped.has(plugin.name));
+    }
+    /**
+     * 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) {
+        return this.usable.flatMap((plugin) => (plugin.manifest.core?.queryKeys ?? []).filter((key) => kind === undefined || key.kinds.includes(kind)));
+    }
+    /**
+     * 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.
+     */
+    async coreExtensions(ctx) {
+        if (this.#ext !== null)
+            return this.#ext;
+        const { ext, problems } = await loadCoreExtensions(this.usable);
+        for (const line of problems)
+            ctx.stderr.write(`${line}\n`);
+        this.#ext = ext;
+        return ext;
+    }
+    /** What a plugin registered for a verb, loading its `./cli` entry if needed. */
+    async handlersFor(ctx, verb) {
+        const declared = this.commands.contributions.get(verb) ?? [];
+        const out = [];
+        for (const { plugin } of declared) {
+            const activated = await this.#activate(ctx, plugin);
+            const handlers = activated?.handlers.get(verb);
+            if (handlers !== undefined)
+                out.push(handlers);
+        }
+        return out;
+    }
+    /** Run a plugin command, loading its `./cli` entry. */
+    async run(ctx, plugin, path, args, opts) {
+        const activated = await this.#activate(ctx, plugin);
+        // Why it did not load is already on stderr; saying it does not implement
+        // the command would blame the plugin for what may be a missing package.
+        if (activated === null)
+            fail(`cannot run '${path}': plugin ${plugin.name} did not load`);
+        const run = activated.commands.get(path);
+        if (run === undefined) {
+            fail(`plugin ${plugin.name} declares '${path}' but does not implement it`);
+        }
+        await run(args, opts);
+    }
+    /** Completion candidates a plugin offers for a declared completer. */
+    async completions(ctx, plugin, id, words) {
+        const activated = await this.#activate(ctx, plugin);
+        return activated?.completers.get(id)?.(words) ?? [];
+    }
+    /** Activate a plugin's CLI entry once per process. */
+    async #activate(ctx, plugin) {
+        const existing = this.#activated.get(plugin.name);
+        if (existing !== undefined)
+            return existing;
+        const entry = await importEntry(plugin, "cli").catch((error) => {
+            ctx.stderr.write(`nav: plugin ${plugin.name} could not be loaded: ${message(error)}\n`);
+            return null;
+        });
+        if (entry === null) {
+            ctx.stderr.write(`nav: plugin ${plugin.name} has no './cli' entry\n`);
+            return null;
+        }
+        if (typeof entry.activate !== "function") {
+            ctx.stderr.write(`nav: plugin ${plugin.name} exports no activate() from './cli'\n`);
+            return null;
+        }
+        const activated = {
+            commands: new Map(),
+            handlers: new Map(),
+            completers: new Map(),
+        };
+        const declaredPaths = declaredCommandPaths(plugin);
+        const declaredVerbs = new Set((plugin.manifest.cli?.contributions ?? []).map((contribution) => contribution.on));
+        const host = {
+            core: await coreModule(),
+            manifest: plugin.manifest,
+            settings: plugin.settings,
+            // The core registrations happen through `coreExtensions`; a CLI entry
+            // calling `register` is registering for nothing, so it is refused rather
+            // than silently ignored.
+            register: () => {
+                fail(`plugin ${plugin.name}: register() belongs in './core', not './cli'`);
+            },
+            ctx,
+            command: (path, run) => {
+                if (!declaredPaths.has(path)) {
+                    ctx.stderr.write(`nav: plugin ${plugin.name} implements '${path}', which its manifest does not declare\n`);
+                    return;
+                }
+                activated.commands.set(path, run);
+            },
+            contribute: (on, handlers) => {
+                if (!declaredVerbs.has(on)) {
+                    ctx.stderr.write(`nav: plugin ${plugin.name} contributes to '${on}', which its manifest does not declare\n`);
+                    return;
+                }
+                activated.handlers.set(on, handlers);
+            },
+            completer: (id, complete) => void activated.completers.set(id, complete),
+            ui: makeUi(ctx),
+        };
+        try {
+            await entry.activate(host);
+        }
+        catch (error) {
+            ctx.stderr.write(`nav: plugin ${plugin.name} failed to activate: ${message(error)}\n`);
+            return null;
+        }
+        this.#activated.set(plugin.name, activated);
+        return activated;
+    }
+}
+/** Every command path a plugin's manifest declares, `noun verb` style. */
+function declaredCommandPaths(plugin) {
+    const paths = new Set();
+    const walk = (specs, prefix) => {
+        for (const spec of specs) {
+            const path = prefix === "" ? spec.name : `${prefix} ${spec.name}`;
+            const children = spec.commands;
+            if (children?.length)
+                walk(children, path);
+            else
+                paths.add(path);
+        }
+    };
+    walk(plugin.manifest.cli?.commands ?? [], "");
+    return paths;
+}
+/** The running core, imported once and shared with every plugin. */
+async function coreModule() {
+    return await import("@navbook/core");
+}
+function makeUi(ctx) {
+    return {
+        fail: (message, details) => fail(message, details ?? []),
+        failFormat: (message, details) => failFormat(message, details ?? []),
+        askYesNo: (question) => askYesNo(ctx, question),
+        confirmAndPerform: (opts) => confirmAndPerform(ctx, opts),
+        composeFile: (opts) => composeFile(ctx, opts),
+        editFile: (path) => openInEditor(ctx, path),
+        renderTable: (columns, rows) => renderTable([...columns], rows, { colors: ctx.colors, width: terminalWidth(ctx.stdout) }),
+        pad,
+        commitReport,
+        collect: (value, previous = []) => [...previous, value],
+    };
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=runtime.js.map

package/dist/plugins/runtime.js.map

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

package/dist/plugins/store.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The per-user plugin store — spec 04 §4.3.
+ *
+ * Plugins live in a directory `nav` owns rather than beside `nav` itself,
+ * because where `nav` itself lives is not knowable: it may have arrived by
+ * `npm -g`, by pnpm, through a version manager, or not be installed at all
+ * under `npx`. A directory of our own works the same way in every one of those.
+ *
+ * The store is an ordinary npm project — a `package.json` and a `node_modules`
+ * — so resolution, transitive dependencies and updates are npm's problem and
+ * not ours. What we add on top is `plugins.json`: an index of what is
+ * installed, with each plugin's manifest copied into it. That file is why
+ * startup costs one read. Scanning `node_modules` to find out what is there
+ * would cost a directory walk and a `package.json` parse per plugin on every
+ * single `nav` invocation, which is the cost spec 05 §5.2 says we cannot pay —
+ * and is exactly the mistake Prettier removed its plugin search for.
+ */
+import { type PluginManifest } from "@navbook/core";
+/** Where the store lives, honouring `$XDG_DATA_HOME` (spec 04 §4.3). */
+export declare function storeDir(env: NodeJS.ProcessEnv): string;
+/** One installed plugin, as the index records it. */
+export interface IndexedPlugin {
+    name: string;
+    version: string;
+    /** Absolute path to the package directory inside the store. */
+    dir: string;
+    /** The `engines.navbook` range, or null when the plugin names none. */
+    engines: string | null;
+    /**
+     * The manifest, copied at install time.
+     *
+     * A copy rather than a reference to the package's own `package.json`,
+     * because reading that file is precisely the work the index exists to avoid.
+     * It goes stale only when the package is replaced, and replacing it goes
+     * through `nav plugin`, which rewrites the index.
+     */
+    manifest: PluginManifest;
+}
+export interface PluginIndex {
+    version: 1;
+    plugins: Record<string, IndexedPlugin>;
+}
+export declare function indexPath(env: NodeJS.ProcessEnv): string;
+/**
+ * Read the index, or null when there is none.
+ *
+ * Null for every fault — no store, no file, unreadable, not JSON, a version
+ * from some future `nav`. A store this `nav` cannot read is a store with no
+ * plugins in it as far as this run is concerned, and refusing to list issues
+ * because of a file in the user's data directory would be absurd. The repair
+ * is `nav plugin install`, which rewrites it.
+ */
+export declare function readIndex(env: NodeJS.ProcessEnv): PluginIndex | null;
+export declare function writeIndex(env: NodeJS.ProcessEnv, index: PluginIndex): void;
+/** Create the store's own `package.json` if it is not there yet. */
+export declare function ensureStore(env: NodeJS.ProcessEnv): string;
+export interface NpmResult {
+    ok: boolean;
+    /** Everything npm said, for a failure worth showing in full. */
+    output: string;
+}
+/**
+ * The npm command a given install would run, as a string to print.
+ *
+ * Printed before it runs (spec 04 §4.3), so that what the user agrees to is
+ * the command rather than a summary of it.
+ */
+export declare function installCommand(specs: readonly string[]): string;
+/** Run npm in the store. Its output is captured rather than streamed. */
+export declare function npmInstall(env: NodeJS.ProcessEnv, specs: readonly string[]): NpmResult;
+export declare function npmRemove(env: NodeJS.ProcessEnv, names: readonly string[]): NpmResult;
+/**
+ * Read an installed package directory as a plugin.
+ *
+ * Used at install time to check what npm actually fetched, and by
+ * `NAVBOOK_PLUGIN_PATH` to read a plugin nobody installed. Faults come back as
+ * a message so the caller can name the directory alongside them.
+ */
+export declare function readPluginAt(dir: string): IndexedPlugin | {
+    error: string;
+};
+/** Where npm put a package inside the store. */
+export declare function packageDir(env: NodeJS.ProcessEnv, name: string): string;
+/**
+ * The packages the store depends on, as npm recorded them: each real package
+ * name, and the specifier npm saved for it.
+ *
+ * What was *asked* for and what was *installed* are not the same string: a
+ * tarball path, a git URL and a short name all resolve to a package whose real
+ * name is inside it, and looking in `node_modules/<what-was-typed>` finds
+ * nothing. npm writes the real name into the store's own `package.json`, so
+ * reading it back — before an install and again after — is how an install
+ * learns what it actually got. The specifier is kept too, because a new
+ * version of a plugin already installed changes it without adding a name.
+ */
+export declare function storeDependencies(env: NodeJS.ProcessEnv): Record<string, string>;

package/dist/plugins/store.js

@@ -0,0 +1,186 @@
+/**
+ * The per-user plugin store — spec 04 §4.3.
+ *
+ * Plugins live in a directory `nav` owns rather than beside `nav` itself,
+ * because where `nav` itself lives is not knowable: it may have arrived by
+ * `npm -g`, by pnpm, through a version manager, or not be installed at all
+ * under `npx`. A directory of our own works the same way in every one of those.
+ *
+ * The store is an ordinary npm project — a `package.json` and a `node_modules`
+ * — so resolution, transitive dependencies and updates are npm's problem and
+ * not ours. What we add on top is `plugins.json`: an index of what is
+ * installed, with each plugin's manifest copied into it. That file is why
+ * startup costs one read. Scanning `node_modules` to find out what is there
+ * would cost a directory walk and a `package.json` parse per plugin on every
+ * single `nav` invocation, which is the cost spec 05 §5.2 says we cannot pay —
+ * and is exactly the mistake Prettier removed its plugin search for.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parsePluginPackage } from "@navbook/core";
+/** Where the store lives, honouring `$XDG_DATA_HOME` (spec 04 §4.3). */
+export function storeDir(env) {
+    const xdg = env.XDG_DATA_HOME;
+    if (xdg !== undefined && xdg.trim() !== "")
+        return join(xdg, "navbook", "plugins");
+    const home = env.HOME ?? env.USERPROFILE ?? "";
+    return join(home, ".local", "share", "navbook", "plugins");
+}
+const INDEX_FILE = "plugins.json";
+const STORE_PACKAGE = {
+    name: "navbook-plugins",
+    private: true,
+    description: "Plugins installed for the nav CLI. Managed by `nav plugin`.",
+    version: "1.0.0",
+};
+export function indexPath(env) {
+    return join(storeDir(env), INDEX_FILE);
+}
+/**
+ * Read the index, or null when there is none.
+ *
+ * Null for every fault — no store, no file, unreadable, not JSON, a version
+ * from some future `nav`. A store this `nav` cannot read is a store with no
+ * plugins in it as far as this run is concerned, and refusing to list issues
+ * because of a file in the user's data directory would be absurd. The repair
+ * is `nav plugin install`, which rewrites it.
+ */
+export function readIndex(env) {
+    const path = indexPath(env);
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (parsed.version !== 1 || typeof parsed.plugins !== "object" || parsed.plugins === null) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeIndex(env, index) {
+    const dir = storeDir(env);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, INDEX_FILE), `${JSON.stringify(index, null, 2)}\n`);
+}
+/** Create the store's own `package.json` if it is not there yet. */
+export function ensureStore(env) {
+    const dir = storeDir(env);
+    mkdirSync(dir, { recursive: true });
+    const manifest = join(dir, "package.json");
+    if (!existsSync(manifest)) {
+        writeFileSync(manifest, `${JSON.stringify(STORE_PACKAGE, null, 2)}\n`);
+    }
+    return dir;
+}
+/**
+ * The npm command a given install would run, as a string to print.
+ *
+ * Printed before it runs (spec 04 §4.3), so that what the user agrees to is
+ * the command rather than a summary of it.
+ */
+export function installCommand(specs) {
+    return `npm ${installArgs(specs).join(" ")}`;
+}
+function installArgs(specs) {
+    return [
+        "install",
+        // A plugin is code somebody chose to install, but its *dependencies* are
+        // not, and a postinstall script is the classic way a package does
+        // something nobody asked for. npm runs none of them here.
+        "--ignore-scripts",
+        // The pair that keeps a second `@navbook/core` out of the store. A plugin
+        // declares core as a peer for its types; installing peers would give it a
+        // copy of its own, and then `instanceof WorkspaceError` would be false
+        // across the boundary and the YAML parser would be loaded twice.
+        // `--omit=peer` alone only leaves peers off the disk: npm still resolves
+        // them, from the registry, and refuses the install when a web half's
+        // optional framework peers do not reconcile. `--legacy-peer-deps` stops it
+        // resolving them at all — the host provides every one.
+        "--omit=peer",
+        "--legacy-peer-deps",
+        "--no-audit",
+        "--no-fund",
+        "--save-exact",
+        ...specs,
+    ];
+}
+/** Run npm in the store. Its output is captured rather than streamed. */
+export function npmInstall(env, specs) {
+    return runNpm(env, installArgs(specs));
+}
+export function npmRemove(env, names) {
+    return runNpm(env, ["uninstall", "--no-audit", "--no-fund", ...names]);
+}
+function runNpm(env, args) {
+    const dir = ensureStore(env);
+    const result = spawnSync("npm", [...args], {
+        cwd: dir,
+        encoding: "utf8",
+        // npm is a shell script on Windows; everywhere Navbook supports it is not.
+        shell: false,
+        env: { ...env },
+    });
+    if (result.error)
+        return { ok: false, output: result.error.message };
+    return {
+        ok: result.status === 0,
+        output: `${result.stdout ?? ""}${result.stderr ?? ""}`.trim(),
+    };
+}
+/**
+ * Read an installed package directory as a plugin.
+ *
+ * Used at install time to check what npm actually fetched, and by
+ * `NAVBOOK_PLUGIN_PATH` to read a plugin nobody installed. Faults come back as
+ * a message so the caller can name the directory alongside them.
+ */
+export function readPluginAt(dir) {
+    const manifestPath = join(dir, "package.json");
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(manifestPath, "utf8"));
+    }
+    catch (error) {
+        return { error: `${manifestPath}: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    const read = parsePluginPackage(raw);
+    if (!read.ok)
+        return { error: read.error };
+    return {
+        name: read.plugin.name,
+        version: read.plugin.version,
+        dir,
+        engines: read.plugin.engines,
+        manifest: read.plugin.manifest,
+    };
+}
+/** Where npm put a package inside the store. */
+export function packageDir(env, name) {
+    return join(storeDir(env), "node_modules", ...name.split("/"));
+}
+/**
+ * The packages the store depends on, as npm recorded them: each real package
+ * name, and the specifier npm saved for it.
+ *
+ * What was *asked* for and what was *installed* are not the same string: a
+ * tarball path, a git URL and a short name all resolve to a package whose real
+ * name is inside it, and looking in `node_modules/<what-was-typed>` finds
+ * nothing. npm writes the real name into the store's own `package.json`, so
+ * reading it back — before an install and again after — is how an install
+ * learns what it actually got. The specifier is kept too, because a new
+ * version of a plugin already installed changes it without adding a name.
+ */
+export function storeDependencies(env) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(storeDir(env), "package.json"), "utf8"));
+        return { ...(pkg.dependencies ?? {}) };
+    }
+    catch {
+        return {};
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/plugins/store.js.map

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

package/dist/program.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Command tree — spec 04 §4.3: noun-verb, with one verb vocabulary shared by
+ * both entity kinds, plus root-level utilities.
+ */
+import { type EntityKind } from "@navbook/core";
+import { Command, Option } from "commander";
+import { type CloseOptions, type ExtraColumn } from "./commands/entity.ts";
+import type { Ctx, GetCtx } from "./context.ts";
+import type { PluginRuntime } from "./plugins/runtime.ts";
+export declare const VERSION: string;
+/**
+ * A plugin's declared `help` line as rows of the table above.
+ *
+ * The manifest writes it as the built-in rows read, syntax then a gap then
+ * the hint; it is re-aligned here so a plugin need not know the column this
+ * help happens to use. A line with no gap is all syntax, and a syntax too wide
+ * for its column puts the hint on the next line rather than against it.
+ */
+export declare function pluginHelpRow(help: string): string[];
+/**
+ * The nouns and utilities this CLI defines, which a plugin may not take.
+ *
+ * Kept as data because two things read it: the collision check that refuses a
+ * plugin claiming one of these (spec 04 §4.3), and completion, which offers
+ * them alongside whatever plugins added.
+ */
+export declare const BUILTIN_NOUNS: readonly ["issue", "pr", "plugin", "init", "id", "doctor", "install", "uninstall"];
+export declare function buildProgram(getCtx: GetCtx, plugins?: PluginRuntime): Command;
+export interface SharedVerbOptions {
+    extraColumns: ExtraColumn[];
+    /** The plugin runtime, when this invocation has one. */
+    plugins?: PluginRuntime;
+    /** The noun these verbs hang off, for looking a contribution up by name. */
+    verbPrefix?: string;
+    /** Extra options the noun's `list` accepts, e.g. `--all-refs` for PRs. */
+    configureList?: (command: Command) => void;
+    /** Extra options the noun's `show` accepts, e.g. `--depth` for issues. */
+    configureShow?: (command: Command) => void;
+    /** Extra options the noun's `delete` accepts, e.g. `--recursive` for issues. */
+    configureDelete?: (command: Command) => void;
+    /** Listing implementation, when the noun needs more than the shared one. */
+    runList?: (ctx: Ctx, terms: string[], options: Record<string, unknown>) => void;
+    /** Close implementation, when the noun needs more than the shared one. */
+    runClose?: (ctx: Ctx, id: string, options: CloseOptions) => void;
+}
+/** Register the verbs both nouns share, so their behavior can never drift. */
+export declare function addSharedVerbs(parent: Command, kind: EntityKind, getCtx: () => Ctx, shared: SharedVerbOptions): void;
+export declare function collect(value: string, previous: string[]): string[];
+export { Option };