thurview 0.19.0 → 0.21.0

package/dist/ui/index.html

@@ -4,6 +4,27 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>thurview</title>
+    <script>
+      // Before first paint, so the page never flashes the other palette: the
+      // reader's pick from the menu wins, and "system" follows the OS, live.
+      (() => {
+        const os = matchMedia("(prefers-color-scheme: dark)");
+        // `chosen` is the menu's pick, so it applies even where storage is blocked
+        const apply = (chosen) => {
+          let pick = typeof chosen === "string" ? chosen : "system";
+          if (typeof chosen !== "string")
+            try {
+              pick = localStorage.getItem("thurview.theme") || "system";
+            } catch {}
+          const root = document.documentElement;
+          root.dataset.themePick = pick;
+          root.dataset.theme = pick === "system" ? (os.matches ? "dark" : "light") : pick;
+        };
+        os.addEventListener("change", () => apply(document.documentElement.dataset.themePick));
+        window.thurviewTheme = apply;
+        apply();
+      })();
+    </script>
     <link rel="stylesheet" href="/app.css" />
   </head>
   <body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thurview",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Guided, evidence-anchored reviews of agent-written code. A coding agent authors the review; you read, ask, comment and decide in the browser.",
   "license": "MIT",
   "type": "module",

package/skills/thurview/SKILL.md

@@ -85,8 +85,7 @@ Read [Document authoring](references/document-authoring.md) before you write.
 Read [Components](references/components.md) before you edit `data.yaml` or add
 a fenced component. Read [Lifecycle](references/lifecycle.md) for statuses,
 storage and thread rules. Read [Software map](references/software-map.md)
-before you author `map.yaml`. Read [Theme](references/theme.md) before you
-write `theme.yaml`.
+before you author `map.yaml`.
 
 ## Workflow
 
@@ -110,7 +109,7 @@ head), when you need to choose between several.
 
 Record from the output: `review.id` (the short id, accepted everywhere),
 `review.dir`, `review.base`, `review.head`, `files.document`, `files.data`,
-`files.map`, `files.theme`, `change` (files, additions, deletions) and
+`files.map`, `change` (files, additions, deletions) and
 `guidance`.
 
 Resolve refs before passing them. Pass commit ids or plain ref names; do not
@@ -237,14 +236,7 @@ not, and publishes as "not assessed". See
 [Document authoring](references/document-authoring.md) and
 [Components](references/components.md).
 
-### 6. Theme the review after the project
-
-Read [Theme](references/theme.md). Decide the look in its order: what the
-user asked for, then the reviewed project's own design system read from its
-files at head, then the default skin. Write `theme.yaml` in the review
-directory when steps 1 or 2 yield tokens; leave it empty otherwise.
-
-### 7. Publish
+### 6. Publish
 
 ```sh
 thurview publish --review <id>
@@ -252,7 +244,7 @@ thurview publish --review <id>
 
 Read every row of `diagnostics`. Fix each `error` and publish again. A
 `warning` does not block. `publish` refuses (code `THREADS_OPEN`) when a
-submitted comment thread is still open (see step 10). On success `published`
+submitted comment thread is still open (see step 9). On success `published`
 carries `rev` and `url`; the status becomes `awaiting-review`.
 
 Then open it for the reader, unless step 2 already did:
@@ -261,7 +253,7 @@ Then open it for the reader, unless step 2 already did:
 thurview open --review <id>            # prints url; --view files|commits|map
 ```
 
-### 8. Hand over
+### 7. Hand over
 
 Tell the user, in a few lines and nothing more:
 
@@ -271,8 +263,6 @@ Tell the user, in a few lines and nothing more:
 - the interface delta `verdict`, in its own words
 - the `security` verdict, in one clause: what the change crosses, or that it
   crosses nothing
-- which theme source you used: the user's request, the project's design
-  system (name the files), or the default skin
 - when the review has no map, why not, in one clause
 - that you are now waiting for their questions and their decision, and that
   a question asked after you stop waiting is queued rather than lost - the
@@ -280,7 +270,7 @@ Tell the user, in a few lines and nothing more:
 
 The page explains its own controls; do not describe them.
 
