Oxygenhub for Visual Studio Code

1. Goals

1. Everything the hub can do about a proposal or an issue is reachable without leaving the editor, and everything that changes history still goes through oxy on the user's machine with the user's key: sealing an approval and landing run oxy, never a hub-side signature.
2. Build on oxygen-vscode, never beside it. Repositories, status, bookmarks and remotes come from its exported API; this extension registers a remote provider so "Open on Remote" works for hubs.
3. Review where the code is. Proposal comments appear as VS Code comment threads on the projected state's files, anchored to atoms exactly as the hub stores them, so they follow the line through rebases.
4. Honest about identity. An approval shows as pending until the hub confirms the seal; a check shows what the hub reports.

Non-goals for 1.0: creating repositories or organisations, administration, notifications beyond the status bar count, editing files on the hub.

2. How it compares

3. Architecture

src/
  extension.ts      activation, wiring, commands
  auth.ts           AuthenticationProvider "oxygenhub": sessions = {hub base URL, token}, stored in SecretStorage
  hub.ts            HubClient: typed fetch over /api/v1 using hub-api's generated types (src/hubapi.d.ts, copied by `npm run types`)
  provider.ts       the RemoteProvider registered with oxygen-vscode: matches a session's base URL, builds hub URLs
  proposals.ts      TreeDataProvider: proposals by repository and bucket; detail webview; actions
  review.ts         CommentController over oxy: content of the projected state, threads placed by atom, reply/resolve
  issues.ts         TreeDataProvider: issues; create, comment, close
  checks.ts         status bar: checks of the current bookmark's proposal; SSE subscription
  hubapi.d.ts       generated from the hub (do not edit)

Pure modules (hub.ts URL building and parsing, provider.ts) are tested with Node against a real hub started from the oxygenhub binary when present; the rest is exercised manually.

4. Sign in

oxygenhub.signIn asks for the hub URL (default: the first remote that looks like a hub, https://…/owner/name minus the last two segments) and a personal access token (Settings › Tokens on the hub; scopes repo:read repo:write proposals:write issues:write). The token is kept in SecretStorage under the base URL; sessions are exposed through vscode.authentication so oxygen-vscode or others can reuse them. oxygenhub.signOut forgets it.

5. Proposals

The Oxygenhub: Proposals view lists, per repository that has a hub remote, proposals in three groups: needing me (open, not mine, where I have not approved or where my approval is pending a seal), mine, and other open ones. Each row shows number, title, author, target, state chips (draft, conflicted, landable) and the check summary. Actions: open detail, open on hub, check out, review (comment / request changes / approve), seal approval, land, close.

Detail is a webview: description, blockers, approvals (sealed or pending), checks, the changes list with signatures, and buttons for the actions. Check out fetches from the hub remote and sets a local bookmark proposal/N to the projected heads, then switches to it, so the files in the editor are the projected state; review threads then appear in place.

6. Review threads

A CommentController for the checked-out proposal. Threads come from GET …/proposals/N/comments; each anchored comment is placed by asking oxy for the current line of its atom (oxy blame --json gives atoms per line; the extension finds the line whose (hash, index) matches). Replying posts a comment anchored to the same atom; a new thread on a line posts with the line's atom. Resolve toggles the hub's resolved flag. Threads whose atom is no longer live are shown in a separate "outdated" list in the view.

7. Approvals and landing

Approve posts the review, then offers to run oxy seal --proposal <url> in the repository's terminal so the approval is backed by the user's seal; the row shows "pending seal" until the hub reports it sealed. Land runs oxy proposal land <url> in a terminal (the hub's own landing is offered when the hub reports it can land, for repositories without a policy). Both use the integrated terminal so the user sees exactly what runs with their key.

8. Issues

The Oxygenhub: Issues view lists open issues per repository (assigned to me first). Actions: open detail (webview with the timeline and a comment box), open on hub, create issue (title and body inputs), close, reopen, assign to me.

9. Checks and status bar

A status bar item shows, for the current repository's current bookmark, the open proposal whose source it is and the state of its checks (✔ n passed, ✘ failing, … running). It subscribes to the hub's proposal event stream and refreshes on check events; clicking opens the proposal.

10. Configuration

oxygenhub.hubs: known hub base URLs (also learnt from sign in). oxygenhub.proposalBookmarkPrefix: proposal/. oxygenhub.autoRefresh: seconds between view refreshes (60).

11. Milestones

12. Open questions

1. Whether to render the proposal diff in a native diff editor (base vs projected content via an oxyhub: content provider) instead of the webview's file list. Likely yes in 0.2, since threads need real editors anyway.
2. Token scopes: the extension could ask for a narrower token per action. Not for 1.0.