@insitue/claude-plugin 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # @insitue/claude-plugin
 
+## 0.5.2
+
+- **Fix (hardcoded protocol version):** `mcp-server.ts` was sending
+  `protocolVersion: 5` as a literal in the WS hello handshake — the
+  same class of bug fixed in `@insitue/companion` 0.4.4 for the CLI
+  subscriber path. The literal would silently mismatch the next time
+  `@insitue/capture-core` bumps `PROTOCOL_VERSION`. The value is now
+  imported from `@insitue/capture-core` (added as a real dependency)
+  so there is a single source of truth. `@insitue/capture-core` is
+  bundled by tsup (not external) — no new runtime dep in the published
+  package.
+- **Fix (subscriber attach race — `start_session` / `list_recent_picks`
+  says "connected" before it is):** `connectToCompanion` previously
+  returned `void` and was not awaited in `ensureSubscriberAttached`.
+  This meant `list_recent_picks` (and therefore the `/insitue:connect`
+  slash command) could return "No picks buffered yet" before the
+  companion had added this MCP server to its `subscribers` set — so
+  the browser launcher badge stayed dark for a moment after claude
+  claimed to be listening. `connectToCompanion` now returns a
+  `Promise<boolean>` that resolves `true` when `subscribe-ok` arrives
+  (subscriber set joined, badge lit), or `false` on pre-subscribe
+  close. `ensureSubscriberAttached` awaits it and resets `attached` on
+  failure so the next explicit call retries cleanly.
+- Bumped 0.5.1 → 0.5.2.
+
+## 0.5.1
+
+- **Docs:** the operating instructions (`commands/connect.md`) now document
+  the cloud-issue workflow — `list_cloud_issues`, `claim_cloud_issue`,
+  `resolve_cloud_issue`, and `release_cloud_issue`. Previously these tools
+  were registered in the MCP server but not mentioned in the instructions
+  surfaced via `/insitue:connect`, `start_session`, or the `connect` prompt,
+  so Claude had no way to know the workflow existed. The new section covers
+  the claim→fix→PR→resolve loop, prerequisites (`insitue login` +
+  `insitue link`), the paid-plan requirement, and how to handle
+  `not_logged_in` / `not_linked` / `not_paid` error codes.
+
+## 0.5.0
+
+- **Feature:** four new MCP tools for working the InSitue Cloud issue queue
+  from a local Claude session:
+  - `list_cloud_issues` — list open bug reports for the linked project.
+  - `claim_cloud_issue(id)` — claim an issue; returns the full repro: note,
+    source `file:line`, page URL, and top console errors.
+  - `resolve_cloud_issue(id, prUrl, branch?)` — mark resolved and attach the
+    GitHub PR URL; `branch` is optional.
+  - `release_cloud_issue(id)` — return a claimed issue to the open queue.
+- **Docs:** added "Fix cloud issues from Claude" section to the README
+  covering prerequisites (`insitue login` + `insitue link`), the
+  claim→fix→resolve loop, and a typical Claude session transcript.
+- **Docs:** added the four cloud-issue tools to the MCP tools reference
+  table in the Architecture section.
+
+Requires a paid InSitue Cloud plan. Uses the project link written by
+`insitue link <projectId>` (the `@insitue/companion` CLI) and the auth
+token from `insitue login`.
+
 ## 0.4.6
 
 - **Fix (Windows):** `isInsideProject` now uses `path.sep` instead of a

package/README.md

@@ -233,6 +233,65 @@ extensively to stderr; claude surfaces them in the transcript.
 
 ---
 
