prreviewbuddy 0.70.2 → 0.71.1

package/dist/main.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { $ as MAX_WORKSPACE_PORT, $r as resolveAgent, A as relativeTime, B as readIndexToken, Dn as MANAGED_ROOT, F as runBatch, Fn as describeSubject, G as reviewsUrl, Gn as loadJob, In as findExistingReview, Jr as resolveTarget, Kr as WITHHELD_REASON, Mn as removeWorktree, Pn as describeMovement, Q as DEFAULT_WORKSPACE_PORT, Qn as clearClaim, Qr as git, R as queueForReview, Tn as modelHelpLines, U as ensureServer, V as bootstrapUrl, Vn as allJobs, X as workspaceUrl, Xn as progressSteps, Y as stopServer, Zn as purposeOf, _ as liveUpdateFor, _r as reviewedRepositories, _t as telemetryUploadConsent, a as wasBlocked, ai as STORE_ROOT, b as recordKissRun, bn as forgeResolver, bt as PACKAGE_NAME, ct as reanalyseReview, d as mergeUpdateInto, dr as mutateWorkspace, dt as append, ei as resolveModel, et as MIN_WORKSPACE_PORT, f as updateReview, fr as positionInLineage, g as UpdateAlreadyRunningError, gt as recordTelemetryUploadConsent, hr as recentWorkspaces, ht as deliver, i as liveJobsFor, ii as CONFIG_PATH, it as writePortPreference, j as batchIdentity, jn as readMarker, li as detectAgents, lr as loadWorkspace, mt as stamp, n as deleteReview$1, ni as readAgentPreference, oi as AGENT_IDS, ot as prepareReview, pt as record$1, qn as PHASES, qr as kissOutcome, ri as writeAgentPreference, rt as statedWorkspacePort, si as agentById, st as settleReview, tr as followedRefName, tt as parseWorkspacePort, ur as matchingWorkspaceIds, ut as startJob, v as runningJobs, vr as summarise, vt as telemetryUploadEnabled, yt as BUILD_VERSION } from "./delete_review-CRPRIRKg.js";
+import { $ as MAX_WORKSPACE_PORT, A as relativeTime, B as readIndexToken, Dn as MANAGED_ROOT, F as runBatch, Fn as describeSubject, G as reviewsUrl, Gn as loadJob, In as findExistingReview, Jr as WITHHELD_REASON, Mn as removeWorktree, Pn as describeMovement, Q as DEFAULT_WORKSPACE_PORT, Qn as clearClaim, R as queueForReview, Tn as modelHelpLines, U as ensureServer, V as bootstrapUrl, Vn as allJobs, X as workspaceUrl, Xn as progressSteps, Xr as resolveTarget, Y as stopServer, Yr as kissOutcome, Zn as purposeOf, _ as liveUpdateFor, _r as reviewedRepositories, _t as telemetryUploadConsent, a as wasBlocked, ai as writeAgentPreference, b as recordKissRun, bn as forgeResolver, bt as PACKAGE_NAME, ci as AGENT_IDS, ct as reanalyseReview, d as mergeUpdateInto, di as detectAgents, dr as mutateWorkspace, dt as append, ei as git, et as MIN_WORKSPACE_PORT, f as updateReview, fr as positionInLineage, g as UpdateAlreadyRunningError, gt as recordTelemetryUploadConsent, hr as recentWorkspaces, ht as deliver, i as liveJobsFor, ii as readAgentPreference, it as writePortPreference, j as batchIdentity, jn as readMarker, li as agentById, lr as loadWorkspace, mt as stamp, n as deleteReview$1, ni as resolveModel, oi as CONFIG_PATH, ot as prepareReview, pt as record$1, qn as PHASES, rt as statedWorkspacePort, si as STORE_ROOT, st as settleReview, ti as resolveAgent, tr as followedRefName, tt as parseWorkspacePort, ur as matchingWorkspaceIds, ut as startJob, v as runningJobs, vr as summarise, vt as telemetryUploadEnabled, yt as BUILD_VERSION } from "./delete_review-BgIZpcsP.js";
 import { basename, dirname, join, resolve } from "node:path";
 import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
