steid

1	# Current
2
3	> Keep this file short. One active step, one ordered backlog. Completed work moves to
4	> [progress.md](progress.md). If this file starts reading like a changelog, it has
5	> drifted — that's exactly what went wrong last time.
6
7	## Active: Milestone 3 — Repo model
8
9	Goal: repositories exist as records and as bare git repos on disk, and they appear
10	on the profile. No git protocol yet — that is milestone 4. This milestone fills the
11	Repositories section and gets the storage layout right before anything serves it.
12
13	Out of scope: clone, push, browsing a tree, README rendering, forks, stars.
14	Deleting a repo — worth having, but it makes the filesystem/database consistency
15	problem twice as interesting, so not in the first pass.
16
17	### Steps
18
19	- [x] Domain: `RepoId`, `RepoName`, `Visibility` (Public/Private), `Repository`
20	- [x] Domain: `RepoRepository` port — `find_by_id`, `find_by_org_and_name`,
21	`list_by_org`, `save`
22	- [x] Infrastructure: in-memory + SQLite implementations, migration
23	- [x] Application: `GitStorage` port — `init_bare`, `remove`, `repo_path`
24	- [x] Infrastructure: `DiskGitStorage`, shelling out to `git init --bare`
25	- [ ] Application: `create_repo` use case — owner only, validates, creates record and
26	bare repo
27	- [ ] Application: `list_repos` / `view_repo` read models — visibility-aware
28	- [ ] Web: `/{handle}/repos/new` form, `/{handle}/repos/{name}` page
29	- [ ] Web: the profile's Repositories section lists what the viewer may see
30	- [ ] `/api/users/{handle}/repos`
31
32	### Done when
33
34	The owner creates a repo through the UI, a bare repo appears at
35	`{data_dir}/{handle}/{name}.git`, and it is listed on the profile. A private repo is
36	invisible to a signed-out visitor. `git clone` does not work yet — that is
37	milestone 4.
38
39	### Settled
40
41	- Repo name rules: `OrgName`'s, plus `.` and `_` for names like `.github` and
42	`foo.js`. Lowercased, max 100. Also rejects a name of nothing but dots and any name
43	ending `.git` — the first is traversal, the second would live at `foo.git.git`.
44	- Reserved repo names: `import`, `new`, `search`. Only names directly under
45	`/{handle}/repos/` can collide.
46	- Visibility defaults to public, matching a portfolio-first product.
47	- Repositories carry an optional description, capped at 300 characters — a sentence
48	for the profile listing, not a README. Kept deliberately: portfolio-first is the
49	tie-break, and this milestone's own "Done when" puts repositories on the profile, so
50	the consumer is inside the milestone rather than hypothetical. The per-repo analogue
51	of `Organization::bio`.
52	- `list_by_org` returns every repository regardless of visibility. Filtering is an
53	authorization decision and belongs to the use case, so the page and `/api` cannot end
54	up applying different rules. The cost is that a private repo is briefly in memory
55	before being filtered, which is fine in-process.
56
57	### Open
58
59	Nothing open. `GitStorage`'s shape and how git is invoked are recorded in
60	[0006](decisions/0006-git-binary-behind-narrow-ports.md).
61
62	### Watch for
63
64	- The database and the filesystem cannot share a transaction. Creating a repo
65	writes a row and a directory. Neither previous attempt solved this properly — see
66	[architecture.md](architecture.md#db-plus-filesystem-writes). A compensating delete is
67	good enough to ship, but write down that an orphaned directory is possible if the
68	process dies between the two, rather than rediscovering it.
69	- Path traversal. `{data_dir}/{handle}/{name}.git` is built from user input. A name
70	containing `..` or `/` must be impossible before it reaches the filesystem, and
71	`RepoName` is the place to make it impossible rather than sanitising at the call site.
72	- Visibility is an authorization decision, so it belongs in the use case. A private
73	repo must be absent from listings, not merely unlinked — and `/api` must agree with
74	the page.
75	- `git` is a dependency of the test suite too, not only of the runtime —
76	`DiskGitStorage`'s tests run real `git init`. A machine without `git` fails
77	`cargo test`, not just the app.
78	- A handle rename is a directory move. The layout is keyed by handle for
79	legibility, so whenever renaming arrives it has to move the tree; it cannot be a row
80	update. Nothing renames handles today.
81	- Bare repos created on macOS carry `ignorecase = true` in their config, because
82	git probes the filesystem at init. Correct where it was created, wrong if the data
83	directory is ever moved to Linux. A migration gotcha, not a bug.
84	- An orphaned directory blocks re-creating that name. `init_bare` refuses rather
85	than adopting what is already there, and repo deletion is out of scope this
86	milestone, so clearing one is a manual `rm` for now.
87
88	### Carried over — small, unblocked
89
90	- Fonts are not loaded. The theme names Geist and IBM Plex Mono; both fall back
91	today. Topcoat's `font-fontsource` feature handles it.
92	- Light mode is untested. The palette defines it; nobody has looked at it.
93	- No rate limiting on `/auth/login` or `/auth/setup`.
94	- `sweep_expired` is never called, so expired session rows accumulate. Expiry is
95	enforced on read, so this is tidiness, not a hole.
96	- CSRF. `SameSite=Lax` covers the common case. Forms now exist, so this is decidable
97	rather than hypothetical.
98
99	## Backlog
100
101	Ordered. Pull from the top.
102
103	1. Milestone 4 — Git over HTTP. `git http-backend` subprocess, PATs over HTTP
104	Basic. See [0001](decisions/0001-git-over-http-not-ssh.md). The `body_limit` cap will
105	reject large pushes until raised.
106	2. Milestone 5 — Repo browsing. Tree, blob, commit log. **Start with domain value
107	objects** — `ObjectId`, `RefName`, `TreeEntry` — before any adapter. A query port
108	returning `String`s is an anaemic pass-through that pushes validation into the page.
109	Also the point to measure fork/exec cost per page view, and to reconsider `gix` for
110	the read path ([0006](decisions/0006-git-binary-behind-narrow-ports.md)).
111	3. Milestone 6 — Writing. Posts, markdown, `/{handle}/posts/{slug}`. Still open
112	whether writing or projects/showcases is the better first portfolio feature.
113
114	## Open questions
115
116	- Topcoat is early (v0.5.0, first released 2026-07-22, breaking changes expected
117	by its own authors). Expect churn that isn't feature work.
118	- Body size limits will reject large pushes at Milestone 4 — `topcoat-router` has a
119	`body_limit` layer that needs raising on the git routes. Recorded here because it
120	will surface as a confusing failure rather than a clear one.
121	- Topcoat ships Tailwind without Node, which reopens the design system attempt #1
122	dropped purely to avoid an npm build step — see [ui.md](ui.md).
123
124	## Routing findings (Milestone 0)
125
126	- Topcoat 0.5 requires rustc ≥ 1.95. On an older toolchain `cargo add topcoat`
127	silently resolves to an empty `topcoat v0.0.0` placeholder instead of failing. Local
128	stable is now 1.97.1.
129	- `Router::builder().discover()` collects `#[page]`-annotated items at link time,
130	so pages can live in any module. Layering is our choice, not the framework's.
131	- `module_router!` derives each URL from the module tree rather than a path string.
132	Still deferred. Application routes now group cleanly (`auth/login`, `api/me`), but
133	handles sit at the root ([0004](decisions/0004-root-handles-grouped-routes.md)), so a
134	parameterised root segment still has to coexist with static ones. Worth checking how
135	`module_router!` handles that before committing to it.
136	- Path and query params are read from `Cx` via `path_param!` / `#[query_params]`, not
137	injected as handler arguments. Parses are memoized per request.
138	- Layouts wrap by path prefix and nest outermost-first, and a layout can catch a page's
139	`NotFoundError` to render a branded 404.
140	- `HOST` / `PORT` configure the bind address, so `STEID_LISTEN_ADDR` is gone.
141	- `Body` is a boxed `http_body::Body` used for both requests and responses, with
142	`into_data_stream()` to read and `Body::new()` to wrap a stream — pack data can
143	stream both directions without buffering. This is what makes Milestone 4 viable.