prreviewbuddy 0.18.1 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # Changelog
 
+## 0.19.0
+
+*It asks before it sends anything, and the npm page stops reading like a manual.*
+
+**PR Review Buddy now asks, once, whether it may send anonymous usage counts.** There is no default:
+nothing is sent until you answer, a bare Return re-asks rather than being read as either answer, and
+answering no is the end of it. If you are not at a terminal, because this is a durable job, a CI run
+or a piped command, it does not ask and does not record an answer, so the same machine is asked
+properly the first time somebody is there to answer.
+
+**Two events reach us, carrying eight fields between them.** `review_started` and `review_finished`,
+with a random UUID generated on your machine, the version, the platform, which agent ran the
+analysis, a timestamp, whether it succeeded and how long it took. That is the whole list, and the
+server refuses any field that is not on it rather than accepting the request and dropping what it
+does not recognise, which is what makes [the published field
+table](https://prreviewbuddy.com/privacy) a claim rather than a description.
+
+Never sent: your code, diffs, prompts, questions, findings, file paths, repository or branch names,
+or the counts of any of those. The identifier is an installation rather than a person, so a laptop,
+a desktop and a CI machine are three and nothing joins them up. No IP address or user agent is
+stored against an event. `prreviewbuddy config set telemetry-upload off` stops it afterwards, and
+`PRB_TELEMETRY=off` stops both that and the local log.
+
+**Rows are deleted after 90 days.** Not archived and not folded into a longer-lived aggregate:
+deleted. Every question the data exists to answer is a weekly one, so thirteen weeks answers all of
+them. A scheduled job in our own application does the deleting, daily, so the period holds whether
+or not anybody sends another event: retention is not a side effect of somebody using the tool.
+
+**The local usage log is unchanged.** It still records the full set of events to
+`~/.prreviewbuddy/events.jsonl`, on by default and disclosed since it existed. The question is about
+transmission, which is a different act from writing a file you own and can read or delete.
+
+**Three usage numbers were quietly zero and are not any more.** Two events the code declared were
+emitted by nothing, so `themesTotal` — the number that tells an abandoned review from one worked
+through — has been zero in every log ever written. A third read a field that does not exist, so the
+count of pull request threads was zero on every pull request review. All three were plausible zeroes
+rather than errors, which is why they lasted; there are now tests that read the values back.
+
+**Deleting a review can no longer take a checkout that is in use.** Both surfaces asked whether
+anything was running and then, with nothing holding that answer still, removed working trees. The
+command-line one put a confirmation prompt in the gap, so the window was however long you took to
+read it; the browser one put a recursive delete over a whole card in it. Deletion and every path
+that starts work now take the same per-review lock, so "nothing is running" stays true for as long
+as it is being acted on, and a job that starts a moment too late is refused with a sentence rather
+than destroyed halfway through.
+
+**An assistant question or an update in progress now counts as work.** Preparing the isolated
+checkout those need registered a job and never claimed it, and the deletion guard answers from
+claims -- so those checkouts were invisible to it always, not merely during a race. Deleting a
+review while the assistant prepared its checkout removed the directory it was reading. It is now
+visible, deletion refuses while it is being made, and the refusal names the branch.
+
+**Two settings could not both survive.** Recording a usage event overwrote `config.json` rather than
+updating it, so a machine that ran `prreviewbuddy config set agent` before it ever recorded an event
+lost the agent on the first event, and `config get agent` then reported no default. Both settings
+now survive each other.
+
+**A branch review no longer claims to have read a pull request.** The progress checklist ticked
+"Read pull request conversation" on every review, including one of a branch with no request, which
+made an ordinary complete review look like an incomplete PR review. An optional stage that did not
+apply is now not drawn at all, rather than drawn as done or drawn as missing: a line in a checklist
+reads as something absent whatever words are in it. A pull request review still shows it from the
+start, and so does a branch review that turns out to have a request, because then the step did real
+work. Why a conversation is absent is still said once, at the end, where it is a fact about the
+finished review rather than a gap in a list of things still happening.
+
+**A failed sign-in says which tool and which profile, and stops there.** It used to answer an
+expired token with five sentences: that this was `claude` and not GitHub, that re-authenticating
+the GitHub CLI would not help, which environment variable had not been set, that a review pins the
+environment it was created under, and that `--fresh` from another shell was an option. All true,
+and debugging notes wearing the clothes of user guidance — one of them introducing GitHub to
+somebody who had not been thinking about GitHub. Two facts are what a person needs at that moment,
+so that is what it says now. The agent's own words are kept on the job record for anybody who wants
+them.
+
+**An old review now lists the newer ones, instead of pointing at the index.** A review that is not
+the latest has always said so. Answering the question that raises took four steps: leave the page,
+find the branch's card, expand its history, pick a row. The other analyses of the branch are now
+listed in the strip itself, newest first, each with the commit it was of and the risk it found, and
+opening one is a single click from the sentence that said it existed. The review being read is
+marked rather than moved, so the list stays a timeline.
+
+No review page carries another review's credential, which is the constraint the whole treatment is
+built around: a review link is a thing people copy and it has to stay worth exactly the one review
+it names. The rows hold identifiers, which open nothing. Turning one into a way in is done by the
+list's own credential, the same one that already authorises pinning and deleting from the index.
+
+**The npm page leads with what this is.** It was 149 lines of reference material with the value
+proposition and the install in the first fifteen. The commands, base resolution, deleting and
+uninstalling are all still there, below a screenshot and an install line, with the longest sections
+folded away.
+
+
 ## 0.18.1
 
 *The review ID, where you would look for it.*

package/README.md

@@ -1,11 +1,8 @@
 # PR Review Buddy
 
-Review a branch, or a pull request, in an isolated checkout. From the terminal.
+**Review a branch, or a pull request, in an isolated checkout. From your terminal.**
 
-The analysis runs in a separate process against a git worktree pinned to one commit, so your own
-checkout is never read or written while it works and you can carry on using it. The result is a
-local workspace you open in a browser: a suggested path through the change, findings, questions,
-and an assistant that has read the diff.
+![The review workspace: a suggested path through the change, its findings and its questions](https://prreviewbuddy.com/npm/workspace.png)
 
 ## Install
 
@@ -13,7 +10,52 @@ and an assistant that has read the diff.
 npm install -g prreviewbuddy
 ```
 
-## Use
+## Review something
+
+```
+prreviewbuddy review
+```
+
+Run it inside the repository you want reviewed. It prints a workspace URL before the analysis
+starts and fills in as the review is made, so you can open the link and watch it arrive.
+
+`prreviewbuddy review --pr <url>` reviews a pull request instead, and `--branch <branch>` reviews
+another branch without checking it out.
+
+## What does the reviewing
+
+A coding agent you have already installed: [Claude Code](https://claude.com/claude-code),
+[Codex CLI](https://developers.openai.com/codex/cli) or
+[Gemini CLI](https://github.com/google-gemini/gemini-cli). Run `prreviewbuddy agents` to see which
+of them this machine has.
+
+There is no account, no API key and nothing to sign up for. PR Review Buddy uses that agent's
+existing authentication; it never sees a token and never asks you for one.
+
+## How it works
+
+The analysis runs in a separate process against a git worktree pinned to one commit, so your own
+checkout is never read or written while it works and you can carry on using it. What you get back
+is a local workspace in your browser: a suggested path through the change, findings, questions, and
+an assistant that has read the diff. The job is durable, so closing the terminal does not stop it.
+
+## Privacy
+
+Your code goes to the coding agent you chose, exactly as it would if you had run that agent
+yourself. It does not pass through us, and no server of ours is in the path of a review.
+
+PR Review Buddy asks once, on first run, whether it may send anonymous usage counts: two event
+names, a random ID generated on your machine, the version, the platform, the agent and a duration.
+Never your code, diffs, file paths, repository names, prompts or review content, and never anything
+at all unless you said yes. [The full field table is published](https://prreviewbuddy.com/privacy).
+
+More at [prreviewbuddy.com](https://prreviewbuddy.com).
+
+---
+
+# Reference
+
+## Commands
 
 A command names what to review, and what to do to it.
 
@@ -37,6 +79,8 @@ prreviewbuddy open <review>             open one review
 
 prreviewbuddy agents                    which coding agents you have
 prreviewbuddy config set agent <agent>  remember which to use when you do not name one
+prreviewbuddy config set telemetry-upload on|off
+                                        send anonymous usage counts, or stop
 
 prreviewbuddy uninstall                 remove everything this put on your machine
 ```
@@ -44,45 +88,17 @@ prreviewbuddy uninstall                 remove everything this put on your machi
 The two halves go together: `prreviewbuddy review --branch feat/foo --update` brings the review of
 `feat/foo` up to date without checking it out.
 
-Run it from inside the repository you want reviewed. `--branch` takes a branch, local or remote, so
-`--branch origin/feat/foo` reviews what is on the remote rather than what is in your clone. A review
-follows the ref it was made from and keeps following it.
-
-## Which base a review is compared against
-
-A base named by its short name resolves to the remote copy of it, and a base named in full resolves
-to exactly what was named.
-
-```
---base main              ->  origin/main
---base refs/heads/main   ->  your own main, deliberately
-```
-
-A local branch is behind the remote from the first day nobody pulls, and it is usually an ancestor
-of the branch under review, so git accepts it as a merge base without complaint and every upstream
-commit you have not pulled lands in the review. There is no error, only a much larger diff and
-findings about code the author never touched. Naming the ref in full is how you say you meant your
-own branch.
-
-A pull request is stricter, because its base is not something you typed. PR Review Buddy asks the
-forge which commit the request is cut from and uses that; failing that, the remote-tracking copy of
-the base branch; and failing both it refuses and asks you to run `git fetch`. It also checks the
-diff it built against the number of files the forge says the request touches, and refuses if the two
-disagree.
+`--branch` takes a branch, local or remote, so `--branch origin/feat/foo` reviews what is on the
+remote rather than what is in your clone. A review follows the ref it was made from and keeps
+following it.
 
 ## What you need
 
 - **Node 20 or newer**, and **git**.
-- **A coding agent**, installed and signed in. It does the analysis. Any one of
-  [Claude Code](https://claude.com/claude-code), [Codex CLI](https://developers.openai.com/codex/cli)
-  or [Gemini CLI](https://github.com/google-gemini/gemini-cli). Run `prreviewbuddy agents` to see
-  which of them this machine has.
+- **A coding agent**, installed and signed in. It does the analysis.
 - **[GitHub CLI](https://cli.github.com/)** (`gh`), signed in, if you want the pull request
   conversation read. Without it the review still runs, on the code alone, and says so.
 
-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; it never sees a token and never asks you for one.
-
 With more than one agent installed and none chosen, the first review asks which to use and offers
 to remember the answer. A review keeps the agent it was made with, so a later question about it is
 answered by whichever agent wrote it.
@@ -93,9 +109,8 @@ started with.
 
 ## What to expect
 
-The workspace URL is printed before the analysis starts and fills in as the review is made. The job
-is durable: closing the terminal does not stop it, and running the same command again after an
-interruption carries on from the phase that stopped rather than starting over.
+The job is durable: closing the terminal does not stop it, and running the same command again after
+an interruption carries on from the phase that stopped rather than starting over.
 
 Reviews are kept in `~/.prreviewbuddy` for thirty days. A local server holds them open and outlives
 the terminal that started it, taking a new port each time it starts, so bookmark
@@ -104,7 +119,34 @@ the terminal that started it, taking a new port each time it starts, so bookmark
 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.
 
-## Deleting a review
+<details>
+<summary><b>Which base a review is compared against</b> — <code>--base main</code> means
+<code>origin/main</code>, and why</summary>
+
+A base named by its short name resolves to the remote copy of it, and a base named in full resolves
+to exactly what was named.
+
+```
+--base main              ->  origin/main
+--base refs/heads/main   ->  your own main, deliberately
+```
+
+A local branch is behind the remote from the first day nobody pulls, and it is usually an ancestor
+of the branch under review, so git accepts it as a merge base without complaint and every upstream
+commit you have not pulled lands in the review. There is no error, only a much larger diff and
+findings about code the author never touched. Naming the ref in full is how you say you meant your
+own branch.
+
+A pull request is stricter, because its base is not something you typed. PR Review Buddy asks the
+forge which commit the request is cut from and uses that; failing that, the remote-tracking copy of
+the base branch; and failing both it refuses and asks you to run `git fetch`. It also checks the
+diff it built against the number of files the forge says the request touches, and refuses if the two
+disagree.
+
+</details>
+
+<details>
+<summary><b>Deleting a review</b></summary>
 
 ```
 prreviewbuddy review --review <review> --delete
@@ -122,6 +164,34 @@ can name several reviews once you have used `--fresh`.
 You can also delete from the list in your browser: the `...` menu on a review offers **Copy review
 ID** and **Delete review**, and the menu on a card deletes every review of that branch at once.
 
+</details>
+
+<details>
+<summary><b>Anonymous usage counts</b> — what is sent, and how to stop it</summary>
+
+Two events reach a server we run, and only if you answered yes when asked on first run:
+`review_started` and `review_finished`. Between them they carry a random UUID generated on your
+machine, the CLI version, the platform, which agent ran the analysis, a timestamp, whether it
+succeeded and how long it took. That is the whole list, and the server refuses any field that is
+not on it rather than accepting the request and dropping what it does not recognise.
+
+Never sent: your code, diffs, prompts, questions, findings, file paths, repository or branch names,
+or the counts of any of those. The identifier is an installation rather than a person, so a laptop,
+a desktop and a CI machine are three, and nothing joins them up. No IP address or user agent is
+stored against an event, and rows are deleted after 90 days.
+
+```
+prreviewbuddy config get telemetry-upload   what it is doing now
+prreviewbuddy config set telemetry-upload off
+PRB_TELEMETRY=off                           turns off the local log as well
+```
+
+PR Review Buddy also keeps a fuller usage log on your own machine, at
+`~/.prreviewbuddy/events.jsonl`. It is yours to read or delete, and only the two events above ever
+leave the machine. [The published field table](https://prreviewbuddy.com/privacy) has the detail.
+
+</details>
+
 ## Uninstall
 
 ```
@@ -142,7 +212,7 @@ still being made rather than refusing over it.
 Removing the package itself is the second line, and it is yours to run: a command that deleted the
 install it was running from would depend on whichever package manager put it there.
 
-## Also available
+---
 
-As a [Claude Code](https://claude.com/claude-code) plugin, and as a Chrome extension that reviews
-pull requests in the browser.
+**Prefer reviewing in GitHub?** PR Review Buddy is also available as a Chrome extension that reviews
+pull requests in the browser. [prreviewbuddy.com](https://prreviewbuddy.com)