# Oxygenhub for Visual Studio Code

| | |
|---|---|
| **Status** | Draft 0.1 |
| **Scope** | The forge in the editor: sign in to an Oxygenhub, see and review proposals with comments anchored to atoms, approve with a seal, land, work with issues, watch checks, and open anything on the hub. The counterpart of the GitHub Pull Requests and Issues extension. |
| **Depends on** | `oxygen-vscode` ≥ 0.7.0 (its exported API and remote providers), Oxygenhub ≥ 0.5 (`/api/v1`), `oxy` with `seal --proposal` and `proposal land` |
| **Date** | 2026-09-27 |

## 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

| GitHub Pull Requests and Issues | Oxygenhub for VS Code |
|---|---|
| Sign in with GitHub (OAuth) | Sign in with a personal access token; an authentication provider `oxygenhub` other extensions can request |
| Pull Requests view: waiting for my review, created by me, all | Proposals view: **Assigned to me** (review requested or approval needed), **Mine**, **Open**, per repository |
| Checkout PR branch | Fetch the proposal's changes and check out its projected state into a bookmark (`oxy` fetch + bookmark set) |
| Review comments in the diff, threads | Comment threads on the projected state's files via the Comments API, anchored to atoms |
| Approve, Request changes | Same; **Approve** also offers to run `oxy seal --proposal` so it counts |
| Merge button | **Land** runs `oxy proposal land` (or the hub lands when it has no policy) |
| Issues view, create issue | Same, with labels, assignees and milestone |
| Checks under the PR | Checks on the projected state, live over the hub's event stream |
| Open on GitHub | Open on Remote, through the remote provider |

## 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

| | Delivers |
|---|---|
| **0.1** | Sign in, hub client with generated types, remote provider (Open on Remote works), proposals view with detail and open-on-hub, issues view with create and comment |
| **0.2** | Check out a proposal, review threads on atoms, reviews, seal and land through the terminal, checks in the status bar with live events |
| **0.3** | Issues: labels, assignees, milestones; notifications count; create proposal from the current bookmark |
| **1.0** | Marketplace listing beside oxygen-vscode, three-platform tests |

## 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.