-### 9. Wait for the reader
+### 8. Wait for the reader
 
 ```sh
 thurview wait --review <id> --timeout <seconds>
@@ -307,14 +297,14 @@ worktree.
   not change the document for a question. Wait again.
 - `awaiting-agent-updates`: the reader submitted with "Request changes".
   `threads` lists what to address and `wait.decision` the summary. Go to
-  step 10.
+  step 9.
 - `accepted`: approved. Report and stop.
 - `closed`: the reader ended the review without approving it. Report and stop.
 - `review-dismissed` or `review-deleted`: stop.
 - `timeout`: nothing happened. Wait again, or tell the user the reader has not
   responded and stop.
 
-### 10. Address requested changes
+### 9. Address requested changes
 
 For each thread in `thurview threads list --review <id> --open`:
 
@@ -327,8 +317,8 @@ For each thread in `thurview threads list --review <id> --open`:
 - `thurview threads resolve <threadId> --review <id>` once the requested
   change is present. Do not resolve a thread you did not address.
 
-Then publish again (step 7), tell the user what changed since the previous
-revision in a line or two, and wait again (step 9). A republish requires zero
+Then publish again (step 6), tell the user what changed since the previous
+revision in a line or two, and wait again (step 8). A republish requires zero
 open submitted comment threads; questions do not block.
 
 ## Sharing a copy that needs no server

package/skills/thurview/references/document-authoring.md

@@ -148,7 +148,6 @@ sequence diagram beats one with four.
 
 ## Files you edit
 
-Only `review.md`, `data.yaml`, `map.yaml` and `theme.yaml` in the review
-directory. Never
+Only `review.md`, `data.yaml` and `map.yaml` in the review directory. Never
 edit `review.json`, `threads.json` or `revisions/`. Threads change only
 through `thurview threads`.

package/skills/thurview/references/lifecycle.md

@@ -139,7 +139,6 @@ ${THURVIEW_HOME:-~/.thurview}/
     ├── review.md            you edit
     ├── data.yaml            you edit
     ├── map.yaml             you edit
-    ├── theme.yaml           you edit (project look; empty = default skin)
     ├── review.json          binding, pins, status, presented revision
     ├── threads.json         threads and decisions (use the CLI)
     └── revisions/<n>/       sealed copies plus compiled document.json, map.json

package/skills/thurview-design/SKILL.md

@@ -75,11 +75,11 @@ Read the guidance files that exist, in this order; the second wins on conflict.
 `thurview design` lists the ones it found under `guidance`.
 
 The `thurview` skill ships the references this one shares — components,
-software map, theme, lifecycle. `thurview skill` prints the path of every
+software map, lifecycle. `thurview skill` prints the path of every
 bundled SKILL.md; the references sit beside each one. Read **Components**
 before you edit `data.yaml`, **Software map** before you author `map.yaml`,
-**Theme** before you write `theme.yaml`, and **Lifecycle** for statuses,
-storage and thread rules — they are identical for all three kinds.
+and **Lifecycle** for statuses, storage and thread rules — they are identical
+for all three kinds.
 
 ## Workflow
 
@@ -213,10 +213,7 @@ The Map tab is where a design shows structure. Put the structure it
 A design that changes one part in place does not raise the question: leave
 `nodes: []` and say so in the handover.
 
-### 6. Theme, then publish
-
-Write `theme.yaml` per the `thurview` skill's Theme reference, or leave it
-empty for the default skin. Then:
+### 6. Publish
 
 ```sh
 thurview publish --review <id>

package/skills/thurview-explain/SKILL.md

@@ -62,12 +62,12 @@ Read the guidance files that exist, in this order; the second wins on conflict.
 `thurview explain` lists the ones it found under `guidance`.
 
 The `thurview` skill ships the references this one shares - document authoring,
-components, software map, searching the code, theme, lifecycle. `thurview skill` prints the path of
+components, software map, searching the code, lifecycle. `thurview skill` prints the path of
 every bundled SKILL.md; the references sit beside each one. Read **Document
 authoring** before you write `review.md`, **Components** before you edit
 `data.yaml`, **Software map** before you author `map.yaml`, **Searching the
