# In-browser code editor

Pressing `.` on any repository page, or opening `/<owner>/<repo>/edit/<ref>`, opens a workspace editor
for that ref. It plays the role github.dev plays on GitHub: browse the tree, edit many files, stage
the changes in the browser and commit them in one go. It costs nothing while nobody is typing.

## Options considered

|              | (a) VS Code for the Web, static                                                                                                                          | (b) Monaco in the React app                                                    | (c) openvscode-server in a Container                                                            |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| Runtime cost | Static assets only (R2 or Workers static assets). No compute while idle.                                                                                 | None beyond the app.                                                           | A container per session: CPU and RAM billed while it runs, plus cold starts of several seconds. |
| Latency      | One-time download of about 15–25 MB (cached and immutable), then local.                                                                                  | Monaco is about 3–5 MB on first load.                                          | Every keystroke round-trips to the container. Cold starts are slow.                             |
| Features     | Full workbench: explorer, search, SCM view, multi-cursor, keybindings, settings sync, web extensions.                                                    | Just the editor widget. Tree, tabs, SCM and search must all be built in React. | Everything, including a terminal, tasks, debuggers and language servers.                        |
| Extensions   | Web extensions from Open VSX.                                                                                                                            | None.                                                                          | Every Open VSX extension, including native ones.                                                |
| Licensing    | VSCodium and openvscode builds are MIT. They must not ship the Microsoft marketplace or Microsoft branding, so we point `extensionsGallery` at Open VSX. | Monaco is MIT.                                                                 | openvscode-server is MIT, with Open VSX only.                                                   |
| Offline      | Works offline once loaded. Edits stay staged in the page, and only reads of uncached blobs and commits need the network.                                 | The same.                                                                      | Doesn't work offline.                                                                           |
| Isolation    | Must run on an isolated origin, because extensions run arbitrary JavaScript.                                                                             | Runs in the app origin unless sandboxed.                                       | The container is isolated, but its HTTP endpoint needs auth.                                    |

### Licensing notes

- The "Visual Studio Code" product (vscode.dev, github.dev) is under the Microsoft licence. Its
  marketplace terms forbid use from non-Microsoft products, so we can't ship Microsoft's build or
  connect to `marketplace.visualstudio.com`.
- The `microsoft/vscode` source is MIT. Gitpod's openvscode builds and VSCodium both produce MIT builds
  with an empty gallery. We set `product.json` to:
  `extensionsGallery: { serviceUrl: "https://open-vsx.org/vscode/gallery", itemUrl: "https://open-vsx.org/vscode/item" }`.
- Open VSX is run by the Eclipse Foundation. Each extension keeps its own licence. Some popular
  Microsoft extensions, such as Pylance, the C# Dev Kit and Remote-*, aren't on Open VSX and are
  licensed for Microsoft products only. Users won't get them, and we document that.

### Decision

**We pick (a).** It is the github.dev model with no backend container, so it costs no compute for each
idle session. That beats Codespaces on cost, and it beats Codespaces on latency because typing never
leaves the browser.

(b) is a fallback, not a target: we'd end up rebuilding the workbench badly. (c) becomes an opt-in
**"Run in container"** mode for the one thing github.dev can't do, which is a terminal. See below.

## Architecture

```
forge origin (cookies)                       isolated origin (no cookies)
┌──────────────────────────────┐ postMessage ┌────────────────────────────────────┐
│ /<o>/<r>/edit/<ref>          │────token───▶│ /editor-frame (sandboxed iframe)   │
│  WorkspaceEditor.tsx         │◀──committed─│  workbench + FileSystemProvider    │
│  mintEditorSession() server fn│            │  fetch /api/editor/* with Bearer   │
└──────────────────────────────┘             └────────────────────────────────────┘
                                                        │
                                   /api/editor/{session,tree,blob,commit}
                                                        ▼
                                  src/server/editor/api.ts → commitFileChanges()
```

### Isolation and authentication

- The frame is `<iframe sandbox="allow-scripts allow-forms allow-modals allow-downloads">`
  **without** `allow-same-origin`. Its origin is opaque (`null`), so it can't read the forge's
  cookies, `localStorage` or DOM. Fetches from it are cross-origin and send no credentials.
- `/editor-frame` is served with a strict CSP:
  `default-src 'none'; script-src 'sha256-…'; style-src 'sha256-…'; connect-src <forge origin>; frame-ancestors 'self'; sandbox allow-scripts allow-modals`.
  Because of the CSP `sandbox` directive, the document stays opaque-origin even if it is opened as a
  top-level page.
  The page can only talk to the forge API, and only the forge can embed it. When the sites domain from
  `roadmap/sites` lands, the frame moves to `editor.<sites-domain>`. The protocol stays the same; only
  `connect-src` and the target origin change.
- **Tokens.** `mintEditorSession` runs in the forge origin with the session cookie. It checks write or
  read access, then stores a random `gitfor_edt_…` token in `auth_tokens` (kind `editor-session`) with
  a one-hour TTL. That token is bound to one user, one repository and one ref. The parent passes it to
  the frame with `postMessage`. Both sides check the message origin, and the frame only accepts its
  parent. On every request `/api/editor/*` re-checks the user's current repository permission, so
  removing a collaborator takes effect at once. Signing out everywhere, resetting a password or revoking
  the minting PAT also ends the session. The API never reads cookies.
- **The `/api/editor/*` CORS policy** is `Access-Control-Allow-Origin: *` with no credentials. That is
  safe because a request is authorized only by the bearer token, and a browser never attaches one
  ambiently.

### Reads

- `GET /api/editor/session` returns the repository, ref, head SHA, permission, and whether the ref is
  protected for this user.
