@satanwagen/reviewkit 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## 0.1.4 — 2026-09-02
+
+### Added
+
+- **`reviewkit` terminal CLI** (in `@satanwagen/reviewkit-cli`, zero deps,
+  Node 21+): `cd repo && reviewkit` opens an interactive live view of every
+  review item across the site's pages: presence (who is online, in their
+  colours), arrow-key navigation, Enter for actions (detail, apply with
+  Claude Code, copy prompt, set status, delete), `a` to hand all open items
+  to Claude Code, filters, live toasts for new / changed / deleted items.
+  Piped output falls back to a plain table plus event stream. `list`, `show`,
+  `status`, `delete`, `watch`, `export`, `prompt`, `rooms`, `projects`, `key`.
+  Project resolution: `-p name` → `.reviewkit/project.json` (walks up from
+  cwd) → `.reviewkit/emblema-sync.json` → global active project.
+- **One-click pairing.** `reviewkit setup` detects the site's sync settings in
+  the repo, listens on loopback (127.0.0.1:48780–48783) and the review panel's
+  new **Connect terminal / agent…** dialog finds it and pushes the connection.
+  Nothing to copy. A copyable `rkc_…` key remains for remote machines
+  (`reviewkit connect <key>`). CSP: the panel needs `connect-src
+  http://127.0.0.1:*` for this (already required by the Emblema bridge).
+- **MCP bridge for coding agents.** `reviewkit mcp` is a stdio MCP server
+  with `reviewkit_prompt`, `reviewkit_list`, `reviewkit_show`,
+  `reviewkit_set_status`, `reviewkit_delete`, `reviewkit_export`,
+  `reviewkit_rooms`, `reviewkit_projects`. `setup` / `mcp-install` register it
+  in Claude Code (`claude mcp add`) and Cursor (`~/.cursor/mcp.json`).
+  Statuses set by the agent appear live in reviewers' browsers.
+- **Sync server: `rooms` request** (protocol v1, additive). Returns the routes
+  of the connection's origin that have review data, live or on disk, with item
+  counts and online peers. Needed by the CLI. Deployed on the satanwagen
+  server, reachable again at `wss://2-59-219-26.sslip.io/rk-sync` (sslip.io
+  hostname, no domain to expire) — and the client's default `syncUrl` again.
+- Panel gear menu: **Connect terminal / agent…** (enabled when live sync is on).
+
+### Changed
+
+- **One word does everything: `<ReviewKit token="…" />`.** Live collaboration
+  is on by default: `syncUrl` defaults to the public ReviewKit server
+  `wss://2-59-219-26.sslip.io/rk-sync` (sslip.io hostname → VPS IP, nothing to
+  expire) and `syncToken` defaults to `token`. The server is now
+  **self-serve**: any token of at least 8 characters gets its own private set
+  of rooms (keyed by origin + route + hash(token)), so no account and no
+  server-side step exist. New prop `sync={false}` forces solo mode;
+  `syncToken` stays as an override when the room secret should differ from
+  the review link. Existing installs that set `token` but no `syncToken`
+  start syncing on upgrade — pass `sync={false}` to keep the old solo mode.
+  Same in the CLI: `init --sync-url` is optional, state files still carrying
+  the retired host fall back to the default with a warning, and `reviewkit
+  setup` picks up the review token from the repo as the room secret.
+- `@satanwagen/reviewkit-cli` now ships two tools. `npx -y
+  @satanwagen/reviewkit-cli …` runs `reviewkit`; the Emblema agent is
+  `npx -p @satanwagen/reviewkit-cli reviewkit-emblema …` (docs and in-app
+  hints updated).
+
 ## 0.1.3 — 2026-09-02
 
 Defaults tightened so a production build behaves the way its code reads.
@@ -24,7 +77,7 @@ each has a one-line migration below.
   stays disabled until both `--sync-url` and `--sync-token` are configured).
 - **CLI moved to `@satanwagen/reviewkit-cli`.** The main package no longer
   ships a `bin`, so a host `npm install` does not pull the Emblema agent.
