@xbghc/warden 0.11.1 → 0.13.0

package/README.md

@@ -43,13 +43,20 @@ or install globally:
 
 ```sh
 npm i -g @xbghc/warden
-warden [repoPath] [--port <n>] [--no-open]
+warden [repoPath] [--port <n>] [--no-open] [--no-update-check]
 ```
 
 The server picks the first free port from 4100 (or `--port`), prints the URL and tries to open a
 browser via `wslview`, `explorer.exe`, then `xdg-open`. If none of those exist it only prints the URL.
 Several instances on the same repository can run at the same time.
 
+On start warden asks the npm registry whether a newer release exists, at most once a day (the answer
+is cached in `~/.local/share/warden/update-check.json`). When there is one, a line in the terminal
+and a chip beside the wordmark say so; clicking the chip copies the command — `npx @xbghc/warden@latest`
+for an npx run, whose cache otherwise keeps serving the old copy, `npm i -g @xbghc/warden@latest`
+for a global install. The check never delays startup and fails silently. `--no-update-check`,
+`WARDEN_NO_UPDATE_CHECK=1`, `NO_UPDATE_NOTIFIER=1` or `CI` turn it off.
+
 ## Targets (what is being reviewed)
 
 | Target | Key | Git equivalent |
@@ -89,6 +96,10 @@ has no control of its own (a saved `lastTarget` can still restore it; *审阅整
 the same diff). Commit, range and `base` targets keep the single tree, and their figure counts 已读
 instead, since nothing can be staged there.
 
+So there is one mark of "done" per kind of target, never two. In the local views it is staging and
+nothing else: a row has no 已读 box, and which block a file sits in is the whole of its review state.
+Everywhere else it is the [已读 mark](#viewed-files).
+
 `base:<ref>` is for a branch a coding agent has been working on, committing as it goes: one tree with
 everything since the branch forked off `<ref>` — the commits plus whatever is still uncommitted or
 untracked. The diff runs against the merge base, so commits that landed on `<ref>` after the fork are
@@ -175,8 +186,7 @@ A partial pick is turned into the patch `git add -p`'s edit mode would want —
 stay as context and the unpicked additions are left out (the mirror image when unstaging) — and applied
 with `git apply --cached`. It never touches the working tree, so what you did not pick is still
 there to stage next. Comments on the lines you staged follow them into the Staged view (see
-[Re-anchoring](#re-anchoring)); the file's *viewed* flag is dropped because its diff changed. Every
-page open on the worktree reloads at once.
+[Re-anchoring](#re-anchoring)). Every page open on the worktree reloads at once.
 
 Limits, each reported as a plain error rather than a half-applied patch:
 
@@ -251,9 +261,13 @@ them deletes on a moved HEAD.
 Comment markers in the diff belong to one view; the rail's *全部* tab lists the whole pool and
 *此文件* lists every comment on the open file regardless of which view it currently sits in.
 
-*已读* is per view, so a half-staged file can be marked read on one side and not the other. It is
-bound to a hash of the file's diff; when the diff changes the flag is dropped and the file is marked
-*已变化*.
+## Viewed files
+
+Commit, range and `base` targets cannot be staged from, so a file there is ticked *已读* instead — the
+box beside it in the sidebar, or the one in the file header. A directory whose files are all read
+recedes with a check. The mark is bound to a hash of the file's diff: when the diff changes (a `base`
+target reads the working tree, so the agent's next edit does that) the mark is dropped and the file
+is flagged *已变化*. The local views keep no such mark — see [Targets](#targets-what-is-being-reviewed).
 
 ## Auto-refresh
 
@@ -325,9 +339,10 @@ can share it. Delete the directory to reset.
 
 `targets` is keyed by target key, plus one *comment scope* per worktree — `local`, or
 `worktree:<path>:local` — holding the comments the three local views share and the HEAD sha the last
-re-anchor saw. `viewed` stays on the individual view keys. Issues and todos are top level. State
-written by an older version is migrated on load: comments filed under `working` / `staged` / `all`
-move into the matching scope the first time the file is read.
+re-anchor saw. `viewed` sits on the key of the commit, range or `base` target it was ticked in; the
+local view keys hold nothing. Issues and todos are top level. State written by an older version is
+migrated on load: comments filed under `working` / `staged` / `all` move into the matching scope the
+first time the file is read, and the 已读 marks those views used to keep are dropped.
 
 ## WSL2 notes
 
@@ -362,6 +377,11 @@ the repository. A mutating request the
 browser labels as coming from another site (`Sec-Fetch-Site: cross-site`) is refused with 403, so a
 page from elsewhere cannot drive the server through the browser it is open in.
 
+The only request warden makes off the machine is the update check: a `GET` of
+`https://registry.npmjs.org/@xbghc%2fwarden/latest`, no more than once a day, carrying nothing about
+the repository or the review. `--no-update-check` (or the environment switches under *Install / run*)
+removes it.
+
 ## Development
 
 ```sh