-code** before you look for callers, tests or importers, **Theme** before you
-write `theme.yaml`, and **Lifecycle** for statuses, storage and thread rules -
+code** before you look for callers, tests or importers, and **Lifecycle** for
+statuses, storage and thread rules -
 they are identical for all three kinds.
 
 Run the CLI as `thurview`; `npx -y thurview` runs the published package with
@@ -212,14 +212,13 @@ the code" - not a finding.
    `interfaces` in `data.yaml` is an error. So is `security`, which is what a
    change carries input across and an explainer has no change. So is
    `graph: base` on an anchor - there is one commit.
-5. `theme.yaml` as usual - see **Theme**.
-6. `thurview publish --review <id>`. Read `coverage` and `notExamined`. If the
+5. `thurview publish --review <id>`. Read `coverage` and `notExamined`. If the
    split is not the one you meant, anchor, place or search more and publish
    again.
-7. `thurview open --review <id>`, then `thurview wait --review <id>`. The loop,
+6. `thurview open --review <id>`, then `thurview wait --review <id>`. The loop,
    the statuses and the thread rules are identical to a review; see
    **Lifecycle**.
-8. To share it beyond the browser, `thurview export --review <id> --out <path>`
+7. To share it beyond the browser, `thurview export --review <id> --out <path>`
    writes a static, read-only copy - see the `thurview` skill's **Sharing a
    copy that needs no server**.
 