-  Migration: `npx @satanwagen/reviewkit-cli init …` / `serve` (the command
+  Migration: `npx -p @satanwagen/reviewkit-cli reviewkit-emblema init …` / `serve` (the command
   inside is still `reviewkit-emblema`).
 - **`emblema.repoPath` is optional.** The repo path is Emblema's local
   knowledge (advertised in its `/intake/ping` answer, and present in

package/README.md

@@ -17,10 +17,10 @@ import { ReviewKit } from '@satanwagen/reviewkit/lazy';   // Vite, CRA, Remix
 // import { ReviewKit } from '@satanwagen/reviewkit/next'; // Next.js App Router ('use client' built in)
 
 // anywhere in your tree, rendered once:
-<ReviewKit token={import.meta.env.VITE_REVIEW_TOKEN} />
+<ReviewKit token="pick-any-word" />
 ```
 
-That's it. The component renders `null` unless review mode is active, and all UI lives in a shadow root appended to `document.body` — your CSS never leaks in, reviewkit's CSS never leaks out. Safe to ship in production builds.
+That's it — one word. Reviewers open `https://your-site/?review=pick-any-word`; the same word is also the secret of your private rooms on the public ReviewKit sync server, so presence, live cursors, shared items, the terminal CLI and the Claude Code bridge all work with no server-side step. The component renders `null` unless review mode is active, and all UI lives in a shadow root appended to `document.body` — your CSS never leaks in, reviewkit's CSS never leaks out. Safe to ship in production builds. Want it offline? `sync={false}`.
 
 Three entries, same props:
 
@@ -49,8 +49,9 @@ if (shouldActivate({ token: TOKEN })) void import('./reviewHost');
 | `enabled` | `boolean` | Master switch, default `true`. `false` renders nothing, installs nothing. Lets you write `enabled={Boolean(TOKEN)}` instead of `if (!TOKEN) return null`. |
 | `devAutoOn` | `boolean` | Force the layer on for this page load, no link needed. Host-controlled dev convenience (`devAutoOn={import.meta.env.DEV}`); the library never reads `NODE_ENV`. Still subject to `enabled`, `allowedHosts` and `?review=off`. |
 | `allowedHosts` | `string[]` | Hostname allowlist with `*` wildcards (`['localhost', '*.staging.example']`). Outside it nothing activates, token or not. Unset = any host (with a one-time console warning on URL activation on a public host). |
-| `syncUrl` | `string` | WebSocket endpoint of your sync server (`realtime/server`), e.g. `wss://your-site.tld/rk-sync`. **No default.** |
-| `syncToken` | `string` | Shared secret of the sync server. Live collaboration (presence, cursors, shared items) runs only when **both** `syncUrl` and `syncToken` are set; otherwise solo mode, no network. Public in the bundle by nature — a gate against casual visitors, not a secret. |
+| `syncUrl` | `string` | WebSocket endpoint of the sync server. Default: the public ReviewKit server `wss://2-59-219-26.sslip.io/rk-sync`, so live collaboration needs no server of your own. Override for a self-hosted `realtime/server`. |
+| `sync` | `boolean` | Live collaboration switch, default `true`. `false` = solo mode, no network. |
+| `syncToken` | `string` | Secret of your rooms on the sync server, **defaults to `token`**. Any string of 8+ characters gets its own private rooms on the public server. Override only if the room secret should differ from the review link. Public in the bundle by nature. |
 | `emblema` | `{ repoPath?: string; port?: number }` | Enables the Emblema bridge (`emblema={{}}` is enough). See "Pairing with Emblema". |
 | `defaultAuthor` | `string` | Pre-fills the reviewer name. |
 | `fxAssetsUrl` | `string` | Base URL for the `/` effect soundtracks (`<base>/rick.mp3` for `/ondro`). Default: the public ReviewKit assets host `https://2-59-219-26.sslip.io/rk-assets`. Override to self-host. Needs `media-src` in CSP. |
@@ -95,18 +96,16 @@ The sticky session is per tab (`sessionStorage`), bound to the token and renewed
   enabled={Boolean(TOKEN)}
   token={TOKEN}
   allowedHosts={['staging.your-site.tld', '*.preview.your-site.tld']}
-  syncUrl="wss://your-site.tld/rk-sync"
-  syncToken={SYNC_TOKEN}
 />
 ```
 
-`token` + `allowedHosts` together: the token says *who*, the allowlist says *where*. Without `allowedHosts` a URL activation on a non-loopback host logs one console warning. `TOKEN`/`SYNC_TOKEN` are public in the bundle by design; use the `/lazy` or `/next` entry so they at least live in the review chunk, not the main one.
+`token` + `allowedHosts` together: the token says *who*, the allowlist says *where*. Without `allowedHosts` a URL activation on a non-loopback host logs one console warning. `TOKEN` is public in the bundle by design; use the `/lazy` or `/next` entry so it at least lives in the review chunk, not the main one.
 
 ### CSP
 
 If the host sends a `Content-Security-Policy`, `connect-src` must allow:
 
-- the sync server origin, as `wss://your-site.tld` (or the `ws:` origin in dev),
+- the sync server origin: `https://2-59-219-26.sslip.io` for the default server (or your own `syncUrl` origin / `ws:` in dev),
 - `http://127.0.0.1:*` when the `emblema` prop is set (intake ports 48752–48755, pairing agent 48770–48773).
 
 and `media-src` must allow `https://2-59-219-26.sslip.io` (or your `fxAssetsUrl`) for the `/` effect sounds; without it the effects run silent.
@@ -267,17 +266,17 @@ Step by step, for any site on any hosting (nginx, IIS, Vercel, …).
 
 Run `npm run build` inside ReviewKit at least once for the `file:`/git variants (the package resolves to `dist/`). With React 18 add `resolve.dedupe: ['react','react-dom']` to your bundler config when using a `file:` link.
 
-**2. Integrate — two lines, done:**
+**2. Integrate — one line, done:**
 
 ```tsx
 import { ReviewKit } from '@satanwagen/reviewkit/lazy';
 
-<ReviewKit token="my-site-token" syncUrl="wss://your-site.tld/rk-sync" syncToken="<the sync server's shared secret>" />
+<ReviewKit token="my-site-token" />
 ```
 
-Live collaboration (presence, live cursors, instantly shared items) runs only when **both** `syncUrl` and `syncToken` are set — there is no default server. Rooms are keyed by the page's origin + path, so different sites never see each other's feedback or presence. If the server is unreachable the tool silently runs local-only (no console errors); omit either prop to disable networking entirely.
+Live collaboration (presence, live cursors, instantly shared items) is on by default: `syncUrl` points at the public ReviewKit server `wss://2-59-219-26.sslip.io/rk-sync` and the room secret is your `token` (8+ characters; `syncToken` overrides it). The server is self-serve: every token gets its own private rooms, no account, no registration. Rooms are keyed by the page's origin + path, so different sites never see each other's feedback or presence. If the server is unreachable the tool silently runs local-only (no console errors); omit either prop to disable networking entirely.
 
-**What a shared server implies (honesty section):** the token and `syncToken` are readable in the browser bundle, so anyone holding a review URL can join and create rooms. Run the server for your own sites only; it is guarded by the shared token, per-connection rate limits (40 msg/s, burst 80), 1 MiB frame cap, 16 clients and 2000 items per room, and a live-room ceiling (`RK_SYNC_MAX_ROOMS`, default 500).
+**What a shared server implies (honesty section):** the token is readable in the browser bundle and in every review link, so anyone holding the link can join your rooms — that is the point of a review link. Rooms of different tokens never mix. The public server is guarded by per-connection rate limits (40 msg/s, burst 80), 1 MiB frame cap, 16 clients and 2000 items per room, and a live-room ceiling (`RK_SYNC_MAX_ROOMS`, default 500).
 
 **3. Run the sync server** — `realtime/server/`: `npm run build`, run `dist/server.js` with `RK_SYNC_TOKEN` (+ optional `RK_SYNC_PORT`, `RK_SYNC_DATA`, `RK_SYNC_MAX_ROOMS`, and `RK_SYNC_ORIGINS` if you *want* an origin allowlist — empty/unset means any origin, which is the default deployment) as a service, point `syncUrl` at it, then put a WebSocket-aware reverse proxy in front:
 
@@ -301,6 +300,30 @@ Live collaboration (presence, live cursors, instantly shared items) runs only wh
 
 **5. Verify it works:** open `https://your-site/?review=<token>` — the Review badge appears; the panel header shows **live** (green dot) when the sync server accepted you, or *local only* when not. In the Network tab you should see one WebSocket to `/rk-sync` with a `welcome` frame. Open the same URL in a second browser: avatars, live cursors and instantly-appearing items confirm collaboration.
 
+## Terminal & coding agents (`reviewkit` CLI)
+
+Review comments do not have to stay in the browser. The `reviewkit` CLI reads the same live rooms, and doubles as the MCP bridge for Claude Code, Cursor and any other MCP client, so an agent can read every comment and mark items applied while reviewers watch the status flip live.
+
+```sh
+npm install -g @satanwagen/reviewkit-cli
+cd my-site
+reviewkit          # first run pairs the repo (one click in the review panel), then the live view
+```
+
+**Pairing is one click, no copy-paste.** Bare `reviewkit` in an unpaired repo runs `setup` first; it detects the site's `token` (and a custom `syncToken` / `syncUrl`, if any) in the repo, opens a loopback port and waits. In the browser open the review panel → gear → **Connect terminal / agent…** → **Connect**: the panel finds the waiting terminal and pushes the connection into `<repo>/.reviewkit/project.json` (gitignored). `setup` also registers the MCP server in Claude Code and Cursor when it finds them. The dialog keeps a copyable key as the fallback for a terminal on another machine.
+
+The live view is interactive: arrow keys walk the items, Enter opens actions (detail, apply this item with Claude Code, copy as prompt, mark applied / accepted / rejected / reopen, delete), `a` hands every open item to Claude Code in the repo, and the header shows who is reviewing right now in their own colours. Everything is the shared room state, so a status flipped in the terminal or by an agent changes in reviewers' browsers instantly, and vice versa.
+
+Everyday commands: `reviewkit list --status open`, `reviewkit show <id>`, `reviewkit status <id> applied`, `reviewkit watch`, `reviewkit export -o review.json`, `reviewkit prompt` (agent-ready work list), `reviewkit rooms`, `reviewkit projects` / `-p <name>` to act on another paired site. Full table in [`cli/README.md`](./cli/README.md).
+
+**Agents.** With the bridge registered, "apply the reviewkit feedback" is enough: the agent calls `reviewkit_prompt`, edits code, then `reviewkit_set_status(id, "applied")` per item. Manual registration:
+
+```sh
+claude mcp add --scope user reviewkit -- npx -y @satanwagen/reviewkit-cli mcp
+```
+
+Requirements: the site has live sync on (the default), Node 21+. The CLI reads shared rooms, never a reviewer's local browser storage. The sync server gained a `rooms` request (protocol v1, additive) so the CLI can find every page with review data; run the 0.1.4 server build.
+
 ## Pairing with Emblema
 
 ReviewKit pairs with the [Emblema](https://emblema.app) desktop app: once paired, the local sync agent streams review items to Emblema, and the paired Emblema shows them as findings in its ReviewKit tile (statuses flow back to the page).
@@ -314,8 +337,8 @@ Sync is automatic and realtime — no manual step. With `emblema={{}}` in the `R
 **Set up and generate a key** (in the project repo; the CLI is its own package so host installs stay CLI-free):
 
 ```sh
-npx @satanwagen/reviewkit-cli init --origin https://your-site --sync-url wss://your-site/rk-sync --sync-token <secret>
-npx @satanwagen/reviewkit-cli serve      # local API + realtime bridge (bridge needs both sync flags)
+npx -p @satanwagen/reviewkit-cli reviewkit-emblema init --origin https://your-site --sync-url wss://your-site/rk-sync --sync-token <secret>
+npx -p @satanwagen/reviewkit-cli reviewkit-emblema serve      # local API + realtime bridge (bridge needs both sync flags)
 ```
 
 Paste the printed key into Emblema. From the page UI the same lives in the panel's gear menu → **Connect to Emblema…** — the menu entry shows the live pairing status at a glance (green dot = paired, amber = the local agent isn't answering, red = key revoked, grey = not paired), and the dialog has **New key (rotate)**, **Copy key** and **Delete key (revoke)**.
@@ -323,9 +346,9 @@ Paste the printed key into Emblema. From the page UI the same lives in the panel
 **Rotate / revoke from the CLI:**
 
 ```sh
-npx @satanwagen/reviewkit-cli key      # print the current key
-npx @satanwagen/reviewkit-cli rotate   # issue a new secret — the old key stops working immediately
-npx @satanwagen/reviewkit-cli revoke   # disable the pairing entirely (rotate re-enables)
+npx -p @satanwagen/reviewkit-cli reviewkit-emblema key      # print the current key
+npx -p @satanwagen/reviewkit-cli reviewkit-emblema rotate   # issue a new secret — the old key stops working immediately
+npx -p @satanwagen/reviewkit-cli reviewkit-emblema revoke   # disable the pairing entirely (rotate re-enables)
 ```
 
 Rotate and revoke take effect immediately, including against an already-running `serve` process — authenticated requests always check the current on-disk key, so a rotated or revoked key can never keep authenticating.
@@ -340,7 +363,7 @@ npm install
 npm run dev   # http://localhost:3010 — devAutoOn keeps the layer on in dev
 ```
 
-Also try `http://localhost:3010/?review=demo` to exercise URL activation. `examples/next-demo` is the same site on Next.js (App Router, `/next` entry, CSP headers) on port 3011.
+Also try `http://localhost:3010/?review=demo-review` to exercise URL activation. `examples/next-demo` is the same site on Next.js (App Router, `/next` entry, CSP headers) on port 3011.
 
 ## Development