@xbghc/warden 0.14.0 → 0.15.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.
package/README.md
CHANGED
|
@@ -5,7 +5,10 @@ with line comments you can copy back to the agent as a prompt.
|
|
|
5
5
|
|
|
6
6
|
- Runs as a single local process per repository (`127.0.0.1` only, no auth, no database).
|
|
7
7
|
- Diff sources: working tree, staged, working tree vs HEAD, a branch since it forked off its base (commits and
|
|
8
|
-
uncommitted work together), any commit, any two refs,
|
|
8
|
+
uncommitted work together), any commit, any two refs, git worktrees, and checkpoints.
|
|
9
|
+
- Checkpoints: note the working tree as it is — untracked files included — and later see only what
|
|
10
|
+
changed since, staged, committed or neither. Taking one writes nothing to the repository (see
|
|
11
|
+
[Checkpoints](#checkpoints)).
|
|
9
12
|
- Worktrees are made and taken down from the page, one per agent branch, with the path ready to paste.
|
|
10
13
|
Their directories are numbered slots beside the repository that get reused rather than remade:
|
|
11
14
|
releasing one keeps the directory, installed dependencies included, for the next branch.
|
|
@@ -34,6 +37,7 @@ with line comments you can copy back to the agent as a prompt.
|
|
|
34
37
|
`git apply --cached`, which is what the stage / unstage controls run, and the worktree slot
|
|
35
38
|
operations (`worktree add` / `remove`, `branch`, `switch`). Reviewing and staging never write the
|
|
36
39
|
working tree or HEAD; only checking a branch out into a free slot, or releasing one, does.
|
|
40
|
+
Checkpoints write into warden's own index copy and object store, never the repository.
|
|
37
41
|
|
|
38
42
|
## Install / run
|
|
39
43
|
|
|
@@ -75,6 +79,8 @@ for a global install. The check never delays startup and fails silently. `--no-u
|
|
|
75
79
|
| Worktree, working tree | `worktree:<path>:working` | same, run inside the worktree |
|
|
76
80
|
| Worktree, branch vs base | `worktree:<path>:range:<base>..<head>` | same, run inside the worktree |
|
|
77
81
|
| Worktree, everything since base | `worktree:<path>:base:<ref>` | same, run inside the worktree |
|
|
82
|
+
| Working tree since a checkpoint (incl. untracked) | `checkpoint:<n>` | `git diff <checkpoint tree>`, see [Checkpoints](#checkpoints) |
|
|
83
|
+
| Worktree, since one of its checkpoints | `worktree:<path>:checkpoint:<n>` | same, run inside the worktree |
|
|
78
84
|
|
|
79
85
|
Refs accept anything git can resolve (`main`, `v1.2`, `HEAD~3`, a sha). `@` is `HEAD`.
|
|
80
86
|
Worktrees are discovered with `git worktree list` (and made in the *Worktree* view, see below) and
|
|
@@ -290,12 +296,42 @@ them — the comment's current view first, then `working`, `staged`, `all`. So:
|
|
|
290
296
|
**deleted** (and unlinked from any issue), because the code they were about is now history.
|
|
291
297
|
Anything still visible in Unstaged or Staged survives, including as a context line.
|
|
292
298
|
|
|
293
|
-
Commit, range
|
|
294
|
-
them deletes on a moved HEAD.
|
|
299
|
+
Commit, range, `base` and checkpoint targets each keep their own pool and only ever search
|
|
300
|
+
themselves, and none of them deletes on a moved HEAD.
|
|
295
301
|
|
|
296
302
|
Comment markers in the diff belong to one view; the rail's *全部* tab lists the whole pool and
|
|
297
303
|
*此文件* lists every comment on the open file regardless of which view it currently sits in.
|
|
298
304
|
|
|
305
|
+
## Checkpoints
|
|
306
|
+
|
|
307
|
+
An agent works in rounds, and after the first one the question is no longer "what is uncommitted"
|
|
308
|
+
but "what did it do since I last looked". The working tree answers that only while the agent
|
|
309
|
+
neither stages nor commits, and a `base` target shows the whole branch every time. A checkpoint is
|
|
310
|
+
the working tree noted at the moment you choose, and `checkpoint:<n>` is one diff from it to the
|
|
311
|
+
working tree now — whatever was staged or committed in between does not show, only what changed.
|
|
312
|
+
|
|
313
|
+
- *新建检查点*, under the progress figure in 工作区, takes one: tracked and untracked files as they are
|
|
314
|
+
on disk, ignored ones left out. *对比检查点 #n* beside it opens the newest. A checkpoint of a working
|
|
315
|
+
tree that has not changed since the newest one is not taken twice; that one is handed back.
|
|
316
|
+
- In a checkpoint's view the picker reads *检查点 #n*, and the row under the figure switches to another
|
|
317
|
+
checkpoint, takes a new one — the round is over, so the view moves on to it, empty — or deletes
|
|
318
|
+
the one in front after asking.
|
|
319
|
+
- Files there carry the [已读 mark](#viewed-files), which the agent's next edit to a file drops, and
|
|
320
|
+
comments on a checkpoint are a pool of their own. Deleting the checkpoint deletes both.
|
|
321
|
+
- Checkpoints are numbered per worktree. A worktree keeps the newest 20; taking one more drops the
|
|
322
|
+
oldest, with its comments. A slot checked out to another branch drops its own.
|
|
323
|
+
|
|
324
|
+
Nothing of this is written to the repository. The snapshot is `git add --all` plus
|
|
325
|
+
`git write-tree` run against a copy of the index kept in warden's data directory, with
|
|
326
|
+
`GIT_OBJECT_DIRECTORY` pointing there too, so the tree and every blob git hashes for it land beside
|
|
327
|
+
the state file; files the index already has right are not hashed again, so taking one costs about
|
|
328
|
+
what changed. A diff runs `git diff <tree>` under another throwaway copy of the index with the
|
|
329
|
+
untracked files added as intent-to-add (which hashes nothing), reading the repository's objects
|
|
330
|
+
through `GIT_ALTERNATE_OBJECT_DIRECTORIES`. The alternates are only ever set for reads: git refreshes
|
|
331
|
+
the mtime of an object it finds in one while writing, and that would be a write to `.git`. Clean
|
|
332
|
+
filters configured for the repository run as they do for any `git add` (Git LFS keeps its cache in
|
|
333
|
+
`.git/lfs`).
|
|
334
|
+
|
|
299
335
|
## Viewed files
|
|
300
336
|
|
|
301
337
|
Commit, range and `base` targets cannot be staged from, so a file there is ticked *已读* instead — the
|
|
@@ -370,12 +406,14 @@ jump to the nearest new-side line; for commit targets the working-tree file is o
|
|
|
370
406
|
|
|
371
407
|
`~/.local/share/warden/<sha1(repoRoot)[:12]>/state.json` (respects `XDG_DATA_HOME`). Plain JSON with a
|
|
372
408
|
`schemaVersion`, written atomically (temp file + rename) under a small lock file so multiple instances
|
|
373
|
-
can share it. Delete the directory to reset.
|
|
409
|
+
can share it. Delete the directory to reset. Checkpoint objects live beside it in `checkpoints/objects`;
|
|
410
|
+
deleting a checkpoint leaves them there, since another may share them.
|
|
374
411
|
|
|
375
412
|
`targets` is keyed by target key, plus one *comment scope* per worktree — `local`, or
|
|
376
413
|
`worktree:<path>:local` — holding the comments the three local views share and the HEAD sha the last
|
|
377
|
-
re-anchor saw. `viewed` sits on the key of the commit, range
|
|
378
|
-
local view keys hold nothing. Issues
|
|
414
|
+
re-anchor saw. `viewed` sits on the key of the commit, range, `base` or checkpoint target it was
|
|
415
|
+
ticked in; the local view keys hold nothing. Issues, todos and `checkpoints` (the tree sha, HEAD and
|
|
416
|
+
time of each, per worktree) are top level. State written by an older version is
|
|
379
417
|
migrated on load: comments filed under `working` / `staged` / `all` move into the matching scope the
|
|
380
418
|
first time the file is read, and the 已读 marks those views used to keep are dropped.
|
|
381
419
|
|
|
@@ -409,7 +447,9 @@ and `git reset --hard` plus `git clean -fd` only on the forced release the revie
|
|
|
409
447
|
a 409. Refs change only when a branch is made for a checkout (plus its upstream setting when it comes
|
|
410
448
|
from a remote) — undone with `branch -D` should the switch into the slot then fail — or deleted on
|
|
411
449
|
request after a release or removal (`-d`, so only a merged one), and the review state lives outside
|
|
412
|
-
the repository. A
|
|
450
|
+
the repository. A checkpoint writes only there: `git add --all [--intent-to-add]` and
|
|
451
|
+
`git write-tree --missing-ok`, with `GIT_INDEX_FILE` and `GIT_OBJECT_DIRECTORY` set to files in
|
|
452
|
+
warden's data directory and no alternates (see [Checkpoints](#checkpoints)). A mutating request the
|
|
413
453
|
browser labels as coming from another site (`Sec-Fetch-Site: cross-site`) is refused with 403, so a
|
|
414
454
|
page from elsewhere cannot drive the server through the browser it is open in.
|
|
415
455
|
|