package/skills/thurview-pr-review/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: thurview-pr-review
+description: Review a pull or merge request on the forge itself and follow it until it merges - one short summary with a confidence score that is edited in place, one resolvable inline thread per finding in a fixed set of categories, threads resolved as their findings are fixed, and only what each push changed re-reviewed. Use when the user asks to review a PR or MR and post the review on it, to watch or follow a PR until it lands, for a Greptile-style or bot-style review, or invokes /thurview-pr-review. Not for a review the reader opens in the browser, which is the thurview skill, nor for fixing what a review finds, which is thurview-fix.
+user-invocable: true
+argument-hint: "<PR or MR number or URL> [--once] [--stop]"
+---
+
+# thurview-pr-review
+
+Review a change request where its author already is, and keep the review true
+until the change request is merged or closed. The forge holds all the state:
+one summary note with a hidden marker, one thread per finding with a hidden
+marker. Nothing is kept on this machine, so the loop can die and resume
+anywhere.
+
+```mermaid
+flowchart LR
+  W[wait] -->|push| R[review only what moved]
+  R --> S[sync: new threads, resolve fixed, edit summary]
+  S --> W
+  W -->|merged, closed, stopped| E[summary says so; stop]
+  W -->|none| W
+```
+
+Run the CLI as `thurview`, or `npx -y thurview` when it is not on PATH. It
+prints TOON, and exit code 2 is a usage error. If it answers `unknown flag` or
+`unknown command` for something below, run `thurview update` and retry once.
+
+## Request
+
+$ARGUMENTS
+
+`--once` posts one pass and stops there. `--stop` runs
+`thurview pr-review stop --change <ref>` and nothing else.
+
+## Never
+
+- Never approve, merge, close or push to the change request. The verdict is
+  the summary's confidence. The command has no verb for any of those, and you
+  do not reach around it with `gh` or `glab`.
+- Never post a second summary. `sync` edits the one it finds.
+- Never post a finding you are not sure of. Leave it out and say in a risk
+  bullet that something was not confirmed.
+- Never post what you would not sign. Follow the user's own rules for text
+  posted in their name when they keep any - a sign-off line goes in `signoff`.
+
+## 1. Where the review stands
+
+```sh
+thurview pr-review status --change <ref>
+```
+
+It prints the change request's head and base, the head the last pass reviewed
+(`review.reviewedHead`), every open finding with its `id`, and the categories
+and confidence scale below. A stopped review stays stopped: do not sync it.
+
+## 2. Review only what moved
+
+- No summary yet: review `git diff <base> <head>`, the whole change.
+- A summary at an older head: review `git diff <reviewedHead> <head>`. When
+  `git merge-base --is-ancestor <reviewedHead> <head>` fails, the branch was
+  rewritten: review the whole change again.
+
+Fetch the head first (`gh pr checkout <n>` or `glab mr checkout <n>`, or
+`git fetch origin <fetchRef>`), and search at the pinned commits with the
+recipes in the `thurview` skill's Searching the code reference
+(`thurview skill` prints its path). The evidence rules are `thurview-fix`'s:
+a problem just as present at the base is not this change's finding, and a
+finding that rests on "no callers" says which search found none.
+
+Then decide each open finding against the new head: **fixed**, or **still
+valid** (do nothing - its thread stays open and is not posted again).
+
+## 3. Findings
+
+One point per finding, on a line the diff touches - the forge refuses any
+other line. Prefer one real defect over many nits.
+
+| Category          | Definition                                                                     |
+| ----------------- | ------------------------------------------------------------------------------ |
+| `bug`             | The code does the wrong thing for an input it accepts.                         |
+| `security`        | An attacker gains access, data or execution they should not have.              |
+| `performance`     | Time, memory or calls grow worse than the change needs.                        |
+| `reliability`     | A failure, retry, timeout or race is handled wrongly or not at all.            |
+| `compatibility`   | A public API, schema, config, flag or data format breaks its callers.          |
+| `maintainability` | The next change here is harder: duplication, dead code, a misleading name.     |
+| `tests`           | A behaviour the change adds or alters is not tested, or a test proves nothing. |
+| `docs`            | A comment, README or doc now says something the code does not do.              |
+
+Severity is `blocking` (must be fixed before merge), `non-blocking` (worth
+fixing) or `nit` (taste, and the comment says `nit:`).
+
+Confidence that the change is safe to merge:
+
+| Score | Meaning                                                     |
+| ----- | ----------------------------------------------------------- |
+| 5     | Safe to merge; nothing open beyond nits.                    |
+| 4     | Safe to merge; non-blocking findings are worth a look.      |
+| 3     | Unsure: a risk is named that the review could not rule out. |
+| 2     | Not yet: a blocking finding is open.                        |
+| 1     | Do not merge: it breaks something that works today.         |
+
+An open blocking finding caps confidence at 2; `sync` refuses more.
+
+## 4. Sync
+
+Write `pass.json` for this head. `findings` holds only what is new; `fixed`
+holds the ids of open findings this push fixed:
+
+```json
+{
+  "head": "<the full sha you reviewed>",
+  "confidence": 2,
+  "reason": "Safe once the retry loop stops on a 4xx.",
+  "risk": ["Every upload goes through the changed retry path.", "No test covers a 4xx."],
+  "change": "Retries a failed upload three times with exponential backoff.",
+  "reviewUrl": "https://reviews.example.com/pr-7/",
+  "signoff": "<the user's sign-off line, when they keep one>",
+  "findings": [
+    {
+      "category": "bug",
+      "severity": "blocking",
+      "path": "src/upload.ts",
+      "line": 42,
+      "startLine": 40,
+      "title": "The retry loop never stops on a 4xx.",
+      "body": "Return the response on any status below 500.",
+      "suggestion": "if (res.status < 500) return res;"
+    }
+  ],
+  "fixed": ["3f2a9c1b07"]
+}
+```
+
+- `head` is the commit you reviewed. `sync` refuses the pass when the change
+  request moved on since: review what the new push added, then sync again.
+- `reason`, `change`, `signoff` and each `risk` bullet are one line each;
+  `sync` refuses a line break in any of them. `reason` is one sentence;
+  `risk` is one to five bullets naming what could break, the blast radius, and
+  anything touching security, data, infra or a public API; `change` is two or
+  three sentences.
+- The summary is capped at 120 words, the counts table aside. `sync` refuses
+  more: cut to what the author acts on.
+- A finding's `title` is the claim in one line, `body` the fix. Title, body
+  and sign-off together fit five lines. `suggestion` replaces the lines from
+  `startLine` to `line` and is optional.
+- `reviewUrl` links the full rendered review. When the user has a publish
+  target - `thurview export --out <folder>` into a Pages folder or a static
+  host they serve - publish there and pass its URL. With none, leave it out.
+
+```sh
+thurview pr-review sync --change <ref> --file pass.json --dry-run
+thurview pr-review sync --change <ref> --file pass.json
+```
+
+The dry run prints the summary as it will read. A finding already open is
+reported under `duplicates` and not posted twice.
+
+## 5. Follow
+
+```sh
+thurview pr-review wait --change <ref>      # --interval 120 --timeout 540 by default
+```
+
+It blocks until there is something to do and prints one `event`:
+
+| Event                         | Do                                           |
+| ----------------------------- | -------------------------------------------- |
+| `push`                        | back to step 2, with `since` as the old head |
+| `none`                        | run `wait` again                             |
+| `merged`, `closed`, `stopped` | stop: the summary already says so            |
+
+With `--once`, stop after the first sync.
+
+A reader stops the loop with the `thurview:stop` label or a comment that
+starts `/thurview stop`; you stop it with `thurview pr-review stop`. A stopped
+review resumes with `thurview pr-review start --change <ref>` once the label
+is gone. Report what you posted and the summary's link when the loop ends.
+
+How GitHub and GitLab differ, and what each supports, is in
+[Forges](references/forges.md).

