@navbook/cli 0.4.0 → 0.5.0

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[]>;
+}

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>;