@xbghc/warden 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +179 -0
  3. package/dist/cli.js +4450 -0
  4. package/dist/web/assets/c-BIGW1oBm.js +1 -0
  5. package/dist/web/assets/cpp-BRuaLJcg.js +1 -0
  6. package/dist/web/assets/csharp-COcwbKMJ.js +1 -0
  7. package/dist/web/assets/css-DPfMkruS.js +1 -0
  8. package/dist/web/assets/dart-CF10PKvl.js +1 -0
  9. package/dist/web/assets/diff-D97Zzqfu.js +1 -0
  10. package/dist/web/assets/dockerfile-BcOcwvcX.js +1 -0
  11. package/dist/web/assets/dotenv-Da5cRb03.js +1 -0
  12. package/dist/web/assets/github-light-DAi9KRSo.js +1 -0
  13. package/dist/web/assets/go-CxLEBnE3.js +1 -0
  14. package/dist/web/assets/graphql-ChdNCCLP.js +1 -0
  15. package/dist/web/assets/html-GMplVEZG.js +1 -0
  16. package/dist/web/assets/index-BWrmu1DB.css +1 -0
  17. package/dist/web/assets/index-CZQadJRz.js +192 -0
  18. package/dist/web/assets/ini-BEwlwnbL.js +1 -0
  19. package/dist/web/assets/java-CylS5w8V.js +1 -0
  20. package/dist/web/assets/javascript-wDzz0qaB.js +1 -0
  21. package/dist/web/assets/json-Cp-IABpG.js +1 -0
  22. package/dist/web/assets/json5-C9tS-k6U.js +1 -0
  23. package/dist/web/assets/jsonc-Des-eS-w.js +1 -0
  24. package/dist/web/assets/jsx-g9-lgVsj.js +1 -0
  25. package/dist/web/assets/kotlin-BdnUsdx6.js +1 -0
  26. package/dist/web/assets/less-B1dDrJ26.js +1 -0
  27. package/dist/web/assets/lua-BaeVxFsk.js +1 -0
  28. package/dist/web/assets/makefile-CHLpvVh8.js +1 -0
  29. package/dist/web/assets/markdown-Cvjx9yec.js +1 -0
  30. package/dist/web/assets/mdx-Cmh6b_Ma.js +1 -0
  31. package/dist/web/assets/nginx-BpAMiNFr.js +1 -0
  32. package/dist/web/assets/php-Dhbhpdrm.js +1 -0
  33. package/dist/web/assets/prisma-Dd19v3D-.js +1 -0
  34. package/dist/web/assets/python-B6aJPvgy.js +1 -0
  35. package/dist/web/assets/ruby-BGX7qA9Y.js +1 -0
  36. package/dist/web/assets/rust-B1yitclQ.js +1 -0
  37. package/dist/web/assets/scss-OYdSNvt2.js +1 -0
  38. package/dist/web/assets/shellscript-Yzrsuije.js +1 -0
  39. package/dist/web/assets/sql-BLtJtn59.js +1 -0
  40. package/dist/web/assets/svelte-DZMnMd3x.js +1 -0
  41. package/dist/web/assets/swift-D82vCrfD.js +1 -0
  42. package/dist/web/assets/toml-vGWfd6FD.js +1 -0
  43. package/dist/web/assets/tsx-COt5Ahok.js +1 -0
  44. package/dist/web/assets/typescript-BPQ3VLAy.js +1 -0
  45. package/dist/web/assets/vue-DVfSmUF7.js +1 -0
  46. package/dist/web/assets/xml-sdJ4AIDG.js +1 -0
  47. package/dist/web/assets/yaml-Buea-lGh.js +1 -0
  48. package/dist/web/index.html +14 -0
  49. package/package.json +58 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 xbghc
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,179 @@
1
+ # warden
2
+
3
+ Local web UI for reviewing git diffs — built for reviewing changes that a coding agent just made,
4
+ with line comments you can copy back to the agent as a prompt.
5
+
6
+ - Runs as a single local process per repository (`127.0.0.1` only, no auth, no database).
7
+ - Diff sources: working tree, staged, working tree vs HEAD, any commit, any two refs, and git worktrees.
8
+ - GitHub-style unified / side-by-side diff with syntax highlighting, collapsed file tree, lazy per-file loading, context expansion, virtual scrolling.
9
+ - Line comments (single line or a dragged range), Markdown, edit / delete.
10
+ - One click copies all comments as an agent-readable prompt to the clipboard.
11
+ - Review state (viewed files, comments, local issues, preferences) persists outside the repo and survives restarts.
12
+ - 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.
13
+ - Local issues (title, Markdown body, open/closed) that link comments.
14
+ - Commit history browser.
15
+ - Click a line number to jump to that line in a running nvim instance (WSL2 friendly).
16
+ - Read-only with respect to git: only whitelisted read sub-commands are ever executed.
17
+
18
+ ## Install / run
19
+
20
+ Node.js 20+ is required.
21
+
22
+ ```sh
23
+ npx @xbghc/warden # review the repo in the current directory
24
+ npx @xbghc/warden ~/proj # or give a path
25
+ ```
26
+
27
+ or install globally:
28
+
29
+ ```sh
30
+ npm i -g @xbghc/warden
31
+ warden [repoPath] [--port <n>] [--no-open]
32
+ ```
33
+
34
+ The server picks the first free port from 4100 (or `--port`), prints the URL and tries to open a
35
+ browser via `wslview`, `explorer.exe`, then `xdg-open`. If none of those exist it only prints the URL.
36
+ Several instances on the same repository can run at the same time.
37
+
38
+ ## Targets (what is being reviewed)
39
+
40
+ | Target | Key | Git equivalent |
41
+ |---|---|---|
42
+ | Working tree, uncommitted (incl. untracked) | `working` | `git diff` + `git diff --no-index /dev/null <file>` |
43
+ | Staged | `staged` | `git diff --cached` |
44
+ | Working tree, everything vs HEAD | `all` | `git diff HEAD` (+ untracked) |
45
+ | One commit | `commit:<sha>` | `git diff <sha>^ <sha>` |
46
+ | Two refs | `range:<base>..<head>` | `git diff <base>...<head>` |
47
+ | Worktree, working tree | `worktree:<path>:working` | same, run inside the worktree |
48
+ | Worktree, branch vs base | `worktree:<path>:range:<base>..<head>` | same, run inside the worktree |
49
+
50
+ Refs accept anything git can resolve (`main`, `v1.2`, `HEAD~3`, a sha). `@` is `HEAD`.
51
+ Worktrees are discovered with `git worktree list` and share the review state of the main repository.
52
+
53
+ ## Keyboard
54
+
55
+ | Key | Action |
56
+ |---|---|
57
+ | `r` | Refresh the current target (file list + open diff, then re-anchor comments) |
58
+ | `j` / `k` | Next / previous file |
59
+ | `n` / `p` | Next / previous hunk |
60
+ | `Ctrl+Enter` | Save the comment being edited |
61
+ | `Esc` | Cancel editing / close a panel / cancel re-attach mode |
62
+
63
+ ## Comments and export
64
+
65
+ Press the `+` that appears next to a line (drag to cover several lines) and write Markdown.
66
+ Each comment belongs to the `old` or `new` side of the diff and has a status:
67
+
68
+ - `active` — not yet exported
69
+ - `exported` — copied at least once (excluded from "copy all" unless *含已导出* is checked)
70
+ - `orphaned` — the code it referred to no longer exists in the current diff
71
+
72
+ "复制评论" copies every active comment of the current target; each comment also has a "复制此条" button.
73
+ The clipboard format is fixed so an agent can read it directly:
74
+
75
+ ````markdown
76
+ # Review comments
77
+ Target: working
78
+ Repo: /home/user/project
79
+ Count: 2
80
+
81
+ ## src/features/order/OrderList.tsx:120-124 (new)
82
+ ```tsx
83
+ 120 | const total = items.reduce((s, i) => s + i.price, 0);
84
+ 121 | // ...
85
+ ```
86
+ > 这里没有考虑 discount 字段，参考 utils/price.ts 里的 calcTotal。
87
+
88
+ ## src/features/order/hooks/useOrder.ts:42 (new)
89
+ ```ts
90
+ 42 | useEffect(() => { fetchOrder(id) }, []);
91
+ ```
92
+ > 依赖数组缺少 id。
93
+ ````
94
+
95
+ Issues can be copied in the same format (with the issue title, status and body on top).
96
+
97
+ ## Re-anchoring
98
+
99
+ Every comment stores a hash of its hunk, of each covered line and of three context lines above and
100
+ below. On refresh the comment is re-attached in this order: same hunk still present → same relative
101
+ position; otherwise search the file for the same line sequence (context lines disambiguate duplicates);
102
+ otherwise it becomes *orphaned* and is listed at the top of the file with the original snippet, where it
103
+ can be deleted or re-attached by picking a new selection.
104
+
105
+ "Viewed" is bound to a hash of the file's diff. When the diff changes the flag is dropped and the file
106
+ is marked *已变化*.
107
+
108
+ ## nvim integration
109
+
110
+ Requirements:
111
+
112
+ - `nvim` on `PATH` of the machine running warden (WSL2 in the typical setup).
113
+ - nvim started normally so it creates its default server socket (`$XDG_RUNTIME_DIR/nvim.<pid>.0`
114
+ or `/tmp/nvim.<user>/…/nvim.<pid>.0`), or with `--listen` into one of those directories.
115
+ - nvim's working directory is the repository (or worktree) root or somewhere below it.
116
+
117
+ warden scans those socket directories, asks each instance for `getcwd()` (500 ms timeout) and keeps the
118
+ instances whose cwd is inside the current target's root. One match is used automatically; with several
119
+ matches a selector appears in the top bar and the choice is remembered per repository root. Results
120
+ are cached for 10 s; use ⟳ to rescan.
121
+
122
+ Clicking a line number runs, roughly, `:edit +<line> <absolute path>` in that instance. Deleted lines
123
+ jump to the nearest new-side line; for commit targets the working-tree file is opened.
124
+
125
+ ## State
126
+
127
+ `~/.local/share/warden/<sha1(repoRoot)[:12]>/state.json` (respects `XDG_DATA_HOME`). Plain JSON with a
128
+ `schemaVersion`, written atomically (temp file + rename) under a small lock file so multiple instances
129
+ can share it. Delete the directory to reset.
130
+
131
+ ## WSL2 notes
132
+
133
+ - Access the UI from the Windows browser at the printed `http://127.0.0.1:<port>/` URL; WSL2 forwards
134
+ localhost automatically.
135
+ - Install [wslu](https://github.com/wslutilities/wslu) for `wslview` if `explorer.exe` doesn't open the
136
+ URL for you, or run with `--no-open`.
137
+ - Keep the repository on the Linux filesystem for reasonable git performance.
138
+ - Clipboard access uses `navigator.clipboard`, which works on `localhost`; if you expose the port via
139
+ another hostname the copy button falls back to `document.execCommand('copy')`.
140
+
141
+ ## Security model
142
+
143
+ Single user, local only. The server binds to `127.0.0.1`, executes git only through
144
+ `execFile('git', [...])` with an argument whitelist (`rev-parse`, `diff`, `show`, `log`, `worktree list`,
145
+ `ls-files`, `status`), refuses option-looking refs and any write-capable flag, and never writes into the
146
+ repository. Requests that would need anything else get HTTP 400.
147
+
148
+ ## Development
149
+
150
+ ```sh
151
+ pnpm install
152
+ pnpm dev # API server on :4100 (tsx watch) + Vite dev server on :5173 with /api proxied
153
+ pnpm test # vitest: diff parser, anchoring, export format, state store, HTTP API on a temp repo
154
+ pnpm typecheck
155
+ pnpm build # dist/web (Vite) + dist/cli.js (tsup, zero runtime dependencies)
156
+ node dist/cli.js path/to/repo
157
+ ```
158
+
159
+ Layout:
160
+
161
+ ```
162
+ bin/cli.ts argument parsing, start server, open browser
163
+ packages/shared types + target key helpers (bundled into both sides)
164
+ packages/server Hono API, git wrapper, diff parser, targets, anchoring, state, export, nvim
165
+ packages/web React + Vite UI (shiki highlighting, @tanstack/react-virtual, react-markdown)
166
+ test/ API integration tests on a generated git repository
167
+ ```
168
+
169
+ Only `dist/`, `README.md`, `LICENSE` and `package.json` are published.
170
+
171
+ Releasing: bump `version` in `package.json`, commit, then push a matching tag —
172
+ `git tag v0.1.0 && git push --tags`. The `Publish to npm` workflow checks the tag against the version,
173
+ runs build + tests through `prepublishOnly`, and publishes with the `NPM_TOKEN` repository secret
174
+ (an npm automation token). CI runs typecheck, tests, build and a `publish --dry-run` on every push to
175
+ `main` and every pull request.
176
+
177
+ ## License
178
+
179
+ MIT