@web-remarq/mcp 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Daniil Postnik
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -39,14 +39,9 @@ automatically:
39
39
  Annotations are stored in a JSON file on disk and served to the widget over a
40
40
  small HTTP endpoint on `127.0.0.1`. No Supabase project, no project key.
41
41
 
42
- Trust model: the endpoint binds to `127.0.0.1` with permissive CORS, so any
43
- page open in the local browser can reach it for as long as the server runs -
44
- this is meant for dev-time use with low-sensitivity data, not a hardened
45
- local API.
46
-
47
42
  | Env var | Default | Purpose |
48
43
  |---------|---------|---------|
49
- | `REMARQ_PORT` | `1817` | Port for the widget-facing HTTP endpoint |
44
+ | `REMARQ_PORT` | `port` in `.remarq/config.json`, else `1817` | Port for the widget-facing HTTP endpoint |
50
45
  | `REMARQ_DATA_FILE` | `.remarq/annotations.json` | Where annotations are persisted |
51
46
 
52
47
  `.remarq/` self-gitignores on first write - nothing to add to your project's
@@ -59,6 +54,97 @@ import { WebRemarq, HttpStorageAdapter } from 'web-remarq'
59
54
  WebRemarq.init({ submitFlow: true, storage: new HttpStorageAdapter() })
