# OxygenHub plan

Milestones from `docs/spec.md` §19. Each item is checked when its tests

pass, clippy is clean, and the change is committed with `oxy`.

## 0.1 Browse (2026-09-27)

- [x] Workspace: `crates/hub` (binary), `crates/hub-api` (API types), askama templates, vendored fonts, one stylesheet from the RetroPlay theme.

- [x] Configuration (`hub.toml` + `OXYHUB_*`), SQLite with embedded migrations (`repositories`, `pushes`).

- [x] Repository registry: bare, unbound-by-default repositories under `<data>/repos/<owner>/<name>`, per-repository read/write locks, trash on delete.

- [x] Embedded wire protocol with visibility and push-token authorisation and a push log.

- [x] Pages: home, owner, overview (tree, README, clone, bookmarks, tags, trust badge, heads and conflict strips), tree, file (highlighting, Markdown, images, raw, blame), history with the dependency graph and path filter, change with diff and dependencies, compare, bookmarks, tags, conflicts, trust, pushes.

- [x] JSON API: repositories, bookmarks, tags; `/health`; `/.well-known/oxyhub-key`.

- [x] CLI: `init` (keys, self-signed TLS), `serve` (HTTP and HTTPS), `admin repo create|list|delete|set`, `check`.

- [x] Tests: unit tests per module and an end-to-end test that pushes with a real `oxy-core` client and fetches every page.

- [x] Oxygen changes it needed (in the Oxygen plan, phase 4): bare repositories, embeddable server, unbound repositories, adoption of anonymous changes by seals, `oxy seal`.

- [x] Developer edition running on Earth with `oxygen`, `oxygen-vscode` and `oxygenhub` hosted (docs/deploy.md), pushed over HTTPS with the policy.

## 0.2 Accounts and access (2026-09-27)

- [x] Schema: accounts, organisations, members, teams, collaborators, tokens, identities, challenges, invitations, settings, audit; pushes carry the pusher.

- [x] Passwords (Argon2id), server-side sessions (random id, hash kept; idle and absolute expiry; listed and ended per browser, #223), CSRF tokens on every form, same-origin check on every non-GET request, TOTP with recovery codes, sign out everywhere.

- [x] Registration modes (open, invite, closed; first account is the administrator), invitations, admin page (accounts, ban, promote, registration mode, audit log).

- [x] Roles: owner and site admin → admin; organisation owners → admin, members → the organisation's default role; collaborators (accounts and teams) → their role; visibility public/internal/private decides the anonymous and signed-in floor. A repository the viewer may not read is a 404 everywhere, including the protocol.

- [x] Personal access tokens: hashed, scoped (`repo:read`, `repo:write`, `repo:admin`, `user:read`), optionally limited to repositories, with expiry; the protocol checks role and scope; site tokens from `hub.toml` remain for bootstrapping.

- [x] Linked identities: upload `oxy identity export`, sign the challenge with `oxy identity sign-challenge`, verified with `verify_challenge`; authors whose key is linked show as accounts on history, change and compare pages.

- [x] Pages: sign in, register, profile, security, keys, tokens, new repository, repository settings (general, collaborators, delete), organisation settings (members, teams), admin.

- [x] CLI: `admin user create|reset-password|list`.

- [x] Tests: `tests/accounts.rs` drives the whole flow through the router and the wire protocol.

- [ ] Email verification and password reset by email (needs SMTP, hub 0.4 with notifications).

- [ ] Passkeys (1.0).

## 0.3 Proposals and review (2026-09-27)

- [x] Schema: proposals with a per-repository number space shared with issues, comments (atom anchored), reviews, events; landing requirements on repositories.

- [x] Projection (`repos/proposals.rs`): union of the target's heads and the source (bookmark, fork with objects copied from the fork's store, or explicit changes), the changes added, the diff and the conflicts the landing would carry, recomputed on every view and remembered for lists, the API and stacking.

- [x] Comments anchored to atoms: a line comment records `(change, index)`; it is placed at the atom's current line, or listed as outdated when the line is gone.

- [x] Reviews: comment, request changes, approve; an approval counts when the reviewer's linked key has sealed every change (`oxy seal --proposal URL`, pushed on its own with `push_seals`); no self-approval.

- [x] Requirements: sealed approvals, code owners from `.oxyowners`, conflicts refused unless allowed, outstanding change requests, drafts, stacking on earlier open proposals.

- [x] Landing: from the hub when the repository has no policy; otherwise the page gives `oxy proposal land URL`, which fetches the projection, sets the bookmark and pushes with the user's key. A proposal whose changes all reach the target by any route is marked landed.

- [x] Pages: list with counts, new with preview, detail with conversation, changes and files tabs; JSON API for proposals used by `oxy proposal show|land` and `oxy seal --proposal`.

- [x] Tests: `tests/proposals.rs` covers bookmark and fork sources, anchoring, approval before and after sealing, requirements, landing.

- [x] Notifications for review requests, mentions and landings (0.4). Mentions and landings were in already; review requests (ask, withdraw, answered by a review, the author told of each review) added 2026-10-01.