- `GET /api/editor/tree` returns a recursive listing at the session's head. It is capped at
  `MAX_TREE_ENTRIES` and reports `truncated`. It uses `GitStore.walk`, which bounds tree reads.
- `GET /api/editor/blob?path=…` returns `{ kind: "text" | "binary" | "lfs" | "too-large", content? }`.
  **LFS pointers are never returned as editable text**: the frame shows a read-only notice, and the
  commit endpoint rejects writes to a path whose current blob is an LFS pointer, or that the root
  `.gitattributes` routes through `filter=lfs`. Symlinks and submodules are read-only too. This stops the
  editor from replacing anything git treats specially with plain text.

All reads go through `limitBrowse` and the same `assertVisibleRevision` checks as the browse server fns.

### Writes

- Changes are staged in the browser as a map of path to new content, or to `null` for a deletion. The
  frame shows a Changes list with a commit message box.
- `POST /api/editor/commit` accepts `{ message, changes[], expectedHeadSha, newBranch?, openPull? }`. It
  calls `commitFileChanges` in `src/server/git/web-commit.ts`, the multi-file core that
  `commitFileChange` now delegates to. As a result, GIT-7 path validation, branch protection
  (`assertDirectUpdate`), the archived-repository check, optimistic concurrency, push triggers and
  rate limits all apply unchanged.
- **Protected branches.** If a direct update would be rejected, or if the user picks "new branch",
  the server commits to `<user>-patch-<n>` and opens a pull request against the original branch
  through `openPull`. It returns the PR URL, and the parent navigates there.
- The request is capped at `MAX_CHANGES` files and `MAX_COMMIT_BYTES` in total. The body is read through
  a capped stream, and duplicate or file-versus-directory paths are rejected.
- If opening the PR fails, or the session can't open PRs (a PAT without `pulls: write`), the commit
  still lands on the new branch and the response carries `pullError`.

### Phase 1 frame vs the VS Code workbench

The frame protocol (token over `postMessage`, plus `/api/editor/*`) is deliberately independent of the
UI. Phase 1 ships a dependency-free "lite" workbench inline in `/editor-frame`, with an explorer, tabs,
an editor, staged changes and commit. It works today and passes the e2e test.

Phase 2 replaces the frame body with the VSCodium web build, served from R2 under an immutable,
hash-named prefix, plus a built-in web extension `gitfor-fs`. That extension:

- registers a `FileSystemProvider` for `gitfor://<owner>/<repo>/<ref>/…`, where `readDirectory` and
  `stat` come from the tree listing and `readFile` comes from `/api/editor/blob`.
- keeps writes in an in-memory overlay, and implements a `SourceControl` provider whose "Commit"
  posts the overlay to `/api/editor/commit`.
- receives the token through the same `postMessage` handshake, via `workbench.html` → extension
  `postMessage`.

## Run in container (opt-in)

The pain point is that github.dev has no terminal. We add a button that starts an openvscode-server
Container (a Cloudflare Container bound to a Durable Object per `(account, repo, branch)`):

- It clones the ref with a short-lived deploy-style token. It pushes only through the normal git
  smart-HTTP path, so receive-pack hooks and protections still apply.
- **Idle shutdown.** The DO tracks the last WebSocket activity and calls `container.stop()` after 15
  minutes idle (`sleepAfter`). There is also a hard cap of 8 hours per session.
- **Billing hooks.** Each start and stop writes a `container_sessions` row (in the migration range
  1100–1199) with the account, instance type and duration. A per-account monthly minute quota is
  checked before starting, using the same pattern as `src/server/lfs/quota.ts`. This lets
  organization owners cap spend, unlike the Codespaces model of paying per hour by surprise.
- The browser frame stays (a). The container only adds a terminal and tasks panel that talks to it
  over a WebSocket.

This isn't implemented in this branch. It needs the Containers binding and billing tables, and it
is gated behind an account setting.

## Live collaboration (stretch)

There is one `EditorRoom` Durable Object per `(repo, branch)`, using the hibernation WebSocket API.
`ProjectRoom` already shows the pattern:

- Each open file is a `Y.Text` in a `Y.Doc`. The DO relays Yjs updates and awareness (presence and
  cursors). Because it hibernates, an idle room costs nothing.
- Joining requires the same `editor-session` token. The DO checks it on upgrade.
- Commits still go through `/api/editor/commit`, sent by whoever clicks Commit. The room then
  broadcasts the new head so other participants rebase their staged state.

## Agents

Agents drive the same session the same way the frame does, so humans and agents see one source of
truth:

1. A user, or an automation running as a user, mints a session with `mintEditorSession`. A PAT holder
   can also call `POST /api/editor/sessions` once that is exposed through `/api/v1`. Either way the
   agent gets a ref-scoped, one-hour token instead of a broad PAT.
2. The agent calls `GET /api/editor/tree` and `GET /api/editor/blob` to read, and
   `POST /api/editor/commit` to commit. It gets the same protections and the same automatic PR when
   the branch is protected.
3. With live collaboration, the agent joins the `EditorRoom` as another Yjs peer, so a human watching
   the editor sees the agent's cursor and edits in real time before anything is committed. With Run
   in container, the agent can also run tests in the shared terminal.

## Testing

- `scripts/e2e-editor.ts` tests the protocol: CSP, CORS, token-only auth, tree and blob reads, LFS and
  path guards, multi-file commits, stale heads, PRs for protected branches, and permission revocation.
- `scripts/e2e-editor-browser.ts` drives headless Chrome over CDP. It signs in, presses `.`, checks that
  the frame is opaque-origin and can't read cookies, edits and commits inside the frame, and then checks
  the commit.