@xbghc/warden 0.1.0 → 0.2.0

package/README.md

@@ -5,12 +5,15 @@ with line comments you can copy back to the agent as a prompt.
 
 - Runs as a single local process per repository (`127.0.0.1` only, no auth, no database).
 - Diff sources: working tree, staged, working tree vs HEAD, any commit, any two refs, and git worktrees.
+- Side-by-side **Unstaged** and **Staged** file lists, so staging a hunk in your editor is what marks it reviewed.
 - GitHub-style unified / side-by-side diff with syntax highlighting, collapsed file tree, lazy per-file loading, context expansion, virtual scrolling.
 - Line comments (single line or a dragged range), Markdown, edit / delete.
 - One click copies all comments as an agent-readable prompt to the clipboard.
-- Review state (viewed files, comments, local issues, preferences) persists outside the repo and survives restarts.
-- Comments re-attach to the code after the agent changes the file; when the commented code itself is gone they are marked *orphaned* and shown at the top of the file.
+- Review state (viewed files, comments, local issues, todos, preferences) persists outside the repo and survives restarts.
+- Comments follow the code: they move with a hunk that gets staged, re-attach after the agent edits the file, and are cleaned up once the change is committed.
+- Auto-refresh — warden watches the repository and reloads itself when you edit, stage, commit or switch branches.
 - Local issues (title, Markdown body, open/closed) that link comments.
+- Branch-scoped todos, exportable as a numbered checklist.
 - Commit history browser.
 - Click a line number to jump to that line in a running nvim instance (WSL2 friendly).
 - Read-only with respect to git: only whitelisted read sub-commands are ever executed.
@@ -50,12 +53,18 @@ Several instances on the same repository can run at the same time.
 Refs accept anything git can resolve (`main`, `v1.2`, `HEAD~3`, a sha). `@` is `HEAD`.
 Worktrees are discovered with `git worktree list` and share the review state of the main repository.
 
+`working`, `staged` and `all` are the three **local views** of one worktree. While any of them is
+selected the sidebar shows two blocks — Unstaged (`working`) and Staged (`staged`) — instead of a
+single tree, and clicking a file switches to the view it belongs to. A file that is only partly
+staged appears in both. Switching between the three keeps your comments, the draft you are typing
+and the current selection; only the diff is reloaded. Commit and range targets keep the single tree.
+
 ## Keyboard
 
 | Key | Action |
 |---|---|
 | `r` | Refresh the current target (file list + open diff, then re-anchor comments) |
-| `j` / `k` | Next / previous file |
+| `j` / `k` | Next / previous file, walking Unstaged then Staged and switching view at the boundary |
 | `n` / `p` | Next / previous hunk |
 | `Ctrl+Enter` | Save the comment being edited |
 | `Esc` | Cancel editing / close a panel / cancel re-attach mode |
