@navbook/cli 0.4.0 → 0.5.0

package/dist/commands/policy.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Saying what the review policy counts, and what it is short of.
+ *
+ * Shared by every verb that reads the policy, so a pull request short of two
+ * approvals is described in the same words wherever it is mentioned. Nothing
+ * here refuses anything: spec 02 §2.7 forbids acting on a review state, and
+ * §2.10 keeps a declared policy inside that. These are sentences, not gates.
+ */
+import { type MarkerVersionFault, type MergePolicyReading, type ReviewPolicyReading, type ReviewSummary } from "@navbook/core";
+import type { Ctx } from "../context.ts";
+/** Warn about a marker whose policy could not be read; D15 is the full report. */
+export declare function warnPolicyProblems(ctx: Ctx, reading: ReviewPolicyReading): void;
+/**
+ * The same, for the merge policy (spec 02 §2.10).
+ *
+ * Kept separate from the review policy's rather than folded into it, because a
+ * merge is the one command that reads both and a caller reading only one
+ * should not be made to hold the other.
+ */
+export declare function warnMergePolicyProblems(ctx: Ctx, reading: MergePolicyReading): void;
+/**
+ * Say that the tree was written by a newer Navbook than this one (D16).
+ *
+ * Only the newer kind: a malformed `version` changes nothing a command does
+ * and is D15's to report, while a newer one means every answer that follows
+ * is this tool's guess at a format it has never seen — which is worth hearing
+ * before the answer rather than after a confusing one.
+ */
+export declare function warnNewerFormat(ctx: Ctx, fault: MarkerVersionFault | null): void;
+/**
+ * What stands between a pull request and its policy, or null when nothing does.
+ *
+ * Only asked of a repository that declared a policy: a decision of `pending`
+ * where nobody asked for anything is not a shortfall, and saying so on every
+ * merge would be noise about a project that never opted in.
+ */
+export declare function describeShortfall(summary: ReviewSummary): string | null;
+/** What a merge should do about a shortfall, before anything is written. */
+export type MergeAction = "proceed" | "warn-and-proceed" | "ask";
+export interface MergeSituation {
+    /** What the pull request is short of, or null when it is short of nothing. */
+    shortfall: string | null;
+    /** `--yes` was given. */
+    assumeYes: boolean;
+    /** There is somebody at a terminal to answer a question. */
+    interactive: boolean;
+}
+/**
+ * Decide how a merge should treat an unmet policy.
+ *
+ * Kept apart from the merge itself so every combination can be checked without
+ * a repository or a terminal, and so the one rule that matters is visible in
+ * one place: no combination returns a refusal. `--yes` proceeds, a terminal is
+ * asked, and everything else says its piece and proceeds — because a pipeline
+ * that stopped for a question nobody can answer would be the gate spec 02 §2.7
+ * forbids, arrived at by accident rather than on purpose.
+ */
+export declare function mergeAction(situation: MergeSituation): MergeAction;

package/dist/commands/policy.js

@@ -26,6 +26,19 @@ function warnMarkerProblems(ctx, problems) {
         ctx.stderr.write(`${ctx.colors.yellow("warning:")} ${ctx.navDir}/${NAV_MARKER}: ${problem}; using the default\n`);
     }
 }
