Jean-Gabriel Gill-Couture
e03a92c570
- Drop fields and functions nothing reads: job and proc tips, fetch time, PR url/author (and their GraphQL fields), spine summaries, diff::commit, unread data attributes, unused CSS and tokens. - One home each for state wording (naming main as the repo does), lane lookup, unseen, outdated, main's tip, the stop wait and the token header. - Narrow visibility; rename render::View to Filter; queue ranking moves to the CLI, its only user. - Token test covers every route; shared checkout snapshot in the fixture. - Client: errors outside Run/Send are toasts, history only after a good load, a drag stays in one file, the agent marker is a ring. - design.md, the skill and AGENTS.md describe what is built.
121 lines
6.0 KiB
Markdown
121 lines
6.0 KiB
Markdown
# branchgraph
|
|
|
|
Job: let a lead review every open branch of one repository fast: see what a
|
|
branch changes (`diff --stat`, then the diff), run it in its own worktree, and
|
|
send comments on lines, files or commits to a coding agent working there. The
|
|
branch graph is the navigation. It changes the user's own checkout only on
|
|
an explicit Check out or Merge in a branch's menu.
|
|
|
|
- Product design: `docs/design.md` (source doc:
|
|
https://claude.ai/code/artifact/f81e88f0-1704-4ff7-9427-293ba42d312c).
|
|
- Target look: `docs/mockup.png` (screenshot of the build, demo repo).
|
|
|
|
## Owner decisions (2026-10-08)
|
|
|
|
- Binary and crate name: `branchgraph`. The folder stays `gitui`; the name
|
|
`gitui` clashes with the TUI installed at `/usr/bin/gitui`.
|
|
- Architecture: option A of the design, a local binary that serves the page
|
|
on localhost. The artifact prototype (milestone 1) is skipped.
|
|
- Work starts at milestone 2. The LLM ask box is milestone 3: do not build it
|
|
yet.
|
|
|
|
## Owner decisions (2026-10-08, revision 4)
|
|
|
|
- The product is the review loop, not the graph (owner: "I can browse
|
|
branches but that's it").
|
|
- Writes allowed: worktree creation (and the local tracking branch it needs),
|
|
and running the configured run command in that worktree. Still never:
|
|
checkout in the user's worktree, merge, rebase, push, branch delete.
|
|
- "Send to agent" runs a user-set command template (`agent` in the
|
|
branch's `.branchgraph`, see the hard rules), any agent CLI; values only
|
|
as environment variables.
|
|
|
|
## Owner decisions (2026-10-09)
|
|
|
|
- `.branchgraph` settings: see the hard rules.
|
|
- Clicking a branch label opens a menu, as gitk does: Review, Check out,
|
|
Merge into the branch checked out in the user's checkout, Preview merge,
|
|
Compare with this, Copy name.
|
|
- Base selector in the top bar: the branch "All" compares with (merge base
|
|
with it), main by default, kept while moving between branches and shown
|
|
in amber whenever it is not main.
|
|
|
|
## Current milestone: 3, the review loop
|
|
|
|
Scope: `docs/design.md`, revision 5. Milestone 2 (the live graph) is built and
|
|
becomes the graph overlay and the data layer.
|
|
|
|
Gate (done when a test shows it):
|
|
- A branch's stat equals `git diff --numstat -M <merge-base> <tip>` for every
|
|
branch of a fixture repo.
|
|
- Run or Send on a remote-only branch creates a worktree that `git worktree
|
|
list` shows, on a local branch tracking origin; the user's checkout (HEAD,
|
|
index, status, local branches) is unchanged; `branchgraph.copy` files are
|
|
copied and `branchgraph.setup` ran once.
|
|
- Send runs `branchgraph.agent` in the worktree with the `BG_*` variables; the
|
|
brief holds every draft with its anchor and excerpt; a branch name holding
|
|
shell syntax runs nothing extra; the drafts are marked sent.
|
|
- Stop sends SIGTERM to the run's main process (a trap in the script shows it).
|
|
- POST endpoints and run output refuse requests without the page token.
|
|
- `branchgraph brief` prints the unsent brief of the current worktree's
|
|
branch; `--ack` marks it sent.
|
|
|
|
## Hard rules
|
|
|
|
- Writes to the clone: fetch (objects, remote-tracking refs and their
|
|
reflogs; never prune, wait while a `*.lock` exists) and worktree creation.
|
|
Merge previews run in object memory. Check out and merge touch the user's
|
|
checkout only from a branch's menu: refused over modified tracked files, a
|
|
conflicting merge is aborted, never in another worktree, never pushed.
|
|
gix cannot switch or merge a working tree yet, so these two run the git
|
|
CLI with arguments, never a shell. No rebase, push or branch delete.
|
|
- Commands (run, setup, copy, agent, verify) come from the branch's
|
|
`.branchgraph` (owner, 2026-10-09): the file in its worktree, else as
|
|
committed on the branch, else main's. No git-config source: settings are
|
|
shared through the repository, not kept per machine. A command the branch
|
|
adds over main's is shown and asked about once before it runs; one the
|
|
user saved in the page counts as approved. Commands start only on a user
|
|
action, and every route needs the page's per-launch token.
|
|
- `.branchgraph` is the only file branchgraph edits in a checkout, saved
|
|
from the page into the branch's worktree. It never commits or pushes it.
|
|
- Bind `127.0.0.1` by default. `--bind <ip>` (owner, 2026-10-08) listens
|
|
wider, for example `0.0.0.0`: then any Host is accepted, every route still
|
|
needs the token, an Origin must match the Host, and startup warns that the
|
|
page is plain HTTP and can run code.
|
|
- Network: only `git fetch` and the GitHub API. No other host, no telemetry.
|
|
branchgraph calls no LLM; the agent it starts is the user's own tool.
|
|
- GitHub token: read from `GH_TOKEN` (run as
|
|
`GH_TOKEN=$(gh auth token) branchgraph`). Never log it, put it in a URL or
|
|
write it to disk. Without a token, draw the graph without PR labels and say
|
|
so on the page.
|
|
- Native libraries over shelling out: read and fetch with `gix`. Tests may use
|
|
the `git` CLI to build fixture repos and to check results.
|
|
- Bounded work: cap commits per lane, diff size (200 KB for the diff pane,
|
|
2 MB for one file loaded on its own) and API pages.
|
|
|
|
## Default stack
|
|
|
|
Change only with a stated reason: `gix`, `tokio` + `axum`, `maud` for HTML,
|
|
SVG drawn on the server, `clap` for arguments, `reqwest` for one GitHub
|
|
GraphQL query (PRs with draft, mergeable and review state). Little or no
|
|
client JS.
|
|
|
|
Approved additions (2026-10-08): `serde` + `serde_json`, `futures-util`,
|
|
`anyhow`, `tempfile` (dev).
|
|
|
|
Ask the owner before adding a dependency outside this list, calling another
|
|
host, or writing to the repository.
|
|
|
|
## Workflow
|
|
|
|
- UI work (comps, templates, CSS, client script, UI review): read
|
|
`.agents/skills/quiet-ui/SKILL.md` first and keep to its budgets.
|
|
Design canvas: https://claude.ai/artifact/Jxue8Rvy2AayN9xDDvcCwV
|
|
- `cargo fmt`, `cargo clippy --all-targets -- -D warnings`, `cargo test`.
|
|
Zero warnings.
|
|
- Prove each behavior with the smallest test. Build fixture repos in temp
|
|
directories.
|
|
- Comments explain why, never what.
|
|
- Commits: short subject and tight bullets. Never add Co-Authored-By or other AI attribution anywhere
|
|
- Use the code review skill ./.agents/skills/code-review/ in a loop until satisfied
|