@insitue/claude-plugin 0.4.5 → 0.5.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "insitue",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "Drive a Claude Code session from the InSitue browser overlay. Pick an element in your app, claude reads the file and proposes the edit.",
   "mcpServers": {
     "insitue": {

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# @insitue/claude-plugin
+
+## 0.4.6
+
+- **Fix (Windows):** `isInsideProject` now uses `path.sep` instead of a
+  hardcoded `/`, so the project-dir sandbox check actually holds on
+  Windows. Previously every `apply_edit` / `write_file` call would be
+  rejected on Windows because `C:\proj/` never matches `C:\proj\file`.
+- **Fix:** the MCP server's reported version (`McpServer({ version })`)
+  is now read from `package.json` at startup, eliminating the stale
+  `"0.3.0"` literal that drifted from the actual 0.4.x releases.
+- **Fix:** stderr message on spawn-timeout now correctly reports "8 s"
+  instead of "5 s" (the loop ceiling is 8 s).
+- **Docs:** rewrote the README's Architecture section to match the
+  current tool surface (next_pick, list_recent_picks, start_session,
+  end_session, diagnose, read_file, apply_edit, write_file) — the
+  previous text claimed only two tools and said "the bridge never
+  writes files" (no longer true on Desktop).
+- **Docs:** added Stability, Versioning, and Security sections to the
+  README.
+- **Docs:** swapped a leaked internal CMS-slug example
+  (`briefings:hairspray-chipping:body`) for a generic one in
+  `mcp-server.ts` JSDoc.
+- **Docs:** clarified `project-dir.ts` JSDoc — said "three forms",
+  listed six.
+- **Metadata:** added `keywords`, `homepage`, `bugs` to `package.json`;
+  included `CHANGELOG.md` in the published tarball.
+- Bumped `.claude-plugin/plugin.json` version in lockstep.
+
+## 0.4.x and earlier
+
+Pre-launch versions — see [git history](https://github.com/InSitue/insitue/commits/main/packages/claude-plugin)
+for changes. Real entries start at the next minor bump.

package/README.md

@@ -237,32 +237,83 @@ extensively to stderr; claude surfaces them in the transcript.
 
 The plugin is a stdio MCP server that:
 
-1. On startup, reads `${CLAUDE_PROJECT_DIR}/.insitue/session.json`
-   to find a running companion. If one's alive, reuse it.
-2. Otherwise spawns `npx -y @insitue/companion@latest dev` as a
-   child process, polls for the new `session.json` to appear,
-   then connects.
-3. Subscribes to the companion's WS broadcast channel. Every
-   pick the browser sends arrives here.
-4. Exposes two MCP tools:
-   - `insitue__next_pick` — long-polls until a pick lands
-     (default 5 min). Returns target + source + screenshot +
-     userNote.
-   - `insitue__list_recent_picks` — buffered picks since the
-     server started.
+1. On startup, resolves the project dir (`--project-dir` argv →
+   `INSITUE_PROJECT_DIR` env → `CLAUDE_PROJECT_DIR` env →
+   walk-up for `.insitue/session.json` → walk-up for
+   `package.json` → cwd).
+2. Reads `.insitue/session.json` to find a running companion.
+   If one's alive (PID up + port responsive), reuse it.
+3. Otherwise spawns `npx -y @insitue/companion@latest dev` as a
+   child process, polls for the new `session.json` to appear
+   (8 s ceiling), then connects.
+4. Subscribes to the companion's WS broadcast channel. Every
+   pick the browser sends arrives here, gets summarised, and
+   buffers (cap: 32) for the polling loop to pull.
 5. Auto-reconnects if the companion restarts (HMR, manual
    stop). The widget reconnects too.
 6. Cleans up on `process.exit` / `SIGTERM` — kills only the
    companion it spawned, leaves user-started companions
    untouched.
 
-The bridge **never writes files**. Claude does, via its native
-Edit tool. This keeps the InSitue trust boundary clean: the
-companion is the only thing that touches fs, and only after
-the user has approved a proposal in the terminal.
+### MCP tools exposed
+
+| Tool | Purpose |
+|---|---|
+| `next_pick` | Long-poll for the next browser pick (default 25 s; max 30 min). |
+| `list_recent_picks` | Up to N buffered picks since the MCP server started. |
+| `start_session` | Returns the operating instructions + current state. Desktop entry point. |
+| `end_session` | Cleanly disconnect: close WS, suppress reconnect, kill spawned companion, drop session file. |
+| `diagnose` | Health check — companion reachability, SDK + SWC-plugin versions + wiring, recommendations. |
+| `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. |
+
+All file tools resolve paths against the project dir and refuse
+anything that resolves outside it (realpath-checked, so `..` games
+are blocked). On Claude Code the agent prefers its native tools;
+the project-scoped ones exist primarily for Claude Desktop, which
+has no built-in file tools.
+
+### Trust boundary
+
+The companion is the only process that holds the user's edit
+authority — it spawns from the project dir, writes only inside it,
+and is gated by the WS handshake's loopback bind + per-session
+token. The MCP bridge here is a read-side subscriber that
+broadcasts picks into the chat. Writes still require the human
+in the terminal to say "yes" before the agent calls `apply_edit`
+(or its native equivalent).
 
 ---
 
+## Stability
+
+The plugin's MCP tool surface is what consumers depend on. We
+treat tool name/argument changes as breaking; descriptions and
+internal behaviour can evolve in patch releases.
+
+## Versioning
+
+- **Major** — backwards-incompatible changes to the MCP tool
+  surface (renames, removed tools, argument shape changes), or
+  changes that require the user to re-run `setup`.
+- **Minor** — additive tools, optional new arguments, new env
+  vars, new CLI subcommands.
+- **Patch** — bug fixes, docs, internal refactors, version-pin
+  bumps for transitive deps.
+
+The plugin pins the InSitue WS protocol version (`5` at the time
+of writing) against the companion. A mismatch is rejected at the
+handshake rather than silently degraded.
+
+## Security
+
+Report vulnerabilities privately — see [SECURITY.md](../../SECURITY.md)
+in the repo root. Especially relevant for this package: anything
+that lets the bridge accept frames over a non-loopback bind, that
+lets `apply_edit` / `write_file` escape the resolved project dir,
+or that leaks the session token outside the local machine.
+
 ## License
 
 MIT. Same as the rest of InSitue.

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-RF5Q55CG.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 } 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("/") ? r : r + "/";
-  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-RF5Q55CG.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";
@@ -166,6 +180,20 @@ function loadInstructions() {
 }
 
 // src/mcp-server.ts
+function readPackageVersion() {
+  const here = dirname3(fileURLToPath2(import.meta.url));
+  for (const base of [join3(here, ".."), here, join3(here, "..", "..")]) {
+    const p = join3(base, "package.json");
+    if (existsSync2(p)) {
+      try {
+        const v = JSON.parse(readFileSync3(p, "utf8")).version;
+        if (v) return v;
+      } catch {
+      }
+    }
+  }
+  return "unknown";
+}
 var MAX_BUFFERED_PICKS = 32;
 var NEXT_PICK_DEFAULT_TIMEOUT_MS = 25 * 1e3;
 var NEXT_PICK_MAX_TIMEOUT_MS = 30 * 60 * 1e3;
@@ -327,7 +355,7 @@ async function ensureCompanion(projectDir2) {
     await new Promise((r) => setTimeout(r, 200));
   }
   process.stderr.write(
-    "[insitue-mcp] companion didn't come up in 5s \u2014 see [companion] / [companion err] above\n"
+    "[insitue-mcp] companion didn't come up in 8s \u2014 see [companion] / [companion err] above\n"
   );
   return null;
 }
@@ -484,7 +512,7 @@ function endSession() {
 }
 var server = new McpServer({
   name: "insitue",
-  version: "0.3.0"
+  version: readPackageVersion()
 });
 server.registerTool(
   "next_pick",
@@ -685,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-RF5Q55CG.js";
+} from "./chunk-UNMH2DN4.js";
+import {
+  diagnose
+} from "./chunk-SGLSPTHD.js";
 
 // src/setup-cli.ts
 import {

package/package.json

@@ -1,14 +1,33 @@
 {
   "name": "@insitue/claude-plugin",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "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",
+    "claude",
+    "mcp",
+    "claude-code",
+    "claude-desktop",
+    "visual-feedback",
+    "browser-overlay"
+  ],
   "license": "MIT",
+  "homepage": "https://www.insitue.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/InSitue/insitue.git",
+    "directory": "packages/claude-plugin"
+  },
+  "bugs": {
+    "url": "https://github.com/InSitue/insitue/issues"
+  },
   "type": "module",
   "files": [
     ".claude-plugin",
     "commands",
     "dist",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "exports": {
     ".": "./dist/mcp-server.js"
@@ -33,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"
   }