+/**
+ * Say that the tree was written by a newer Navbook than this one (D16).
+ *
+ * Only the newer kind: a malformed `version` changes nothing a command does
+ * and is D15's to report, while a newer one means every answer that follows
+ * is this tool's guess at a format it has never seen — which is worth hearing
+ * before the answer rather than after a confusing one.
+ */
+export function warnNewerFormat(ctx, fault) {
+    if (fault?.kind !== "newer")
+        return;
+    ctx.stderr.write(`${ctx.colors.yellow("warning:")} ${ctx.navDir}/${NAV_MARKER}: ${fault.message}\n`);
+}
 /**
  * What stands between a pull request and its policy, or null when nothing does.
  *

package/dist/commands/policy.js.map

@@ -1 +1 @@
-{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../src/commands/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAEL,UAAU,GAGX,MAAM,eAAe,CAAC;AAGvB,kFAAkF;AAClF,MAAM,UAAU,kBAAkB,CAAC,GAAQ,EAAE,OAA4B;IACvE,kBAAkB,CAAC,GAAG,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAQ,EAAE,OAA2B;IAC3E,kBAAkB,CAAC,GAAG,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;AAC5C,CAAC;AAED,SAAS,kBAAkB,CAAC,GAAQ,EAAE,QAA2B;IAC/D,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,GAAG,CAAC,MAAM,CAAC,KAAK,CACd,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,GAAG,CAAC,MAAM,IAAI,UAAU,KAAK,OAAO,uBAAuB,CAChG,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAsB;IACtD,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS;SAC/B,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,KAAK,iBAAiB,CAAC;SACpD,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAChC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,wBAAwB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;IAE9E,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC;IAC9C,IAAI,KAAK,IAAI,QAAQ;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,GAAG,KAAK,OAAO,QAAQ,qBAAqB,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;AACjF,CAAC;AAcD;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,SAAyB;IACnD,IAAI,SAAS,CAAC,SAAS,KAAK,IAAI,IAAI,SAAS,CAAC,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1E,OAAO,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,kBAAkB,CAAC;AAC5D,CAAC"}
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../src/commands/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAGL,UAAU,GAGX,MAAM,eAAe,CAAC;AAGvB,kFAAkF;AAClF,MAAM,UAAU,kBAAkB,CAAC,GAAQ,EAAE,OAA4B;IACvE,kBAAkB,CAAC,GAAG,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAQ,EAAE,OAA2B;IAC3E,kBAAkB,CAAC,GAAG,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;AAC5C,CAAC;AAED,SAAS,kBAAkB,CAAC,GAAQ,EAAE,QAA2B;IAC/D,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,GAAG,CAAC,MAAM,CAAC,KAAK,CACd,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,GAAG,CAAC,MAAM,IAAI,UAAU,KAAK,OAAO,uBAAuB,CAChG,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,GAAQ,EAAE,KAAgC;IACxE,IAAI,KAAK,EAAE,IAAI,KAAK,OAAO;QAAE,OAAO;IACpC,GAAG,CAAC,MAAM,CAAC,KAAK,CACd,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,GAAG,CAAC,MAAM,IAAI,UAAU,KAAK,KAAK,CAAC,OAAO,IAAI,CACnF,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAsB;IACtD,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS;SAC/B,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,KAAK,iBAAiB,CAAC;SACpD,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAChC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,wBAAwB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;IAE9E,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC;IAC9C,IAAI,KAAK,IAAI,QAAQ;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,GAAG,KAAK,OAAO,QAAQ,qBAAqB,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;AACjF,CAAC;AAcD;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,SAAyB;IACnD,IAAI,SAAS,CAAC,SAAS,KAAK,IAAI,IAAI,SAAS,CAAC,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1E,OAAO,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,kBAAkB,CAAC;AAC5D,CAAC"}

package/dist/commands/pr-elsewhere.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Writing to a pull request whose branch is not checked out here.
+ *
+ * A pull request's files live on its source branch (spec 03 §3.5), so the
+ * verbs that write into its directory refuse from any other checkout — core's
+ * `findPrToWrite` names the branch, and the worktree that has it. Everything
+ * needed to perform the write anyway is already known at that moment, so when
+ * somebody can be asked, this asks instead of only pointing:
+ *
+ * - When a clean worktree already has the branch, the write happens there.
+ * - When none has it, the branch is checked out into a temporary worktree,
+ *   the write happens there, and the worktree goes away again once it holds
+ *   nothing the user would lose.
+ *
+ * No directory changes either way. A child process cannot move its parent
+ * shell's working directory, and nothing is spawned in any case: a second
+ * `Ctx` rooted at the other worktree is enough, and the verb runs against it
+ * unchanged.
+ */
+import { type EntityRecord } from "@navbook/core";
+import type { Ctx } from "../context.ts";
+/**
+ * Help for `-y`, which answers the question in advance. The same letter
+ * answers `nav pr merge` and `nav install` in advance, and means the same
+ * thing here: this verb's one question, whichever of the two it would be.
+ */
+export declare const YES_HELP = "accept the offer to write in a worktree on the source branch \u2014 the clean one that has it, or a temporary one";
+export interface PrWriteOptions {
+    /** `-y`: accept either offer in advance, and ask nobody. */
+    yes?: boolean;
+}
+/**
+ * Run a pull-request write where it belongs, asking first when that is not here.
+ *
+ * `write` gets the context to write in and the pull request as that context
+ * sees it. When the write cannot or may not move, this is core's refusal
+ * naming where the pull request lives — declining the question included: the
+ * answer was "not there", not "do it here".
+ */
+export declare function withPrWriteSite<T>(ctx: Ctx, prefix: string, opts: PrWriteOptions, write: (at: Ctx, entity: EntityRecord) => T): T;

