carlos / todomvc-bakeoff Public

Download this file

1	# 🤖 AGENTS.md: todo-zig
2
3	TodoMVC for the CARLOS bakeoff, written in Zig. The brief and contract at
4	the repo root (`BRIEF.md`, `CONTRACT.md`) are binding; this file adds what
5	is particular to this app.
6
7	## The one rule
8
9	**The page works without JavaScript.** Every action is a plain HTML form
10	that posts and gets a 303 back. The script in `static/app.js` only
11	intercepts those same forms and swaps in the fresh markup the server
12	renders. If a feature can't be done with a form and a redirect, it isn't
13	done.
14
15	## Tenancy
16
17	- **One instance for the whole app.** Every visitor is served by the same
18	process and the same SQLite file.
19	- **Each visitor's list is kept separately by an anonymous cookie.** The
20	cookie holds 256 random bits; the database stores only its SHA-256, so
21	the database alone can't be used to take over a list. A cookie the app
22	doesn't recognise gets a fresh, empty list.
23	- **No sign-in.** There are no accounts, passwords or email addresses.
24	- **Trust class C.** Todo text is stored as plain text in SQLite. That is
25	a deliberate choice: the data is low-value, anonymous and typed by the
26	visitor, and nothing is gained by sealing it.
27
28	## Working here
29
30	- Zig 0.17.0 from `scripts/env.sh`; never reinstall it. SQLite comes in
31	as the official amalgamation through `build.zig.zon` and is compiled by
32	Zig as C.
33	- All Zig caches live in `.cache/` (see the `Makefile`), so
34	`make clean-deps` can drop compiled artifacts without touching anything
35	outside this directory.
36	- Migrations in `src/db.zig` only ever add. Never drop or rewrite data.
37	- Bind `127.0.0.1` only; scratch goes in `mktemp -d -p "$TMPDIR"`.
38