+## Fix cloud issues from Claude
+
+> Requires a **paid InSitue Cloud plan** and the `@insitue/companion` CLI.
+
+If your project uses InSitue Cloud, bug reports captured in production land in your Cloud issue queue. The four `cloud_issue_*` MCP tools let Claude list those issues, claim one, read the full repro, fix it locally, and mark it resolved — all without leaving the terminal.
+
+### Prerequisites
+
+1. **Authenticate:** run `insitue login` (from the `@insitue/companion` CLI). This stores a token at `~/.insitue/auth.json`. Get the token at <https://app.insitue.com/app/settings/developer>.
+2. **Link your project:** run `insitue link <projectId>` in your project root. The tools read the linked project from `.insitue/project.json`.
+
+### The loop
+
+```
+list_cloud_issues        ← what's open?
+  ↓
+claim_cloud_issue(id)    ← lock the issue; receive full repro
+  ↓
+(Claude reads source file, applies fix, opens a PR)
+  ↓
+resolve_cloud_issue(id, prUrl, branch?)   ← attach the PR; close the issue
+```
+
+If you claim an issue and decide not to fix it, call `release_cloud_issue(id)` to return it to the queue so someone else can pick it up.
+
+### MCP tools
+
+| Tool | Arguments | What it does |
+|---|---|---|
+| `list_cloud_issues` | — | Lists open bug reports for the linked project. |
+| `claim_cloud_issue` | `id` | Claims the issue and returns the full repro: description (note), source `file:line`, page URL, and top console errors. |
+| `resolve_cloud_issue` | `id`, `prUrl`, `branch?` | Marks the issue resolved and attaches the GitHub PR URL. `branch` is optional — include it when the fix isn't on the default branch yet. |
+| `release_cloud_issue` | `id` | Returns a claimed issue to the open queue without resolving it. |
+
+### Typical Claude session
+
+```
+> /insitue:connect
+# (pick-and-edit loop starts as normal)
+
+# Switch to cloud issues:
+> list open cloud issues
+# Claude calls list_cloud_issues, picks one.
+
+> claim issue <id>
+# Claude calls claim_cloud_issue — gets note, file:line, page URL, console errors.
+# Claude opens the source file at the reported line, reads context, writes a fix.
+# Claude opens a PR via gh or the normal git flow.
+
+> resolve issue <id> with PR https://github.com/…/pull/42
+# Claude calls resolve_cloud_issue(id, "https://github.com/…/pull/42").
+```
+
+The cloud-issue tools compose naturally with the pick→edit loop — you can interleave browser picks and issue fixes in the same session.
+
+See [Fix cloud issues locally](../../docs/fix-cloud-issues-locally.md) for a full walkthrough.
+
+---
+
 ## Architecture (skip unless curious)
 
 The plugin is a stdio MCP server that:
@@ -267,6 +326,10 @@ The plugin is a stdio MCP server that:
 | `read_file` | Project-scoped file read. Desktop fallback (Code has native Read). |
 | `apply_edit` | Project-scoped string-replacement edit. Desktop fallback (Code has native Edit). |
 | `write_file` | Project-scoped full-file write. Desktop fallback. |
