thurview 0.11.0 → 0.12.0

package/README.md

@@ -1,83 +1,45 @@
 # thurview
 
-Guided, evidence-anchored reviews of agent-written code.
-
-A coding agent studies a branch, pull request or commit range and writes a
-short document in which every claim is anchored to an exact file and line
-range at a pinned commit. thurview validates the anchors, seals a revision,
-and serves it in your browser: the walkthrough, live code peeks, the diff,
-commits, and a software map. You ask questions, leave anchored comments, and
-approve or request changes. The agent answers and republishes.
-
-It also explains a codebase. A **code explainer** is the same document over a
-different unit: one pinned commit instead of a range, so a reader can see the
-architecture well enough to spot design problems themselves. It has no diff and
-nothing to approve, it surfaces structure rather than grading it, and it states
-what it did not examine.
-
-It does not review the code for you. It helps you understand it fast enough
-to review it yourself.
-
-![thurview demo: the agent publishes and answers in the terminal, the reader
-peeks, comments and decides in the browser](./media/thurview-demo.gif)
-
-The clip is the `/thurview` skill's loop end to end: `thurview publish`, a
-question arriving in `thurview wait`, the reply, then the reader following an
-anchor into the code, commenting on a line range in the diff, reading the
-answer in the threads panel and requesting changes.
-
-## What the reader sees
-
-Prose with every claim anchored to code, opened beside the text:
-
-![The review document, with a call stack diff, a storage view and an anchored
-peek open in the side panel](./media/review-review.png)
-
-The diff at the pinned commits, commenting on a selected line range:
-
-![The Files tab, split diff, with a comment on lines 9 to 12 of
-src/auth.ts](./media/review-files.png)
-
-The software map: where the change landed in the system, and what sits next to
-it — the question the diff cannot answer:
-
-![The Map tab: the parts the change touched, drawn first, the links between
-them, and the selected node's files, code and neighbours](./media/review-map.png)
-
-Threads: a question the agent already answered, and a comment held for the
-decision:
-
-![The threads panel, one answered question and one pending
-comment](./media/review-threads.png)
-
-Approve, or send it back with the comments:
-
-![The submit dialog, one pending comment, Approve or Request
-changes](./media/review-decision.png)
-
-```mermaid
-flowchart LR
-  A[Branch, PR or range] --> B[Agent pins base and head]
-  B --> C[Agent authors review.md + data.yaml + map.yaml]
-  C --> D[thurview publish: validate, seal revision]
-  D --> E[You read, ask, comment in the browser]
-  E -->|Request changes| C
-  E -->|Approve| F[Done]
-```
+Guided, evidence-anchored reviews of agent-written code. A coding agent studies
+a branch, pull request or commit range and writes a short document in which
+every claim is anchored to an exact file and line range at a pinned commit. You
+read it in your browser, ask the agent questions, comment on the code, and
+approve or send it back.
 
 ## Install
 
 Give your agent the skill, with the [skills](https://github.com/vercel-labs/skills)
-CLI. It works with Claude Code, Codex, Cursor, OpenCode and every agent that
+CLI - it works with Claude Code, Codex, Cursor, OpenCode and every agent that
 reads the Agent Skills format:
 
 ```sh
 npx skills@latest add https://github.com/Thurbeen/thurview \
   --skill thurview --agent universal claude-code --global --yes
-npx skills@latest add https://github.com/Thurbeen/thurview \
-  --skill review-fix --agent universal claude-code --global --yes   # optional, see below
 ```
 
+The skill reaches the `thurview` command through `npx`, so the requirements
+are Node 22 or later and git (`gh` for pull requests, `glab` for merge
+requests). Then, in any repository, ask your agent:
+
+```text
+Use the thurview skill to review my current branch against up-to-date main
+and open it.
+```
+
+![thurview demo: the reader follows an anchor into the code, comments on a line
+range in the diff, reads the agent's answer and requests changes](./media/thurview-demo.gif)
+
+The clip is the reader's half, the agent working off camera: following an anchor
+from the prose into the code, opening a call stack frame, commenting on a line
+range of the diff, seeing on the map what the change added, reading in the
+threads panel the answer to a question already asked, and sending the review
+back with changes requested.
+
+<details>
+<summary><b>Other ways to install</b> - pin the skill to a release, install the
+command from npm, run from a checkout, session hooks, the review-fix
+skill</summary>
+
 `--global` installs for your user, so one install covers every repository.
 `universal` puts the one real copy in `~/.agents/skills/thurview`, the directory
 no single agent owns, and every other agent you name gets a symlink to it, such
@@ -103,13 +65,11 @@ The npm package ships the same skill, so `thurview setup skill` links the copy
 that matches the command you have installed. Use that when you want the two to
 move together.
 
-The skill drives the `thurview` command, which needs Node 22 or later and
-git (`gh` for pull requests, `glab` for merge requests). Install it, or let
-the skill reach it through `npx`:
+Install the command itself, rather than leaving the skill to reach it through
+`npx` on every run:
 
 ```sh
 npm install -g thurview     # or: pnpm add -g thurview
-npx -y thurview             # no install; the skill falls back to this
 ```
 
 The review reasons over a code graph thurview builds itself from the pinned
@@ -132,14 +92,72 @@ with the reviews of its working directory. `thurview setup skill` links the
 skill from this checkout instead of the `skills` CLI copy; use one or the
 other.
 
-Then, in any repository, ask your agent:
+Also available: `review-fix`, the browserless companion skill described
+[below](#review-and-fix).
 
-```text
-Use the thurview skill to review my current branch against up-to-date main
-and open it.
+```sh
+npx skills@latest add https://github.com/Thurbeen/thurview \
+  --skill review-fix --agent universal claude-code --global --yes
+```
+
+</details>
+
+## How it works
+
+thurview validates every anchor against the pinned commits, seals a revision,
+and serves it in your browser: the walkthrough, live code peeks, the diff,
+commits, and a software map. You ask questions, leave anchored comments, and
+approve or request changes. The agent answers and republishes.
+
+It also explains a codebase. A **code explainer** is the same document over a
+different unit: one pinned commit instead of a range, so a reader can see the
+architecture well enough to spot design problems themselves. It has no diff and
+nothing to approve, it surfaces structure rather than grading it, and it states
+what it did not examine.
+
+It does not review the code for you. It helps you understand it fast enough
+to review it yourself.
+
+```mermaid
+flowchart LR
+  A[Branch, PR or range] --> B[Agent pins base and head]
+  B --> C[Agent authors review.md + data.yaml + map.yaml]
+  C --> D[thurview publish: validate, seal revision]
+  D --> E[You read, ask, comment in the browser]
+  E -->|Request changes| C
+  E -->|Approve| F[Done]
 ```
 
-## What the reader gets
+## What the reader sees
+
+Prose with every claim anchored to code, opened beside the text:
+
+![The review document, with a call stack diff, a storage view and an anchored
+peek open in the side panel](./media/review-review.png)
+
+The diff at the pinned commits, commenting on a selected line range:
+
+![The Files tab, split diff, with a comment on lines 9 to 12 of
+src/auth.ts](./media/review-files.png)
+
+The software map: where the change landed in the system, and what sits next to
+it — the question the diff cannot answer:
+
+![The Map tab: the parts the change touched, drawn first, the links between
+them, and the selected node's files, code and neighbours](./media/review-map.png)
+
+Threads: a question the agent already answered, and a comment held for the
+decision:
+
+![The threads panel, one answered question and one pending
+comment](./media/review-threads.png)
+
+Approve, or send it back with the comments:
+
+![The submit dialog, one pending comment, Approve or Request
+changes](./media/review-decision.png)
+
+## What's in a review
 
 - **Interface delta**: above the document, what the change added to, changed
   in or removed from the surfaces other code can reach - exported functions
@@ -193,7 +211,7 @@ bar.
 | `thurview wait --review ID [--timeout S]`                             | Block until the reader needs the agent                            |
 | `thurview threads list\|get\|reply\|resolve`                          | Read and answer threads                                           |
 | `thurview graph interfaces\|impact\|callers\|tests-for\|architecture` | Ask the code graph at a review's pins, or at `--base`/`--head`    |
-| `thurview forge status\|prior\|submit\|reply`                         | Read a change request through its forge, and post the review back |
+| `thurview forge status\|prior\|pass\|submit\|reply`                   | Read a change request through its forge, and post the review back |
 | `thurview serve` / `thurview stop`                                    | Run the server in the foreground / stop the background one        |
 | `thurview setup hooks\|skill\|status`                                 | Session hooks, agent skill, install state                         |
 | `thurview update`                                                     | Self-update from npm                                              |
@@ -232,6 +250,7 @@ on the change request, through `thurview forge`:
 ```sh
 thurview forge status --change 123    # what CI actually did, and whether it is a gate at all
 thurview forge prior  --change 123    # the previous pass, thread by thread
+thurview forge pass   --review <id>   # the reader's submitted threads, as the file below takes
 thurview forge submit --change 123 --file pass.json --dry-run
 thurview forge reply <threadId> --change 123 --body "<answer>" --resolve --at <head>
 ```
@@ -242,6 +261,14 @@ a change request from a fork typically runs a fraction of them, and a
 cancelled job shows no failure while asserting nothing. `ci.trustworthy` is
 the only field that means the tests really passed.
 
+`pass` goes the other way, from a review a reader submitted in the browser to
+that same file: one inline comment per thread anchored to a line, questions and
+resolved threads left out, and threads with no line - a document block, a map
+node, a whole file - gathered into the summary and named in the output, so
+nobody assumes their comment was posted where they wrote it. The verdict comes
+from the reader's decision, `close` becomes a `comment`, and an approve with
+threads still open is refused rather than quietly downgraded.
+
 `submit` takes one JSON file so a human can read the pass before it is posted,
 refuses an `approve` without `--confirm`, and warns about comments too long to
 be read. `reply --resolve` takes `--at <sha>` and refuses any commit but the

package/dist/cli.js

@@ -9,17 +9,18 @@ import { join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import open from "open";
 import * as g from "./git.js";
-import { SCHEMA, home, newId, now, readReview, writeReview, listReviews, reviewsFor, reviewDir, revisionDir, readThreads, readText, writeText, writeJson, readJson, serverStateFile, deleteReview, kindOf, } from "./store.js";
+import { SCHEMA, home, newId, now, readReview, writeReview, listReviews, reviewsFor, reviewDir, revisionDir, passFile, readThreads, readText, writeText, writeJson, readJson, serverStateFile, deleteReview, kindOf, } from "./store.js";
 import { compileDocument, compileMap, globToRegExp } from "./document/compile.js";
 import { computeCoverage, scopeGlob, scopeGraph, scopeTruncated, } from "./coverage.js";
 import { parseTheme, compileTheme } from "./theme.js";
 import { registerTheme } from "./highlight.js";
 import { replyThread, setThreadStatus, needsAgent } from "./threads.js";
+import { targetLabel, truncate } from "./thread-state.js";
 import { attach } from "./presence.js";
 import { startServer } from "./server/server.js";
 import { parseFlags, helpFor, str, bool } from "./flags.js";
 import { forgeFor, repoOf, summariseCi, } from "./forge/index.js";
-import { parseSubmission, longComments } from "./forge/submission.js";
+import { parseSubmission, longComments, buildPass } from "./forge/submission.js";
 import { VERSION } from "./version.js";
 const execFileP = promisify(execFile);
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -30,24 +31,6 @@ function note(msg) {
 function short(id) {
     return id.slice(0, 8);
 }
-function truncate(text, max) {
-    return text.length > max
-        ? `${text.slice(0, max)}... (truncated, ${text.length} chars total)`
-        : text;
-}
-function targetLabel(t) {
-    if (t.type === "document")
-        return `document${t.quote ? ` "${truncate(t.quote, 40)}"` : ""}`;
-    if (t.type === "file") {
-        if (!t.line)
-            return `${t.path} (file)`;
-        const range = t.endLine && t.endLine > t.line ? `${t.line}-${t.endLine}` : String(t.line);
-        return `${t.path}:${range}${t.side === "base" ? " (base)" : ""}`;
-    }
-    if (t.type === "map")
-        return `map ${t.node}`;
-    return "review";
-}
 /** `PR #12` or `MR !12`, because the forge's own word is what the reader knows. */
 function bindingLabel(b) {
     if (b.kind !== "pr")
@@ -77,7 +60,13 @@ async function worktreeOf(cwd) {
         return null;
     }
 }
-async function resolveReview(idOpt) {
+/**
+ * `terminal` keeps an approved or closed review in the search. `forge pass`
+ * needs it: approve and close are two of the three decisions it carries, and
+ * both of them end the review, so without it the command cannot find the very
+ * review it was asked about unless the id is spelled out.
+ */
+async function resolveReview(idOpt, opts = {}) {
     if (idOpt) {
         const r = await readReview(idOpt);
         if (r)
@@ -92,7 +81,7 @@ async function resolveReview(idOpt) {
         throw new AxiError("not inside a git repository", "VALIDATION_ERROR", [
             "Run inside the source worktree, or pass --review <id>",
         ]);
-    const mine = (await reviewsFor(worktree)).filter((r) => !r.dismissed && r.status !== "accepted" && r.status !== "closed");
+    const mine = (await reviewsFor(worktree)).filter((r) => !r.dismissed && (opts.terminal || (r.status !== "accepted" && r.status !== "closed")));
     if (mine.length === 1)
         return mine[0];
     if (mine.length)
@@ -478,7 +467,7 @@ const SPECS = {
     },
     forge: {
         description: "Read a pull or merge request through its forge, and post the review back to it",
-        args: 'status|prior|submit --file <path>|reply <threadId> --body "<text>"',
+        args: 'status|prior|pass|submit --file <path>|reply <threadId> --body "<text>"',
         flags: {
             review: { kind: "string", help: "review id prefix; its binding names the change request" },
             change: { kind: "string", help: "change request number or URL, instead of a review binding" },
@@ -488,6 +477,10 @@ const SPECS = {
             },
             repo: { kind: "string", help: "host/path, when `origin` is not the repository to post to" },
             file: { kind: "string", help: "submit: the JSON submission to post" },
+            out: {
+                kind: "string",
+                help: "pass: where to write the submission (default: ~/.thurview/passes/<id>.json)",
+            },
             body: { kind: "string", help: "reply: the answer text" },
             resolve: { kind: "boolean", help: "reply: resolve the thread as well as answering it" },
             at: { kind: "string", help: "reply --resolve: the commit the point was verified at" },
@@ -504,6 +497,7 @@ const SPECS = {
         examples: [
             "thurview forge status --change 123",
             "thurview forge prior --change 123 --mine",
+            "thurview forge pass --review <id>",
             "thurview forge submit --file pass.json --dry-run",
             'thurview forge reply <threadId> --body "<answer>" --resolve --at <sha>',
         ],
@@ -1500,10 +1494,11 @@ const commands = {
         const usage = [
             "thurview forge status [--change <ref>] [--review <id>]",
             "thurview forge prior [--change <ref>] [--mine] [--full]",
+            "thurview forge pass [--review <id>] [--out <path>]",
             "thurview forge submit --file <path> [--dry-run] [--confirm]",
             'thurview forge reply <threadId> --body "<text>" [--resolve --at <sha>]',
         ];
-        if (!sub || !["status", "prior", "submit", "reply"].includes(sub))
+        if (!sub || !["status", "prior", "pass", "submit", "reply"].includes(sub))
             throw new AxiError(`unknown forge command${sub ? ` ${sub}` : ""}`, "VALIDATION_ERROR", usage);
         const common = {
             review: s["review"],
@@ -1618,6 +1613,70 @@ const commands = {
                     : ["This is the first pass; there is no prior review to answer"],
             };
         }
+        if (sub === "pass") {
+            const p = parseFlags("forge pass", rest, { review: s["review"], out: s["out"] });
+            // Approve and close both end the review, so a pass has to be able to
+            // reach a finished one - but only when no active review answers first,
+            // or a review the reader finished last week shadows the one in hand.
+            const review = await resolveReview(str(p, "review")).catch((e) => {
+                if (e instanceof AxiError && e.code === "NOT_FOUND")
+                    return resolveReview(str(p, "review"), { terminal: true });
+                throw e;
+            });
+            const t = await readThreads(review.id);
+            const id = short(review.id);
+            const decision = t.decisions[t.decisions.length - 1];
+            if (!decision)
+                throw new AxiError(`review ${id} has no decision to carry to the forge`, "NOT_FOUND", [
+                    "The reader decides in the browser; nothing is posted before they submit",
+                    `Run \`thurview wait --review ${id}\` to block until they do`,
+                ]);
+            const plan = buildPass(t.threads, decision);
+            const out = resolve(process.cwd(), str(p, "out") ?? passFile(review.id));
+            const text = JSON.stringify(plan.submission, null, 2) + "\n";
+            // Checked by the parser `submit` reads it with, so a file this wrote is
+            // never one that command refuses.
+            parseSubmission(text, out);
+            await writeText(out, text);
+            return {
+                pass: {
+                    review: id,
+                    file: out,
+                    decision: plan.decision,
+                    verdict: plan.submission.verdict,
+                    ...(plan.verdictReason ? { why: plan.verdictReason } : {}),
+                    inline: plan.inline.length,
+                    summary: plan.summary.length,
+                    skipped: plan.skipped.length,
+                    anchoredAt: review.pins.head,
+                },
+                comments: plan.inline.length
+                    ? plan.inline.map((c) => ({ thread: c.thread, at: c.at, side: c.side }))
+                    : "0 (a summary-only pass)",
+                summary: plan.summary.length
+                    ? plan.summary.map((x) => ({ thread: x.thread, target: x.target, why: x.why }))
+                    : "0 (every comment is anchored to a line)",
+                skipped: plan.skipped.length
+                    ? plan.skipped.map((x) => ({ thread: x.thread, target: x.target, why: x.why }))
+                    : "0 (no question, resolved or held thread to leave out)",
+                help: [
+                    `Read ${out} before it is posted; the file is the thing a human checks`,
+                    `Every anchor is a line at ${review.pins.head.slice(0, 12)}; run \`thurview forge status --review ${id}\` first, because a forge refuses a comment on a line its current head does not have`,
+                    `Run \`thurview forge submit --review ${id} --file ${out} --dry-run\` to see what would reach the change request`,
+                    "Tell the reader which comments went to the summary, and why they are not on their line",
+                    ...(decision.revision === review.revision
+                        ? []
+                        : [
+                            `The decision is the reader's on revision ${decision.revision} and the review is at ${review.revision}; they have not judged what you published since`,
+                        ]),
+                    ...(review.binding.kind === "pr"
+                        ? []
+                        : [
+                            `This review is bound to ${review.binding.name}, not to a change request; \`forge submit\` will need --change <ref>`,
+                        ]),
+                ],
+            };
+        }
         if (sub === "submit") {
             const p = parseFlags("forge submit", rest, {
                 ...common,