@xbghc/warden 0.7.0 → 0.9.0

package/README.md

@@ -6,6 +6,7 @@ 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, a branch since it forked off its base (commits and
   uncommitted work together), any commit, any two refs, and git worktrees.
+- Worktrees are made and taken down from the page, one per agent branch, with the path ready to paste.
 - Side-by-side **Unstaged** and **Staged** file lists: staged means reviewed. Stage from the UI by dragging
   over the lines you have read (or a hunk, or a file), and unstage the same way from the Staged view.
 - GitHub-style unified / side-by-side diff with syntax highlighting, collapsed file tree, lazy per-file loading, context expansion, virtual scrolling.
@@ -60,31 +61,36 @@ Several instances on the same repository can run at the same time.
 | Worktree, everything since base | `worktree:<path>:base:<ref>` | same, run inside the worktree |
 
 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.
+Worktrees are discovered with `git worktree list` (and made in the *Worktrees* tab, see below) and
+share the review state of the main repository.
 One whose directory is gone (git lists it as *prunable*) is not offered, and a remembered target
 inside a removed worktree falls back to the working tree on the next load. The comments and viewed
 flags kept under that worktree's key stay in the state file and come back if a worktree is created
 at the same path again.
 
-There is no target switcher in the UI: the sidebar's two blocks *are* the working tree, a commit is
-picked from the *Commits* panel, and the *Branch vs* and *Range* fields at the top of that panel open
-the other two. The sidebar names whatever is under review in its block header and puts a
+The sidebar is the navigation, and the only navigation: its three tabs — *变更*, *提交*, *Worktree* —
+each fill the left column with the controls for what the middle is showing, and the top bar carries
+none of it. There is no target switcher: the *变更* tab's two blocks *are* the working tree, a commit
+is picked from the *提交* list, and the *审阅整条分支* and *对比两个 ref* forms below that tab's filters
+open the other two. The sidebar names whatever is under review in its block header and puts a
 *返回工作区* link above it.
 
 `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
+selected the sidebar shows two blocks — 未暂存 (`working`) and 已暂存 (`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. `all` has no control of its own (a saved
-`lastTarget` can still restore it; *Branch vs* `@` shows the same diff). Commit, range and `base`
-targets keep the single tree.
+staged appears in both. Above them sits the one figure in the app: how many of the files under review
+are fully staged, which is what "staged means reviewed" amounts to. Switching between the three keeps
+your comments, the draft you are typing and the current selection; only the diff is reloaded. `all`
+has no control of its own (a saved `lastTarget` can still restore it; *审阅整条分支* against `@` shows
+the same diff). Commit, range and `base` targets keep the single tree, and their figure counts 已读
+instead, since nothing can be staged there.
 
 `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
-not listed as reverted (which is what a plain `git diff <ref>` would do). The *Branch vs* field in the
-Commits panel suggests the base for you — the main worktree's branch when a sibling worktree is under
-review, otherwise `main` or `master` — and takes any ref. Beside it the panel names the fork point (the
+not listed as reverted (which is what a plain `git diff <ref>` would do). The *相对于* field under
+*审阅整条分支* suggests the base for you — the main worktree's branch when a sibling worktree is under
+review, otherwise `main` or `master` — and takes any ref. Under it the form names the fork point (the
 merge base with that ref, `GET /api/fork-point`) with how many commits the branch is ahead of it and how
 many landed on the base since, and the list marks that commit with a *分叉自* chip and a rule above it:
 what sits above is the branch's own work. Unlike the three local views, `base` keeps its own
@@ -92,6 +98,29 @@ pool of comments and a commit never deletes them: the round under review is not
 commits, so a comment whose lines changed stays *orphaned*, snippet and all, until you have checked
 the fix and delete or re-attach it.
 
+## Worktrees
+
+Agents do their best work each in a worktree of its own, and the sidebar's *Worktree* tab is
+where those are made and taken down without a trip to the terminal:
+
+- *新建 worktree*, the form in the sidebar, takes a branch and a base. A name that is not a branch yet becomes one from the
+  base (`main` or `master` unless you say otherwise; any ref goes) — `git worktree add -b <branch>
+  <path> <base>`; an existing branch is checked out as it is, unless another worktree already has it.
+  The path is suggested as a sibling of the main worktree named `<repo>-<branch>` (slashes become
+  dashes) and can be edited, within limits: it has to sit under the main worktree's parent directory,
+  outside every existing worktree, and be new or an empty directory.
+- Each row names the checkout, its branch, and whether it is clean or how many paths `git status`
+  reports. *查看* switches the review to it (the kind of target carries over, as with the selector
+  in the top bar), *复制路径* is for the agent's prompt.
+- *删除* always asks first, in the row it would remove, and runs `git worktree remove` without
+  `--force`: a worktree with uncommitted changes is not removed until you confirm again, since those
+  changes go with it, and whatever else git refuses without `--force` is put to you the same way.
+  *一并删除分支* is offered in that same confirmation, ticked by default, and takes the branch by
+  `git branch -d`: one that is not merged is kept and the toast says why. The comments and viewed
+  flags kept under the worktree's key stay in the state file, as before.
+- A worktree whose directory was deleted behind git's back is listed struck through; *清理* drops that
+  one entry (`git worktree remove` handles it; nothing is pruned wholesale).
+
 ## Keyboard
 
 | Key | Action |
@@ -101,7 +130,7 @@ the fix and delete or re-attach it.
 | `n` / `p` | Next / previous hunk |
 | `s` | Stage (Unstaged view) or unstage (Staged view) the picked lines |
 | `Ctrl+Enter` | Save the comment being edited |
-| `Esc` | Drop the picked lines / cancel editing / close a panel / cancel re-attach mode |
+| `Esc` | Drop the picked lines / cancel editing / cancel re-attach mode / shut the rail / back to 变更 |
 
 ## Staging
 
@@ -132,12 +161,18 @@ Limits, each reported as a plain error rather than a half-applied patch:
 
 ## Comments and export
 
-Press the `+` that appears next to a line (drag to cover several lines) and write Markdown.
+Press the `+` that appears next to a line (drag to cover several lines) and write Markdown. What you
+write lands in the right-hand rail, which is shut until it has something to hold: it costs 360px of
+the code column, which is most of it once the diff is side by side on a laptop. Writing a comment,
+focusing one or re-attaching one opens it; so does the *评论* switch at the right of the top bar,
+which carries the count and turns violet while any comment is still waiting to go back to the agent.
+`Esc` shuts it again.
+
 Each comment belongs to the `old` or `new` side of the diff and has a status:
 
-- `active` — not yet exported
-- `exported` — copied at least once (excluded from "copy all" unless *含已导出* is checked)
-- `orphaned` — the code it referred to no longer exists in the current diff
+- `active` (待导出) — not yet exported
+- `exported` (已导出) — copied at least once (excluded from "copy all" unless *含已导出* is checked)
+- `orphaned` (已失联) — the code it referred to no longer exists in the current diff
 
 "复制评论" copies every active comment of the current target; each comment also has a "复制此条" button.
 The clipboard format is fixed so an agent can read it directly:
@@ -187,7 +222,7 @@ 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.
 
-"Viewed" is per view, so a half-staged file can be marked read on one side and not the other. It is
+*已读* 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
 *已变化*.
 
@@ -205,9 +240,9 @@ refreshes by hand.
 
 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. They sit in the right-hand
-rail next to the comments, under the *Todo* tab, as a task list that works the way Google Tasks does:
+rail next to the comments, under the *待办* tab, as a task list that works the way Google Tasks does:
 
-- *添加 Todo* opens an empty row at the top; type the title and press Enter, and the next row opens
+- *添加待办* opens an empty row at the top; type the title and press Enter, and the next row opens
   right under it. Esc or Backspace on an empty row drops it.
 - Titles and details are edited where they are: click into the text. Enter at the end of a title
   starts the next todo under it; Backspace on an emptied title deletes the todo. The details field
@@ -220,10 +255,10 @@ rail next to the comments, under the *Todo* tab, as a task list that works the w
 - The picker at the top is the list selector: the current branch, any other branch that has todos,
   or all of them with the branch on each row. A new todo goes to the branch being shown.
 
-Issues (the *Issues* tab in the top bar) are the same list: closing an issue is ticking it, a
+Issues (the rail's third tab) are the same list: closing an issue is ticking it, a
 *已关闭* section holds the closed ones, and the comments linked to an issue sit under its open row
 like subtasks, each with *跳转* and *解除关联*. Tick comments in the rail and the *创建 Issue* button
-opens the drawer with the add row ready and the comments attached on creation; for an existing
+switches to that tab with the add row ready and the comments attached on creation; for an existing
 issue, open its row and use *关联选中的评论*.
 
 Each row has its own *复制* button, and there is deliberately no "copy all": a todo is one task to
@@ -280,18 +315,24 @@ move into the matching scope the first time the file is read.
 Single user, local only. The server binds to `127.0.0.1` and executes git only through
 `execFile('git', [...])`. Reads go through an argument whitelist (`rev-parse`, `diff`, `show`, `log`,
 `worktree list`, `ls-files`, `status`, `merge-base`, `rev-list`) that refuses option-looking refs and any write-capable
-flag; requests that would need anything else get HTTP 400. The one write is `POST /api/targets/:key/stage`,
-which runs `git apply --cached` (with `--reverse` for the Staged view) on a patch the server itself builds
-from the diff it just produced — the patch is never taken from the request, only the line indices are,
-and they are checked against the diff's hash first. Nothing writes to the working tree, HEAD or the
-refs, and the review state lives outside the repository.
+flag; requests that would need anything else get HTTP 400. The writes are few and each composes its
+own arguments. `POST /api/targets/:key/stage` runs `git apply --cached` (with `--reverse` for the
+Staged view) on a patch the server itself builds from the diff it just produced — the patch is never
+taken from the request, only the line indices are, and they are checked against the diff's hash
+first. `POST /api/worktrees` and `POST /api/worktrees/remove` run `git worktree add`, `git worktree
+remove` and `git branch -d` with a branch name git has validated, a ref that resolves, and a
+path confined to the main worktree's parent directory. Nothing writes to the working tree or HEAD of
+an existing checkout; refs change only when a worktree is made (its new branch) or removed (its merged
+branch, on request), and the review state lives outside 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.
 
 ## Development
 
 ```sh
 pnpm install
 pnpm dev          # API server on :4100 (tsx watch) + Vite dev server on :5173 with /api proxied
-pnpm test         # vitest: diff parser, staging patches, anchoring, comment scopes, watcher, todos, export, state, HTTP API
+pnpm test         # vitest: diff parser, staging patches, anchoring, comment scopes, watcher, todos, worktrees, 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
@@ -302,7 +343,7 @@ Layout:
 ```
 bin/cli.ts           argument parsing, start server, open browser
 packages/shared      types + target key / comment scope helpers (bundled into both sides)
-packages/server      Hono API, git wrapper, diff parser, staging patches, targets, anchoring, watcher, state, export, nvim
+packages/server      Hono API, git wrapper, diff parser, staging patches, targets, worktrees, 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
 ```
@@ -321,3 +362,7 @@ to `main` and every pull request.
 ## License
 
 MIT
+
+## Storybook
+
+Run `pnpm storybook` for isolated review and layout components at http://127.0.0.1:6006. Stories use in-memory fixtures and include interaction checks. Run `pnpm build:storybook` to build the static preview.