- [ ] Hub-side landing under a policy through the delegate key (needs the attestation delegate rule in oxy, see spec §18).

## 0.4 Issues and notifications (2026-09-27)

- [x] Issues sharing the number space with proposals (`/issue/N` redirects to a proposal of that number), comments with edit and delete, timeline events, close with a reason, reopen, lock, pin.

- [x] Labels (on issues and proposals), assignees, milestones with counts; list filters `label: assignee: milestone: state:` plus words; issue templates from `.oxyhub/ISSUE_TEMPLATE/*.md`.

- [x] Cross references: `#12`, `owner/name#12`, `@user` and change hashes become links outside code; `closes #N` in a change landed on the default bookmark closes the issue, from pushes and hub landings.

- [x] Notifications: inbox with unread count in the header, thread subscriptions (acting on a thread subscribes you), watching a repository, mentions, direct targets (authors, assignees); optional email through SMTP with a one-click unsubscribe.

- [x] Search: FTS5 over issues and proposals with highlighted snippets, plus repositories and accounts, limited to what the viewer may see.

- [x] Tests: `tests/issues.rs`.

- [ ] Email verification and password reset (needs the SMTP path proven on Earth).

- [ ] Import from GitHub and GitLab (1.x).

## 0.5 API, webhooks, checks (2026-09-27)

- [x] `/api/v1` covers repositories (list, create, get), bookmarks, tags, history, changes, tree, file, blame, conflicts, trust, pushes, proposals (list, create, get, comments, reviews, checks), issues (list, create, get, state, comments), labels, milestones, hooks, checks, user, users, orgs, search. Bearer tokens with scopes; a repository the caller may not read is a 404; RFC 7807 problems.

- [x] `hub-api` types carry JSON Schema; `make ts` writes `crates/hub-api/ts/index.d.ts` for the extensions.

- [x] Webhooks per repository (and organisation): events `push`, `proposal.*`, `review`, `comment.*`, `issue.*`, `check`, `ping`; keyed-BLAKE3 signature header; a worker with backoff over a day; delivery log with redeliver; settings page and API.

- [x] Checks on state hashes: any `checks:write` or write token reports; required checks per repository gate landing on the projected state; the proposal page shows them and reloads on a server-sent `check` event.

- [x] Tests: `tests/api.rs` with a local webhook receiver that fails the first attempt.

- [ ] Organisation webhooks page (the API and delivery path handle them; no settings page yet).

## 0.6 Web edits, releases, mirror, code search (2026-09-27)

- [x] Oxygen: `Repo::build_change`, `host_ref_update`, `apply_hosted`; delegates of a policy rule's identities may sign reference and tag attestations, on push and on fetch (spec §14.5, Draft 0.8g).

- [x] Web edits: edit, create, rename and delete files with CodeMirror 6 (bundled from npm in `web/editor`, served from `assets/vendor`); EasyMDE for Markdown fields; commit to the bookmark or propose a new one. Authored by the user's linked identity, signed by the hub key as its delegate, applied through the push checks; refused with instructions until the user delegates.

- [x] Browser conflict resolution: conflicted text files open with their markers; a save without markers is a resolution change depending on every side.

- [x] Hub landing under a policy through the delegate key.

- [x] Releases on tags: generated notes from the changes since the previous release, pre-releases, the latest marker, assets stored by BLAKE3 with download counts, source archives (`.tar.zst`, `.zip`) of any state built once and cached; API to list, create and upload; webhook `release.published`.

- [x] Read-only Git mirror of the default bookmark: exported with `oxy git export` after every update, served by `git http-backend` behind the hub's access checks (Basic auth with a token for private repositories), pushes refused.

- [x] Code search per repository: substring or regex, match case, path prefix, a 2 s budget and 300-hit cap, cached per state.

- [x] API: anchored proposal comments (`path`, `line`).

- [x] Tests: `tests/edits.rs`, `tests/releases.rs` (real `git clone` and `git push` against the mirror).

- [ ] Organisation webhooks page; import from GitHub and GitLab; trigram code index (1.x).

## Later

- 0.7 runner · 1.0 hardening.

## Notes

- State caching (spec §16.3): `repos::cache::StateCache`, a bounded LRU of loaded states keyed by repository id and heads, shared across threads since `State` became `Send + Sync`. Measured on the `oxygen` repository (90 changes): overview 154 ms cold and under 2 ms warm, history 25 ms, tree under 1 ms. Rendered-page and syntax-highlight caches are still to do.

<<<<<<< oxy conflict 1 of 1, side 1 of 2: deleted by change 138969c8 "State cache keyed by heads; history and graph through oxy-core's lanes and log window"

-------

- `State` holds `Rc` values, so a cross-thread cache needs a `Send` snapshot type in `oxy-core` first.

======= oxy conflict 1 of 1, side 2 of 2: change a8a6b660 "Push log records states, heads and change counts from the push report"

The cross-product order of work is in `oxygen/docs/roadmap.md`.

>>>>>>> oxy conflict 1 of 1 end