# Current

> Keep this file short. One active step, one ordered backlog. Completed work moves to
> [progress.md](progress.md). If this file starts reading like a changelog, it has
> drifted — that's exactly what went wrong last time.

## Active: Milestone 5 — Repo browsing

**Goal:** a repository's contents are readable on the web — the file tree at a ref, a
single file's contents, and the commit log. A visitor can look at code without cloning
it, which is the first time the profile behaves like a portfolio rather than a list of
names.

**Out of scope:** editing files, diffs, blame, syntax highlighting, rendering a README as
markdown (that wants the markdown pipeline Milestone 6 brings), search, and a
last-commit-per-file column — see Open, where that one is a decision rather than an
omission.

### Steps

- [ ] Domain: `ObjectId`, `RefName`, `TreeEntry` — value objects **before** any adapter,
      per [0006](decisions/0006-git-binary-behind-narrow-ports.md)
- [ ] Application: `GitQuery` port — `resolve_ref`, `list_tree`, `read_blob`, `log`
- [ ] Infrastructure: adapter over the `git` binary, through the existing `git_command`
- [ ] Application: `browse_repo` read model, reusing `view_repo`'s visibility rule
- [ ] Web: the tree page, and the repository page showing its default branch
- [ ] Web: the blob page, and the commit log
- [ ] Verify in a browser against a real repository, including an empty one

### Done when

A visitor can open a public repository from a profile, see its files at the default
branch, click into a directory and then a file and read its contents, and open the commit
log. A private repository shows none of this to someone who may not see it. An empty
repository says so rather than erroring.

### Settled

- **Value objects come first.** A query port returning `String`s is an anaemic
  pass-through that pushes validation into the page, which
  [0006](decisions/0006-git-binary-behind-narrow-ports.md) rejected in advance.

