| 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 | |
2eb8681docs: put git next, plan the repo model24d | 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 | |
c6d74a8docs: record the repo model decisions24d | 19 | - [x] Domain: `RepoId`, `RepoName`, `Visibility` (Public/Private), `Repository` |
c5b3ff5feat: repository persistence24d | 20 | - [x] Domain: `RepoRepository` port — `find_by_id`, `find_by_org_and_name`, |
2eb8681docs: put git next, plan the repo model24d | 21 | `list_by_org`, `save` |
c5b3ff5feat: repository persistence24d | 22 | - [x] Infrastructure: in-memory + SQLite implementations, migration |
02eb2e4feat: GitStorage port and DiskGitStorage24d | 23 | - [x] Application: `GitStorage` port — `init_bare`, `remove`, `repo_path` |
| 24 | - [x] Infrastructure: `DiskGitStorage`, shelling out to `git init --bare` |
11e7a39feat: create_repo use case24d | 25 | - [x] Application: `create_repo` use case — owner only, validates, creates record and |
2eb8681docs: put git next, plan the repo model24d | 26 | bare repo |
285f5fdfeat: create and view repositories through the browser24d | 27 | - [x] Application: `view_repo` read model — visibility-aware |
| 28 | - [x] Web: `/{handle}/repos/new` form, `/{handle}/repos/{name}` page |
0c5ca49feat: list repositories on the profile8d | 29 | - [x] Application: `list_repos` + the profile's Repositories section listing what the |
285f5fdfeat: create and view repositories through the browser24d | 30 | viewer may see |
2eb8681docs: put git next, plan the repo model24d | 31 | - [ ] `/api/users/{handle}/repos` |
| 32 | |
| 33 | ### Done when |
| 34 | |
2eb8681docs: put git next, plan the repo model24d | 35 | The owner creates a repo through the UI, a bare repo appears at |
| 36 | `{data_dir}/{handle}/{name}.git`, and it is listed on the profile. A private repo is |
| 37 | invisible to a signed-out visitor. `git clone` does **not** work yet — that is |
| 38 | milestone 4. |
| 39 | |
c6d74a8docs: record the repo model decisions24d | 40 | ### Settled |
2eb8681docs: put git next, plan the repo model24d | 41 | |
0c5ca49feat: list repositories on the profile8d | 42 | - **`list_repos` returns `Option<Vec<_>>`.** `None` is an unknown handle, |
| 43 | `Some(vec![])` a handle whose repositories the viewer cannot see. `/api` needs that |
| 44 | difference to answer 404 rather than `[]` for a user who does not exist. |
| 45 | - **`RepoSummary` is separate from `RepoView`.** The owning handle and |
| 46 | `viewer_is_owner` are constant across a listing and already known to the page, so a |
| 47 | listing type carries neither. |
285f5fdfeat: create and view repositories through the browser24d | 48 | - **`list_repos` was split from `view_repo`** and moved to the listing step. `view_repo` |
| 49 | had a consumer immediately; `list_repos` would have been a third read model with no |
| 50 | caller, which is what the previous three steps already were. |
| 51 | - **An invisible private repo is `None`, not `Forbidden`.** `view_repo` answers the same |
| 52 | way for "does not exist" and "not allowed to see", and the page 404s identically. A |
| 53 | 403 would confirm the repository exists and leak its name. |
| 54 | - **Private repos are visible to any member**, not only the owner — seeing is weaker |
| 55 | than changing, matching attempt #2's clone rule. |
| 56 | |
c6d74a8docs: record the repo model decisions24d | 57 | - **Repo name rules:** `OrgName`'s, plus `.` and `_` for names like `.github` and |
| 58 | `foo.js`. Lowercased, max 100. Also rejects a name of nothing but dots and any name |
| 59 | ending `.git` — the first is traversal, the second would live at `foo.git.git`. |
| 60 | - **Reserved repo names:** `import`, `new`, `search`. Only names directly under |
| 61 | `/{handle}/repos/` can collide. |
| 62 | - **Visibility defaults to public**, matching a portfolio-first product. |
| 63 | - **Repositories carry an optional description**, capped at 300 characters — a sentence |
02eb2e4feat: GitStorage port and DiskGitStorage24d | 64 | for the profile listing, not a README. Kept deliberately: portfolio-first is the |
| 65 | tie-break, and this milestone's own "Done when" puts repositories on the profile, so |
| 66 | the consumer is inside the milestone rather than hypothetical. The per-repo analogue |
| 67 | of `Organization::bio`. |
c5b3ff5feat: repository persistence24d | 68 | - **`list_by_org` returns every repository regardless of visibility.** Filtering is an |
| 69 | authorization decision and belongs to the use case, so the page and `/api` cannot end |
| 70 | up applying different rules. The cost is that a private repo is briefly in memory |
| 71 | before being filtered, which is fine in-process. |
3954b45docs: record milestone 2 phase 125d | 72 | |
be4fac5docs: correct the Topcoat guidance in CLAUDE.md24d | 73 | ### Open |
| 74 | |
02eb2e4feat: GitStorage port and DiskGitStorage24d | 75 | Nothing open. `GitStorage`'s shape and how git is invoked are recorded in |
| 76 | [0006](decisions/0006-git-binary-behind-narrow-ports.md). |
be4fac5docs: correct the Topcoat guidance in CLAUDE.md24d | 77 | |
bd48b4bdocs: serve git over smart HTTP, reorder roadmap portfolio-first1mo | 78 | ### Watch for |
d7b99d9docs: record milestone 0 progress and routing findings1mo | 79 | |
285f5fdfeat: create and view repositories through the browser24d | 80 | - **`redirect()` is a 307 and re-POSTs.** Post/redirect/get needs a 303. `see_other()` |
| 81 | is the right status but is a *response* type, and `#[page]` must return a view so the |
| 82 | layout can wrap a failure re-render. The way to get both from one handler is a |
| 83 | `StatusCode` and a `Location` pair inside `view!` — wrapped as |
| 84 | `context::location`. This shipped broken in Milestone 2's settings form and was |
| 85 | caught by browser verification, not by any test. |
| 86 | |
11e7a39feat: create_repo use case24d | 87 | - **An orphaned directory is indistinguishable from a duplicate to the visitor.** |
| 88 | `create_repo` maps `GitStorageError::AlreadyExists` to "that name is taken", which is |
| 89 | true from outside but hides the inconsistency from the operator. There is no logging |
| 90 | story yet for it to surface in. The durable fix is the reconciliation sweep in |
| 91 | [architecture.md](architecture.md#db-plus-filesystem-writes). |
| 92 | - **The duplicate check races.** Two concurrent creates of the same name can both pass |
| 93 | `find_by_org_and_name`; the loser is then stopped by `init_bare` or, failing that, by |
| 94 | the `unique (org_id, name)` constraint — which surfaces as an opaque storage error |
| 95 | rather than "name taken". Correct, just ugly, and single-user for now. |
| 96 | |
2eb8681docs: put git next, plan the repo model24d | 97 | - **The database and the filesystem cannot share a transaction.** Creating a repo |
| 98 | writes a row and a directory. Neither previous attempt solved this properly — see |
| 99 | [architecture.md](architecture.md#db-plus-filesystem-writes). A compensating delete is |
| 100 | good enough to ship, but write down that an orphaned directory is possible if the |
| 101 | process dies between the two, rather than rediscovering it. |
| 102 | - **Path traversal.** `{data_dir}/{handle}/{name}.git` is built from user input. A name |
| 103 | containing `..` or `/` must be impossible before it reaches the filesystem, and |
| 104 | `RepoName` is the place to make it impossible rather than sanitising at the call site. |
| 105 | - **Visibility is an authorization decision**, so it belongs in the use case. A private |
| 106 | repo must be absent from listings, not merely unlinked — and `/api` must agree with |
| 107 | the page. |
02eb2e4feat: GitStorage port and DiskGitStorage24d | 108 | - **`git` is a dependency of the test suite too**, not only of the runtime — |
| 109 | `DiskGitStorage`'s tests run real `git init`. A machine without `git` fails |
| 110 | `cargo test`, not just the app. |
| 111 | - **A handle rename is a directory move.** The layout is keyed by handle for |
| 112 | legibility, so whenever renaming arrives it has to move the tree; it cannot be a row |
| 113 | update. Nothing renames handles today. |
| 114 | - **Bare repos created on macOS carry `ignorecase = true`** in their config, because |
| 115 | git probes the filesystem at init. Correct where it was created, wrong if the data |
| 116 | directory is ever moved to Linux. A migration gotcha, not a bug. |
| 117 | - **An orphaned directory blocks re-creating that name.** `init_bare` refuses rather |
| 118 | than adopting what is already there, and repo deletion is out of scope this |
| 119 | milestone, so clearing one is a manual `rm` for now. |
076dbc9docs: close milestone 1, open milestone 21mo | 120 | |
f0444b7docs: plan milestone 2 in two phases1mo | 121 | ### Carried over — small, unblocked |
076dbc9docs: close milestone 1, open milestone 21mo | 122 | |
2eb8681docs: put git next, plan the repo model24d | 123 | - **Fonts are not loaded.** The theme names Geist and IBM Plex Mono; both fall back |
| 124 | today. Topcoat's `font-fontsource` feature handles it. |
| 125 | - **Light mode is untested.** The palette defines it; nobody has looked at it. |
f0444b7docs: plan milestone 2 in two phases1mo | 126 | - **No rate limiting** on `/auth/login` or `/auth/setup`. |
076dbc9docs: close milestone 1, open milestone 21mo | 127 | - **`sweep_expired` is never called**, so expired session rows accumulate. Expiry is |
| 128 | enforced on read, so this is tidiness, not a hole. |
2eb8681docs: put git next, plan the repo model24d | 129 | - **CSRF.** `SameSite=Lax` covers the common case. Forms now exist, so this is decidable |
| 130 | rather than hypothetical. |
| 131 | |
| 132 | ## Backlog |
| 133 | |
| 134 | Ordered. Pull from the top. |
| 135 | |
2eb8681docs: put git next, plan the repo model24d | 136 | 1. **Milestone 4 — Git over HTTP.** `git http-backend` subprocess, PATs over HTTP |
| 137 | Basic. See [0001](decisions/0001-git-over-http-not-ssh.md). The `body_limit` cap will |
| 138 | reject large pushes until raised. |
02eb2e4feat: GitStorage port and DiskGitStorage24d | 139 | 2. **Milestone 5 — Repo browsing.** Tree, blob, commit log. **Start with domain value |
| 140 | objects** — `ObjectId`, `RefName`, `TreeEntry` — before any adapter. A query port |
| 141 | returning `String`s is an anaemic pass-through that pushes validation into the page. |
| 142 | Also the point to measure fork/exec cost per page view, and to reconsider `gix` for |
| 143 | the read path ([0006](decisions/0006-git-binary-behind-narrow-ports.md)). |
2eb8681docs: put git next, plan the repo model24d | 144 | 3. **Milestone 6 — Writing.** Posts, markdown, `/{handle}/posts/{slug}`. Still open |
| 145 | whether writing or projects/showcases is the better first portfolio feature. |
| 146 | |
| 147 | ## Open questions |
| 148 | |
bd48b4bdocs: serve git over smart HTTP, reorder roadmap portfolio-first1mo | 149 | - **Topcoat is early** (v0.5.0, first released 2026-07-22, breaking changes expected |
| 150 | by its own authors). Expect churn that isn't feature work. |
ca76e1bdocs: fix milestone cross-references after the reorder24d | 151 | - Body size limits will reject large pushes at Milestone 4 — `topcoat-router` has a |
bd48b4bdocs: serve git over smart HTTP, reorder roadmap portfolio-first1mo | 152 | `body_limit` layer that needs raising on the git routes. Recorded here because it |
| 153 | will surface as a confusing failure rather than a clear one. |
| 154 | - Topcoat ships Tailwind without Node, which reopens the design system attempt #1 |
| 155 | dropped purely to avoid an npm build step — see [ui.md](ui.md). |
| 156 | |
| 157 | ## Routing findings (Milestone 0) |
| 158 | |
| 159 | - **Topcoat 0.5 requires rustc ≥ 1.95.** On an older toolchain `cargo add topcoat` |
| 160 | silently resolves to an empty `topcoat v0.0.0` placeholder instead of failing. Local |
| 161 | stable is now 1.97.1. |
| 162 | - `Router::builder().discover()` collects `#[page]`-annotated items **at link time**, |
| 163 | so pages can live in any module. Layering is our choice, not the framework's. |
| 164 | - `module_router!` derives each URL from the module tree rather than a path string. |
aaefaabfeat: root handles, grouped routes, reserved-handle denylist1mo | 165 | Still deferred. Application routes now group cleanly (`auth/login`, `api/me`), but |
| 166 | handles sit at the root ([0004](decisions/0004-root-handles-grouped-routes.md)), so a |
| 167 | parameterised root segment still has to coexist with static ones. Worth checking how |
| 168 | `module_router!` handles that before committing to it. |
bd48b4bdocs: serve git over smart HTTP, reorder roadmap portfolio-first1mo | 169 | - Path and query params are read from `Cx` via `path_param!` / `#[query_params]`, not |
| 170 | injected as handler arguments. Parses are memoized per request. |
| 171 | - Layouts wrap by path prefix and nest outermost-first, and a layout can catch a page's |
| 172 | `NotFoundError` to render a branded 404. |
| 173 | - `HOST` / `PORT` configure the bind address, so `STEID_LISTEN_ADDR` is gone. |
| 174 | - `Body` is a boxed `http_body::Body` used for both requests and responses, with |
| 175 | `into_data_stream()` to read and `Body::new()` to wrap a stream — pack data can |
ca76e1bdocs: fix milestone cross-references after the reorder24d | 176 | stream both directions without buffering. This is what makes Milestone 4 viable. |