# Oxygen for Visual Studio Code

| | |

|---|---|

| **Status** | Draft 0.1 |

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

| **Depends on** | `oxy` (reference implementation, spec Draft 0.8a) with the machine interface of §4 |

## 1. Goals

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.

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.

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.

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

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

## 2. How it compares

| Built-in Git extension | Oxygen extension | Notes |

|---|---|---|

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

| Commit box, `Ctrl+Enter` | Same | `oxy commit -m`; amend from the menu |

| Quick diff gutter | Same | Base content via `oxy cat` (§4) |

| File decorations (M, A, D, U, C) | M, A, D, R (renamed), X (mode), ‼ (conflict markers), ✔ (resolved) | From `oxy status --json` |

| Branch picker in the status bar | **Bookmark** picker: switch, create, merge | `oxy bookmark` |

| Sync (fetch, pull, push) | Same, plus per-bookmark push | Counts from `oxy bookmark list --json` |

| Timeline view (file history) | Timeline: changes that touched the file, from `oxy log --json --path` | Exact, follows renames |

| Merge conflict editor (Accept current / incoming / both) | **Conflict editor** over `oxy` markers with the same CodeLens actions, plus "Mark resolved" that runs `oxy resolve` | Markers name the contributing changes |

| Stash | Workspaces (`oxy workspace add`) | Stash has no equivalent; a second workspace is the honest answer |

| Git graph (via extensions) | **History view**: heads and dependencies as a graph | `oxy log --json` carries dependencies |

| Blame (via GitLens) | Inline blame toggle and a Blame view | `oxy blame --json` |

| Undo last commit | **Operation log** view: any operation undone with one click | `oxy op log --json`, `oxy undo` |

| Submodules | Subrepos node in the SCM view with update and status | `oxy submodule status --json` |

| — | Bisect panel | `oxy bisect` |

| — | Trust panel: signature status per change, policy summary | `oxy verify --json`, `oxy policy show --json` |

| Git output channel | Oxygen output channel with every command run | |

## 3. Architecture

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

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

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

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

- **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`.

- **Activation.** On `workspaceContains:.oxy` and on the `oxygen.*` commands.

## 4. Machine interface required from `oxy`

The extension depends on stable JSON outputs. These are additions to the reference implementation, tracked as phase 3 in `oxygen/docs/plan.md`:

| Command | Output |

|---|---|

| `oxy root` | The repository root and workspace id for the current directory, or exit 1 |

| `oxy status --json` | Exists: paths with status, conflicts |

| `oxy log --json [-n N] [--path P] [--bookmark B]` | Changes with hash, ChangeId, author, date, message, deps, heads flag, signature status |

| `oxy show --json CHANGE` | The change's metadata plus per-file summaries |

| `oxy diff --json [CHANGE]` | Per file: kind of change and hunks with line ranges and text, for the working copy or a change |

| `oxy cat PATH [-r CHANGE]` | Raw content of a file at a state (default: the working copy's base) |

| `oxy hunks --json` | Numbered hunks of the working copy, as `commit -i` offers them |

| `oxy commit --hunks 1,4,5` | Non-interactive hunk selection |

| `oxy bookmark list --json` | Name, heads, current, ahead, behind |

| `oxy op log --json` | Operations with id, time, command, and whether undo can reach them |

| `oxy blame --json` | Exists |

| `oxy resolve --json` | Per conflicted path: resolved, markers, unresolved |

| `oxy submodule status --json` | Path, pin, actual, dirty, url |

| `oxy bisect status --json` | The `BisectStep` |

| `oxy verify --json [CHANGE]` | Signature status per change |

| `oxy policy show --json` | Roots, rules, revoked, expiry |

| `oxy remote list --json`, `fetch --json`, `pull --json`, `push --json` | Names, urls, results |

| `oxy prompt` | Exists; used for the status bar |

| `oxy discard PATH..` | Restore paths to the working copy's base (new; the extension's "Discard changes") |

| `oxy --version --json` | Version and protocol version |

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.

## 5. User interface

### 5.1 Source Control view

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

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

- Multi-select commit: selecting entries and choosing "Commit selected" runs `oxy commit PATH..`.

- The view's badge is the number of changed paths; the badge turns red with the conflict count while conflicts exist.

### 5.2 Diff editor and quick diff

- Quick diff decorations in the gutter come from the base content served over `oxy:`.

- The diff editor title is `path (base ↔ working copy)`; for history diffs, `path (change A ↔ change B)`.

- "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`).

### 5.3 Commit

- The message box supports multi-line messages; `Ctrl+Enter` commits everything, the dropdown offers **Commit selected paths**, **Commit hunks…** (opens a quick pick of hunks from `oxy hunks --json`), **Amend**, **Amend into…** (quick pick of changes), and **Commit and push**.

- Empty message: the extension opens an editor for the message, like Git's.

- A pre-commit hook veto shows its stderr in a notification with "Show output".

### 5.4 Status bar