- **The read path stays on the `git` binary, one process per query**, with
  `cat-file --batch` as the named upgrade and `gix` closed off — reasoning, the
  measurement, and the reopening conditions in
  [0006](decisions/0006-git-binary-behind-narrow-ports.md#amendment--20260829-the-milestone-5-read-path).
- **`GitQuery` is a shared handle in app context**, not constructed per request the way
  the SQLite adapters are. Stage 1 does not need the sharing; stage 2 owns live
  subprocesses and cannot work without it. The port gives us the seam, not the lifetime,
  and getting the lifetime wrong now means touching every page later.
- **No per-file last-commit column in v1.** The direct consequence of the above: at one
  fork per entry a twenty-file directory is ~230ms. If it is missed, that is the trigger
  to climb to stage 2 rather than to reopen `gix`.
- **Fork/exec is ~11–12ms per call, and it is the process, not the query.** Measured on
  a 201-commit repository, averaged over 50 runs each: `rev-parse` 11.2ms, `ls-tree`
  11.7ms, `cat-file` 11.6ms, `log -20` 11.8ms, `for-each-ref` 14.4ms. The work is
  free; starting git is not — which matches the ~13ms `git init --bare` measured in
  Milestone 3. **A three-call page therefore costs ~35ms of pure overhead.** That is the
  number the Open decision below turns on, and it is why a per-file last-commit column is
  a decision and not a detail: at one call per entry, a twenty-file directory is ~230ms
  before any real work.

### Open

- **The ref-versus-path ambiguity in the URL.** `/{handle}/repos/{name}/tree/{ref}/{path}`
  is unparseable in general, because a ref may contain slashes: `tree/feature/x/README`
  splits two ways. GitHub resolves it by trying candidate splits against the real ref
  list; GitLab inserts a `/-/` separator. A third option is a single-segment ref with the
  path after it, refusing refs with slashes. This is a URL shape, so it is expensive to
  change later. **Recommendation: the separator.** Candidate splits cost a ref lookup —
  another fork on every page — which the decision above makes more expensive, and a
  separator is unambiguous by construction rather than by lookup.
- **How a blob page handles what is not source code.** Binary files, invalid UTF-8, and
  very large files all arrive at the same page. Deciding beats discovering.
- **How far back the commit log goes** before it needs paging.

### Watch for

- **An empty repository has no `HEAD`.** Steid creates repositories empty, and
  Milestone 4 made it easy to have one that was never pushed to. `rev-parse HEAD` fails
  rather than returning nothing, and the repository page must say "nothing here yet"
  instead of erroring.
- **A blob is not necessarily text.** Binary files, invalid UTF-8, and very large files
  all reach the same page. Decide what each does rather than discovering it.
- **Paths in URLs reach the filesystem indirectly**, via git rather than directly, but a
  path is still user input arriving at a subprocess argument. `--` before path arguments,
  as `init_bare` already does.
- **The commit log is unbounded.** A repository with 50,000 commits needs a limit before
  the page renders one.

### Carried over — small, unblocked

- **A client that disappears mid-request leaves the body-copy task waiting.** The copy
  into git's stdin runs in its own task and nothing cancels it if the connection drops.
  Bounded by the backend exiting and closing the pipe, but not by anything deliberate.
- **`REMOTE_USER` is not set on the backend**, so a push is recorded in the repository's
  reflog without naming who made it. Steid knows the actor by then; it simply is not
  passed through. Small, and worth doing before anything reads reflogs.
- **No rate limiting on token authentication.** A token is 256 bits so guessing is not
  the worry; unbounded hashing on an open endpoint is.
- **Tokens have no expiry and no last-used timestamp.** Both deliberate omissions for
  now — see [0007](decisions/0007-tokens-over-http-basic.md) — but a token list with no
  "last used" makes it hard to know which are safe to revoke.
- **A subprocess per git request.** Unlike Milestone 3's once-per-creation, this is on a
  hot path and has not been measured. Milestone 5 is where that bill comes due.
- **Streaming is by construction, not by measurement.** The response body is never
  collected, but no clone large enough to prove it has been run.
- **An orphaned repo directory is possible** if the process dies between the record
  write and the filesystem write, and it then blocks re-creating that name. The durable
  fix is a reconciliation sweep on boot
  ([architecture.md](architecture.md#db-plus-filesystem-writes)); clearing one is a
  manual `rm` today, since repo deletion does not exist.
- **The duplicate-name check races.** The loser is caught by `init_bare` or the unique
  constraint, but surfaces as an opaque storage error rather than "name taken".
- **Bare repos created on macOS carry `ignorecase = true`.** A migration gotcha if the
  data directory ever moves to Linux.
- **Fonts are not loaded.** The theme names Geist and IBM Plex Mono; both fall back
  today. Topcoat's `font-fontsource` feature handles it.
- **Light mode is untested.** The palette defines it; nobody has looked at it.
- **No rate limiting** on `/auth/login` or `/auth/setup`.
- **`sweep_expired` is never called**, so expired session rows accumulate. Expiry is
  enforced on read, so this is tidiness, not a hole.
- **CSRF.** `SameSite=Lax` covers the common case. Forms now exist, so this is decidable
  rather than hypothetical.

## Backlog

Ordered. Pull from the top.

1. **Milestone 6 — Writing.** Posts, markdown, `/{handle}/posts/{slug}`. Still open
   whether writing or projects/showcases is the better first portfolio feature.

## Open questions

- **Topcoat is early** (v0.5.0, first released 2026-07-22, breaking changes expected
  by its own authors). Expect churn that isn't feature work.
- Topcoat ships Tailwind without Node, which reopens the design system attempt #1
  dropped purely to avoid an npm build step — see [ui.md](ui.md).

## Routing findings (Milestone 0)

- **Topcoat 0.5 requires rustc ≥ 1.95.** On an older toolchain `cargo add topcoat`
  silently resolves to an empty `topcoat v0.0.0` placeholder instead of failing. Local
  stable is now 1.97.1.
- `Router::builder().discover()` collects `#[page]`-annotated items **at link time**,
  so pages can live in any module. Layering is our choice, not the framework's.
- `module_router!` derives each URL from the module tree rather than a path string.
  Still deferred. Application routes now group cleanly (`auth/login`, `api/me`), but
  handles sit at the root ([0004](decisions/0004-root-handles-grouped-routes.md)), so a
  parameterised root segment still has to coexist with static ones. Worth checking how
  `module_router!` handles that before committing to it.
- Path and query params are read from `Cx` via `path_param!` / `#[query_params]`, not
  injected as handler arguments. Parses are memoized per request.
- Layouts wrap by path prefix and nest outermost-first, and a layout can catch a page's
  `NotFoundError` to render a branded 404.
- `HOST` / `PORT` configure the bind address, so `STEID_LISTEN_ADDR` is gone.
- `Body` is a boxed `http_body::Body` used for both requests and responses, with
  `into_data_stream()` to read and `Body::new()` to wrap a stream — pack data can
  stream both directions without buffering. This is what makes Milestone 4 viable.