@insitue/claude-plugin 0.4.6 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @insitue/claude-plugin
 
+## 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/chunk-5APYM634.js

@@ -0,0 +1,31 @@
+// src/cloud/config.ts
+import { homedir } from "os";
+import { join } from "path";
+import { existsSync, readFileSync } from "fs";
+function loadAuth() {
+  const p = join(homedir(), ".insitue", "auth.json");
+  if (!existsSync(p)) return {};
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function loadProjectId(projectDir) {
+  const p = join(projectDir, ".insitue", "project.json");
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, "utf8")).projectId ?? null;
+  } catch {
+    return null;
+  }
+}
+function resolveHost(cfg) {
+  return process.env["INSITUE_API_HOST"] ?? cfg.host ?? "https://app.insitue.com";
+}
+
+export {
+  loadAuth,
+  loadProjectId,
+  resolveHost
+};

package/dist/chunk-IRPBZWNQ.js

@@ -0,0 +1,66 @@
+// src/cloud/api.ts
+var CloudApiError = class extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "CloudApiError";
+  }
+  status;
+  code;
+};
+async function call(host, token, method, path, body) {
+  const res = await fetch(`${host}${path}`, {
+    method,
+    headers: {
+      authorization: `Bearer ${token}`,
+      ...body ? { "content-type": "application/json" } : {}
+    },
+    ...body ? { body: JSON.stringify(body) } : {}
+  });
+  const text = await res.text();
+  let json = {};
+  try {
+    json = text ? JSON.parse(text) : {};
+  } catch {
+  }
+  const errMsg = json?.error;
+  if (!res.ok) {
+    const code = res.status === 401 ? "unauthorized" : res.status === 402 ? "not_paid" : res.status === 404 ? "not_found" : res.status === 409 ? "conflict" : "error";
+    throw new CloudApiError(res.status, code, errMsg ?? `HTTP ${res.status}`);
+  }
+  return json;
+}
+var listIssues = (host, token, projectId) => call(
+  host,
+  token,
+  "GET",
+  `/api/v1/dev/issues?projectId=${encodeURIComponent(projectId)}`
+);
+var claimIssue = (host, token, id) => call(
+  host,
+  token,
+  "POST",
+  `/api/v1/dev/issues/${encodeURIComponent(id)}/claim`
+);
+var resolveIssue = (host, token, id, prUrl, branch) => call(
+  host,
+  token,
+  "POST",
+  `/api/v1/dev/issues/${encodeURIComponent(id)}/resolve`,
+  { prUrl, branch }
+);
+var releaseIssue = (host, token, id) => call(
+  host,
+  token,
+  "POST",
+  `/api/v1/dev/issues/${encodeURIComponent(id)}/release`
+);
+
+export {
+  CloudApiError,
+  listIssues,
+  claimIssue,
+  resolveIssue,
+  releaseIssue
+};

package/dist/{chunk-U4C5CDNQ.js → chunk-SGLSPTHD.js}

@@ -1,9 +1,9 @@
 // src/diagnose.ts
-import { existsSync, readFileSync } from "fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "fs";
 import { request as httpRequest } from "http";
 import { join } from "path";
