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 2 — Profile page
8
9	Goal: `/{handle}` is the real profile page — public, working signed out, and the
10	frame that repos, writing, and projects hang off later. It replaces the Milestone 0
11	placeholder.
12
13	Out of scope: repos, posts, and projects don't exist yet, so there is nothing to
14	list. Avatars, following, and anything social. Organisation profiles beyond what falls
15	out for free.
16
17	### Phase 1 — the page
18
19	Shippable on its own: a public profile that renders signed out.
20
21	- [x] Settle URL shape — handles at the root, routes grouped under prefixes
22	([0004](decisions/0004-root-handles-grouped-routes.md))
23	- [x] Reserved-handle denylist in `OrgName::new`; auth routes moved under `/auth/`
24	- [x] Explicit `#[page]` paths for now; `module_router!` still unexamined, and four
25	routes is too few to judge it against
26	- [x] `PublicProfile` read model + `view_profile` use case — no email field, by design
27	- [x] `/{handle}` page: label, handle, bio, and the section frame; 404 on unknown,
28	case-insensitive
29	- [x] Asserted `/auth/login` and `/api/me` still route with `/{handle}` at the root —
30	static beats parameterised
31	- [x] `/` redirects to the owner's profile once claimed, retiring the placeholder
32	- [x] `/api/users/{handle}` — same read model, public JSON
33	- [x] Migration `orgs.bio`, pulled forward so the page had a field to render
34
35	### Phase 2 — make it yours
36
37	A profile you can't change is a stub. This is what makes it a portfolio page.
38
39	- [ ] Decide the styling approach — Tailwind and Topcoat UI, or hand-rolled CSS
40	- [ ] Flash messages — the first edit form needs success and failure feedback, and
41	every form after it inherits whatever we build here
42	- [ ] `/{handle}/settings` — edit display name and bio, owner only, enforced in the use
43	case (settings belong to the org, and this scales to organisations)
44	- [ ] Owner-only affordances on the profile (edit link)
45
46	### Done when
47
48	Signed out, `/{handle}` renders the owner's display name and handle and nothing
49	private. An unknown handle 404s. The owner can set a display name and bio and see them
50	on the page. `/api/users/{handle}` returns the same public view.
51
52	### Findings — phase 1
53
54	- `path_param` is an attribute in Topcoat 0.5, applied to a tuple struct
55	(`#[path_param] struct Handle(str);`), not the function-like `path_param!(handle)`
56	that the docs on `main` describe. Read the vendored crate, not GitHub `main` —
57	the framework is two weeks old and the two have already diverged.
58	- A `str` inner type yields the raw percent-decoded segment with no parsing, which
59	suits validating through `OrgName` and 404ing what fails.
60	- Static routes beat parameterised ones, so `/auth/login` and `/api/me` still work
61	with `/{handle}` registered at the root. Verified, not assumed.
62	- Topcoat serves bundled assets from `/_topcoat/assets/…` with content-hashed URLs.
63
64	### Watch for
65
66	- Do not leak email. `describe_identity` carries email, and `/api/me` returns it —
67	correctly, because that endpoint describes the caller to themselves. The public
68	profile needs its own read model; reusing `Identity` would publish the owner's
69	email address to anonymous visitors. This is the single most likely mistake in this
70	milestone.
71	- Route precedence between static routes and `/{handle}`. The reserved list stops a
72	user owning `auth`, but it does not stop the router matching `/api/me` against
73	`/{handle}/{x}` and shadowing the real route. Static-over-parameterised is near
74	universal, so this is an assertion when the route lands, not a blocking spike.
75	- Case-insensitive handles. Storage is `collate nocase` and `OrgName::new`
76	lowercases, so `/JamesGill` must resolve rather than 404.
77	- Authorization on settings belongs in the use case, taking an `Actor` — not in the
78	page. Otherwise `/api` gets a different answer from the web form.
79	- A profile is public. This is the first page rendering for anonymous visitors by
80	design, so anything private must be gated explicitly rather than by assuming a
81	session exists.
82	- Reserve handles early. Adding to the denylist later is a breaking change for
83	whoever holds that handle ([0004](decisions/0004-root-handles-grouped-routes.md)).
84
85	### Settled
86
87	- Settings live at `/{handle}/settings`. They belong to the organisation, which
88	scales to real organisations in Milestone 7 without moving.
89	- Render the full frame from the start, including sections with nothing in them.
90	A profile page that renders almost nothing is a poor start for a portfolio-first
91	product; the shape of the page is part of what is being built, not scaffolding for
92	it.
93
94	### Carried over — small, unblocked
95
96	- No rate limiting on `/auth/login` or `/auth/setup`.
97	- `sweep_expired` is never called, so expired session rows accumulate. Expiry is
98	enforced on read, so this is tidiness, not a hole.
99	- CSRF. `SameSite=Lax` covers the common case; whether forms also want tokens is
100	still undecided. Phase 2 adds a form, so this is the natural time to settle it.
101	- Styling. Everything is unstyled HTML. Topcoat ships Tailwind without Node, and
102	`steid-backup/AGENTS/UI.md` has a full OKLCH system to mine. Cheaper now than at ten
103	pages — see [ui.md](ui.md).
104
105	## Backlog
106
107	Ordered. Pull from the top.
108
109	1. Milestone 3 — Writing. Posts, markdown rendering, `/{handle}/posts/{slug}`.
110	*Open question: is writing actually the first portfolio feature, or is it
111	projects/showcases?*
112	2. Milestone 4 — Repo model. `Repository` entity, `Visibility`, `create_repo`,
113	bare repo on disk at `{data_dir}/{org}/{repo}.git`. Watch the DB-plus-filesystem
114	atomicity problem — see [architecture.md](architecture.md#db-plus-filesystem-writes).
115	3. Milestone 5 — Git over HTTP. `git http-backend` subprocess, PATs over HTTP
116	Basic. See [0001](decisions/0001-git-over-http-not-ssh.md).
117
118	## Open questions
119
120	- Topcoat is early (v0.5.0, first released 2026-07-22, breaking changes expected
121	by its own authors). Expect churn that isn't feature work.
122	- Body size limits will reject large pushes at Milestone 5 — `topcoat-router` has a
123	`body_limit` layer that needs raising on the git routes. Recorded here because it
124	will surface as a confusing failure rather than a clear one.
125	- Topcoat ships Tailwind without Node, which reopens the design system attempt #1
126	dropped purely to avoid an npm build step — see [ui.md](ui.md).
127
128	## Routing findings (Milestone 0)
129
130	- Topcoat 0.5 requires rustc ≥ 1.95. On an older toolchain `cargo add topcoat`
131	silently resolves to an empty `topcoat v0.0.0` placeholder instead of failing. Local
132	stable is now 1.97.1.
133	- `Router::builder().discover()` collects `#[page]`-annotated items at link time,
134	so pages can live in any module. Layering is our choice, not the framework's.
135	- `module_router!` derives each URL from the module tree rather than a path string.
136	Still deferred. Application routes now group cleanly (`auth/login`, `api/me`), but
137	handles sit at the root ([0004](decisions/0004-root-handles-grouped-routes.md)), so a
138	parameterised root segment still has to coexist with static ones. Worth checking how
139	`module_router!` handles that before committing to it.
140	- Path and query params are read from `Cx` via `path_param!` / `#[query_params]`, not
141	injected as handler arguments. Parses are memoized per request.
142	- Layouts wrap by path prefix and nest outermost-first, and a layout can catch a page's
143	`NotFoundError` to render a branded 404.
144	- `HOST` / `PORT` configure the bind address, so `STEID_LISTEN_ADDR` is gone.
145	- `Body` is a boxed `http_body::Body` used for both requests and responses, with
146	`into_data_stream()` to read and `Body::new()` to wrap a stream — pack data can
147	stream both directions without buffering. This is what makes Milestone 5 viable.