+| `list_cloud_issues` | List open InSitue Cloud bug reports for the linked project. Paid plan + `insitue link` required. |
+| `claim_cloud_issue` | Claim an issue by `id`; returns note, source `file:line`, page URL, and top console errors. |
+| `resolve_cloud_issue` | Mark an issue resolved; attach `prUrl` and optional `branch`. |
+| `release_cloud_issue` | Return a claimed issue to the open queue. |
 
 All file tools resolve paths against the project dir and refuse
 anything that resolves outside it (realpath-checked, so `..` games

package/commands/connect.md

@@ -115,6 +115,56 @@ Either path is fine; pick whichever your runtime has.
   first and ask "want me to do X too?" rather than bundling
   silently.
 
+## Cloud-issue loop (paid plan, signed-in users)
+
+In addition to browser picks, you can pull and fix pre-captured bug
+reports from the InSitue dashboard. This is a separate workflow —
+both can be used in the same session.
+
+**Tools:**
+
+- `mcp__insitue__list_cloud_issues` — show the open issue queue for
+  the linked project. Each entry has an `id`, a short `description`,
+  and a `source file:line` where known. Call this when the user says
+  "show me issues", "what's in the queue", or similar.
+- `mcp__insitue__claim_cloud_issue <id>` — claim an issue (marks it
+  "fixing locally" in the dashboard) and return its repro context:
+  `note` (the reporter's description), `source.file:line`, `url`
+  (the page where it was captured), and `consoleErrors`. On a
+  successful claim: read the source file around the reported line,
+  reproduce from the note, make the fix, open a PR, then call
+  `resolve_cloud_issue`.
+- `mcp__insitue__resolve_cloud_issue <id> <prUrl>` — mark the issue
+  resolved and attach the GitHub PR URL. Call this after the PR is
+  open, not before.
+- `mcp__insitue__release_cloud_issue <id>` — abandon the claim and
+  return the issue to the open queue (use when you decide not to fix
+  it locally).
+
+**Prerequisites.** These tools require:
+  - `insitue login` (creates `~/.insitue/auth.json` — generate a
+    token at https://app.insitue.com/app/settings/developer)
+  - `insitue link <projectId>` run in this repo (writes
+    `.insitue/project.json` — find the id in your project settings)
+  - A paid InSitue Cloud plan
+
+If any tool returns `error: "not_logged_in"`, `"not_linked"`, or
+`"not_paid"`, relay the `message` field verbatim to the user and
+stop — do not retry. The message contains the exact corrective
+action.
+
+**Typical loop:**
+
+1. `list_cloud_issues` → pick an issue with the user.
+2. `claim_cloud_issue <id>` → read `source.file` around `source.line`,
+   understand the repro from `note` + `consoleErrors`, make the fix.
+3. Open a PR.
+4. `resolve_cloud_issue <id> <prUrl>`.
+
+The cloud-issue workflow follows the same guardrails as browser picks:
+never auto-apply writes, always wait for explicit user approval before
+editing files.
+
 ## Failure modes to handle gracefully
 
 - **`source.file` doesn't exist**: tell the user the path the

package/dist/mcp-server.js

@@ -29,6 +29,7 @@ import { dirname as dirname3, join as join3 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import WebSocket from "ws";
 import { z } from "zod";
+import { PROTOCOL_VERSION } from "@insitue/capture-core";
 
 // src/file-tools.ts
 import {
@@ -388,68 +389,81 @@ var activeWs = null;
 var reconnectTimer = null;
 var disconnecting = false;
 function connectToCompanion(s) {
-  const url = `ws://127.0.0.1:${s.port}/insitue/cli`;
-  const ws = new WebSocket(url, {
-    headers: { "user-agent": "insitue-claude-plugin" }
-  });
-  activeWs = ws;
-  ws.on("open", () => {
-    ws.send(
-      JSON.stringify({
-        t: "hello",
-        // Pin to the companion's pinned protocol version. Bump
-        // when the wire format breaks.
-        protocolVersion: 5,
-        token: s.token
-      })
-    );
-  });
-  ws.on("message", (data) => {
-    let m;
-    try {
-      m = JSON.parse(String(data));
-    } catch {
-      return;
-    }
-    if (m && typeof m === "object") {
-      const tag = m.t;
-      if (tag === "hello-ok") {
-        ws.send(JSON.stringify({ t: "subscribe" }));
+  return new Promise((subscribeResolve) => {
+    let subscribed = false;
+    const url = `ws://127.0.0.1:${s.port}/insitue/cli`;
+    const ws = new WebSocket(url, {
+      headers: { "user-agent": "insitue-claude-plugin" }
+    });
+    activeWs = ws;
+    ws.on("open", () => {
+      ws.send(
+        JSON.stringify({
+          t: "hello",
+          // Imported from @insitue/capture-core — the single source of
+          // truth for the wire protocol version. A hardcoded literal here
+          // would silently drift the moment the capture-core version is
+          // bumped (same class of bug fixed in companion 0.4.4).
+          protocolVersion: PROTOCOL_VERSION,
+          token: s.token
+        })
+      );
+    });
+    ws.on("message", (data) => {
+      let m;
+      try {
+        m = JSON.parse(String(data));
+      } catch {
         return;
       }
-      if (tag === "broadcast-capture") {
-        try {
-          const summary = summariseBundle(
-            m
-          );
-          buffer.push(summary);
-          const note = summary.userNote ? summary.userNote.length > 60 ? `${summary.userNote.slice(0, 57)}\u2026` : summary.userNote : "(no description)";
-          const where = summary.source ? `${summary.source.file}:${summary.source.line}` : summary.target;
-          process.stderr.write(
-            `[insitue] \u{1F4E5} pick received \u2014 "${note}" @ ${where}
+      if (m && typeof m === "object") {
+        const tag = m.t;
+        if (tag === "hello-ok") {
+          ws.send(JSON.stringify({ t: "subscribe" }));
+          return;
+        }
+        if (tag === "subscribe-ok") {
+          if (!subscribed) {
+            subscribed = true;
+            subscribeResolve(true);
+          }
+          return;
+        }
+        if (tag === "broadcast-capture") {
+          try {
+            const summary = summariseBundle(
+              m
+            );
+            buffer.push(summary);
+            const note = summary.userNote ? summary.userNote.length > 60 ? `${summary.userNote.slice(0, 57)}\u2026` : summary.userNote : "(no description)";
+            const where = summary.source ? `${summary.source.file}:${summary.source.line}` : summary.target;
+            process.stderr.write(
+              `[insitue] \u{1F4E5} pick received \u2014 "${note}" @ ${where}
 `
-          );
-        } catch (err) {
-          process.stderr.write(
-            `[insitue-mcp] dropped malformed pick: ${err.message}
+            );
+          } catch (err) {
+            process.stderr.write(
+              `[insitue-mcp] dropped malformed pick: ${err.message}
 `
-          );
+            );
+          }
+          return;
         }
-        return;
+        if (tag === "broadcast-ask") return;
       }
-      if (tag === "broadcast-ask") return;
-    }
-  });
-  ws.on("close", () => {
-    if (activeWs === ws) activeWs = null;
-    buffer.dropWaiters();
-    if (disconnecting) return;
-    process.stderr.write(
-      "[insitue-mcp] companion link dropped \u2014 reconnecting in 2s\n"
-    );
-    reconnectTimer = setTimeout(() => connectToCompanion(s), 2e3);
-  });
-  ws.on("error", () => {
+    });
+    ws.on("close", () => {
+      if (!subscribed) subscribeResolve(false);
+      if (activeWs === ws) activeWs = null;
+      buffer.dropWaiters();
+      if (disconnecting) return;
+      process.stderr.write(
+        "[insitue-mcp] companion link dropped \u2014 reconnecting in 2s\n"
+      );
+      reconnectTimer = setTimeout(() => void connectToCompanion(s), 2e3);
+    });
+    ws.on("error", () => {
+    });
   });
 }
 var projectDir = resolveProjectDir();
@@ -473,7 +487,13 @@ async function ensureSubscriberAttached(opts = {}) {
     if (!session) return;
   }
   attached = true;
-  connectToCompanion(session);
+  const ok = await connectToCompanion(session);
+  if (!ok) {
+    attached = false;
+    process.stderr.write(
+      "[insitue-mcp] subscriber attach failed \u2014 companion handshake did not complete\n"
+    );
+  }
 }
 function endSession() {
   disconnecting = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@insitue/claude-plugin",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Drive Claude (Code AND Desktop) from the InSitue browser overlay — pick an element in your app, claude reads the file and proposes the edit.",
   "keywords": [
     "insitue",
@@ -38,7 +38,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "ws": "^8.18.0",
-    "zod": "^3.23.8"
+    "zod": "^3.23.8",
+    "@insitue/capture-core": "0.4.1"
   },
   "devDependencies": {
     "@types/ws": "^8.5.13",