collin/anvil

9711016c694d9ebef20b00b2126660305e91b132 / 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
24	history, so to actually see one, get the bytes and `Read` the file. Two ways:
25
26	Preferred — over git, no credentials. anvil mirrors every attachment into
27	`refs/anvil/attachments` (a flat tree of `<hash> → blob`, off the branch
28	namespace so a default pull never drags it down). From a clone, opt in once:
29
30	```
31	git fetch origin '+refs/anvil/attachments:refs/anvil/attachments'
32	git cat-file -p "refs/anvil/attachments:<hash>" > /tmp/att && # then Read /tmp/att
33	```
34
35	This uses the clone's existing git auth — no PAT — and works offline afterward.
36
37	Fallback — HTTP with a PAT (no clone, or the ref isn't fetched). Credentials
38	live in the git-ignored `.anvil-credentials` at the repo root (`ANVIL_BASE_URL` +
39	a read-only `ANVIL_TOKEN`); `source` it, then:
40
41	```
42	curl -fsS -H "Authorization: Bearer $ANVIL_TOKEN" \
43	"$ANVIL_BASE_URL/{owner}/{repo}/-/attachments/{hash}" -o /tmp/att && # Read it
44	```
45
46	The PAT is read-only (GET/HEAD only), safe to hold. If neither the ref nor
47	`.anvil-credentials` is available, ask the user rather than guessing.
48
49	Attachments are often phone screenshots larger than the `Read` tool's 256KB
50	cap. Downscale before reading (macOS `sips`):
51
52	```
53	sips -Z 1100 -s formatOptions 70 /tmp/att --out /tmp/att-small.jpg # then Read that
54	```
55
56	Current status, resume notes, the agreed next steps (a/b/c), and the roadmap live
57	in the TODO. Read it first:
58
59	@TODO.md