collin/anvil

a5967525842c191da6222ccc680929935e41a68c / CLAUDE.md

1	# anvil
2
3	A minimal, self-hosted git forge in Rust, built on gix (gitoxide).
4
5	## Design rules
6
7	- Pure gitoxide — never the git binary. The product (server, CI broker,
8	mirroring, deploy image) must not invoke or depend on a `git` executable.
9	When gix lacks a capability, implement the protocol on gix plumbing instead
10	of shelling out — e.g. gix can't push yet, so `anvil-git/src/push.rs` speaks
11	the send-pack wire format itself (with `gitserver-core` covering the server
12	side). Tests may use the git CLI, but only as a fixture/interop check, never
13	on the code path under test.
14
15	Dev setup: `git config core.hooksPath .githooks` — the pre-commit hook checks
16	that `rust-toolchain.toml`'s pin satisfies Cargo.toml's `rust-version` floor,
17	then runs `cargo +nightly fmt` (nightly, for the unstable options in
18	rustfmt.toml), `cargo sort-derives` (`cargo install cargo-sort-derives`), and
19	`cargo clippy --workspace --all-targets -- -D warnings`.
20
21	Every crate opts into `[workspace.lints]`, which turns on
22	`clippy::multiple_crate_versions` — so adding a dependency that drags in a
23	second copy of something already in the tree fails the hook. The duplicates
24	that exist today are listed in `clippy.toml` with a note on who is holding
25	each back; delete an entry when a bump makes it unnecessary rather than
26	letting the list rot.
27
28	The Rust version is set in exactly one place: `rust-toolchain.toml`. It
29	pins the toolchain and the musl cross target for every `cargo` invocation here,
30	and `docker/runner/build.sh` parses `[toolchain] channel` out of it to bake the
31	same version into `anvil-runner:rust` — so a CI job and a checkout compile with
32	the same rustc. Bumping Rust means editing that file and Cargo.toml's floor
33	(the hook catches you if you forget the second), then rebuilding the image.
34
35	## Viewing attachments referenced in tasks
36
37	TODO items and tickets may embed an uploaded image as
38	`![...](/{owner}/{repo}/-/attachments/{hash})`. These bytes live outside git
39	history, so to actually see one, get the bytes and `Read` the file. Two ways:
40
41	Preferred — over git, no credentials. anvil mirrors every attachment into
42	`refs/anvil/attachments` (a flat tree of `<hash> → blob`, off the branch
43	namespace so a default pull never drags it down). From a clone, opt in once:
44
45	```
46	git fetch origin '+refs/anvil/attachments:refs/anvil/attachments'
47	git cat-file -p "refs/anvil/attachments:<hash>" > /tmp/att && # then Read /tmp/att
48	```
49
50	This uses the clone's existing git auth — no PAT — and works offline afterward.
51
52	Fallback — HTTP with a PAT (no clone, or the ref isn't fetched). Credentials
53	live in the git-ignored `.anvil-credentials` at the repo root (`ANVIL_BASE_URL` +
54	a read-only `ANVIL_TOKEN`); `source` it, then:
55
56	```
57	curl -fsS -H "Authorization: Bearer $ANVIL_TOKEN" \
58	"$ANVIL_BASE_URL/{owner}/{repo}/-/attachments/{hash}" -o /tmp/att && # Read it
59	```
60
61	The PAT is read-only (GET/HEAD only), safe to hold. If neither the ref nor
62	`.anvil-credentials` is available, ask the user rather than guessing.
63
64	Attachments are often phone screenshots larger than the `Read` tool's 256KB
65	cap. Downscale before reading (macOS `sips`):
66
67	```
68	sips -Z 1100 -s formatOptions 70 /tmp/att --out /tmp/att-small.jpg # then Read that
69	```
70
71	note that we can't use portless for this app because of a websocets bug with http/2
72
73	## Remote runners: where this stands
74
75	anvil does not execute CI. Runners dial out, claim jobs, and run them on
76	their own Docker daemon. Design and rationale: `docs/remote-runners.md`.
77
78	M1 is done: `anvil-job` (wire format), `anvil-docker` (connect/ensure_image),
79	`anvil-worker` (the runner binary), five endpoints under `/-/runner/`,
80	in-memory leases, and no Docker socket on the deployed container.
81
82	M2 is done: `platform` in `.anvil/ci.toml`, a `[ci] platform` default, and
83	two-tier routing — a claiming runner is offered the runs that match its
84	architecture (or name none), then the runs no connected runner is native to,
85	so a lone arm64 Mac still runs `linux/amd64` pipelines under Rosetta instead of
86	stranding them. `Dispatch` tracks who is connected from claims and heartbeats
87	(`RUNNER_TTL`, 5 min); `anvil-docker::check_platform` fails a job whose image
88	came back the wrong architecture.
89
90	Invariants to not break. These are the reasons the split is shaped the way
91	it is, and each is easy to undo by accident:
92
93	- The runner never parses `.anvil/ci.toml`. Image resolution, the allowlist
94	check and script assembly happen in `build_job`, so a runner cannot widen
95	what it is permitted to run.
96	- `store_artifact` stays server-side. The runner uploads a raw tar; `browse`
97	decides whether that becomes a servable directory tree, which is anvil's
98	call, not a runner's.
99	- A job's secrets live on its lease, not the vault, once dispatched.
100	`Vault::take` fails after the repo's unlock TTL lapses, so re-reading at
101	finish time would silently skip log masking on exactly the long runs whose
102	logs most need it.
103	- `anvil-job` depends on serde and nothing else. It exists so the runner does
104	not link toasty, SQLite and gix.
105
106	Next, in order:
107
108	1. M3, the deploy agent. Image builds cannot be CI jobs, because job
109	containers get no Docker socket by design. `docker build --platform
110	linux/amd64` plus `docker push` belongs to a separate process on the build
111	host at a different trust level, triggered by the existing `deploy_webhook`.
112	Folding it into the dial-out channel as a privileged "publish" job kind,
113	authorized by the `is_deploy_target` check that already scopes CD to one
114	repo, would remove the last inbound path to the build host.
115	2. CI concurrency. "One job at a time" was a property of the old in-process
116	loop and is gone. Nothing bounds in-flight jobs now beyond how many runners
117	exist. Needs a `max_concurrent` equivalent — more pressing now that platform
118	routing makes a second runner worth having.
119	3. Per-runner credentials. One shared `[ci] runner_token` means one
120	revocation for every runner, no `last_used_at`, and any holder can claim any
121	job and receive its secrets. Wants the API-token write scope first (see
122	TODO.md).
123	4. Live logs. The result POST is a single write, matching the old
124	behaviour. Streaming needs chunked append with offsets and a UI that
125	tolerates gaps. Newly worth doing now that a producer exists.
126
127	Operationally: nothing runs until a runner is started and `[ci]
128	runner_token` is set; queued runs just sit, with a warning logged at startup.
129	Setting one up on the Mac mini (build, Rosetta, the launchd agent in
130	`deploy/worker/`) is written out in `docs/remote-runners.md` § Isolation on
131	macOS. Locally, `compose.override.yaml` runs two of them in containers
132	(`./deploy/build.sh --debug --worker`, then `docker compose up -d --build`) so
133	concurrency and routing are testable on one machine; that mount is a
134	development-only concession, never production's. Who is connected, and what
135	each is running, is at `/-/admin/runners` — presence comes from ordinary claims
136	and heartbeats rather than a ping of its own, so anything watching for a runner
137	to go quiet has to allow a full claim poll first.
138	Agent sessions still drive Docker locally and are the one thing the dropped
139	socket mount gives up. They are off by default.
140
141	Current status, resume notes, the agreed next steps (a/b/c), and the roadmap live
142	in the TODO. Read it first:
143