package/skills/thurview-pr-review/references/forges.md

@@ -0,0 +1,47 @@
+# Forges
+
+`thurview pr-review` drives the same seam as `thurview forge`: `gh api` for
+GitHub and `glab api` for GitLab, a self-hosted host owned by whichever CLI is
+authenticated for it. The seam has no merge, close or push, so neither does
+this command.
+
+## What each forge does
+
+| Step              | GitHub                                     | GitLab                                              |
+| ----------------- | ------------------------------------------ | --------------------------------------------------- |
+| The summary       | one issue comment, `PATCH`ed in place      | one merge request note, `PUT` in place              |
+| A finding         | one review comment, a resolvable thread    | one diff discussion, a resolvable thread            |
+| A line range      | anchored as the range                      | anchored at its last line                           |
+| A suggestion      | ` ```suggestion ` over the range           | ` ```suggestion:-N+0 ` reaching back over the range |
+| Resolving a fixed | a reply, then `resolveReviewThread`        | a reply, then `PUT .../discussions/<id>` resolved   |
+| The stop label    | `thurview:stop` among the pull's labels    | `thurview:stop` among the merge request's labels    |
+| The stop command  | an issue comment starting `/thurview stop` | a top-level note starting `/thurview stop`          |
+| Merged or closed  | `merged`, or `state: closed`               | `state: merged` or `closed`                         |
+
+## Where the state lives
+
+The summary carries
+`<!-- thurview-pr-review {"head":"<sha>","state":"active","seen":"<note id>"} -->`
+and each finding's first comment
+`<!-- thurview-finding {"id":"<id>","category":"bug","severity":"blocking"} -->`.
+`state` is `active`, `stopped`, `merged` or `closed`. `seen` is the newest
+note already read, so a `/thurview stop` posted before a `start` stops nothing.
+Only a summary posted by the account the CLI is logged in as counts, so a
+pasted marker changes nothing. A finding's id is the `id` given in the pass, or a hash of its category, path
+and title, which is how the same finding found on the next push is recognised.
+
+## Gaps
+
+- No forge approve. A forge approve can arm an auto-merge, and the verdict
+  lives in the summary; `thurview forge submit` is the command for one.
+- GitHub reads the newest 100 review threads (`reviewThreads(last:100)`), the
+  same limit `thurview forge prior` has; GitLab reads every page.
+- Every call asks the forge who it is (`gh api user`, `glab api user`) to
+  tell its own markers from pasted ones, so it needs a token that can read its
+  own user; a GitHub App installation token cannot.
+- A finding must sit on a line the diff touches. A finding on an untouched
+  caller goes in a risk bullet.
+- GitLab reports no per-thread staleness, and its adapter is driven by stub
+  tests but has not been run against a live instance.
+- The full-review link is whatever URL the pass names; this command publishes
+  nothing itself.