@@ -98,12 +107,53 @@ Issues can be copied in the same format (with the issue title, status and body o
 
 Every comment stores a hash of its hunk, of each covered line and of three context lines above and
 below. On refresh the comment is re-attached in this order: same hunk still present → same relative
-position; otherwise search the file for the same line sequence (context lines disambiguate duplicates);
-otherwise it becomes *orphaned* and is listed at the top of the file with the original snippet, where it
-can be deleted or re-attached by picking a new selection.
+position; otherwise search the file for the same line sequence (context lines disambiguate duplicates).
+
+The three local views of a worktree share one pool of comments, and re-anchoring searches all of
+them — the comment's current view first, then `working`, `staged`, `all`. So:
+
+- Comment on an unstaged hunk, then `git add` it → the comment turns up in the Staged view,
+  unchanged. The card shows which view it moved to; clicking it jumps there.
+- The agent edits the commented line → nothing matches, and the comment becomes *orphaned*: listed
+  at the top of the rail with its original snippet, ready to be deleted or re-attached to a new selection.
+- `git commit` → re-anchoring notices HEAD moved. Comments that no longer have a home anywhere are
+  **deleted** (and unlinked from any issue), because the code they were about is now history.
+  Anything still visible in Unstaged or Staged survives, including as a context line.
+
+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.
+
+"Viewed" 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
+*已变化*.
+
+## Auto-refresh
+
+warden polls the worktree every 1.5 s while the page is open (`git status --porcelain`, HEAD, the
+branch name, plus mtime and size of the paths status reports — enough to notice a second edit to an
+already-modified file) and pushes a change event over `GET /api/events` (SSE). The page then re-runs
+the normal refresh: re-anchor, reload both file lists, reload the open diff. Your draft comment,
+selection, current view and current file are left alone, and the diff is scrolled back to where you
+were reading. Turn it off with the *自动刷新* checkbox; `r` still refreshes by hand.
+
+## Todos
 
-"Viewed" is bound to a hash of the file's diff. When the diff changes the flag is dropped and the file
-is marked *已变化*.
+Notes attached to a branch rather than to a line of code, for the things you notice while reviewing
+that do not belong in a comment. They are not deleted when you commit. The Todos drawer filters by
+status, defaults to the current branch and can show all branches; *复制 Todo* copies the open ones
+(optionally including the done ones, marked ` (done)`) as:
+
+```markdown
+# TODO
+Branch: feature/x
+Repo: /home/user/project
+Count: 2
+
+## 1. 补充 OrderList 的空状态
+描述正文（Markdown）…
+
+## 2. useOrder 的依赖数组缺少 id
+```
 
 ## nvim integration
 
@@ -128,6 +178,12 @@ jump to the nearest new-side line; for commit targets the working-tree file is o
 `schemaVersion`, written atomically (temp file + rename) under a small lock file so multiple instances
 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.
+
 ## WSL2 notes
 
 - Access the UI from the Windows browser at the printed `http://127.0.0.1:<port>/` URL; WSL2 forwards
@@ -150,7 +206,7 @@ repository. Requests that would need anything else get HTTP 400.
 ```sh
 pnpm install
 pnpm dev          # API server on :4100 (tsx watch) + Vite dev server on :5173 with /api proxied
-pnpm test         # vitest: diff parser, anchoring, export format, state store, HTTP API on a temp repo
+pnpm test         # vitest: diff parser, anchoring, comment scopes, watcher, todos, export, state, HTTP API
 pnpm typecheck
 pnpm build        # dist/web (Vite) + dist/cli.js (tsup, zero runtime dependencies)
 node dist/cli.js path/to/repo
@@ -160,8 +216,8 @@ Layout:
 
 ```
 bin/cli.ts           argument parsing, start server, open browser
-packages/shared      types + target key helpers (bundled into both sides)
-packages/server      Hono API, git wrapper, diff parser, targets, anchoring, state, export, nvim
+packages/shared      types + target key / comment scope helpers (bundled into both sides)
+packages/server      Hono API, git wrapper, diff parser, targets, anchoring, watcher, state, export, nvim
 packages/web         React + Vite UI (shiki highlighting, @tanstack/react-virtual, react-markdown)
 test/                API integration tests on a generated git repository
 ```
@@ -169,10 +225,12 @@ test/                API integration tests on a generated git repository
 Only `dist/`, `README.md`, `LICENSE` and `package.json` are published.
 
 Releasing: bump `version` in `package.json`, commit, then push a matching tag —
-`git tag v0.1.0 && git push --tags`. The `Publish to npm` workflow checks the tag against the version,
-runs build + tests through `prepublishOnly`, and publishes with the `NPM_TOKEN` repository secret
-(an npm automation token). CI runs typecheck, tests, build and a `publish --dry-run` on every push to
-`main` and every pull request.
+`git tag v0.2.0 && git push origin v0.2.0`. The `Publish to npm` workflow checks the tag against the
+version, runs build + tests through `prepublishOnly`, and publishes over OIDC trusted publishing —
+no `NPM_TOKEN` secret, and provenance is attested automatically. It relies on a trusted publisher
+configured on the package's npmjs.com settings page (user `xbghc`, repo `warden`, workflow
+`publish.yml`). CI runs typecheck, tests, build and a `publish --dry-run` on every push to `main` and
+every pull request.
 
 ## License