-function readPkgVersion(projectDir, pkgName) {
-  const pkgJson = join(projectDir, "node_modules", pkgName, "package.json");
+function readPkgVersionAt(dir, pkgName) {
+  const pkgJson = join(dir, "node_modules", pkgName, "package.json");
   if (!existsSync(pkgJson)) return null;
   try {
     return JSON.parse(readFileSync(pkgJson, "utf8")).version ?? null;
@@ -11,6 +11,38 @@ function readPkgVersion(projectDir, pkgName) {
     return null;
   }
 }
+function listWorkspaceMembers(projectDir) {
+  const out = [];
+  for (const parent of ["apps", "packages"]) {
+    const parentDir = join(projectDir, parent);
+    if (!existsSync(parentDir)) continue;
+    let entries;
+    try {
+      entries = readdirSync(parentDir);
+    } catch {
+      continue;
+    }
+    for (const name of entries) {
+      const child = join(parentDir, name);
+      try {
+        if (statSync(child).isDirectory() && existsSync(join(child, "package.json"))) {
+          out.push(child);
+        }
+      } catch {
+      }
+    }
+  }
+  return out;
+}
+function readPkgVersion(projectDir, pkgName) {
+  const v = readPkgVersionAt(projectDir, pkgName);
+  if (v) return v;
+  for (const ws of listWorkspaceMembers(projectDir)) {
+    const v2 = readPkgVersionAt(ws, pkgName);
+    if (v2) return v2;
+  }
+  return null;
+}
 function readSession(projectDir) {
   const file = join(projectDir, ".insitue", "session.json");
   if (!existsSync(file)) return null;
@@ -21,7 +53,7 @@ function readSession(projectDir) {
   }
 }
 async function pokeCompanion(port) {
-  return new Promise((resolve2) => {
+  return new Promise((resolve) => {
     const req = httpRequest(
       {
         host: "127.0.0.1",
@@ -32,26 +64,27 @@ async function pokeCompanion(port) {
       },
       (res) => {
         res.resume();
-        resolve2({ alive: true, subscribers: null });
+        resolve({ alive: true, subscribers: null });
       }
     );
-    req.on("error", () => resolve2({ alive: false, subscribers: null }));
+    req.on("error", () => resolve({ alive: false, subscribers: null }));
     req.on("timeout", () => {
       req.destroy();
-      resolve2({ alive: false, subscribers: null });
+      resolve({ alive: false, subscribers: null });
     });
     req.end();
   });
 }
-function detectSwcPluginConfigured(projectDir) {
-  for (const f of [
-    "next.config.mjs",
-    "next.config.js",
-    "next.config.ts",
-    "vite.config.ts",
-    "vite.config.js"
-  ]) {
-    const p = join(projectDir, f);
+var FRAMEWORK_CONFIGS = [
+  "next.config.mjs",
+  "next.config.js",
+  "next.config.ts",
+  "vite.config.ts",
+  "vite.config.js"
+];
+function detectSwcPluginConfiguredAt(dir) {
+  for (const f of FRAMEWORK_CONFIGS) {
+    const p = join(dir, f);
     if (existsSync(p)) {
       try {
         const c = readFileSync(p, "utf8");
@@ -63,6 +96,18 @@ function detectSwcPluginConfigured(projectDir) {
   }
   return null;
 }
+function detectSwcPluginConfigured(projectDir) {
+  let foundAnyConfig = false;
+  const direct = detectSwcPluginConfiguredAt(projectDir);
+  if (direct === true) return true;
+  if (direct === false) foundAnyConfig = true;
+  for (const ws of listWorkspaceMembers(projectDir)) {
+    const r = detectSwcPluginConfiguredAt(ws);
+    if (r === true) return true;
+    if (r === false) foundAnyConfig = true;
+  }
+  return foundAnyConfig ? false : null;
+}
 async function diagnose(projectDir) {
   const session = readSession(projectDir.dir);
   const hasSessionFile = session !== null;
@@ -119,76 +164,6 @@ async function diagnose(projectDir) {
   };
 }
 
-// src/project-dir.ts
-import { existsSync as existsSync2, realpathSync } from "fs";
-import { dirname, isAbsolute, join as join2, resolve, sep } from "path";
-function readProjectDirArg(argv) {
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === "--project-dir" && i + 1 < argv.length) return argv[i + 1];
-    if (a.startsWith("--project-dir=")) return a.slice("--project-dir=".length);
-  }
-  return null;
-}
-function walkUpFor(start, marker) {
-  let dir = resolve(start);
-  while (true) {
-    if (existsSync2(join2(dir, marker))) return dir;
-    const parent = dirname(dir);
-    if (parent === dir) return null;
-    dir = parent;
-  }
-}
-function realpathSafe(p) {
-  try {
-    return realpathSync(p);
-  } catch {
-    return resolve(p);
-  }
-}
-function resolveProjectDir(argv = process.argv.slice(2), env = process.env) {
-  const fromArg = readProjectDirArg(argv);
-  if (fromArg) {
-    return { dir: realpathSafe(fromArg), source: "argv" };
-  }
-  if (env.INSITUE_PROJECT_DIR) {
-    return {
-      dir: realpathSafe(env.INSITUE_PROJECT_DIR),
-      source: "INSITUE_PROJECT_DIR"
-    };
-  }
-  if (env.CLAUDE_PROJECT_DIR) {
-    return {
-      dir: realpathSafe(env.CLAUDE_PROJECT_DIR),
-      source: "CLAUDE_PROJECT_DIR"
-    };
-  }
-  const cwd = process.cwd();
-  const sessionDir = walkUpFor(cwd, ".insitue");
-  if (sessionDir && existsSync2(join2(sessionDir, ".insitue", "session.json"))) {
-    return { dir: realpathSafe(sessionDir), source: "session-walk-up" };
-  }
-  const pkgDir = walkUpFor(cwd, "package.json");
-  if (pkgDir) {
-    return { dir: realpathSafe(pkgDir), source: "package-walk-up" };
-  }
-  return { dir: realpathSafe(cwd), source: "cwd" };
-}
-function isInsideProject(root, target) {
-  const r = realpathSafe(root);
-  let t;
-  try {
-    t = realpathSync(target);
-  } catch {
-    t = resolve(target);
-  }
-  if (!isAbsolute(r) || !isAbsolute(t)) return false;
-  const rWithSep = r.endsWith(sep) ? r : r + sep;
-  return t === r || t.startsWith(rWithSep);
-}
-
 export {
-  diagnose,
-  resolveProjectDir,
-  isInsideProject
+  diagnose
 };

package/dist/chunk-UNMH2DN4.js

@@ -0,0 +1,72 @@
+// src/project-dir.ts
+import { existsSync, realpathSync } from "fs";
+import { dirname, isAbsolute, join, resolve, sep } from "path";
+function readProjectDirArg(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--project-dir" && i + 1 < argv.length) return argv[i + 1];
+    if (a.startsWith("--project-dir=")) return a.slice("--project-dir=".length);
+  }
+  return null;
+}
+function walkUpFor(start, marker) {
+  let dir = resolve(start);
+  while (true) {
+    if (existsSync(join(dir, marker))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+function realpathSafe(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return resolve(p);
+  }
+}
+function resolveProjectDir(argv = process.argv.slice(2), env = process.env) {
+  const fromArg = readProjectDirArg(argv);
+  if (fromArg) {
+    return { dir: realpathSafe(fromArg), source: "argv" };
+  }
+  if (env.INSITUE_PROJECT_DIR) {
+    return {
+      dir: realpathSafe(env.INSITUE_PROJECT_DIR),
+      source: "INSITUE_PROJECT_DIR"
+    };
+  }
+  if (env.CLAUDE_PROJECT_DIR) {
+    return {
+      dir: realpathSafe(env.CLAUDE_PROJECT_DIR),
+      source: "CLAUDE_PROJECT_DIR"
+    };
+  }
+  const cwd = process.cwd();
+  const sessionDir = walkUpFor(cwd, ".insitue");
+  if (sessionDir && existsSync(join(sessionDir, ".insitue", "session.json"))) {
+    return { dir: realpathSafe(sessionDir), source: "session-walk-up" };
+  }
+  const pkgDir = walkUpFor(cwd, "package.json");
+  if (pkgDir) {
+    return { dir: realpathSafe(pkgDir), source: "package-walk-up" };
+  }
+  return { dir: realpathSafe(cwd), source: "cwd" };
+}
+function isInsideProject(root, target) {
+  const r = realpathSafe(root);
+  let t;
+  try {
+    t = realpathSync(target);
+  } catch {
+    t = resolve(target);
+  }
+  if (!isAbsolute(r) || !isAbsolute(t)) return false;
+  const rWithSep = r.endsWith(sep) ? r : r + sep;
+  return t === r || t.startsWith(rWithSep);
+}
+
+export {
+  resolveProjectDir,
+  isInsideProject
+};

package/dist/cloud/api.js

@@ -0,0 +1,14 @@
+import {
+  CloudApiError,
+  claimIssue,
+  listIssues,
+  releaseIssue,
+  resolveIssue
+} from "../chunk-IRPBZWNQ.js";
+export {
+  CloudApiError,
+  claimIssue,
+  listIssues,
+  releaseIssue,
+  resolveIssue
+};

package/dist/cloud/config.js

@@ -0,0 +1,10 @@
+import {
+  loadAuth,
+  loadProjectId,
+  resolveHost
+} from "../chunk-5APYM634.js";
+export {
+  loadAuth,
+  loadProjectId,
+  resolveHost
+};

package/dist/diagnose.js

@@ -0,0 +1,6 @@
+import {
+  diagnose
+} from "./chunk-SGLSPTHD.js";
+export {
+  diagnose
+};

package/dist/mcp-server.js

@@ -1,9 +1,23 @@
 #!/usr/bin/env node
 import {
-  diagnose,
   isInsideProject,
   resolveProjectDir
-} from "./chunk-U4C5CDNQ.js";
+} from "./chunk-UNMH2DN4.js";
+import {
+  diagnose
+} from "./chunk-SGLSPTHD.js";
+import {
+  CloudApiError,
+  claimIssue,
+  listIssues,
+  releaseIssue,
+  resolveIssue
+} from "./chunk-IRPBZWNQ.js";
+import {
+  loadAuth,
+  loadProjectId,
+  resolveHost
+} from "./chunk-5APYM634.js";
 
 // src/mcp-server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -699,6 +713,199 @@ server.registerTool(
     };
   }
 );
+function cloudSetup() {
+  const auth = loadAuth();
+  if (!auth.token) {
+    return {
+      error: "not_logged_in",
+      message: "Run `insitue login` (create a token at https://app.insitue.com/app/settings/developer) so InSitue can read this account's issues."
+    };
+  }
+  const projectId = loadProjectId(projectDir.dir);
+  if (!projectId) {
+    return {
+      error: "not_linked",
+      message: "Link this repo to a cloud project: `insitue link <projectId>` (find the id in your InSitue dashboard project settings)."
+    };
+  }
+  return { token: auth.token, host: resolveHost(auth), projectId };
+}
+function cloudErrPayload(e) {
+  if (e instanceof CloudApiError) {
+    return {
+      error: e.code,
+      message: e.code === "not_paid" ? `${e.message} \u2014 upgrade to a paid InSitue plan to use cloud issues.` : e.message
+    };
+  }
+  return null;
+}
+server.registerTool(
+  "list_cloud_issues",
+  {
+    description: "List open InSitue cloud issues (captured bug reports) for the linked project, so you can fix them locally. Returns id, description (note), status, and source file:line where known. Then call `claim_cloud_issue` to start one.",
+    inputSchema: {}
+  },
+  async () => {
+    const setup = cloudSetup();
+    if ("error" in setup) {
+      return {
+        content: [{ type: "text", text: JSON.stringify(setup) }]
+      };
+    }
+    const { token, host, projectId } = setup;
+    try {
+      const result = await listIssues(host, token, projectId);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ status: "ok", projectId, issues: result.issues })
+          }
+        ]
+      };
+    } catch (e) {
+      const payload = cloudErrPayload(e) ?? {
+        error: "error",
+        message: String(e)
+      };
+      return {
+        content: [{ type: "text", text: JSON.stringify(payload) }]
+      };
+    }
+  }
+);
+server.registerTool(
+  "claim_cloud_issue",
+  {
+    description: "Claim a cloud issue into local work (marks it 'fixing locally' in the dashboard) and return its repro: description, source file:line, page URL, console errors. Read the file, fix it, open a PR, then call resolve_cloud_issue.",
+    inputSchema: {
+      id: z.string().describe("The issue id from list_cloud_issues.")
+    }
+  },
+  async ({ id }) => {
+    const setup = cloudSetup();
+    if ("error" in setup) {
+      return {
+        content: [{ type: "text", text: JSON.stringify(setup) }]
+      };
+    }
+    const { token, host } = setup;
+    try {
+      const result = await claimIssue(host, token, id);
+      const bundle = result.bundle;
+      const targetObj = bundle?.["target"];
+      const sourceObj = targetObj?.["source"];
+      const runtimeObj = bundle?.["runtime"];
+      const errorsArr = (runtimeObj?.["errors"] ?? runtimeObj?.["console"])?.slice(0, 3);
+      const consoleErrors = Array.isArray(errorsArr) ? errorsArr.map((e) => typeof e === "string" ? e : JSON.stringify(e)).filter(Boolean) : [];
+      const source = typeof sourceObj?.["file"] === "string" ? {
+        file: sourceObj["file"],
+        ...typeof sourceObj["line"] === "number" ? { line: sourceObj["line"] } : {}
+      } : null;
+      const url = typeof runtimeObj?.["url"] === "string" ? runtimeObj["url"] : null;
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              status: "ok",
+              id,
+              note: result.note,
+              source,
+              url,
+              consoleErrors,
+              instructions: "Read the source file around the line, reproduce the issue from the description, make the fix, open a PR, then call resolve_cloud_issue with the PR url."
+            })
+          }
+        ]
+      };
+    } catch (e) {
+      const payload = cloudErrPayload(e) ?? {
+        error: "error",
+        message: String(e)
+      };
+      return {
+        content: [{ type: "text", text: JSON.stringify(payload) }]
+      };
+    }
+  }
+);
+server.registerTool(
+  "resolve_cloud_issue",
+  {
+    description: "Mark a claimed cloud issue resolved and attach the GitHub PR URL of your local fix. The dashboard shows it as resolved_local with the PR linked. Call after you've opened the PR.",
+    inputSchema: {
+      id: z.string().describe("The issue id."),
+      prUrl: z.string().describe("The GitHub PR URL for the fix."),
+      branch: z.string().optional().describe("The branch name (optional, inferred from the PR if omitted).")
+    }
+  },
+  async ({ id, prUrl, branch }) => {
+    const setup = cloudSetup();
+    if ("error" in setup) {
+      return {
+        content: [{ type: "text", text: JSON.stringify(setup) }]
+      };
+    }
+    const { token, host } = setup;
+    try {
+      const result = await resolveIssue(host, token, id, prUrl, branch);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ status: "ok", runId: result.runId })
+          }
+        ]
+      };
+    } catch (e) {
+      const payload = cloudErrPayload(e) ?? {
+        error: "error",
+        message: String(e)
+      };
+      return {
+        content: [{ type: "text", text: JSON.stringify(payload) }]
+      };
+    }
+  }
+);
+server.registerTool(
+  "release_cloud_issue",
+  {
+    description: "Release a previously-claimed cloud issue back to the open queue (you decided not to fix it locally).",
+    inputSchema: {
+      id: z.string().describe("The issue id to release.")
+    }
+  },
+  async ({ id }) => {
+    const setup = cloudSetup();
+    if ("error" in setup) {
+      return {
+        content: [{ type: "text", text: JSON.stringify(setup) }]
+      };
+    }
+    const { token, host } = setup;
+    try {
+      await releaseIssue(host, token, id);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ status: "ok", released: true })
+          }
+        ]
+      };
+    } catch (e) {
+      const payload = cloudErrPayload(e) ?? {
+        error: "error",
+        message: String(e)
+      };
+      return {
+        content: [{ type: "text", text: JSON.stringify(payload) }]
+      };
+    }
+  }
+);
 server.registerPrompt(
   "connect",
   {

package/dist/setup-cli.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 import {
-  diagnose,
   resolveProjectDir
-} from "./chunk-U4C5CDNQ.js";
+} from "./chunk-UNMH2DN4.js";
+import {
+  diagnose
+} from "./chunk-SGLSPTHD.js";
 
 // src/setup-cli.ts
 import {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@insitue/claude-plugin",
-  "version": "0.4.6",
+  "version": "0.5.1",
   "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",
@@ -52,8 +52,9 @@
     "node": ">=24"
   },
   "scripts": {
-    "build": "tsup src/dispatcher.ts src/mcp-server.ts src/setup-cli.ts --format esm --clean --external @modelcontextprotocol/sdk --external ws --external zod",
-    "dev": "tsup src/dispatcher.ts src/mcp-server.ts src/setup-cli.ts --format esm --watch --external @modelcontextprotocol/sdk --external ws --external zod",
+    "build": "tsup src/dispatcher.ts src/mcp-server.ts src/setup-cli.ts src/diagnose.ts src/cloud/api.ts src/cloud/config.ts --format esm --clean --external @modelcontextprotocol/sdk --external ws --external zod",
+    "dev": "tsup src/dispatcher.ts src/mcp-server.ts src/setup-cli.ts src/diagnose.ts src/cloud/api.ts src/cloud/config.ts --format esm --watch --external @modelcontextprotocol/sdk --external ws --external zod",
+    "test": "node --test \"test/*.test.mjs\"",
     "typecheck": "tsc --noEmit",
     "lint": "tsc --noEmit"
   }