@navbook/cli 0.3.0 → 0.5.0

package/dist/program.js

@@ -4,15 +4,20 @@
  */
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
+import { DEADLINE_TERMS, entityJson, MERGE_METHODS, QUERY_STATUSES, queryTermsFor, REVIEW_DECISIONS, readMarkerVersion, } from "@navbook/core";
 import { Command, Option } from "commander";
+import { finiteNumber, wholeNumber } from "./args.js";
 import { cmdComplete } from "./commands/complete.js";
 import { cmdDoctor } from "./commands/doctor.js";
 import { cmdClose, cmdComment, cmdDelete, cmdEdit, cmdList, cmdReopen, cmdShow, } from "./commands/entity.js";
-import { cmdFeatureEdit, cmdFeatureList, cmdFeatureOpen, cmdFeatureShow, cmdSpecAdd, cmdSpecEdit, cmdSpecList, } from "./commands/feature.js";
 import { cmdId, cmdInit } from "./commands/init.js";
 import { cmdInstall, cmdUninstall } from "./commands/install.js";
 import { cmdIssueLink, cmdIssueOpen, cmdIssueUnlink } from "./commands/issue.js";
+import { cmdPluginInstall, cmdPluginList, cmdPluginRemove, cmdPluginUpdate, } from "./commands/plugin.js";
+import { warnNewerFormat } from "./commands/policy.js";
 import { cmdPrClose, cmdPrList, cmdPrMerge, cmdPrOpen, cmdPrRequest, cmdPrReview, cmdPrUpdate, } from "./commands/pr.js";