package/dist/commands/pr-elsewhere.js

@@ -0,0 +1,209 @@
+/**
+ * Writing to a pull request whose branch is not checked out here.
+ *
+ * A pull request's files live on its source branch (spec 03 §3.5), so the
+ * verbs that write into its directory refuse from any other checkout — core's
+ * `findPrToWrite` names the branch, and the worktree that has it. Everything
+ * needed to perform the write anyway is already known at that moment, so when
+ * somebody can be asked, this asks instead of only pointing:
+ *
+ * - When a clean worktree already has the branch, the write happens there.
+ * - When none has it, the branch is checked out into a temporary worktree,
+ *   the write happens there, and the worktree goes away again once it holds
+ *   nothing the user would lose.
+ *
+ * No directory changes either way. A child process cannot move its parent
+ * shell's working directory, and nothing is spawned in any case: a second
+ * `Ctx` rooted at the other worktree is enough, and the verb runs against it
+ * unchanged.
+ */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { addWorktree, findPrToWrite, gitRun, isTreeClean, locatePrToWrite, refusePrWrite, removeWorktree, } from "@navbook/core";
+import { makeContext } from "../context.js";
+import { fail } from "../errors.js";
+import { askYesNo, isInteractive } from "../prompt.js";
+/**
+ * Help for `-y`, which answers the question in advance. The same letter
+ * answers `nav pr merge` and `nav install` in advance, and means the same
+ * thing here: this verb's one question, whichever of the two it would be.
+ */
+export const YES_HELP = "accept the offer to write in a worktree on the source branch — the clean one that has it, or a temporary one";
+/**
+ * Where the write could go instead of here, or null when nowhere can take it.
+ *
+ * An existing worktree must be clean: without `--commit` a write leaves a
+ * staged change behind, and one mixed into somebody's work in progress where
+ * they are not looking is not a favour; with it, the commit would be refused
+ * over the unrelated staged paths anyway. A branch no worktree has can be
+ * checked out into a new one — but only a local branch: checking out a
+ * remote-tracking one would create a local branch as a side effect, which is
+ * more than a comment should do.
+ */
+function destination(where) {
+    if (where.sourceRemote)
+        return null;
+    if (where.worktree === null)
+        return { branch: where.branch, worktree: null };
+    return where.worktreeClean ? { branch: where.branch, worktree: where.worktree } : null;
+}
+/** Ask whether to write there, unless `-y` already said yes. */
+function agreed(ctx, entity, to, opts) {
+    if (opts.yes)
+        return true;
+    // Only ever asked, never assumed. A run with nothing to answer the question
+    // keeps the refusal it has always had: a pipeline that started writing into
+    // a checkout nobody mentioned would be a worse surprise than exit 1.
+    if (!isInteractive(ctx))
+        return false;
+    if (to.worktree !== null) {
+        ctx.stdout.write(`#${entity.id} is on '${to.branch}', checked out in ${to.worktree} ${ctx.colors.dim("(clean)")}\n`);
+        return askYesNo(ctx, "Write it there? [y/N] ");
+    }
+    ctx.stdout.write(`#${entity.id} is on '${to.branch}', which no worktree has checked out\n`);
+    return askYesNo(ctx, "Check it out in a temporary worktree and write it there? [y/N] ");
+}
+/**
+ * A context rooted at `worktree`, reporting to the terminal we already have.
+ *
+ * The Navbook directory is the one already resolved here rather than found
+ * again: the pull request was located under it, and a second discovery from
+ * another root is one more chance to land somewhere it is not. The plugin
+ * extensions carry over for the same reason: the other checkout's tree is
+ * the same format, and read without them its registered keys would be raw.
+ */
+function contextIn(ctx, worktree) {
+    return makeContext({
+        cwd: worktree,
+        env: ctx.env,
+        stdout: ctx.stdout,
+        stderr: ctx.stderr,
+        navDir: ctx.navDir,
+        ext: ctx.ext,
+    });
+}
+/**
+ * Run `write` in `worktree`, refusing if that checkout does not hold the pull
+ * request after all — the branch moved since we looked, say. Without this the
+ * write would land beside no `pr.md`, the stranded comment the refusal exists
+ * to prevent.
+ */
+function writeIn(ctx, worktree, prefix, write) {
+    const there = contextIn(ctx, worktree);
+    return write(there, findPrToWrite(there, prefix));
+}
+/**
+ * A new worktree on `branch` in a fresh temporary directory.
+ *
+ * `mkdtemp` rather than a fixed name, so two runs never collide and nothing a
+ * user made is ever in the way; under `os.tmpdir()`, so `TMPDIR` says where.
+ * The branch only flavours the name, so it is cut short: a directory name has
+ * a length limit and a branch name has none.
+ */
+function checkOutTemporarily(ctx, branch) {
+    const safe = branch.replace(/[^A-Za-z0-9._-]+/g, "-").slice(0, 40);
+    let dir = null;
+    try {
+        dir = mkdtempSync(join(tmpdir(), `nav-${safe}-`));
+        addWorktree(ctx.repoRoot, dir, branch);
+        return dir;
+    }
+    catch (error) {
+        if (dir !== null)
+            rmSync(dir, { recursive: true, force: true });
+        fail(`could not check '${branch}' out into a temporary worktree`, [
+            error instanceof Error ? error.message.trim() : String(error),
+        ]);
+    }
+}
+/**
+ * Take a temporary worktree away again, unless it holds what the user would lose.
+ *
+ * After `--commit` the write is on the branch and the worktree holds nothing.
+ * Without it — or when the commit itself failed, a hook refusing it, say — the
+ * write is staged there and nowhere else, so the worktree stays and says where
+ * it is: removing it would throw away a review somebody just wrote. A run that
+ * failed before writing anything leaves it clean, and it goes. Untracked files
+ * do not count: nothing but this run has been in there.
+ */
+function release(ctx, dir, branch, failed) {
+    if (isTreeClean(dir, { untracked: false })) {
+        try {
+            removeWorktree(ctx.repoRoot, dir, { force: true });
+        }
+        catch {
+            // Never mask the error that brought us here with one about tidying up.
+            // Deleting the directory alone would leave git recording the branch as
+            // checked out at a path that no longer exists, so prune that too.
+            rmSync(dir, { recursive: true, force: true });
+            gitRun(["worktree", "prune"], { cwd: ctx.repoRoot });
+        }
+        if (!failed) {
+            ctx.stderr.write(`${ctx.colors.dim(`written in a temporary worktree on '${branch}', since removed`)}\n`);
+        }
+        return;
+    }
+    ctx.stderr.write(`${ctx.colors.yellow("note:")} the change is staged in ${dir}, a temporary worktree on '${branch}'\n` +
+        `commit it there, then remove it: 'git worktree remove ${dir}'\n`);
+}
+/** Terminal signals, which reach the editor and git as well as us. */
+const TERMINAL_SIGNALS = ["SIGINT", "SIGQUIT", "SIGHUP"];
+/**
+ * Run `body` with terminal signals left to the children.
+ *
+ * Ctrl-C while `$EDITOR` is open goes to the whole foreground process group.
+ * By default it would kill us mid-`spawnSync`, before any `finally` runs, and
+ * leave the temporary worktree registered with the branch checked out. Git
+ * ignores these signals while its own editor runs, for the same reason; so
+ * does this. The editor still gets the signal, exits, and the command fails
+ * through its ordinary path — which is the one that tidies up.
+ */
+function sheltered(body) {
+    const ignore = () => { };
+    for (const signal of TERMINAL_SIGNALS)
+        process.on(signal, ignore);
+    try {
+        return body();
+    }
+    finally {
+        for (const signal of TERMINAL_SIGNALS)
+            process.off(signal, ignore);
+    }
+}
+/**
+ * Run a pull-request write where it belongs, asking first when that is not here.
+ *
+ * `write` gets the context to write in and the pull request as that context
+ * sees it. When the write cannot or may not move, this is core's refusal
+ * naming where the pull request lives — declining the question included: the
+ * answer was "not there", not "do it here".
+ */
+export function withPrWriteSite(ctx, prefix, opts, write) {
+    const { entity, elsewhere } = locatePrToWrite(ctx, prefix);
+    if (elsewhere === null)
+        return write(ctx, entity);
+    const to = destination(elsewhere);
+    // Built from what was just found, rather than scanning every ref again.
+    if (to === null || !agreed(ctx, entity, to, opts))
+        refusePrWrite(entity, elsewhere);
+    if (to.worktree !== null) {
+        const result = writeIn(ctx, to.worktree, prefix, write);
+        ctx.stderr.write(`${ctx.colors.dim(`written in ${to.worktree}`)}\n`);
+        return result;
+    }
+    const { branch } = to;
+    return sheltered(() => {
+        const dir = checkOutTemporarily(ctx, branch);
+        let failed = true;
+        try {
+            const result = writeIn(ctx, dir, prefix, write);
+            failed = false;
+            return result;
+        }
+        finally {
+            release(ctx, dir, branch, failed);
+        }
+    });
+}
+//# sourceMappingURL=pr-elsewhere.js.map

