vscode-cowriting-plugin/README.md

# vscode-cowriting-plugin

Non-shippable **proof-of-concept** (Feature #2 of Epic #1): a standalone VS Code
extension that drives **[`@cline/sdk`](https://www.npmjs.com/package/@cline/sdk)**
— validating Approach A (own coauthoring extension on the Cline SDK, no fork).

## What it does

Registers one command, **`Cowriting: Show Cline SDK Info`**, which loads
`@cline/sdk` and shows the SDK build version plus the agent's builtin tool
catalog (a pure, key-free SDK call) in a notification and the
"Cowriting (Cline SDK)" output channel.

Features shipped so far: F2 region-anchored threads (Feature #4), F3 live
human/Claude attribution (Feature #6), F4 propose/accept diff flow
(Feature #12), F5 cross-rung sidecar contract (Feature #14), F6 diff-view
toggle (Feature #17).

## Architecture

- CommonJS extension bundled with esbuild (`src/extension.ts` → `out/extension.cjs`).
- `@cline/sdk` is ESM-only (Node ≥22) and uses `createRequire(import.meta.url)`,
  so it is **not** bundled — it is shipped in `node_modules` and loaded at
  runtime via dynamic `import()` from the vscode-free `src/cline.ts`.

## Run it (F5)

1. `npm install`
2. `npm run build`
3. Press **F5** (or Run → "Run Extension") to launch the Extension Development Host.
   It opens the committed **`sandbox/`** playground as its workspace (not the
   repo itself — VS Code won't open one folder in two windows, #8); start with
   `sandbox/playground.md`.
4. In the new window: **Cmd/Ctrl+Shift+P** → **"Cowriting: Show Cline SDK Info"**.

## F2 — Region-anchored threads (Feature #4)

Attach durable, region-anchored discussion threads to any document. Threads
render in the native VS Code **Comments** gutter and persist as git-native
sidecars under `.threads/<doc-path>.json` (plain, diffable JSON — no server).

- **Create:** select text → run **"Cowriting: Add Coauthoring Thread on Selection"**
  (or the Comments gutter "+").
- **Reply / Resolve:** use the native Comments reply box and the thread's
  Resolve/Reopen actions.
- **Survives edits, reload, and external change (`git pull`):** a hybrid anchor
  (durable content fingerprint + live offset tracking) re-resolves the thread.
  If the anchored text can't be confidently re-found, the thread is shown as
  **orphaned** at its last-known line — never silently moved.

Design: `vscode-cowriting-plugin-content/specs/coauthoring-inner-loop.md`. No live
`@cline/sdk` turn and no credentials are involved in F2.

## F3 — Live human/Claude attribution (Feature #6)

As you and Claude coauthor, every span in the buffer carries an author: human
edits render with a subtle left border, Claude-authored spans with a background
tint. Text that predates tracking stays plain — the honest record. Edits that
touch a boundary (split, merge, partial overwrite) are handled char-precisely.

Attribution is persisted git-natively in the same `.threads/` sidecars
(`attributions[]`, sharing the same `anchors` fingerprints as F2 threads). On
reload, fingerprints re-resolve spans against the current document; spans that
can't be confidently re-found are **orphaned** (status-bar count + "Cowriting
Attribution" output channel) rather than silently moved or discarded.

**Commands**

- **`Cowriting: Ask Claude to Edit Selection`** — select text → enter an
  instruction → a live `@cline/sdk` turn runs on the built-in `claude-code`
  provider (rides your local Claude Code Pro/Max login; the extension stores no
  credentials). As of F4 the turn ends in a **proposal** (see below); accepted
  text lands as a Claude-attributed span.
- **`Cowriting: Toggle Attribution`** — show/hide attribution decorations.
- `cowriting.applyAgentEdit` _(palette-hidden)_ — the single machine-edit
  ingress seam. Tests drive this directly so CI requires no LLM.

Design: `vscode-cowriting-plugin-content/specs/coauthoring-attribution.md`.

## F4 — Propose/accept diff flow (Feature #12)

Claude's edits arrive as **pending proposals** — propose-by-default, the
document never changes without your say-so. A proposal renders two ways at
once: an **amber tint** on the target range, and a "Claude proposes" comment
thread showing a fenced `diff` of current → proposed text with two actions:

- **✓ Accept Proposal** — applies the replacement through the `applyAgentEdit`
  seam, so it lands Claude-attributed (F3) — and the proposal disappears.
- **✗ Reject Proposal** — the document is untouched; the proposal disappears.

Pending proposals persist git-natively in the same sidecar (`proposals[]`,
sharing the F2/F3 `anchors` fingerprints), survive reload, and re-anchor as
surrounding text changes. If the **target text itself** changes, the proposal
goes **stale** (status-bar count, accept disabled — never applied by guess);
undo the change and it becomes decidable again. `cowriting.proposeAgentEdit`
_(palette-hidden)_ is the programmatic propose ingress E2E drives — no LLM in
CI.

Design: `vscode-cowriting-plugin-content/specs/coauthoring-propose-accept.md`.
Live smoke: [`docs/MANUAL-SMOKE-F4.md`](docs/MANUAL-SMOKE-F4.md).

## F5 — Cross-rung format + round-trip (Feature #14)

The `.threads/` sidecar is the **published cross-rung contract**: any rung of
the ladder (this editor → Gitea substrate → rfc-app) reads and writes the same
record per the contract; git push/pull is the transport, no re-homing ever.

- **Normative contract (INV-14):**
  `vscode-cowriting-plugin-content/specs/coauthoring-sidecar-contract.md` —
  format changes land there first, then schema, then code.
- **Machine-checkable half:**
  [`schemas/coauthoring-sidecar.schema.json`](schemas/coauthoring-sidecar.schema.json);
  validate any sidecar from any rung with
  `node scripts/validate-sidecar.mjs <file>`. The unit suite validates every
  serialized artifact — contract drift fails CI.
- **Identity crosses rungs:** `Provenance.email` (git's own join key —
  populated from the workspace git config when available) and
  `agent.onBehalfOf` (who the machine acted for).
- **Writers preserve unknown fields (INV-15):** rewriting a sidecar never
  destroys another rung's data — unknown keys survive, after known keys,
  sorted.
- **Newer-major sidecars are read-only (INV-16):** the editor renders what it
  understands, warns once, and writes nothing (the store refuses as a
  backstop).
- **Deterministic merge (INV-17):** `src/mergeArtifacts.ts` — union-by-id,
  documented tie-breaks, every resolved divergence surfaced in `conflicts`.
- **The round-trip is proven, not asserted:**
  [`scripts/crossrung-reply.mjs`](scripts/crossrung-reply.mjs) is a
  self-contained conforming foreign writer (the Gitea-rung stand-in); host E2E
  drives editor-thread → stand-in reply → external-change → the reply renders
  in the thread.

Design: `vscode-cowriting-plugin-content/specs/coauthoring-cross-rung-format.md`.

## F6 — Diff-view toggle (Feature #17, #19)

**`Ctrl+Alt+D`** (the same chord on macOS — not `Cmd`; or **Cowriting: Toggle
Diff View**) flips the focused document into a native `vscode.diff` against a
**coauthoring baseline** — the readonly baseline on the left, your **live,
editable** document on the right (so you keep writing inside the diff; toggling
again closes it). The diff answers "what did *I* change?" in one keystroke
instead of git archaeology.

- **Works on any file (#19):** any document you can edit — a file inside or
  outside the workspace folder, or an **untitled** scratch buffer. Only a
  non-text-editor focus warns. (Untitled buffers diff in-memory; saving makes
  the baseline persist.)
- **Machine-factored baseline (INV-18):** the baseline initializes when a doc
  is first seen and **advances automatically at every machine landing** (every
  successful `applyAgentEdit` seam apply — INV-9). So text Claude landed never
  shows as a change; everything the diff shows is operator-authored by
  construction — no attribution filtering.
- **Pin on demand:** **Cowriting: Pin Diff Baseline to Now** resets the
  baseline to the current buffer for a deliberate "review my next pass" epoch;
  the diff tab title names the epoch (`opened` / `Claude landed` / `pinned`).
- **Pure view, repo-free (INV-19):** the baseline snapshot lives in VS Code
  **global** extension storage, keyed by a hash of the document URI, **never**
  the repo — `.threads/`, the cross-rung contract (INV-14..17), and
  `SCHEMA_VERSION` are untouched. Storage-unavailable degrades to in-memory
  baselines + one warning.
- **No LLM in CI:** host E2E (`test/e2e/suite/diffView.test.ts`) drives the same
  programmatic seam ingress (propose + accept) the F4 suite uses.

Design: `vscode-cowriting-plugin-content/specs/coauthoring-diff-view.md`.
Live smoke: [`docs/MANUAL-SMOKE-F6.md`](docs/MANUAL-SMOKE-F6.md).

## Develop

- `npm run watch` — rebuild on change.
- `npx vitest run` — unit suite (SDK driver, schema, store, anchorer, thread
  mutations, attribution split/merge).
- `npm run test:e2e` — `@vscode/test-electron` host E2E
  (create → reply → resolve → persist → reload → re-anchor → orphan; drives
  `cowriting.applyAgentEdit` directly — no LLM required).
- `npm run smoke:live` — scripted live-turn smoke test for F3; requires Claude
  Code installed and signed in. See
  [`docs/MANUAL-SMOKE-F3.md`](docs/MANUAL-SMOKE-F3.md).
- `npm run typecheck` — type-check without emit.