Ben Stull
113 lines
5.5 KiB
Markdown
113 lines
5.5 KiB
Markdown
# 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).
|
|
|
|
## 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).
|
|
|
|
## 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.
|