package/dist/commands/pr-elsewhere.js.map

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

package/dist/commands/pr.d.ts

@@ -0,0 +1,69 @@
+/**
+ * `nav pr <verb>` — spec 04 §4.3.
+ *
+ * The eight shared verbs come from `entity.ts`; this module adds the four that
+ * only pull requests have (`update`, `request`, `review`, `merge`) and the
+ * parts of the shared verbs that must reach across branches, because a PR's
+ * files live on the branch it proposes to merge (spec 03 §3.5).
+ */
+import type { Ctx } from "../context.ts";
+import { type CloseOptions, type GlobalFlags, type ListOptions } from "./entity.ts";
+import { type PrWriteOptions } from "./pr-elsewhere.ts";
+export interface PrOpenOptions extends GlobalFlags {
+    target?: string;
+    title?: string;
+    message?: string;
+    draft?: boolean;
+    label?: string[];
+    assignee?: string[];
+    reviewer?: string[];
+    milestone?: string;
+    /**
+     * Frontmatter a plugin contributed, from an option it declared (§2.12).
+     *
+     * Written by the same composer that writes the format's own keys, so a
+     * plugin's value lands in the file exactly as a built-in one would.
+     */
+    ext?: Record<string, string | readonly string[]>;
+}
+export declare function cmdPrOpen(ctx: Ctx, opts: PrOpenOptions): void;
+export interface PrUpdateOptions extends GlobalFlags, PrWriteOptions {
+}
+export declare function cmdPrUpdate(ctx: Ctx, prefix: string, opts: PrUpdateOptions): void;
+export interface RequestOptions extends GlobalFlags, PrWriteOptions {
+    remove?: boolean;
+}
+export declare function cmdPrRequest(ctx: Ctx, prefix: string, people: string[], opts: RequestOptions): void;
+export interface ReviewOptions extends GlobalFlags, PrWriteOptions {
+    approve?: boolean;
+    requestChanges?: boolean;
+    comment?: boolean;
+    message?: string;
+    revision?: string;
+    file?: string;
+    line?: string;
+}
+export declare function cmdPrReview(ctx: Ctx, prefix: string, opts: ReviewOptions): void;
+export interface PrListOptions extends ListOptions {
+    allRefs?: boolean;
+}
+export declare function cmdPrList(ctx: Ctx, terms: string[], opts: PrListOptions): void;
+export interface MergeOptions extends GlobalFlags {
+    /** `--method`: land by this method instead of the marker's (spec 02 §2.10). */
+    method?: string;
+    continue?: boolean;
+    /** Answer the review-policy question in advance. */
+    yes?: boolean;
+    /** `--no-sync-source`: leave the source branch where it is. */
+    syncSource?: boolean;
+}
+export declare function cmdPrMerge(ctx: Ctx, prefix: string | undefined, opts: MergeOptions): void;
+/**
+ * Decline a pull request.
+ *
+ * Its files usually live on the source branch, so when the ID is not in the
+ * current tree the directory is first checked out from the ref that has it —
+ * which is exactly the manual recipe spec 02 §2.8 describes for keeping a
+ * durable record of a declined PR on the default branch.
+ */
+export declare function cmdPrClose(ctx: Ctx, prefix: string, opts: CloseOptions): void;