60
55
  ```
61
56
 
57
+ ### Access model (mcp 0.5.0, protocol 2)
58
+
59
+ On first start the server writes `.remarq/config.json`:
60
+
61
+ ```json
62
+ {
63
+ "projectId": "prj_…", // stable identity of this store
64
+ "token": "…", // random bearer credential for the HTTP endpoint
65
+ "allowedOrigins": ["http://localhost:*", "http://127.0.0.1:*", "http://[::1]:*"]
66
+ }
67
+ ```
68
+
69
+ An optional `"port": 4000` there sets the HTTP port when `REMARQ_PORT` is not
70
+ set; the Vite plugin passes the port of the running server to the widget.
71
+ `npx @web-remarq/cli init` creates the same file up front. It is owner-only
72
+ and gitignored; the token never appears in source, URLs, ticket files, logs or
73
+ `doctor` output.
74
+
75
+ Every request except `GET /health` needs `Authorization: Bearer <token>` -
76
+ reads included. Browser requests must also come from an origin in
77
+ `allowedOrigins` (exact scheme + host; `:*` means any port). Foreign, `null`
78
+ and look-alike origins (`localhost.evil.com`) are refused on preflight, read
79
+ and write; a `Host` header that does not name this loopback listener is
80
+ refused too (DNS rebinding). Remote/staging origins are never allowed unless
81
+ you list them on purpose.
82
+
83
+ How the widget gets the token, in development only:
84
+
85
+ - **Vite**: `@web-remarq/unplugin` serves it at `/__web-remarq/config.json`
86
+ on your dev server; `HttpStorageAdapter` fetches it same-origin.
87
+ - **Next.js**: `withRemarq()` exposes it as `NEXT_PUBLIC_WEB_REMARQ_TOKEN`;
88
+ the `RemarqDevTools` snippet passes it as `new HttpStorageAdapter({ token })`.
89
+ - **Plain HTML / other bundlers**: paste it once in the browser console -
90
+ `WebRemarq.pair('<token>')` - it is kept in localStorage for that endpoint.
91
+
92
+ Rotating the token (edit the file, restart the server) does not change
93
+ `projectId` and does not touch annotations; widgets show "not paired" until
94
+ they get the new token. Changing `projectId` is a different project: widgets
95
+ keep their queued changes for the old one.
96
+
97
+ What this protects: the HTTP boundary, against other pages in your browser
98
+ and against rebinding attacks. What it does not protect: a process on your
99
+ machine with file access (it can read `.remarq/config.json`), and it is not a
100
+ cryptographic "human approval" - the lifecycle records who acted, it does not
101
+ authenticate them.
102
+
103
+ ### Protocol 2 endpoints
104
+
105
+ | Route | Auth | Purpose |
106
+ |-------|------|---------|
107
+ | `GET /health` | none, any origin | `{ ok, protocol: 2 }` - liveness only, no data |
108
+ | `GET /store` | token | `{ rev, protocol, projectId, store }`; every annotation carries its own `rev` |
109
+ | `PUT /annotations/:id` | token | Create (no `If-Match`) or update (`If-Match: <rev>` required). Body is validated (types, enums, sizes, filename-safe id, unknown top-level fields rejected). Wrong revision → `409 { code: "conflict", details: { current } }`; missing → `428` |
110
+ | `DELETE /annotations/:id` | token | Optional `If-Match`; mismatch → 409 |
111
+ | `DELETE /annotations` | token | Clear |
112
+
113
+ Limits: 512 KB body, 10 000-character comments, 500 lifecycle events,
114
+ `application/json` only. An invalid request is a 4xx and changes neither the
115
+ store nor `.remarq/tasks/`.
116
+
117
+ **Upgrading from mcp 0.4.x**: widgets older than `web-remarq` 0.9.0 get 401
118
+ from a 0.5.0 server and go into their offline buffer instead of losing data;
119
+ upgrade the widget and the buffer is migrated (see "Offline and durability" in
120
+ the core README). A 0.9.0 widget refuses to talk to a 0.4.x server
121
+ ("incompatible") rather than writing without revisions.
122
+
123
+ Only one server may serve a store: `.remarq/server.lock` names the owning
124
+ process, and a second start against the same store exits with an error. The
125
+ atomic transition guarantee below depends on this.
126
+
127
+ ### Atomic transitions
128
+
129
+ `acknowledge`, `claim_fix` and `dismiss` are atomic per annotation: the read,
130
+ the lifecycle check and the write happen inside one critical section (local
131
+ file store) or as one conditional `UPDATE … WHERE id = ? AND rev = ?` (cloud,
132
+ needs `004_rev.sql`). Of several concurrent callers exactly one wins; the
133
+ others get `invalid_transition` with `details.conflict: true`, the current
134
+ status/revision and the last event - do not start work, re-read the annotation.
135
+
136
+ Pass `operationId` (any unique string you keep) to make a call idempotent: a
137
+ retry after a lost response finds the event already recorded and returns
138
+ `{ ok: true, replayed: true }` instead of appending a second one. A different
139
+ `operationId` never impersonates the earlier winner.
140
+
141
+ The guarantee is "one winner per transition", not "an authenticated owner":
142
+ nothing identifies which agent won, the lifecycle records `actor: 'agent'`.
143
+ Cloud mode has the same contract through the conditional update; the
144
+ disposable-database run that proves it against real Postgres is still an open
145
+ verification step (the adapter tests assert the exact statement, not SQL
146
+ atomicity).
147
+
62
148
  ### Watching for new feedback
63
149
 
64
150
  `watch_annotations` returns immediately if pending annotations already exist;
@@ -135,14 +221,57 @@ There is no mode switch:
135
221
  > Work through the tickets in .remarq/tasks/, one background subagent per
136
222
  > file, in parallel. Follow the instructions inside each file.
137
223
 
138
- Duplicate work is prevented by the lifecycle machine, not by locks: the first
139
- thing any executor does is `acknowledge` - if that fails, someone else owns
140
- the task and the file should be skipped.
224
+ Duplicate work is prevented by the atomic lifecycle transition, not by file
225
+ locks: the first thing any executor does is `acknowledge` with a fresh
226
+ `operationId` - if it answers `invalid_transition`, someone else already moved
227
+ the annotation and the file should be skipped; if the call fails without an
228
+ answer, retry with the same `operationId`.
229
+
230
+ ## Channel delivery (Claude Code, research preview)
231
+
232
+ In local mode the server is also a Claude Code *channel*: a mark you submit in
233
+ the browser reaches your open Claude Code session by itself and is fixed
234
+ without you typing anything. The agent fixes each mark, then calls `claim_fix`
235
+ (or `dismiss` with a reason); a human still verifies in the widget.
236
+
237
+ Start the session with the development-channel flag:
238
+
239
+ ```bash
240
+ claude --dangerously-load-development-channels server:web-remarq
241
+ ```
242
+
243
+ How it works: pending marks (never drafts) are pushed as one batch at a time.
244
+ The next batch is sent only after every mark of the current one was reported
245
+ (`claim_fix`, `dismiss`, or deleted) plus a short settle delay, because Claude
246
+ Code acts on an event that starts a turn but treats one arriving mid-turn as
247
+ untrusted. A batch that stays unreported is re-pushed once after the stale
248
+ timeout, and after a session restart the unfinished batch is re-pushed shortly
249
+ after initialization. The in-flight ledger is `.remarq/delivery.json`.
250
+
251
+ | Env var | Default | Purpose |
252
+ |---------|---------|---------|
253
+ | `REMARQ_CHANNEL` | `on` | `off` turns channel delivery off entirely (no capability, no ledger, no notifications) |
254
+ | `REMARQ_CHANNEL_SETTLE_MS` | `3000` | Quiet time after a batch is fully reported before the next one |
255
+ | `REMARQ_CHANNEL_STALE_MS` | `180000` | A batch in flight this long without progress is re-pushed once |
256
+ | `REMARQ_CHANNEL_REDELIVER_MS` | `2000` | Delay after MCP initialization before the unfinished batch is re-pushed |
257
+
258
+ Limits:
259
+
260
+ - Claude Code shows a warning dialog at start for development channels.
261
+ - Events are delivered only while a session is open; there is no acknowledgement.
262
+ - For unattended use the agent needs permission rules that allow `claim_fix`,
263
+ `dismiss` and file edits, otherwise it stops at a permission prompt.
264
+ - Clients that are not channels ignore the notifications.
265
+
266
+ `watch_annotations` and the prompts keep working as before: they are the
267
+ fallback and the path for other agents (Cursor, Codex, Windsurf). Channel
268
+ delivery is local mode only; cloud mode is unchanged.
141
269
 
142
270
  ## Cloud mode prerequisites
143
271
 
144
- 1. A Supabase project provisioned with `@web-remarq/cloud` (≥0.2.0). Run both
145
- `001_init.sql` and `002_lifecycle.sql` from the cloud package.
272
+ 1. A Supabase project provisioned with `@web-remarq/cloud` (≥0.4.0). Run
273
+ `001_init.sql`, `002_lifecycle.sql`, `003_quality.sql` and `004_rev.sql`
274
+ from the cloud package (all additive).
146
275
  2. A project key generated via `npx @web-remarq/cloud gen-key --name "..."`.
147
276
 
148
277
  ## Configuration
@@ -178,9 +307,9 @@ if any are missing or malformed. Leave all three unset for local mode.
178
307
  |------|-------|---------|
179
308
  | `list_annotations` | `{ route?, status?, viewportBucket?, file?, limit? }` | `{ annotations[], total }` - `status` accepts `draft`, `pending`, `in_progress`, `fixed_unverified`, `verified`, `dismissed`; each item carries `quality` (`clear` \| `ambiguous` \| `unactionable`) when an AI pre-flight check ran |
180
309
  | `get_annotation` | `{ id }` | Full `AgentAnnotation` shape (source + searchHints + lifecycle + `qualityCheck` when present) |
181
- | `acknowledge` | `{ id }` | `{ ok, status }` after `pending → in_progress` |
182
- | `claim_fix` | `{ id }` | `{ ok, status }` after `pending\|in_progress → fixed_unverified` |
183
- | `dismiss` | `{ id, reason? }` | `{ ok, status }` after non-terminal → `dismissed` |
310
+ | `acknowledge` | `{ id, operationId? }` | `{ ok, status, rev, replayed? }` after `pending → in_progress` (atomic, one winner) |
311
+ | `claim_fix` | `{ id, operationId? }` | `{ ok, status, rev, replayed? }` after `pending\|in_progress → fixed_unverified` |
312
+ | `dismiss` | `{ id, reason?, operationId? }` | `{ ok, status, rev, replayed? }` after non-terminal → `dismissed` |
184
313
  | `watch_annotations` | `{ timeoutSeconds? }` (1-120, default 25) | `{ annotations[], total, timedOut }` - long-polls for new pending annotations |
185
314
 
186
315
  When `qualityCheck.score` is `ambiguous` or `unactionable`, the comment likely needs designer clarification — prefer `dismiss` with a reason over guessing at intent.
@@ -188,7 +317,7 @@ When `qualityCheck.score` is `ambiguous` or `unactionable`, the comment likely n
188
317
  ### Error codes
189
318
 
190
319
  - `annotation_not_found` — id absent in project (also returned if RLS hides it)
191
- - `invalid_transition` — lifecycle action not allowed from current status; payload includes `currentStatus`
320
+ - `invalid_transition` — lifecycle action not allowed from current status. `details` carries `conflict: true`, `currentStatus`, `currentRev`, `lastEvent` and `requestedTransition`: treat it as "someone else got there first" - do not start work, re-read the annotation. Storage adapters without `mutate()` (custom ones) answer `atomic: false` on success
192
321
  - `storage_error` - Supabase / network failure in cloud mode, or a local
193
322
  file-store error (e.g. corrupted store) in local mode; payload includes root
194
323
  cause