+import { YES_HELP } from "./commands/pr-elsewhere.js";
+import { applyOption, buildPluginCommand as buildDeclaredCommand, optionCollision, } from "./plugins/commands.js";
 import { DEFAULT_SORT, SORT_ORDERS } from "./sort.js";
 /**
  * Read straight from package.json rather than duplicating the version as a
@@ -27,26 +32,91 @@ function readOwnVersion() {
     return pkg.version;
 }
 export const VERSION = readOwnVersion();
-const QUERY_HELP = `Query terms AND together. Terms:
-  status:open|closed|merged   entity status (path); 'merged' is PR-only
-  label:L                     L is among the entity's labels (repeatable, ANDs)
-  assignee:EMAIL              assignee address, or a fragment of its domain
-  author:EMAIL                author address, same matching
-  milestone:M                 exact milestone
-  feature:SLUG                SLUG is among the entity's features (repeatable, ANDs)
-  reviewer:EMAIL              asked to review it; PRs only, same matching
-  review:DECISION             pending, approved or changes-requested; PRs only
-  awaiting:EMAIL              asked to review it and has not yet; PRs only
-  WORD or "some phrase"       case-insensitive substring of the title,
-                              description, or any comment body
-Same-key terms OR for single-valued fields (status, author, milestone, review)
-and AND for multi-valued ones (label, assignee, feature, reviewer, awaiting).
-The default query is status:open.`;
+/**
+ * What each keyed term means, in the words `--help` uses.
+ *
+ * Only the prose lives here: which terms exist, which noun has them and how
+ * they combine all come from `QUERY_TERMS`, which the parser reads too, and so
+ * do the values of the three keys that take a fixed set. Keyed by `QueryKey`,
+ * so a term added to the grammar does not type-check until it is described.
+ * `status` is the one whose values differ by noun, so `queryHelp` writes it.
+ */
+const TERM_HELP = {
+    label: { syntax: "label:L", hint: ["L is among the entity's labels (repeatable, ANDs)"] },
+    assignee: { syntax: "assignee:EMAIL", hint: ["assignee address, or a fragment of its domain"] },
+    author: { syntax: "author:EMAIL", hint: ["author address, same matching"] },
+    milestone: { syntax: "milestone:M", hint: ["exact milestone"] },
+    reviewer: { syntax: "reviewer:EMAIL", hint: ["asked to review it; same matching"] },
+    review: { syntax: "review:DECISION", hint: [`one of ${REVIEW_DECISIONS.join(", ")}`] },
+    awaiting: { syntax: "awaiting:EMAIL", hint: ["asked to review it and has not yet"] },
+    deadline: {
+        syntax: `deadline:${DEADLINE_TERMS.join("|")}`,
+        hint: ["overdue: due before today (UTC), strictly;", "none: no deadline at all"],
+    },
+};
+/** How wide the syntax column is, as the help has always aligned it. */
+const SYNTAX_WIDTH = 28;
+function helpRow(syntax, hint) {
+    return hint.map((line, i) => `  ${(i === 0 ? syntax : "").padEnd(SYNTAX_WIDTH)}${line}`);
+}
+/**
+ * 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 function pluginHelpRow(help) {
+    const [syntax = "", hint = ""] = help.trim().split(/\s{2,}(.*)/s);
+    if (hint === "")
+        return [`  ${syntax}`];
+    if (syntax.length >= SYNTAX_WIDTH)
+        return [`  ${syntax}`, ...helpRow("", [hint])];
+    return helpRow(syntax, [hint]);
+}
+/**
+ * The query grammar as `nav {issue,pr} list --help` states it.
+ *
+ * Built per noun, so neither page offers a term its own parser refuses. The
+ * terms plugins declared for the noun follow the built-in ones, read from
+ * their manifests alone (spec 04 §4.3: help costs no plugin code).
+ */
+function queryHelp(kind, pluginKeys = []) {
+    const terms = queryTermsFor(kind);
+    const rows = terms.flatMap(({ key }) => {
+        if (key === "status") {
+            return helpRow(`status:${QUERY_STATUSES[kind].join("|")}`, ["entity status (path)"]);
+        }
+        return helpRow(TERM_HELP[key].syntax, TERM_HELP[key].hint);
+    });
+    rows.push(...pluginKeys.flatMap((key) => pluginHelpRow(key.help)));
+    const combining = (combines) => terms
+        .filter((term) => term.combines === combines)
+        .map((term) => term.key)
+        .join(", ");
+    return [
+        "Query terms AND together. Terms:",
+        ...rows,
+        ...helpRow('WORD or "some phrase"', [
+            "case-insensitive substring of the title,",
+            "description, or any comment body; also the",
+            "entity's own ID, from four characters",
+        ]),
+        `Same-key terms OR for single-valued fields (${combining("or")})`,
+        `and AND for multi-valued ones (${combining("and")}).`,
+        // A manifest says what its term means but not how it combines, so the
+        // sentence above cannot name it; its own description has to.
+        ...(pluginKeys.length > 0 ? ["A plugin's terms combine as their descriptions say."] : []),
+        "The default query is status:open.",
+    ].join("\n");
+}
 /**
  * Help for `--commit`, naming the subject the verb commits under (spec 03 §3.2).
  *
- * The argument is the commit's scope rather than an entity kind: `feature` is
- * one of the scopes and is deliberately not one of the kinds.
+ * The argument is the commit's scope rather than an entity kind: a plugin
+ * declares scopes of its own (spec 03 §3.2), and those are deliberately not
+ * kinds.
  */
 function commitHelp(scope) {
     return `wrap the change in a 'docs${scope ? `(${scope})` : ""}:' commit`;
@@ -63,7 +133,45 @@ function commitHelp(scope) {
 function withoutHelpVerb(command) {
     return command.helpCommand(false);
 }
-export function buildProgram(getCtx) {
+/**
+ * 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 const BUILTIN_NOUNS = [
+    "issue",
+    "pr",
+    "plugin",
+    "init",
+    "id",
+    "doctor",
+    "install",
+    "uninstall",
+];
+/**
+ * The top-level commands that do not warn about a newer tree: `doctor` reports
+ * it as D16 itself, and the rest set the repository up or print something
+ * that does not depend on the format.
+ */
+const FORMAT_INDEPENDENT = new Set([
+    "init",
+    "id",
+    "doctor",
+    "install",
+    "uninstall",
+    "plugin",
+    "__complete",
+]);
+/** Whether a command, by its top-level name, answers from the tree. */
+function readsTheTree(action) {
+    let top = action;
+    while (top.parent?.parent)
+        top = top.parent;
+    return !FORMAT_INDEPENDENT.has(top.name());
+}
+export function buildProgram(getCtx, plugins) {
     const program = withoutHelpVerb(new Command());
     program
         .name("nav")
@@ -71,6 +179,22 @@ export function buildProgram(getCtx) {
         .version(VERSION, "-V, --version")
         .showHelpAfterError()
         .enablePositionalOptions();
+    // Before any command that reads or writes the tree, and before it can fail:
+    // an answer from a tool older than the tree is a guess, and the person
+    // reading it should know that first (spec 04 §4.3, D16).
+    program.hook("preAction", (_program, action) => {
+        if (!readsTheTree(action))
+            return;
+        let ctx;
+        try {
+            ctx = getCtx();
+        }
+        catch {
+            return; // the action will report what is wrong with the context
+        }
+        if (ctx.hasNavbook)
+            warnNewerFormat(ctx, readMarkerVersion(ctx));
+    });
     program
         .command("init")
         .description("create the Navbook skeleton at the repository root")
@@ -79,7 +203,7 @@ export function buildProgram(getCtx) {
     program
         .command("id")
         .description("mint and print a fresh Navbook ID")
-        .option("-n, --count <n>", "how many IDs to print", (value) => Number.parseInt(value, 10), 1)
+        .option("-n, --count <n>", "how many IDs to print", wholeNumber("IDs", 1), 1)
         .action((opts) => cmdId(getCtx(), opts));
     program
         .command("doctor")
@@ -110,13 +234,91 @@ export function buildProgram(getCtx) {
         .command("__complete", { hidden: true })
         .description("internal: print completion candidates for the words typed so far")
         .argument("[words...]")
-        .action((words) => cmdComplete(getCtx(), words));
-    program.addCommand(buildIssueCommand(getCtx));
-    program.addCommand(buildPrCommand(getCtx));
-    program.addCommand(buildFeatureCommand(getCtx));
+        .action(async (words) => cmdComplete(getCtx(), words, plugins));
+    program.addCommand(buildPluginCommand(getCtx));
+    program.addCommand(buildIssueCommand(getCtx, plugins));
+    program.addCommand(buildPrCommand(getCtx, plugins));
+    // Built from manifests alone: no plugin code is imported here, which is what
+    // lets `nav --help` cost the same with plugins installed as without
+    // (spec 04 §4.3).
+    for (const [, { plugin, spec }] of plugins?.commands.nouns ?? []) {
+        program.addCommand(buildDeclaredCommand(plugin, spec, getCtx, (target, path, args, opts) => plugins.run(getCtx(), target, path, args, opts)));
+    }
+    warnUnknownContributions(program, getCtx, plugins);
     return program;
 }
-function buildPrCommand(getCtx) {
+/**
+ * Say which contributions name a command that does not exist.
+ *
+ * Checked once the whole tree is built, so every noun — built-in, shared verb
+ * or another plugin's — has had its chance to be the target. A contribution
+ * that matches nothing does nothing, and a plugin author who typed
+ * `issue lsit` deserves to hear that rather than wonder where their option went.
+ */
+function warnUnknownContributions(program, getCtx, plugins) {
+    for (const [on, entries] of plugins?.commands.contributions ?? []) {
+        let command = program;
+        for (const word of on.split(" ").filter(Boolean)) {
+            command = command?.commands.find((candidate) => candidate.name() === word);
+        }
+        if (command !== undefined && command !== program)
+            continue;
+        for (const { plugin } of entries) {
+            stderrOf(getCtx).write(`nav: plugin ${plugin.name} contributes to '${on}', which is not a nav command\n`);
+        }
+    }
+}
+/**
+ * Where to warn while the command tree is being built.
+ *
+ * The context's stream when there is one; the process's otherwise, because
+ * building a context needs a repository and `nav id` outside one must not fail
+ * over a warning about a plugin.
+ */
+function stderrOf(getCtx) {
+    try {
+        return getCtx().stderr;
+    }
+    catch {
+        return process.stderr;
+    }
+}
+/**
+ * `nav plugin` — the store verbs of spec 04 §4.3.
+ *
+ * The store is per user, not per repository, so none of these needs one:
+ * installing a plugin from a home directory is as ordinary as installing it
+ * from a checkout. Inside a repository they still read its declaration.
+ */
+function buildPluginCommand(getRepoCtx) {
+    const getCtx = () => getRepoCtx({ requireRepo: false });
+    const plugin = withoutHelpVerb(new Command("plugin")).description("install and manage plugins");
+    plugin
+        .command("install")
+        .argument("[name...]", "packages to install; the repository's declaration otherwise")
+        .description("install plugins into the per-user store")
+        .option("-y, --yes", "do not ask for confirmation")
+        .action((names, opts) => cmdPluginInstall(getCtx(), names, opts));
+    plugin
+        .command("remove")
+        .argument("<name...>", "packages to remove")
+        .description("remove plugins from the store")
+        .option("-y, --yes", "do not ask for confirmation")
+        .action((names, opts) => cmdPluginRemove(getCtx(), names, opts));
+    plugin
+        .command("update")
+        .argument("[name...]", "packages to update; all of them otherwise")
+        .description("update installed plugins")
+        .option("-y, --yes", "do not ask for confirmation")
+        .action((names, opts) => cmdPluginUpdate(getCtx(), names, opts));
+    plugin
+        .command("list")
+        .description("what is installed, and whether this repository declares it")
+        .option("--json", "one JSON object per plugin, newline-delimited")
+        .action((opts) => cmdPluginList(getCtx(), opts));
+    return plugin;
+}
+function buildPrCommand(getCtx, plugins) {
     const pr = withoutHelpVerb(new Command("pr")).description("work with pull requests");
     pr.command("open")
         .description("open a pull request from the current branch")
@@ -128,12 +330,12 @@ function buildPrCommand(getCtx) {
         .option("--assignee <email>", "assign to a person (repeatable)", collect, [])
         .option("--reviewer <email>", "ask a person to review it (repeatable)", collect, [])
         .option("--milestone <name>", "milestone")
-        .option("--feature <slug>", "attach it to a feature (repeatable)", collect, [])
         .option("--commit", commitHelp("pr"))
-        .action((opts) => cmdPrOpen(getCtx(), opts));
+        .action(async (opts) => cmdPrOpen(getCtx(), { ...opts, ext: await openFields(getCtx(), plugins, "pr open", opts) }));
     pr.command("update")
         .argument("<id>", "ID or unambiguous prefix")
         .description("append a revision pinning the current HEAD")
+        .option("-y, --yes", YES_HELP)
         .option("--commit", commitHelp("pr"))
         .action((id, opts) => cmdPrUpdate(getCtx(), id, opts));
     pr.command("request")
@@ -141,6 +343,7 @@ function buildPrCommand(getCtx) {
         .argument("<email...>", "who to ask")
         .description("ask people to review a pull request")
         .option("--remove", "take them off the reviewers instead")
+        .option("-y, --yes", YES_HELP)
         .option("--commit", commitHelp("pr"))
         .action((id, people, opts) => cmdPrRequest(getCtx(), id, people, opts));
     pr.command("review")
@@ -153,18 +356,19 @@ function buildPrCommand(getCtx) {
         .option("--revision <sha>", "bind to this revision instead of the latest")
         .option("--file <path>", "anchor the comment to a file")
         .option("--line <n|start-end>", "anchor the comment to a line or range")
+        .option("-y, --yes", YES_HELP)
         .option("--commit", commitHelp("pr"))
         .action((id, opts) => cmdPrReview(getCtx(), id, opts));
     pr.command("merge")
         .argument("[id]", "ID or unambiguous prefix")
         .description("merge a pull request into the checked-out target branch")
-        .option("--no-ff", "always create a merge commit")
+        .option("--method <name>", `how to land it (${MERGE_METHODS.join(" | ")})`)
         .option("--continue", "finish a merge that stopped for conflict resolution")
         .option("-y, --yes", "merge without asking when the review policy is not met")
         .option("--no-sync-source", "leave the source branch behind instead of fast-forwarding it")
-        // Commander models `--no-ff` as the negation of an implicit `--ff`.
-        .action((id, opts) => cmdPrMerge(getCtx(), id, { ...opts, noFf: opts.ff === false }));
+        .action((id, opts) => cmdPrMerge(getCtx(), id, opts));
     addSharedVerbs(pr, "pr", getCtx, {
+        ...(plugins ? { plugins, verbPrefix: "pr" } : {}),
         // No extra columns here: `cmdPrList` owns the PR listing's columns, because
         // it appends a `refs` one when scanning across branches.
         extraColumns: [],
@@ -174,74 +378,12 @@ function buildPrCommand(getCtx) {
         },
         runList: (ctx, terms, options) => cmdPrList(ctx, terms, options),
     });
+    // After the shared verbs, which are as much this noun's commands as `open`:
+    // an option contributed to `pr list` has to find `list` already there.
+    applyContributedOptions(pr, "pr", plugins, getCtx);
     return pr;
 }
-/**
- * `nav feature` — spec 04 §4.3.
- *
- * None of the shared verbs appear here. A feature does not open and close, and
- * it is not discussed: the discussion belongs to the issues attached to it. So
- * the family is small on purpose, and `spec` groups what acts on the documents
- * rather than on the feature itself.
- */
-function buildFeatureCommand(getCtx) {
-    const feature = withoutHelpVerb(new Command("feature")).description("work with features");
-    feature
-        .command("open")
-        .argument("<title>", "one-line name for the feature")
-        .description("create a feature")
-        .option("-m, --message <text>", "summary text; without it $EDITOR is opened")
-        .option("--slug <slug>", "directory name to file it under; derived from the title otherwise")
-        .option("--commit", commitHelp("feature"))
-        .action((title, opts) => cmdFeatureOpen(getCtx(), title, opts));
-    feature
-        .command("list")
-        .description("list features, with how much work is attached to each")
-        .option("--json", "one JSON object per feature, newline-delimited")
-        .action((opts) => cmdFeatureList(getCtx(), opts));
-    feature
-        .command("show")
-        .argument("<slug>", "the feature's directory name")
-        .description("render a feature, its documents, and what has touched it")
-        .option("--json", "emit a single JSON object naming its issues and pull requests")
-        .option("--commits <n>", "recent commits to list (default 10)", (value) => value.trim() === "" ? Number.NaN : Number(value))
-        .action((slug, opts) => cmdFeatureShow(getCtx(), slug, opts));
-    feature
-        .command("edit")
-        .argument("<slug>", "the feature's directory name")
-        .description("open the feature's feature.md in $EDITOR")
-        .option("--commit", commitHelp("feature"))
-        .action((slug, opts) => cmdFeatureEdit(getCtx(), slug, opts));
-    feature.addCommand(buildSpecCommand(getCtx));
-    return feature;
-}
-function buildSpecCommand(getCtx) {
-    const spec = withoutHelpVerb(new Command("spec")).description("work with a feature's specification documents");
-    spec
-        .command("add")
-        .argument("<slug>", "the feature's directory name")
-        .argument("<title>", "one-line name for the document")
-        .description("add a specification document to a feature")
-        .option("-m, --message <text>", "document text; without it $EDITOR is opened")
-        .option("--file <name>", "file to write it to; derived from the title otherwise")
-        .option("--commit", commitHelp("feature"))
-        .action((slug, title, opts) => cmdSpecAdd(getCtx(), slug, title, opts));
-    spec
-        .command("edit")
-        .argument("<slug>", "the feature's directory name")
-        .argument("<file>", "the document's file name")
-        .description("open a specification document in $EDITOR")
-        .option("--commit", commitHelp("feature"))
-        .action((slug, file, opts) => cmdSpecEdit(getCtx(), slug, file, opts));
-    spec
-        .command("list")
-        .argument("<slug>", "the feature's directory name")
-        .description("list a feature's specification documents")
-        .option("--json", "one JSON object per document, newline-delimited")
-        .action((slug, opts) => cmdSpecList(getCtx(), slug, opts));
-    return spec;
-}
-function buildIssueCommand(getCtx) {
+function buildIssueCommand(getCtx, plugins) {
     const issue = withoutHelpVerb(new Command("issue")).description("work with issues");
     issue
         .command("open")
@@ -251,15 +393,14 @@ function buildIssueCommand(getCtx) {
         .option("--label <label>", "add a label (repeatable)", collect, [])
         .option("--assignee <email>", "assign to a person (repeatable)", collect, [])
         .option("--milestone <name>", "milestone")
-        .option("--feature <slug>", "attach it to a feature (repeatable)", collect, [])
-        // Number rather than parseInt, and blank rather than 0, for the reason
-        // `--depth` does it: a value the command must refuse has to reach it
-        // intact rather than arrive silently rounded or defaulted.
-        .option("--rank <n>", "where it sits in the queue; lower first", (value) => value.trim() === "" ? Number.NaN : Number(value))
+        .option("--rank <n>", "where it sits in the queue; lower first", finiteNumber)
         .option("--deadline <date>", "when the work is wanted, YYYY-MM-DD")
         .option("--parent <id>", "file it as a subtask of an existing issue")
         .option("--commit", commitHelp("issue"))
-        .action((title, opts) => cmdIssueOpen(getCtx(), title, opts));
+        .action(async (title, opts) => cmdIssueOpen(getCtx(), title, {
+        ...opts,
+        ext: await openFields(getCtx(), plugins, "issue open", opts),
+    }));
     issue
         .command("link")
         .argument("<id>", "ID or unambiguous prefix")
@@ -275,17 +416,44 @@ function buildIssueCommand(getCtx) {
         .option("--commit", commitHelp("issue"))
         .action((id, opts) => cmdIssueUnlink(getCtx(), id, opts));
     addSharedVerbs(issue, "issue", getCtx, {
+        ...(plugins ? { plugins, verbPrefix: "issue" } : {}),
         extraColumns: [],
         configureList: (command) => command.option("--sort <order>", `listing order: ${SORT_ORDERS.join(", ")} (default ${DEFAULT_SORT})`),
         configureShow: (command) => 
-        // Number, not parseInt: '2.5' has to reach the command as 2.5 so it can
-        // be refused, rather than being silently rounded to something valid.
         // No default here — `cmdShow` owns it, so every caller gets the same one.
-        command.option("--depth <n>", "levels of subtasks to render (default 1)", (value) => value.trim() === "" ? Number.NaN : Number(value)),
+        command.option("--depth <n>", "levels of subtasks to render (default 1)", wholeNumber("levels")),
         configureDelete: (command) => command.option("-r, --recursive", "delete its subtasks too, to any depth"),
     });
+    // After the shared verbs, for the reason `buildPrCommand` gives.
+    applyContributedOptions(issue, "issue", plugins, getCtx);
     return issue;
 }
+/** What plugins contributed to one of this noun's verbs, loading them if any. */
+async function verbHandlers(ctx, shared, verb) {
+    if (shared.plugins === undefined || shared.verbPrefix === undefined)
+        return [];
+    return shared.plugins.handlersFor(ctx, `${shared.verbPrefix} ${verb}`);
+}
+/**
+ * One `jsonExtra` from several, or undefined when no plugin contributed one.
+ *
+ * A key the entity's own JSON already has is dropped: `title`, `status` and
+ * every frontmatter key are the format's answer, and the one a reader of
+ * `nav --json` is entitled to (spec 04 §4.2). A plugin adds keys; it does not
+ * get to quietly replace the built-in ones.
+ */
+function mergedJsonExtra(handlers) {
+    const contributors = handlers.filter((handler) => handler.jsonExtra !== undefined);
+    if (contributors.length === 0)
+        return undefined;
+    return (entity) => {
+        const merged = Object.assign({}, ...contributors.map((handler) => handler.jsonExtra?.(entity) ?? {}));
+        // Which keys exist does not depend on the Navbook directory's name.
+        for (const key of Object.keys(entityJson("", entity)))
+            delete merged[key];
+        return merged;
+    };
+}
 /** Register the verbs both nouns share, so their behavior can never drift. */
 export function addSharedVerbs(parent, kind, getCtx, shared) {
     const noun = kind === "issue" ? "issue" : "pull request";
@@ -294,31 +462,55 @@ export function addSharedVerbs(parent, kind, getCtx, shared) {
         .command("list")
         .argument("[query...]", "query terms; default status:open")
         .description(`list ${kind === "issue" ? "issues" : "pull requests"} matching a query`)
-        .addHelpText("after", `\n${QUERY_HELP}`)
+        .addHelpText("after", `\n${queryHelp(kind, shared.plugins?.queryKeys(kind))}`)
         .option("--json", "one JSON object per entity, newline-delimited");
     shared.configureList?.(list);
-    list.action((terms, opts) => shared.runList
-        ? shared.runList(getCtx(), terms, { ...opts, extraColumns })
-        : cmdList(getCtx(), kind, terms, { ...opts, extraColumns }));
+    list.action(async (terms, opts) => {
+        const contributed = await verbHandlers(getCtx(), shared, "list");
+        const columns = [...extraColumns, ...contributed.flatMap((h) => h.columns ?? [])];
+        const jsonExtra = mergedJsonExtra(contributed);
+        const options = { ...opts, extraColumns: columns, ...(jsonExtra ? { jsonExtra } : {}) };
+        if (shared.runList)
+            shared.runList(getCtx(), terms, options);
+        else
+            cmdList(getCtx(), kind, terms, options);
+    });
     const show = parent
         .command("show")
         .argument("<id>", "ID or unambiguous prefix")
         .description(`render one ${noun} and its comments`)
         .option("--json", "emit a single JSON object including comments");
     shared.configureShow?.(show);
-    show.action((id, opts) => cmdShow(getCtx(), kind, id, opts));
-    parent
+    show.action(async (id, opts) => {
+        const contributed = await verbHandlers(getCtx(), shared, "show");
+        const jsonExtra = mergedJsonExtra(contributed);
+        const sections = contributed.flatMap((handlers) => handlers.showSection ? [handlers.showSection] : []);
+        cmdShow(getCtx(), kind, id, {
+            ...opts,
+            ...(jsonExtra ? { jsonExtra } : {}),
+            ...(sections.length > 0 ? { sections } : {}),
+        });
+    });
+    // An issue lives on whatever branch you are standing on, so there is never
+    // another worktree to send its write to: the flag is a pull-request notion.
+    const edit = parent
         .command("edit")
         .argument("<id>", "ID or unambiguous prefix")
-        .description(`open the ${noun}'s file in $EDITOR`)
+        .description(`open the ${noun}'s file in $EDITOR`);
+    if (kind === "pr")
+        edit.option("-y, --yes", YES_HELP);
+    edit
         .option("--commit", commitHelp(kind))
         .action((id, opts) => cmdEdit(getCtx(), kind, id, opts));
-    parent
+    const comment = parent
         .command("comment")
         .argument("<id>", "ID or unambiguous prefix")
         .description(`add a comment to a ${noun}`)
         .option("-m, --message <text>", "comment text; without it $EDITOR is opened")
-        .option("--reply-to <comment-id>", "comment this one replies to")
+        .option("--reply-to <comment-id>", "comment this one replies to");
+    if (kind === "pr")
+        comment.option("-y, --yes", YES_HELP);
+    comment
         .option("--commit", commitHelp(kind))
         .action((id, opts) => cmdComment(getCtx(), kind, id, opts));
     parent
@@ -353,5 +545,52 @@ export function addSharedVerbs(parent, kind, getCtx, shared) {
 export function collect(value, previous) {
     return [...previous, value];
 }
+/**
+ * Add the options plugins declared for one verb, refusing a collision.
+ *
+ * From the manifest, so no plugin code runs: a `--feature` on `issue open`
+ * exists in `--help` and in completion whether or not anybody has run the
+ * command that would load the plugin implementing it.
+ */
+function applyContributedOptions(noun, kind, plugins, getCtx) {
+    if (plugins === undefined)
+        return;
+    for (const [on, entries] of plugins.commands.contributions) {
+        const [target, verb] = on.split(" ");
+        if (target !== kind || verb === undefined)
+            continue;
+        const command = noun.commands.find((candidate) => candidate.name() === verb);
+        if (command === undefined)
+            continue;
+        for (const { plugin, spec } of entries) {
+            for (const option of spec.options ?? []) {
+                const problem = optionCollision(command, option);
+                if (problem !== null) {
+                    // Before `.option()`, which throws on a duplicate flag: the plugin
+                    // loses its option and says so, rather than taking the CLI down.
+                    stderrOf(getCtx).write(`nav: plugin ${plugin.name} option skipped on '${on}': ${problem}\n`);
+                    continue;
+                }
+                applyOption(command, option);
+            }
+        }
+    }
+}
+/**
+ * Frontmatter a plugin wants on a newly opened entity, read off its options.
+ *
+ * This is the one contribution that loads plugin code on a built-in verb, and
+ * only when a plugin declared a contribution to *this* verb — so `nav issue
+ * open` with no such plugin imports nothing.
+ */
+async function openFields(ctx, plugins, verb, opts) {
+    if (plugins === undefined || !plugins.commands.contributions.has(verb))
+        return undefined;
+    const fields = {};
+    for (const handlers of await plugins.handlersFor(ctx, verb)) {
+        Object.assign(fields, handlers.openFields?.(opts) ?? {});
+    }
+    return Object.keys(fields).length > 0 ? fields : undefined;
+}
 export { Option };
 //# sourceMappingURL=program.js.map