package/dist/commands/pr.js

@@ -6,12 +6,13 @@
  * parts of the shared verbs that must reach across branches, because a PR's
  * files live on the branch it proposes to merge (spec 03 §3.5).
  */
-import { applyComment, bindReviewRevision, commitReport, continuePrMerge, countOpenPrsOnOtherRefs, currentAuthor, entityJson, executePrMerge, findPrToWrite, isMergeMethod, listEntities, listPrsAcrossRefs, MERGE_METHODS, materializePrIfAbsent, newCommentFile, newPrFile, openPr, parseListQuery, parsePerson, planPrMerge, preparePrOpen, readReviewers, readReviewPolicy, requestReview, reviewSummary, sameEmail, stringField, toNdjson, updatePr, validateComment, validatePr, } from "@navbook/core";
+import { applyComment, bindReviewRevision, commitReport, continuePrMerge, countOpenPrsOnOtherRefs, currentAuthor, entityJson, executePrMerge, isMergeMethod, listEntities, listPrsAcrossRefs, MERGE_METHODS, materializePrIfAbsent, newCommentFile, newPrFile, openPr, parseListQuery, parsePerson, planPrMerge, preparePrOpen, readReviewers, readReviewPolicy, requestReview, reviewSummary, sameEmail, stringField, toNdjson, updatePr, validateComment, validatePr, } from "@navbook/core";
 import { fail } from "../errors.js";
 import { askYesNo, isInteractive } from "../prompt.js";
 import { composeFile } from "./compose.js";
 import { cmdClose, reportList, } from "./entity.js";
 import { describeShortfall, mergeAction, warnMergePolicyProblems, warnPolicyProblems, } from "./policy.js";
