|**Scope**| A VS Code extension giving Oxygen repositories the same integrated experience the built-in Git extension gives Git, plus what the Oxygen model makes possible |
7
|**Depends on**|`oxy` (reference implementation, spec Draft 0.8a) with the machine interface of §4 |
8
9
##1. Goals
10
11
1.**Parity with the built-in Git extension.** Everything a VS Code user does with Git through the UI must be doable with Oxygen through the UI: see what changed, diff it, commit some or all of it, switch bookmarks, sync with a remote, see history, resolve conflicts, and get gutter and explorer decorations, without opening a terminal.
12
2.**Expose what Oxygen does better.** Exact blame, first-class conflicts with a resolution flow, undo of any operation, bisect, subrepositories, and the trust policy get first-class UI rather than being hidden behind the Git vocabulary.
13
3.**Never lie about state.** The extension shows what `oxy` reports and nothing it infers; every mutation goes through `oxy`, so the operation log stays the single source of truth and `oxy undo` works on what the extension did.
14
4.**Fast enough to run on every keystroke pause.** Status refresh after a file save must complete within the manifest stat-cache budget (tens of milliseconds on a warm repository, spec §12.4).
15
16
Non-goals for 1.0: a web UI, code review, issue tracking (those belong to `oxyhub`), a Git compatibility mode (the built-in Git extension already covers Git repositories), and remote development on a machine without `oxy`.
| Source Control view with Changes / Staged | Source Control view with **Changes** and **Conflicts** groups | No staging area; partial commits select paths or hunks at commit time (§5.3) |
23
| Commit box, `Ctrl+Enter`| Same |`oxy commit -m`; amend from the menu |
24
| Quick diff gutter | Same | Base content via `oxy cat` (§4) |
25
| File decorations (M, A, D, U, C) | M, A, D, R (renamed), X (mode), ‼ (conflict markers), ✔ (resolved) | From `oxy status --json`|
| Merge conflict editor (Accept current / incoming / both) |**Conflict editor** over `oxy` markers with the same CodeLens actions, plus "Mark resolved" that runs `oxy resolve`, "Keep a Side" for binary files and subrepo pins, and "Keep Both Sides" for lines added at the same place | Markers name the contributing changes |
| Git output channel | Oxygen output channel with every command run ||
38
39
##3. Architecture
40
41
-**Language and build.** TypeScript, bundled with esbuild, targeting the current VS Code engine. Tests with `@vscode/test-electron` against a fixture repository created with `oxy` in a temporary directory.
42
-**Process model.** The extension spawns `oxy` per operation with `--plain --json` (§4) and parses its output; it never reads `.oxy/` itself. Long operations (clone, push, fetch, bisect run) stream progress to a VS Code progress notification and can be cancelled by killing the process. One operation mutates a repository at a time; reads may run concurrently.
43
-**Repository model.** One `Repository` object per workspace folder containing (or nested under) an oxy repository, found with `oxy root` (§4). It holds the last `status --json`, `bookmark list --json`, and `prompt` results, and refreshes on: a file watcher over the workspace (debounced 250 ms, ignoring `.oxy/`), a watcher on `.oxy/ops/head` (any operation, including ones from a terminal), window focus, and after every command the extension runs itself.
44
-**Binary discovery.**`oxygen.path` setting, else `oxy` on `PATH`, else `~/.local/bin/oxy`. The extension checks `oxy --version` at activation and shows a one-click "Install or locate oxy" message if it is missing or older than the minimum it supports.
45
-**URIs.**`oxy:` URIs serve file content from a state: `oxy:/<path>?change=<hash>&repo=<root>`; `change` may be `@base` (the working copy's base), a ChangeHash, a ChangeId prefix, or a bookmark. A `TextDocumentContentProvider` answers them with `oxy cat`.
46
-**Activation.** On `workspaceContains:.oxy` and on the `oxygen.*` commands.
47
48
##4. Machine interface required from `oxy`
49
50
The extension depends on stable JSON outputs. These are additions to the reference implementation, tracked as phase 3 in `oxygen/docs/plan.md`:
51
52
| Command | Output |
53
|---|---|
54
|`oxy root`| The repository root and workspace id for the current directory, or exit 1 |
55
|`oxy status --json`| Exists: paths with status, conflicts |
|`oxy commit -m M PATH..`, `oxy amend PATH..`| Commit or amend only these paths, a conflict's resolution included; the rest stays uncommitted (oxy 0.5.0) |
74
|`oxy bookmark list --all --json`| Also remotes' bookmarks with no local one, named `REMOTE/NAME`; `oxy merge REMOTE/NAME` merges one as last fetched (oxygen#117) |
75
|`oxy resolve PATH..`| Settle a binary file's or subrepo pin's replace conflict with what the working copy holds there (oxygen#140) |
76
|`oxy resolve --both [--reverse] [PATH..]`| Keep every side of each adjacent insertion, earliest change first; reports what keeps its markers and why (oxygen#121, oxy 0.8.0) |
77
|`oxy tag delete NAME -r REASON`| Withdraw a tag: a signed withdrawal kept beside its creation; the name is never reused |
78
|`oxy tlog verify --json [HUB]`| The hub's transparency log checked: checkpoint size, root, witnesses' cosignatures, this repository's entries |
79
|`oxy clone --depth 0 URL DIR`| A shallow clone from the remote's checkpoint: the latest state only |
|`oxy --version --json`| Version and protocol version |
81
82
Every JSON command MUST print one JSON document on stdout and nothing else, use exit status 0 for success, and put human-readable errors on stderr with a non-zero status. Ids are hex strings. Times are milliseconds since the epoch.
83
84
##5. User interface
85
86
###5.1 Source Control view
87
88
-Groups: **Conflicts** (only when present, listed first), **Changes**. Each entry shows the path, a status letter, and a tooltip with the status word; clicking opens the diff editor (working file against `oxy:` base content; for an added file the file itself; for a removed file the base content).
89
- Title actions: Commit (with message box), Refresh, Fetch, Pull, Push, More… (Amend, Undo last operation, Open history, Open operation log).
- Entry actions: Open file, Open changes, Discard changes (confirm), Commit only this path, Amend selected paths.
91
- Multi-select commit: selecting entries and choosing "Commit selected" runs `oxy commit PATH..`; "Amend Selected Paths" runs `oxy amend PATH..`, folding only those into the head the working copy sits on.
- The view's badge is the number of changed paths; the badge turns red with the conflict count while conflicts exist.
93
94
###5.2 Diff editor and quick diff
95
96
-Quick diff decorations in the gutter come from the base content served over `oxy:`.
97
- The diff editor title is `path (base ↔ working copy)`; for history diffs, `path (change A ↔ change B)`.
98
- "Commit this hunk" and "Discard this hunk" CodeLens actions in the diff editor call `oxy commit --hunks` and `oxy discard --hunks` (the latter is a phase 3 addition to `oxy`).
- Empty message: the extension opens an editor for the message, like Git's.
104
- A pre-commit hook veto shows its stderr in a notification with "Show output".
105
106
###5.4 Status bar
107
108
-Left: `⚛ main 658990aa ✎` from `oxy prompt --glyphs`, coloured by state; click opens the bookmark picker.
109
- Next to it: `↑2 ↓1` sync counts; click runs Sync (fetch then pull then push, each confirmed on first use).
110
- A spinner while any command runs; conflicts show `‼ 2` in the warning colour; click opens the Conflicts group.
111
112
###5.5 Bookmarks
113
114
-Picker: current bookmark marked, each with heads count and ahead/behind, plus **Create bookmark…**, **Merge bookmark into current…**, **Delete bookmark…**. Switching with uncommitted changes offers Discard or Cancel (never silently).
-**Merge bookmark…** lists the other local bookmarks, then remotes' bookmarks that have no local one (`oxy bookmark list --all --json`, shown as `origin/develop`, "as last fetched"); picking one runs `oxy merge` with that name.
116
-**Tags…** lists tags to check out, plus **Create tag…** and **Withdraw a tag…**. **Withdraw Tag…** asks for the tag and a reason, confirms in a modal that the withdrawal is signed with your key, kept beside the tag's creation and logged (pushed to remotes that have the tag), and that the name is never used again, then runs `oxy tag delete NAME -r REASON`.
- Explorer context menu on a folder: "Open in new workspace" runs `oxy workspace add`.
118
119
###5.6 History view
120
121
-A webview showing the bookmark's changes as a graph: nodes are changes, edges are dependencies, heads highlighted, the working copy at the top. Multiple heads render side by side with no fake merge nodes.
122
- Clicking a change opens its summary (message, author, files, signature); actions: checkout, describe, abandon, squash into…, rebase onto…, tag, blame this version of a file, open diff against parent.
123
- Filters: bookmark, author, path, text.
124
125
###5.7 Conflicts
126
127
-Files with markers open in the editor with CodeLens over each region: **Accept side 1**, **Accept side 2**, **Accept both**, **Compare sides**. Side labels are the contributing changes' short ids and subjects, as the markers carry them.
128
- Tree conflicts (`.oxy-conflict-N` candidates) appear under Conflicts with actions "Keep this candidate" (renames it into place and removes the rest).
- A binary file's or subrepo pin's conflict (a replace conflict, no markers to edit) shows **Keep a Side…**. For a file it offers each side, labelled with the side's change, plus the version on disk: keeping a side writes that change's version of the file (`oxy cat PATH -r CHANGE`), removes the `.oxy-conflict-N` candidates, and runs `oxy resolve PATH`, which settles the conflict with what the working copy holds. For a subrepo pin it offers the pin the nested repository holds now, or opening the subrepo to move it first (oxygen#140).
130
- A text conflict, and the Conflicts group, offer **Keep Both Sides (Lines Added at the Same Place)…**: `oxy resolve --both [PATH..]`, earliest change first or (`--reverse`) latest first. Where the sides changed the same lines the markers stay, and oxy's reason is shown (oxygen#121; needs oxy 0.8.0).
- "Mark resolved" runs `oxy resolve --json` and reports what remains; the commit action reads "Commit resolution" while conflicts are resolved but not committed.
-**Commit Resolution of Selected Paths**, on entries of the Conflicts group, commits only those paths' resolution (`oxy commit -m M PATH..`) while other conflicts stay for later; it asks first if a chosen path is not resolved yet.
-Command "Toggle inline blame" decorates each line's end with `changeid · author · age`; hovering shows the full message with a link to the change. A "Blame" side view lists the same per line. Uses `oxy blame --json` on the base content and adjusts for unsaved edits by dimming lines that differ from base.
137
138
###5.9 Operation log
139
140
-A tree view listing operations newest first with time and command; each has **Undo to here**. The item corresponding to the current view is marked. Snapshot operations are hidden by default.
141
142
###5.10 Subrepositories
143
144
-A **Subrepos** node in the SCM view when `.oxymodules` exists or subrepo nodes are tracked: each entry shows path, pin, and state (at pin, differs, dirty, missing) with actions Update, Update all (--init), Open folder.
145
146
###5.11 Bisect
147
148
-Panel with Start, Good/Bad marking of the state under test, Run with a task or command, Skip, Reset, and a progress line ("7 candidates, about 3 steps"). The culprit opens in the history view.
149
150
###5.12 Trust
151
152
-Each change in the history view shows a signature badge (signed, sealed, unsigned, invalid, revoked key). A **Trust** section in the SCM view summarises the policy (roots, rules, expiry) and flags an expired policy or an unverified remote.
- The Trust view's last line is the hub's **transparency log**. It is checked on request, not on refresh, since it asks the hub: **Verify Transparency Log** (the view's title button, the line itself, or the command) runs `oxy tlog verify --json` against the checkout's remote and shows "verified up to checkpoint N" with the log's origin and this repository's entry count, then one line per witness that cosigned the checkpoint (or a warning that none you trust did), or the error when the check fails.
-Remote picker for fetch/pull/push when more than one remote exists; results shown as notifications (rejected pushes explain why and offer Pull). Tokens are read from the repository configuration; the extension never stores secrets itself.
-**Clone Repository…** asks for the URL and the parent folder, then offers **Full history** or **Shallow** (latest state only, fast for big repositories), which runs `oxy clone --depth 0 URL DIR`.
Keybindings match the Git extension where a counterpart exists (for example `Ctrl+Enter` in the commit box).
177
178
##6. Behaviour rules
179
180
-**Refresh is cheap and debounced**; a refresh never blocks the UI thread and never runs two `status` calls at once per repository.
181
-**Errors** from `oxy` appear verbatim in a notification with "Show output"; the output channel logs every command, its working directory, duration, and exit status.
182
-**Nothing destructive without a confirmation**: discard, delete bookmark, abandon, `--discard` switches, and force push all confirm, with a "Don't ask again" option per action.
183
-**Multi-root workspaces**: one repository model per folder; the SCM view shows a provider per repository, as Git does.
184
-**Files outside the sparse filter** are shown greyed with a tooltip.
185
-**Large repositories**: history and blame are paged (`-n`) and fetched on demand; decorations use `status --json` only.
assets/images/ oxygen.svg (the extension icon), history webview assets
201
test/ integration tests against a fixture repository
202
docs/spec.md this document
203
```
204
205
Build with `npm run build` (esbuild), test with `npm test`, package with `vsce package`, publish to the Marketplace under the `oxygen` publisher once 1.0 is reached. CI runs lint, build, and tests on Linux, macOS, and Windows with a pinned `oxy` release.
206
207
##8. Milestones
208
209
1.**0.1 Read-only**: activation, binary discovery, SCM view with Changes and Conflicts, diff editor over `oxy:`, quick diff, decorations, status bar. Requires `oxy root`, `cat`, `status --json` (exists), `prompt`.
-The Timeline API is still proposed in VS Code, so file history is a command with a quick pick and diffs between versions rather than a Timeline provider.
220
-`oxy` gained `tag list --json` and `workspace list --json` for §4, and two bugs the extension's tests found were fixed in `oxy`: a chosen addition hunk now carries its content, and an unsigned repository keeps a tag's message.
221
- Extensions are per VS Code profile; the install command must name the profile a workspace uses.
##8b. Implementation notes (2026-10-29): oxy 0.5 to 0.9
224
225
-Brought up to oxy 0.9 (oxygen-vscode#11): tag withdrawal, the transparency log in the Trust view, shallow clone, keep-a-side and keep-both-sides settling, commit and amend by paths, and merging a remote's bookmark, each through the commands in §4.
226
- The CLI names a withdrawal `oxy tag delete NAME -r REASON` (help: "Withdraw a tag"); there is no `tag withdraw` subcommand.
227
-`oxy resolve PATH` settles a replace conflict with whatever the working copy holds; there is no per-side flag, so the extension writes the chosen side's version first. `oxy status --json` does not say which text conflicts are adjacent insertions (only the human output does), so **Keep Both Sides** is offered on every text conflict and reports oxy's refusals.
228
-`oxy resolve --both` needs oxy 0.8.0; the tests that use it are skipped on older oxy.
229
-`bookmark list --all --json` marks no field for a remote's bookmark; the extension recognises one by its `REMOTE/` name prefix, `remote` field and null ahead/behind counts.
`activate` returns an `OxygenAPI` (`src/api.ts`): the repositories as handles (root, status, bookmarks, current bookmark, `remotes()`, `json(args)`, `refresh()`), `onDidChangeStatus`, `onDidChangeRepositories`, `getRepository(path)`, and `registerRemoteProvider`. A remote provider gives an id and label, `matches(remoteUrl)` and `urlFor(remoteUrl, target)` for repository, bookmark, change, file (with line), proposals and issues targets. This extension uses the providers for its **Open on Remote** commands and sets the `oxygen.hasRemoteProvider` context; oxygenhub-vscode registers one for hubs and consumes the handles instead of running `oxy` itself, mirroring how the GitHub Pull Requests extension builds on the built-in Git extension.
1.Whether the extension should ship `oxy` binaries for the three platforms or only locate one; shipping simplifies onboarding but ties releases together.
238
2. Whether inline blame should run on every edit (as GitLens does) or only on save; the stat cache makes per-save cheap, per-edit needs a content-aware diff against base in the extension.
239
3. Whether a long-lived `oxy` daemon (`oxy serve-ide`) is warranted for very large repositories, where spawning a process per refresh would dominate.