@@ -106,24 +106,35 @@ var AUDIENCES = {
 	author: "writes the report to whoever wrote the code, as changes to make before submitting it",
 	reviewer: "writes it for somebody reviewing somebody else's work, with whether each one is worth raising"
 };
+function isCommandName(word) {
+	return word !== void 0 && Object.hasOwn(VALUED, word);
+}
 function parse(argv) {
 	if (argv.length === 0) return {
 		name: "help",
 		via: "bare"
 	};
 	const [head, ...rest] = argv;
-	if (head === "--help" || head === "-h" || head === "help") return {
-		name: "help",
-		via: "asked"
-	};
+	if (head === "--help" || head === "-h" || head === "help") {
+		const topic = rest[0];
+		return isCommandName(topic) ? {
+			name: "help",
+			via: "asked",
+			topic
+		} : {
+			name: "help",
+			via: "asked"
+		};
+	}
 	if (head === "--version" || head === "-v") return { name: "version" };
-	if (head === void 0 || !(head in VALUED)) return {
+	if (!isCommandName(head)) return {
 		name: "error",
 		message: unknownCommand(head)
 	};
 	if (rest.includes("--help") || rest.includes("-h")) return {
 		name: "help",
-		via: "asked"
+		via: "asked",
+		topic: head
 	};
 	const values = {};
 	const flags = /* @__PURE__ */ new Set();
@@ -166,7 +177,7 @@ function parse(argv) {
 		}
 		return {
 			name: "error",
-			message: `\`${head}\` does not take ${name}. Run \`prreviewbuddy --help\` to see what it takes.`
+			message: `\`${head}\` does not take ${name}. Run \`prreviewbuddy ${head} --help\` to see what it takes.`
 		};
 	}
 	if (head === "review" && positional[0]) {
@@ -240,7 +251,7 @@ function parse(argv) {
 		const [action, key, value] = positional;
 		if (action !== "get" && action !== "set" && action !== "path") return {
 			name: "error",
-			message: "`config` takes `get`, `set` or `path`. Run `prreviewbuddy --help` for what it can read and set."
+			message: "`config` takes `get`, `set` or `path`. Run `prreviewbuddy config --help` for what it can read and set."
 		};
 		if (action === "path") return {
 			name: "config",
@@ -759,16 +770,6 @@ function orList(items) {
 }
 var AGENT_NAMES = orList([...AGENT_IDS].sort());
 /**
-* Where model names come from, laid out from what each adapter says about its own tool.
-*
-* Built from the registry for the same reason `AGENT_NAMES` is, and one step further: this file
-* names neither the agents nor the way each is asked. An adapter that learns a better answer
-* changes it in one place, and a fourth adapter appears here without this string being touched.
-*
-* No model is named anywhere in it, deliberately. Which models exist belongs to the vendor, and a
-* copy of it here would be wrong by the next release.
-*/
-/**
 * The adapters, skipping any this build cannot produce.
 *
 * Guarded for the reason `review_job.ts` guards its own registry lookups: an id the registry cannot
@@ -785,139 +786,188 @@ function knownAgents() {
 		}
 	});
 }
-var HELP = `PR Review Buddy reviews a branch in an isolated checkout and opens the result
-in your browser. The review runs in a separate process against a worktree pinned to one commit, so
-your own checkout is never read or written while it works.
-
-  prreviewbuddy review                    review the current branch
-  prreviewbuddy review --branch <branch>  review another branch, without checking it out
-  prreviewbuddy review --commit <commit>  review the change one commit made, against its parent
-  prreviewbuddy review --pr <url>         review a pull request
-  prreviewbuddy review --pr <url> <url> ...
-                                          review several pull requests, each on its own, two at a
-                                          time; --concurrency <n> changes how many
-  prreviewbuddy review ... --queue        also put each review on your review queue, as soon as
-                                          it exists rather than when it is ready
-  prreviewbuddy review --base <ref>       compare against a base of your choosing
-  prreviewbuddy review --agent <agent>    review with ${AGENT_NAMES}
-  prreviewbuddy review --model <model>    ask that agent for a particular model. Reviews keep
-                                          their requested model when reanalysed; use
-                                          --reanalyse --model <model> to change it.${((rows) => {
+/**
+* Where model names come from, laid out from what each adapter says about its own tool, under
+* `--model` in `review --help` at the column it is given.
+*
+* Built from the registry for the same reason `AGENT_NAMES` is, and one step further: this file
+* names neither the agents nor the way each is asked. An adapter that learns a better answer
+* changes it in one place, and a fourth adapter appears here without this string being touched.
+*
+* No model is named anywhere in it, deliberately. Which models exist belongs to the vendor, and a
+* copy of it here would be wrong by the next release.
+*
+* Measured rather than guessed: a hardcoded column would go ragged the day an adapter with a longer
+* display name is registered, and nothing would fail to say so. The lead-in belongs to the table
+* rather than to the flag, so an empty table takes its promise with it. "To find the names:"
+* followed by nothing would be worse than saying nothing at all.
+*
+* The flag's own sentence deliberately does not say what happens without it. It used to read
+* "rather than whichever one it uses by default", which is a claim about the no-flag case and is
+* false once a review is pinned: re-analysing one asks for the pin, not the agent's default.
+*/
+function modelHelp(indent) {
+	const rows = modelHelpLines(knownAgents());
 	if (rows.length === 0) return "";
 	const width = Math.max(...rows.map(([name]) => name.length));
-	const table = rows.map(([name, how]) => `${" ".repeat(44)}${name.padEnd(width + 2)}${how}`).join("\n");
-	return `\n${" ".repeat(42)}To find the names:\n${table}`;
-})(modelHelpLines(knownAgents()))}
-
-  prreviewbuddy review --lens <name>      run a specialised review lens: ${orList([...LENS_NAMES])}
-  prreviewbuddy review --lens kiss --audience author
-                                          ask whether the change is more complicated than it needs
-                                          to be, written for whoever wrote it
-  prreviewbuddy review --lens kiss --audience reviewer
-                                          the same question, written for reviewing somebody else's
-                                          work
-
-  prreviewbuddy review --update           bring the review of that target up to date
-  prreviewbuddy review --reanalyse        analyse the same commit again, for a fresh judgement
-  prreviewbuddy review --fresh            review the target again, keeping the existing review
-  prreviewbuddy review --review <review> --update
-                                          act on one review by its review ID
-  prreviewbuddy review --review <review> --delete
-                                          delete one review and its isolated checkouts
+	const table = rows.map(([name, how]) => `${" ".repeat(indent + 2)}${name.padEnd(width + 2)}${how}`).join("\n");
+	return `\n${" ".repeat(indent)}To find the names:\n${table}`;
+}
+/**
+* The lenses, named in the help from the registry that defines them.
+*
+* Built rather than written down for the same reason `AGENT_NAMES` is: a hand-written list is copy
+* that goes quietly wrong the day a second lens is registered, and the help is the one place
+* somebody looks to find out what `--lens` takes.
+*/
+var LENS_LIST = orList([...LENS_NAMES]);
+/**
+* The help, at four levels:
+*
+* - `ORIENTATION`, for `prreviewbuddy` on its own: what this is and what to type next.
+* - `HELP`, for `prreviewbuddy help` and `--help`: every command, one line each.
+* - `COMMAND_HELP`, for `prreviewbuddy <command> --help`: that command's syntax and flags.
+* - Help in the workspace (`help_page.ts`): what a review covers, and what its parts mean.
+*/
+var ORIENTATION = `PR Review Buddy
+Understand before you approve.
 
-  prreviewbuddy open                      list your reviews and open the index
-  prreviewbuddy open <review>             open a review by its review ID
+Review code changes with ${orList(knownAgents().map((agent) => agent.displayName))} in an isolated checkout,
+then explore the review in your browser.
 
-  prreviewbuddy agents                    which coding agents you have
-  prreviewbuddy agents <agent>            show details for ${AGENT_NAMES}
-  prreviewbuddy config get agent          the coding agent used when you do not name one
-  prreviewbuddy config set agent <agent>  remember ${AGENT_NAMES}
-  prreviewbuddy config get telemetry-upload
-                                          whether usage telemetry is sent. On by default
-  prreviewbuddy config set telemetry-upload on|off
-                                          send it, or stop
-  prreviewbuddy config get port           the port the workspace runs on
-  prreviewbuddy config set port <port>    move it, from the next start onwards
-  prreviewbuddy config path               where these settings are kept, to edit by hand
+  prreviewbuddy review             Review this branch
+  prreviewbuddy review --pr <url>  Review a pull request
+  prreviewbuddy open               Open previous reviews
 
-  prreviewbuddy uninstall                 remove everything this put on your machine
-  prreviewbuddy uninstall --keep-reviews  keep your reviews and settings, clear the rest
+More: prreviewbuddy help`;
+/** Where the concepts are explained, said the same way wherever the CLI points at it. */
+var WORKSPACE_HELP = "Help in the workspace (open it with `prreviewbuddy open`, then choose Help)";
+var HELP = `PR Review Buddy
+Understand before you approve.
 
-Anything in the first group says what to review. Anything in the second says what to do to it, and
-they go together: \`prreviewbuddy review --branch feat/foo --update\` brings the review of feat/foo up
-to date without checking it out. \`prreviewbuddy open\` prints a review ID beside each review, and
-you need one to tell two reviews of the same branch apart or to delete one. Deleting a review
-removes its record and the checkouts it was made in, and never touches your branch or its commits.
+Usage: prreviewbuddy <command> [options]
 
-A review lens asks a specialised question of the same change instead of the standard review's.
-\`--lens kiss\` asks not whether the change is correct, but whether the complexity it introduces is
-justified, or whether the same requirements could be met with less machinery. A lens runs beside
-the standard review in the same workspace rather than replacing it, and it does not need one to
-have been made first. \`--audience\` is required with \`--lens kiss\` and is never guessed from what
-you are reviewing, because a reviewer checks out somebody else's branch and an author reviews their
-own pull request.
+Commands
+  prreviewbuddy review             review this branch, another branch, a commit or pull requests
+  prreviewbuddy open               list your reviews and open the workspace in your browser
+  prreviewbuddy agents             which coding agents you have
+  prreviewbuddy config             the default agent, the workspace port and usage telemetry
+  prreviewbuddy uninstall          remove everything PR Review Buddy put on your machine
 
-Several pull requests at once are several ordinary reviews, each with its own link, and the command
-prints them all when it ends. One that fails does not stop the others. Ctrl-C stops them all, and
-running the same command again carries each one on from where it got to.
+Common examples
+  prreviewbuddy review             review the branch you have checked out
+  prreviewbuddy review --pr <url>  review a pull request
+  prreviewbuddy review --update    bring that review up to date with new commits
+  prreviewbuddy open <review>      open one review by its review ID
 
-Reviews can also be deleted from the list in your browser, one at a time or a whole branch at once.
+More
+  prreviewbuddy <command> --help   that command's options, such as \`review --help\`
+  prreviewbuddy --version          the version you have
+  Help in the workspace            what a review covers, updating and reanalysing, lenses, and
+                                   how long reviews are kept. Run \`prreviewbuddy open\`, then
+                                   choose Help`;
+var REVIEW_HELP = `prreviewbuddy review: review a change in an isolated checkout and open it in your browser.
 
-What gets reviewed
+Usage: prreviewbuddy review [what to review] [what to do to it] [options]
 
-A review is the combined change between a base and the branch you review, as one diff. It is not
-just the latest commit. The base determines the split point (git's merge-base of the base and your
-branch), and PR Review Buddy reviews the changes on your branch since that point.
+What to review. Leave it out for the branch you have checked out.
+  --branch <branch>           another branch, local or remote, without checking it out.
+                              origin/feat/foo reviews what is on the remote
+  --commit <commit>           the change one commit made, against its parent
+  --pr <url>                  a pull request
+  --pr <url> <url> ...        several pull requests, each its own review
+  --review <review>           one existing review, by its review ID. \`prreviewbuddy open\`
+                              prints a review ID beside each review
 
-  main:      A---B---C
-                  \\
-  feature:         D---E
+What to do to it. Leave it out to start a review, or to find the one that exists.
+  --update                    bring the review up to date with new commits
+  --reanalyse                 analyse the same commit again, for a fresh judgement
+  --fresh                     review the target again, keeping the existing review
+  --delete                    delete the review and its isolated checkouts, never your branch.
+                              Asks first; --yes answers for you
 
-  prreviewbuddy review --base main    reviews D and E together
+Options
+  --base <ref>                compare against this base instead of the default branch. When
+                              your local and remote copies of it differ, you are asked which
+  --agent <agent>             review with ${AGENT_NAMES}
+  --model <model>             ask that agent for a particular model. Reviews keep their
+                              requested model when reanalysed; use --reanalyse --model <model>
+                              to change it.${modelHelp(30)}
+  --lens <name>               run a specialised review lens: ${LENS_LIST}
+  --audience <audience>       who the lens writes for: author (whoever wrote the change) or
+                              reviewer (somebody reviewing it). Required with --lens kiss
+  --concurrency <n>           with several --pr URLs, how many are reviewed at once. Default 2
+  --queue                     put each review on your review queue as soon as it exists
 
-C is on main but not on your branch, so it is not part of the review, and the review does not show
-its changes as removed. Commits already in the base are never reviewed again.
+A target and an operation go together:
+  prreviewbuddy review --branch feat/foo --update
+  prreviewbuddy review --base origin/main
+  prreviewbuddy review --pr <url> <url> --queue
+  prreviewbuddy review --lens kiss --audience author
+  prreviewbuddy review --review <review> --delete
 
-When your local main and origin/main are different commits, which one you name moves the split
-point:
+What a review covers, and how updating, reanalysing and lenses work, is in
+${WORKSPACE_HELP}.`;
+var OPEN_HELP = `prreviewbuddy open: list your reviews and open the workspace in your browser.
 
-  origin/main:   A---B
-                      \\
-  local main:          C---D
-                            \\
-  feature:                   E
+Usage
+  prreviewbuddy open             list your reviews, each with its review ID, and open the list
+  prreviewbuddy open <review>    open one review by its review ID
 
-  --base refs/heads/main      reviews E
-  --base origin/main          reviews C, D and E together
+The workspace starts if it is not running. How long reviews are kept, and how to stop or move the
+workspace, is in ${WORKSPACE_HELP}.`;
+/**
+* What each adapter says about setting up its own tool, under its name. From the registry, as the
+* model table is, so this file names no agent's configuration. Empty when no adapter has a note.
+*/
+function agentSetupNotes() {
+	return knownAgents().filter((agent) => agent.setupNotes?.length).map((agent) => `\n\n${agent.displayName}\n${(agent.setupNotes ?? []).map((line) => `  ${line}`).join("\n")}`).join("");
+}
+/** Each command's own help, for `prreviewbuddy <command> --help` and `prreviewbuddy help <command>`. */
+var COMMAND_HELP = {
+	review: REVIEW_HELP,
+	open: OPEN_HELP,
+	agents: `prreviewbuddy agents: the coding agents PR Review Buddy can review with.
 
-Without --base, the repository's default branch is the base. If its local and remote copies are
-different commits, PR Review Buddy asks which one you mean and says what each would review.
-Uncommitted changes are never included: a review is a fixed snapshot of your commits.
+Usage
+  prreviewbuddy agents           which coding agents you have, and which one is used by default
+  prreviewbuddy agents <agent>   show details for ${AGENT_NAMES}
 
-Common examples
+Choose the default with \`prreviewbuddy config set agent <agent>\`, or one review's agent with
+\`prreviewbuddy review --agent <agent>\`.
 
-  prreviewbuddy review --base refs/heads/main
-                                          everything on this branch since it left your local main
-  prreviewbuddy review --base origin/main
-                                          everything on this branch not yet on origin/main
-  prreviewbuddy review --commit <commit>  one commit, against its parent
+Each agent uses its own installation and its existing authentication.${agentSetupNotes()}`,
+	config: `prreviewbuddy config: read and change your settings.
 
-There is no account and no API key. PR Review Buddy uses a coding agent installed on your machine
-and that agent's existing authentication, and nothing here ever asks you for a credential.
+Usage
+  prreviewbuddy config get agent          the coding agent used when you do not name one
+  prreviewbuddy config set agent <agent>  remember ${AGENT_NAMES}
+  prreviewbuddy config get telemetry-upload
+                                          whether usage telemetry is sent. On by default
+  prreviewbuddy config set telemetry-upload on|off
+                                          send it, or stop
+  prreviewbuddy config get port           the port the workspace runs on. ${DEFAULT_WORKSPACE_PORT} by default
+  prreviewbuddy config set port <port>    move it, from the next time the workspace starts
+  prreviewbuddy config path               where these settings are kept, to edit by hand
 
-Your workspace is at http://localhost:${DEFAULT_WORKSPACE_PORT} and each review has an address
-under it, so a link to one is worth keeping and still opens tomorrow. Move it with
-\`prreviewbuddy config set port\`, or from Settings in the workspace itself, and the new port is used
-the next time the workspace starts. If something else is already on that port, PR Review Buddy says
-so rather than quietly moving somewhere you have not bookmarked.
+The port can also be changed from Settings in the workspace.`,
+	uninstall: `prreviewbuddy uninstall: remove everything PR Review Buddy put on your machine.
 
-Reviews are kept in ~/.prreviewbuddy for thirty days. The workspace server outlives this command,
-so a review stays open after the terminal that started it has closed. There is no command to stop
-it, on purpose: open any review and use "Stop server" in the left rail. One server serves all of
-them, and the page says so before it asks.
+Usage
+  prreviewbuddy uninstall                 remove your reviews, settings and isolated checkouts,
+                                          stop the workspace, and clean up the git bookkeeping
+                                          left in the repositories it reviewed
+  prreviewbuddy uninstall --keep-reviews  keep your reviews and settings, clear the rest
 
-The isolated checkout a review was made in is kept for six hours after it finishes, because that is
-what the assistant reads when you ask it questions, and is then removed along with the rest.`;
+Options
+  --yes      do not ask for confirmation first
+  --force    stop a review that is still being made, rather than refusing over it`
+};
+/** What a `help` command prints. */
+function helpFor(command) {
+	if (command.via === "bare") return ORIENTATION;
+	return command.topic ? COMMAND_HELP[command.topic] : HELP;
+}
 /**
 * An agent asked for by name that this build does not have.
 *
@@ -1610,7 +1660,7 @@ function firstRun(version) {
 		`PR Review Buddy ${version}`,
 		"",
 		"  prreviewbuddy agents   which coding agents you have",
-		"  prreviewbuddy --help   everything it does",
+		"  prreviewbuddy help     every command",
 		""
 	].join("\n");
 }
@@ -1770,6 +1820,20 @@ function out(text) {
 function err(text) {
 	process.stderr.write(`${text}\n`);
 }
+//#endregion
+//#region src/commands/review_batch.ts
+/**
+* `prreviewbuddy review --pr <url> <url> ...`: several ordinary reviews, started together.
+*
+* Orchestration only. Each pull request is resolved, looked up, started and run through exactly
+* the functions a single `--pr` uses (`prepareReview`, `settleReview`), and ends as an ordinary
+* review with its own workspace, job and link. There is no batch record and nothing is compared
+* across pull requests. What this adds is the scheduling, one screen describing all of them, a
+* summary at the end, and Ctrl-C.
+*
+* The harness calls arrive as `BatchDeps` so the glue is testable without mocking the harness
+* module by module; `realDeps` is the only place they are wired to the real thing.
+*/
 /**
 * What to call each pull request on screen: `#128`, or `!45` for a merge request. Two from
 * different repositories with one number are given the repository's name too.
@@ -3346,7 +3410,7 @@ async function main(argv) {
 async function run(command) {
 	switch (command.name) {
 		case "help":
-			out(HELP);
+			out(helpFor(command));
 			return 0;
 		case "version":
 			out(BUILD_VERSION);