+import { withPrWriteSite } from "./pr-elsewhere.js";
 export function cmdPrOpen(ctx, opts) {
     const draft = preparePrOpen(ctx, { target: opts.target, title: opts.title });
     const composed = composeFile(ctx, {
@@ -31,9 +32,9 @@ export function cmdPrOpen(ctx, opts) {
             labels: opts.label,
             assignee: opts.assignee,
             milestone: opts.milestone,
-            features: opts.feature,
+            ...(opts.ext ? { ext: opts.ext } : {}),
         }),
-        validate: validatePr,
+        validate: (parsed) => validatePr(parsed, ctx.ext),
     });
     const { id, dirPath, run } = openPr(ctx, { content: composed.content, fallbackTitle: draft.title }, { commit: opts.commit });
     ctx.stdout.write(`Created ${ctx.navDir}/${dirPath}/  (#${id})\n`);
@@ -41,72 +42,83 @@ export function cmdPrOpen(ctx, opts) {
     if (opts.commit)
         ctx.stdout.write(`${commitReport(run)}\n`);
 }
-/* ------------------------------------------------------------------- update */
 export function cmdPrUpdate(ctx, prefix, opts) {
-    const { entity, head, revisionCount, run } = updatePr(ctx, prefix, { commit: opts.commit });
-    ctx.stdout.write(`Recorded revision ${revisionCount} of #${entity.id}  head ${head.slice(0, 12)}\n`);
-    if (opts.commit)
-        ctx.stdout.write(`${commitReport(run)}\n`);
+    // The revision pinned is the HEAD of wherever this runs, so moving the write
+    // to a worktree on the source branch is what pins the right one — this
+    // checkout's HEAD was never the head under review.
+    withPrWriteSite(ctx, prefix, opts, (at) => {
+        const { entity, head, revisionCount, run } = updatePr(at, prefix, { commit: opts.commit });
+        ctx.stdout.write(`Recorded revision ${revisionCount} of #${entity.id}  head ${head.slice(0, 12)}\n`);
+        if (opts.commit)
+            ctx.stdout.write(`${commitReport(run)}\n`);
+    });
 }
 export function cmdPrRequest(ctx, prefix, people, opts) {
-    const { entity, changed, unchanged, run } = requestReview(ctx, prefix, people, {
-        commit: opts.commit,
-        remove: opts.remove,
+    withPrWriteSite(ctx, prefix, opts, (at) => {
+        const { entity, changed, unchanged, run } = requestReview(at, prefix, people, {
+            commit: opts.commit,
+            remove: opts.remove,
+        });
+        const verb = opts.remove ? "No longer reviewing" : "Asked to review";
+        ctx.stdout.write(`${verb} #${entity.id}: ${changed.join(", ")}\n`);
+        // Naming who was already there matters most when only some of a list moved:
+        // the count alone would leave the caller counting names themselves.
+        for (const person of unchanged) {
+            ctx.stdout.write(`${ctx.colors.dim(opts.remove ? "not listed:" : "already listed:")} ${person}\n`);
+        }
+        if (opts.commit)
+            ctx.stdout.write(`${commitReport(run)}\n`);
     });
-    const verb = opts.remove ? "No longer reviewing" : "Asked to review";
-    ctx.stdout.write(`${verb} #${entity.id}: ${changed.join(", ")}\n`);
-    // Naming who was already there matters most when only some of a list moved:
-    // the count alone would leave the caller counting names themselves.
-    for (const person of unchanged) {
-        ctx.stdout.write(`${ctx.colors.dim(opts.remove ? "not listed:" : "already listed:")} ${person}\n`);
-    }
-    if (opts.commit)
-        ctx.stdout.write(`${commitReport(run)}\n`);
 }
 export function cmdPrReview(ctx, prefix, opts) {
-    const entity = findPrToWrite(ctx, prefix);
+    // Checked before anything is resolved, so a mistyped flag never costs a
+    // temporary checkout.
     const chosen = [opts.approve, opts.requestChanges, opts.comment].filter(Boolean).length;
     if (chosen > 1) {
         fail("choose one of --approve, --request-changes or --comment, not several");
     }
-    const revision = bindReviewRevision(entity, opts.revision);
     if (opts.line && !opts.file)
         fail("--line needs --file");
-    // This verb files reviews, so with no flag the verdict is the one that judges
-    // nothing (spec 04 §4.3). The exception is an inline anchor: a note about one
-    // line is discussion, and recording it as a review would say its author had
-    // read the whole revision. `nav pr comment` remains the unbound comment.
-    const verdict = opts.approve
-        ? "approve"
-        : opts.requestChanges
-            ? "request-changes"
-            : opts.file === undefined || opts.comment
-                ? "comment"
-                : undefined;
-    const isReview = verdict !== undefined || opts.file !== undefined;
-    const base = {
-        author: currentAuthor(ctx),
-        body: "",
-        ...(verdict ? { verdict } : {}),
-        ...(isReview ? { revision } : {}),
-        ...(opts.file ? { file: opts.file } : {}),
-        ...(opts.line ? { line: opts.line } : {}),
-    };
-    const composed = composeFile(ctx, {
-        message: opts.message,
-        bufferName: "NAVBOOK_REVIEW.md",
-        noun: verdict ? "review" : "comment",
-        render: (body) => newCommentFile({ ...base, body }),
-        validate: (parsed) => validateComment(parsed, { onPr: true }),
+    withPrWriteSite(ctx, prefix, opts, (at, entity) => {
+        const revision = bindReviewRevision(entity, opts.revision);
+        // This verb files reviews, so with no flag the verdict is the one that judges
+        // nothing (spec 04 §4.3). The exception is an inline anchor: a note about one
+        // line is discussion, and recording it as a review would say its author had
+        // read the whole revision. `nav pr comment` remains the unbound comment.
+        const verdict = opts.approve
+            ? "approve"
+            : opts.requestChanges
+                ? "request-changes"
+                : opts.file === undefined || opts.comment
+                    ? "comment"
+                    : undefined;
+        const isReview = verdict !== undefined || opts.file !== undefined;
+        const base = {
+            author: currentAuthor(at),
+            body: "",
+            ...(verdict ? { verdict } : {}),
+            ...(isReview ? { revision } : {}),
+            ...(opts.file ? { file: opts.file } : {}),
+            ...(opts.line ? { line: opts.line } : {}),
+        };
+        const composed = composeFile(ctx, {
+            message: opts.message,
+            bufferName: "NAVBOOK_REVIEW.md",
+            noun: verdict ? "review" : "comment",
+            render: (body) => newCommentFile({ ...base, body }),
+            validate: (parsed) => validateComment(parsed, { onPr: true }),
+        });
+        const { id, path, run } = applyComment(at, entity, { content: composed.content, review: isReview }, { commit: opts.commit });
+        const label = verdict ? `Reviewed (${verdict})` : "Commented on";
+        ctx.stdout.write(`${label} #${entity.id}  ${at.navDir}/${path}  (#${id})\n`);
+        if (isReview)
+            ctx.stdout.write(`Bound to revision ${revision.slice(0, 12)}\n`);
+        if (opts.commit)
+            ctx.stdout.write(`${commitReport(run)}\n`);
+        // The policy that decides whether a verdict counts is the one in the tree
+        // the review was written into.
+        warnIfOwnVerdict(at, entity, verdict);
     });
-    const { id, path, run } = applyComment(ctx, entity, { content: composed.content, review: isReview }, { commit: opts.commit });
-    const label = verdict ? `Reviewed (${verdict})` : "Commented on";
-    ctx.stdout.write(`${label} #${entity.id}  ${ctx.navDir}/${path}  (#${id})\n`);
-    if (isReview)
-        ctx.stdout.write(`Bound to revision ${revision.slice(0, 12)}\n`);
-    if (opts.commit)
-        ctx.stdout.write(`${commitReport(run)}\n`);
-    warnIfOwnVerdict(ctx, entity, verdict);
 }
 /**
  * Warn an author that their own verdict will not be counted.
@@ -161,10 +173,13 @@ export function cmdPrList(ctx, terms, opts) {
             when: (entities) => entities.some((entity) => summaryOf(entity).reviewers.length > 0),
         },
     ];
+    // The listing's own columns first, then whatever plugins contributed: the
+    // caller's are added to these, never replaced by them.
+    const columns = [...extraColumns, ...(opts.extraColumns ?? [])];
     const query = parseListQuery(ctx, terms, "pr");
     if (!opts.allRefs) {
         const here = listEntities(ctx, "pr", query);
-        reportList(ctx, "pr", here, { ...opts, extraColumns });
+        reportList(ctx, "pr", here, { ...opts, extraColumns: columns });
         if (here.length === 0)
             hintOtherRefs(ctx, opts);
         return;
@@ -173,7 +188,10 @@ export function cmdPrList(ctx, terms, opts) {
     if (opts.json) {
         if (matched.length === 0)
             return;
-        ctx.stdout.write(`${toNdjson(matched.map((entry) => entityJson(ctx.navDir, entry.entity, { refs: entry.refs.map((ref) => ref.short) })))}\n`);
+        ctx.stdout.write(`${toNdjson(matched.map((entry) => entityJson(ctx.navDir, entry.entity, {
+            ...(opts.jsonExtra?.(entry.entity) ?? {}),
+            refs: entry.refs.map((ref) => ref.short),
+        })))}\n`);
         return;
     }
     if (matched.length === 0) {
@@ -183,7 +201,7 @@ export function cmdPrList(ctx, terms, opts) {
     reportList(ctx, "pr", listEntities(ctx, "pr", query, { entities: matched.map((e) => e.entity) }), {
         ...opts,
         extraColumns: [
-            ...extraColumns,
+            ...columns,
             {
                 header: "refs",
                 value: (entity) => (matched.find((entry) => entry.entity.id === entity.id)?.refs ?? [])
@@ -208,7 +226,15 @@ export function cmdPrList(ctx, terms, opts) {
 function hintOtherRefs(ctx, opts) {
     if (opts.json)
         return;
-    const count = countOpenPrsOnOtherRefs(ctx);
+    let count;
+    try {
+        count = countOpenPrsOnOtherRefs(ctx);
+    }
+    catch {
+        // The listing this follows has already been printed and is right; a branch
+        // git cannot read is `--all-refs`'s to report, not a reason to fail this.
+        return;
+    }
     if (count === 0)
         return;
     ctx.stderr.write(`${ctx.colors.dim(`${count} open pull ${count === 1 ? "request" : "requests"} on other branches; ` +