collin/anvil

91f548f3896bf4aa6e26dd840b646683c4157526 / 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 runs
16	`cargo +nightly fmt` (nightly, for the unstable options in rustfmt.toml),
17	`cargo sort-derives` (`cargo install cargo-sort-derives`), and
18	`cargo clippy --workspace --all-targets -- -D warnings`.
19
20	## Viewing attachments referenced in tasks
21
22	TODO items and tickets may embed an uploaded image as
23	`![...](/{owner}/{repo}/-/attachments/{hash})`. These bytes live outside git on
24	the anvil instance, so to actually see one, fetch it from the instance and
25	`Read` the file. With `ANVIL_BASE_URL` (the instance URL) and `ANVIL_TOKEN` (a
26	read-only PAT — mint one with `anvild user token create <user>`) set:
27
28	```
29	curl -fsS -H "Authorization: Bearer $ANVIL_TOKEN" \
30	"$ANVIL_BASE_URL/{owner}/{repo}/-/attachments/{hash}" -o /tmp/att.png
31	```
32
33	Then `Read /tmp/att.png` to view it. The PAT is read-only (it authenticates
34	GET/HEAD only), so it's safe to hold; public-repo attachments need no token.
35	If those env vars aren't set, ask the user for the instance URL and a token
36	rather than guessing.
37
38	Current status, resume notes, the agreed next steps (a/b/c), and the roadmap live
39	in the TODO. Read it first:
40
41	@TODO.md