@navbook/cli 0.4.0 → 0.5.0

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