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	- [x] Styling: Tailwind via Topcoat, theme retuned, primitives copied in, `flash`
40	written by hand ([0005](decisions/0005-tailwind-and-copied-components.md))
41	- [x] Flash messages — `flash` component, hand-written; the registry has no alert
42	- [x] `/{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	- [x] 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 2
53
54	- Components are invoked bare inside `view!` — `label(attrs: …, "Text")`, not
55	`(label(…)?)`. `if`, `match`, `for` and `let` are native to the macro too, so the
56	wrapper-block pattern is unnecessary.
57	- `#[query_params]` needs `error = …` to be usable with `?`. Without it the `Err`
58	side borrows from `cx` and the borrow escapes the handler.
59	- Post-redirect-get on success, re-render on failure. A redirect after an error
60	would discard what was typed and lose the reason — the exact problem `flash` exists
61	to solve.
62	- `PublicProfile` carries `display_name` separately from `label`, so an edit form can
63	leave the field empty rather than prefilling the handle.
64
65	### Findings — phase 1
66
67	- `path_param` is an attribute in Topcoat 0.5, applied to a tuple struct
68	(`#[path_param] struct Handle(str);`), not the function-like `path_param!(handle)`
69	that the docs on `main` describe. Read the vendored crate, not GitHub `main` —
70	the framework is two weeks old and the two have already diverged.
71	- A `str` inner type yields the raw percent-decoded segment with no parsing, which
72	suits validating through `OrgName` and 404ing what fails.
73	- Static routes beat parameterised ones, so `/auth/login` and `/api/me` still work
74	with `/{handle}` registered at the root. Verified, not assumed.
75	- Topcoat serves bundled assets from `/_topcoat/assets/…` with content-hashed URLs.
76
77	### Watch for
78
79	- Do not leak email. `describe_identity` carries email, and `/api/me` returns it —
80	correctly, because that endpoint describes the caller to themselves. The public
81	profile needs its own read model; reusing `Identity` would publish the owner's
82	email address to anonymous visitors. This is the single most likely mistake in this
83	milestone.
84	- Route precedence between static routes and `/{handle}`. The reserved list stops a
85	user owning `auth`, but it does not stop the router matching `/api/me` against
86	`/{handle}/{x}` and shadowing the real route. Static-over-parameterised is near
87	universal, so this is an assertion when the route lands, not a blocking spike.
88	- Case-insensitive handles. Storage is `collate nocase` and `OrgName::new`
89	lowercases, so `/JamesGill` must resolve rather than 404.
90	- Authorization on settings belongs in the use case, taking an `Actor` — not in the
91	page. Otherwise `/api` gets a different answer from the web form.
92	- A profile is public. This is the first page rendering for anonymous visitors by
93	design, so anything private must be gated explicitly rather than by assuming a
94	session exists.
95	- Reserve handles early. Adding to the denylist later is a breaking change for
96	whoever holds that handle ([0004](decisions/0004-root-handles-grouped-routes.md)).
97
98	### Settled
99
100	- Settings live at `/{handle}/settings`. They belong to the organisation, which
101	scales to real organisations in Milestone 7 without moving.
102	- Render the full frame from the start, including sections with nothing in them.
103	A profile page that renders almost nothing is a poor start for a portfolio-first
104	product; the shape of the page is part of what is being built, not scaffolding for
105	it.
106
107	### Carried over — small, unblocked
108
109	- No rate limiting on `/auth/login` or `/auth/setup`.
110	- `sweep_expired` is never called, so expired session rows accumulate. Expiry is
111	enforced on read, so this is tidiness, not a hole.
112	- CSRF. `SameSite=Lax` covers the common case; whether forms also want tokens is
113	still undecided. Phase 2 adds a form, so this is the natural time to settle it.
114	- Light mode is untested. The palette defines it, but every page has been looked at
115	dark-only. There is no toggle yet either.
116	- Fonts are not loaded. The theme names Geist and IBM Plex Mono; neither is
117	installed, so both fall back. `topcoat`'s `font-fontsource` feature handles this.
118
119	## Backlog
120
121	Ordered. Pull from the top.
122
123	1. Milestone 3 — Writing. Posts, markdown rendering, `/{handle}/posts/{slug}`.
124	*Open question: is writing actually the first portfolio feature, or is it
125	projects/showcases?*
126	2. Milestone 4 — Repo model. `Repository` entity, `Visibility`, `create_repo`,
127	bare repo on disk at `{data_dir}/{org}/{repo}.git`. Watch the DB-plus-filesystem
128	atomicity problem — see [architecture.md](architecture.md#db-plus-filesystem-writes).
129	3. Milestone 5 — Git over HTTP. `git http-backend` subprocess, PATs over HTTP
130	Basic. See [0001](decisions/0001-git-over-http-not-ssh.md).
131
132	## Open questions
133
134	- Topcoat is early (v0.5.0, first released 2026-07-22, breaking changes expected
135	by its own authors). Expect churn that isn't feature work.
136	- Body size limits will reject large pushes at Milestone 5 — `topcoat-router` has a
137	`body_limit` layer that needs raising on the git routes. Recorded here because it
138	will surface as a confusing failure rather than a clear one.
139	- Topcoat ships Tailwind without Node, which reopens the design system attempt #1
140	dropped purely to avoid an npm build step — see [ui.md](ui.md).
141
142	## Routing findings (Milestone 0)
143
144	- Topcoat 0.5 requires rustc ≥ 1.95. On an older toolchain `cargo add topcoat`
145	silently resolves to an empty `topcoat v0.0.0` placeholder instead of failing. Local
146	stable is now 1.97.1.
147	- `Router::builder().discover()` collects `#[page]`-annotated items at link time,
148	so pages can live in any module. Layering is our choice, not the framework's.
149	- `module_router!` derives each URL from the module tree rather than a path string.
150	Still deferred. Application routes now group cleanly (`auth/login`, `api/me`), but
151	handles sit at the root ([0004](decisions/0004-root-handles-grouped-routes.md)), so a
152	parameterised root segment still has to coexist with static ones. Worth checking how
153	`module_router!` handles that before committing to it.
154	- Path and query params are read from `Cx` via `path_param!` / `#[query_params]`, not
155	injected as handler arguments. Parses are memoized per request.
156	- Layouts wrap by path prefix and nest outermost-first, and a layout can catch a page's
157	`NotFoundError` to render a branded 404.
158	- `HOST` / `PORT` configure the bind address, so `STEID_LISTEN_ADDR` is gone.
159	- `Body` is a boxed `http_body::Body` used for both requests and responses, with
160	`into_data_stream()` to read and `Body::new()` to wrap a stream — pack data can
161	stream both directions without buffering. This is what makes Milestone 5 viable.