- Left: `⚛ main 658990aa ✎` from `oxy prompt --glyphs`, coloured by state; click opens the bookmark picker.

- Next to it: `↑2 ↓1` sync counts; click runs Sync (fetch then pull then push, each confirmed on first use).

- A spinner while any command runs; conflicts show `‼ 2` in the warning colour; click opens the Conflicts group.

### 5.5 Bookmarks

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

- Explorer context menu on a folder: "Open in new workspace" runs `oxy workspace add`.

### 5.6 History view

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

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

- Filters: bookmark, author, path, text.

### 5.7 Conflicts

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

- Tree conflicts (`.oxy-conflict-N` candidates) appear under Conflicts with actions "Keep this candidate" (renames it into place and removes the rest).

- "Mark resolved" runs `oxy resolve --json` and reports what remains; the commit action reads "Commit resolution" while conflicts are resolved but not committed.

### 5.8 Blame

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

### 5.9 Operation log

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

### 5.10 Subrepositories

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

### 5.11 Bisect

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

### 5.12 Trust

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

### 5.13 Remotes and sync

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

### 5.14 Settings

| Setting | Default | Meaning |

|---|---|---|

| `oxygen.path` | `""` | Path to the `oxy` binary |

| `oxygen.autoRefresh` | `true` | Watch the workspace and refresh |

| `oxygen.autoFetch` | `false` | Fetch every `oxygen.autoFetchPeriod` seconds (default 180) |

| `oxygen.inlineBlame` | `false` | Show inline blame by default |

| `oxygen.showSnapshotOperations` | `false` | List snapshot operations in the operation log |

| `oxygen.confirmSync` | `true` | Confirm before pushing |

| `oxygen.decorations.enabled` | `true` | Explorer and tab decorations |

### 5.15 Commands (all prefixed `Oxygen:`)

Commit, Commit Selected Paths, Commit Hunks…, Amend, Amend Into…, Discard Changes, Refresh, Fetch, Pull, Push, Push Bookmark…, Sync, Switch Bookmark…, Create Bookmark…, Merge Bookmark…, Delete Bookmark…, Open History, Open Operation Log, Undo Last Operation, Toggle Inline Blame, Show Blame, Resolve Conflicts, Mark Resolved, Checkout Change…, Describe Change…, Abandon Change…, Squash Into…, Rebase Onto…, Create Tag…, Add Workspace…, Update Subrepos, Bisect Start/Good/Bad/Skip/Run/Reset, Verify Signatures, Show Policy, Open Output, Clone Repository…, Initialize Repository.

Keybindings match the Git extension where a counterpart exists (for example `Ctrl+Enter` in the commit box).

## 6. Behaviour rules

- **Refresh is cheap and debounced**; a refresh never blocks the UI thread and never runs two `status` calls at once per repository.

- **Errors** from `oxy` appear verbatim in a notification with "Show output"; the output channel logs every command, its working directory, duration, and exit status.

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

- **Multi-root workspaces**: one repository model per folder; the SCM view shows a provider per repository, as Git does.

- **Files outside the sparse filter** are shown greyed with a tooltip.

- **Large repositories**: history and blame are paged (`-n`) and fetched on demand; decorations use `status --json` only.

## 7. Repository layout and tooling

```

oxygen-vscode/

  package.json          contributes: commands, views, menus, keybindings, settings, scm

  src/

    extension.ts        activation, repository discovery

    oxy.ts              process wrapper and JSON parsing (one function per §4 command)

    model/              Repository, status, bookmarks, operations

    scm/                SourceControl provider and resource groups

    views/              history (webview), operation log, blame, subrepos, bisect, trust

    editor/             oxy: content provider, quick diff, conflict CodeLens, inline blame

    commands/           one file per command group

  assets/images/        oxygen.svg (the extension icon), history webview assets

  test/                 integration tests against a fixture repository

  docs/spec.md          this document

```

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.

## 8. Milestones

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

2. **0.2 Write**: commit (all, paths, hunks, amend), discard, refresh on operations, undo, operation log view. Requires `hunks --json`, `commit --hunks`, `discard`, `op log --json`.

3. **0.3 Bookmarks and sync**: picker, create/switch/merge/delete, fetch/pull/push with results, remotes. Requires `bookmark list --json`, sync `--json` outputs.

4. **0.4 History and blame**: history webview, timeline, inline blame, show. Requires `log --json`, `show --json`, `diff --json`.

5. **0.5 Conflicts**: conflict editor CodeLens, tree conflict candidates, resolve flow. Requires `resolve --json`.

6. **0.6 The rest**: subrepos, bisect, trust, tags, workspaces, clone and init.

7. **1.0**: tests on three platforms, Marketplace listing, documentation.

## 9. Open questions

1. Whether the extension should ship `oxy` binaries for the three platforms or only locate one; shipping simplifies onboarding but ties releases together.

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.

3. Whether a long-lived `oxy` daemon (`oxy serve-ide`) is warranted for very large repositories, where spawning a process per refresh would dominate.