@insitue/claude-plugin 0.4.4 → 0.4.6

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/commands/connect.md

@@ -77,11 +77,7 @@ Either path is fine; pick whichever your runtime has.
    question while you're between calls, answer it first (since
    the chat is responsive), then resume the loop with
    `next_pick`.
-4. If a pick comes back with `target` starting with
-   `[insitue]` (e.g. "companion disconnected"), tell the user
-   what happened in one sentence and call `next_pick` again —
-   the bridge auto-reconnects.
-5. **End the session properly.** When the user says "stop",
+4. **End the session properly.** When the user says "stop",
    "done", "quit", "thanks", "exit", "disconnect", "stop
    insitue", or anything else that clearly ends the InSitue
    session, do BOTH of these:

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

@@ -121,7 +121,7 @@ async function diagnose(projectDir) {
 
 // src/project-dir.ts
 import { existsSync as existsSync2, realpathSync } from "fs";
-import { dirname, isAbsolute, join as join2, resolve } from "path";
+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];
@@ -183,7 +183,7 @@ function isInsideProject(root, target) {
     t = resolve(target);
   }
   if (!isAbsolute(r) || !isAbsolute(t)) return false;
-  const rWithSep = r.endsWith("/") ? r : r + "/";
+  const rWithSep = r.endsWith(sep) ? r : r + sep;
   return t === r || t.startsWith(rWithSep);
 }
 

package/dist/mcp-server.js

@@ -3,7 +3,7 @@ import {
   diagnose,
   isInsideProject,
   resolveProjectDir
-} from "./chunk-RF5Q55CG.js";
+} from "./chunk-U4C5CDNQ.js";
 
 // src/mcp-server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -166,6 +166,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;
@@ -238,22 +252,18 @@ var PickBuffer = class {
   recent(limit) {
     return this.picks.slice(-limit);
   }
-  /** WS reconnects — drop pending waiters with a sentinel so claude
-   *  sees the disruption instead of hanging forever. */
-  rejectAll(reason) {
+  /** WS dropped — release pending waiters silently. They resolve to
+   *  `null` (same shape as a natural timeout), so the agent's
+   *  next_pick loop just calls again and the auto-reconnect 2s
+   *  timer heals the bridge invisibly. We previously synthesized a
+   *  fake "reconnect" pick here; that surfaced HMR / plugin-reload
+   *  blips to the user as if they were real picks and trained the
+   *  agent to stop looping. The stderr trace at the close call site
+   *  is the operator-visible signal; the agent stays quiet. */
+  dropWaiters() {
     for (const w of this.waiters) {
       clearTimeout(w.timer);
-      w.resolve({
-        id: "reconnect",
-        at: (/* @__PURE__ */ new Date()).toISOString(),
-        source: null,
-        confidence: "n/a",
-        target: `[insitue] ${reason}`,
-        selector: null,
-        userNote: null,
-        url: null,
-        componentStack: []
-      });
+      w.resolve(null);
     }
     this.waiters.length = 0;
   }
@@ -331,7 +341,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;
 }
@@ -418,8 +428,11 @@ function connectToCompanion(s) {
   });
   ws.on("close", () => {
     if (activeWs === ws) activeWs = null;
-    buffer.rejectAll("companion disconnected \u2014 restart `claude` to reconnect");
+    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", () => {
@@ -485,7 +498,7 @@ function endSession() {
 }
 var server = new McpServer({
   name: "insitue",
-  version: "0.3.0"
+  version: readPackageVersion()
 });
 server.registerTool(
   "next_pick",

package/dist/setup-cli.js

@@ -2,7 +2,7 @@
 import {
   diagnose,
   resolveProjectDir
-} from "./chunk-RF5Q55CG.js";
+} from "./chunk-U4C5CDNQ.js";
 
 // src/setup-cli.ts
 import {

package/package.json

@@ -1,14 +1,33 @@
 {
   "name": "@insitue/claude-plugin",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "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"