@insitue/claude-plugin 0.5.1 → 0.6.0

package/.claude-plugin/plugin.json

@@ -1,11 +1,14 @@
 {
   "name": "insitue",
-  "version": "0.4.6",
+  "version": "0.5.0",
   "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": {
       "command": "npx",
-      "args": ["-y", "@insitue/claude-plugin@latest"],
+      "args": [
+        "-y",
+        "@insitue/claude-plugin@latest"
+      ],
       "cwd": "${CLAUDE_PROJECT_DIR}"
     }
   }

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @insitue/claude-plugin
 
+## 0.6.0
+
+- **Sign in from Claude.** New `/insitue:login` command + `authenticate` / `complete_authentication` MCP tools open a browser, you approve, and a token is stored automatically — no manual paste.
+- **CLI subcommands.** `insitue login` / `insitue link` / `insitue whoami` for terminal use.
+- **Auth-aware.** `diagnose` reports authentication + linked-project state; cloud-issue errors now point at `/insitue:login`.
+
+## 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

package/commands/connect.md

@@ -142,10 +142,14 @@ both can be used in the same session.
   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)
+  - Signing in to InSitue Cloud — run `/insitue:login` (Code) for a
+    browser-based sign-in (no token paste needed), or manually generate
+    a token at https://app.insitue.com/app/settings/developer and set it
+    with `npx @insitue/claude-plugin login --token <pat>`
+  - Linking this repo to a cloud project — `/insitue:login` auto-links
+    when it can match by git remote; otherwise run
+    `npx @insitue/claude-plugin link <projectId>` (find the id in your
+    project settings)
   - A paid InSitue Cloud plan
 
 If any tool returns `error: "not_logged_in"`, `"not_linked"`, or

package/commands/login.md

@@ -0,0 +1,54 @@
+---
+description: Sign in to InSitue Cloud via browser — no token paste required. Auto-links this repo to its cloud project.
+---
+
+# /insitue:login
+
+Signs you in to InSitue Cloud using a secure browser-based flow (PKCE).
+No token paste required — approve in your browser and you're done.
+Cloud issues will become available via the claude-plugin tools once signed in.
+
+## Your behaviour
+
+1. Call `mcp__insitue__authenticate` (no arguments).
+
+2. The tool returns `{ status: "browser_opened", url, userCode, message }`.
+   Show the user:
+
+   > I've opened your browser to sign in to InSitue. Please:
+   > 1. Complete the sign-in on the consent page.
+   > 2. Confirm the page shows the pairing code: **`<userCode>`**
+   >
+   > (If your browser didn't open, visit this URL manually: `<url>`)
+
+   Do NOT proceed to step 3 until the user says they've approved or you
+   detect they're ready. Wait for the user to confirm.
+
+3. Call `mcp__insitue__complete_authentication` (no arguments).
+   This waits up to 5 minutes for the browser approval.
+
+4. On `{ status: "ok" }`:
+   - If `linked: true`: reply "Signed in as **@`<login>`** and linked to
+     project `<projectId>`. Cloud issues are now available — call
+     `/insitue:connect` or `list_cloud_issues` to get started."
+   - If `linked: false` and `projectId` is null: reply "Signed in as
+     **@`<login>`**. To link this repo to a cloud project run:
+     `npx @insitue/claude-plugin link <projectId>` (find the project id in
+     your InSitue dashboard settings)."
+
+5. On `{ status: "timeout" }`: tell the user the browser sign-in timed out
+   and they can try again by running `/insitue:login`.
+
+6. On `{ status: "error" }`: relay the `message` field and suggest running
+   `/insitue:login` again.
+
+## Notes
+
+- The pairing `userCode` is a visual confirmation only — the user does NOT
+  type it anywhere. It just proves the browser consent page corresponds to
+  THIS sign-in request.
+- Never call `complete_authentication` more than once per `authenticate` call.
+  If the user needs to retry, run `/insitue:login` from the start.
+- Cloud issue tools (`list_cloud_issues`, `claim_cloud_issue`, etc.) require
+  both a signed-in account AND a linked project. This command handles both
+  steps where possible.

package/dist/chunk-B3HSTDGI.js

@@ -0,0 +1,59 @@
+// src/cloud/config.ts
+import { homedir } from "os";
+import { join } from "path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } 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";
+}
+function saveAuth(patch) {
+  const dir = join(homedir(), ".insitue");
+  const p = join(dir, "auth.json");
+  mkdirSync(dir, { recursive: true });
+  let existing = {};
+  if (existsSync(p)) {
+    try {
+      existing = JSON.parse(readFileSync(p, "utf8"));
+    } catch {
+    }
+  }
+  const merged = { ...existing, ...patch };
+  writeFileSync(p, JSON.stringify(merged, null, 2) + "\n", {
+    encoding: "utf8",
+    mode: 384
+  });
+}
+function saveProjectLink(projectDir, projectId) {
+  const dir = join(projectDir, ".insitue");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "project.json"),
+    JSON.stringify({ projectId }, null, 2) + "\n",
+    { encoding: "utf8" }
+  );
+}
+
+export {
+  loadAuth,
+  loadProjectId,
+  resolveHost,
+  saveAuth,
+  saveProjectLink
+};

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

@@ -1,3 +1,8 @@
+import {
+  loadAuth,
+  loadProjectId
+} from "./chunk-B3HSTDGI.js";
+
 // src/diagnose.ts
 import { existsSync, readdirSync, readFileSync, statSync } from "fs";
 import { request as httpRequest } from "http";
@@ -126,7 +131,21 @@ async function diagnose(projectDir) {
     "@insitue/swc-source-attr"
   );
   const swcPluginConfigured = detectSwcPluginConfigured(projectDir.dir);
+  const auth = loadAuth();
+  const authenticated = Boolean(auth.token);
+  const login = auth.login ?? null;
+  const linkedProjectId = loadProjectId(projectDir.dir);
   const recommendations = [];
+  if (!authenticated) {
+    recommendations.push(
+      "Not authenticated \u2014 run `/insitue:login` (Code) or `npx @insitue/claude-plugin login` to sign in to InSitue Cloud."
+    );
+  }
+  if (authenticated && !linkedProjectId) {
+    recommendations.push(
+      "Signed in but no project linked \u2014 run `npx @insitue/claude-plugin link` to link this repo to a cloud project."
+    );
+  }
   if (!sdkVersion) {
     recommendations.push(
       "`@insitue/sdk` not installed in the project \u2014 `pnpm add -D @insitue/sdk`"
@@ -160,6 +179,9 @@ async function diagnose(projectDir) {
     sdkVersion,
     swcPluginVersion,
     swcPluginConfigured,
+    authenticated,
+    login,
+    linkedProjectId,
     recommendations
   };
 }

package/dist/chunk-RS3B7P4N.js

@@ -0,0 +1,211 @@
+// src/cloud/login.ts
+import { createHash, randomBytes, timingSafeEqual } from "crypto";
+import { createServer } from "http";
+import { spawn } from "child_process";
+import { platform } from "os";
+import { execFileSync } from "child_process";
+function toBase64Url(buf) {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+function genPkce() {
+  const verifier = toBase64Url(randomBytes(32));
+  const challenge = toBase64Url(
+    createHash("sha256").update(verifier).digest()
+  );
+  return { verifier, challenge };
+}
+var SUCCESS_HTML = `<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="utf-8"><title>InSitue \u2014 signed in</title>
+<style>body{font-family:system-ui,sans-serif;display:flex;align-items:center;justify-content:center;min-height:100vh;margin:0;background:#f9fafb;}
+.card{background:#fff;border-radius:12px;padding:40px 48px;text-align:center;box-shadow:0 1px 4px rgba(0,0,0,.12);}
+h1{font-size:1.4rem;margin:0 0 8px;}p{color:#6b7280;margin:0;}</style></head>
+<body><div class="card"><h1>You're signed in to InSitue</h1>
+<p>You can close this tab and return to your terminal.</p></div></body></html>`;
+var ERROR_HTML = `<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="utf-8"><title>InSitue \u2014 error</title></head>
+<body><p>Authorization failed. You may close this tab.</p></body></html>`;
+function openBrowserUrl(url) {
+  try {
+    const p = platform();
+    const [cmd, ...args] = p === "darwin" ? ["open", url] : p === "win32" ? ["cmd", "/c", `start "" "${url}"`] : ["xdg-open", url];
+    spawn(cmd, [...args], { detached: true, stdio: "ignore" }).unref();
+  } catch {
+  }
+}
+async function startLogin(opts) {
+  const { host, label, repo, openBrowser = true } = opts;
+  const { verifier, challenge } = genPkce();
+  const state = toBase64Url(randomBytes(16));
+  let resolveCode;
+  let rejectCode;
+  const codePromise = new Promise((res, rej) => {
+    resolveCode = res;
+    rejectCode = rej;
+  });
+  const server = createServer((req, res) => {
+    const raw = req.url ?? "";
+    const u = new URL(raw, "http://127.0.0.1");
+    if (u.pathname !== "/callback") {
+      res.writeHead(404).end();
+      return;
+    }
+    const errorParam = u.searchParams.get("error");
+    if (errorParam) {
+      res.writeHead(200, { "content-type": "text/html" }).end(ERROR_HTML);
+      server.close();
+      rejectCode(new Error(`authorization_denied: ${errorParam}`));
+      return;
+    }
+    const incomingState = u.searchParams.get("state") ?? "";
+    let stateOk = false;
+    try {
+      const a = Buffer.from(incomingState);
+      const b = Buffer.from(state);
+      stateOk = a.length === b.length && timingSafeEqual(a, b);
+    } catch {
+      stateOk = false;
+    }
+    if (!stateOk) {
+      res.writeHead(400, { "content-type": "text/plain" }).end("state mismatch");
+      server.close();
+      rejectCode(new Error("state mismatch"));
+      return;
+    }
+    const code = u.searchParams.get("code") ?? "";
+    res.writeHead(200, { "content-type": "text/html" }).end(SUCCESS_HTML);
+    server.close();
+    resolveCode(code);
+  });
+  await new Promise((res, rej) => {
+    server.on("error", rej);
+    server.listen(0, "127.0.0.1", () => res());
+  });
+  const addr = server.address();
+  if (!addr || typeof addr === "string") {
+    throw new Error("Failed to bind loopback server");
+  }
+  const port = addr.port;
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+  const startRes = await fetch(`${host}/api/v1/cli/authorize/start`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      code_challenge: challenge,
+      code_challenge_method: "S256",
+      redirect_uri: redirectUri,
+      ...label ? { label } : {},
+      ...repo ? { repo } : {}
+    })
+  });
+  if (!startRes.ok) {
+    server.close();
+    const text = await startRes.text().catch(() => "");
+    throw new Error(
+      `authorize/start failed: HTTP ${startRes.status} ${text}`
+    );
+  }
+  const startJson = await startRes.json();
+  const { request_id: requestId, user_code: userCode } = startJson;
+  const authorizeUrl = `${host}/cli/authorize?request_id=${encodeURIComponent(requestId)}&state=${encodeURIComponent(state)}`;
+  if (openBrowser) {
+    openBrowserUrl(authorizeUrl);
+  }
+  function cancel() {
+    try {
+      server.close();
+    } catch {
+    }
+    rejectCode(new Error("cancelled"));
+  }
+  async function wait() {
+    let timeoutHandle;
+    try {
+      const code = await Promise.race([
+        codePromise,
+        new Promise((_, rej) => {
+          timeoutHandle = setTimeout(
+            () => rej(new Error("timeout")),
+            3e5
+          );
+        })
+      ]);
+      clearTimeout(timeoutHandle);
+      const tokenRes = await fetch(`${host}/api/v1/cli/token`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ code, code_verifier: verifier, redirect_uri: redirectUri })
+      });
+      if (!tokenRes.ok) {
+        throw new Error("invalid_grant");
+      }
+      const tokenJson = await tokenRes.json();
+      return {
+        token: tokenJson.token,
+        host: tokenJson.host,
+        login: tokenJson.login,
+        projectId: tokenJson.projectId ?? null
+      };
+    } finally {
+      clearTimeout(timeoutHandle);
+      try {
+        server.close();
+      } catch {
+      }
+    }
+  }
+  return { authorizeUrl, userCode, port, wait, cancel };
+}
+function parseRemoteToOwnerName(remote) {
+  remote = remote.trim();
+  const sshMatch = remote.match(
+    /^git@[^:]+:([A-Za-z0-9._-]+\/[A-Za-z0-9._-]+?)(?:\.git)?$/
+  );
+  if (sshMatch) return sshMatch[1];
+  try {
+    const u = new URL(remote);
+    const parts = u.pathname.replace(/^\//, "").replace(/\.git$/, "").split("/");
+    if (parts.length >= 2 && parts[0] && parts[1]) {
+      return `${parts[0]}/${parts[1]}`;
+    }
+  } catch {
+  }
+  return null;
+}
+function detectGitRemote(cwd) {
+  try {
+    const out = execFileSync("git", ["-C", cwd, "remote", "get-url", "origin"], {
+      encoding: "utf8",
+      timeout: 5e3,
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    return parseRemoteToOwnerName(out);
+  } catch {
+    return null;
+  }
+}
+async function pickProjectIdForRepo(host, token, repo) {
+  const res = await fetch(`${host}/api/v1/dev/projects`, {
+    headers: { authorization: `Bearer ${token}` }
+  });
+  if (!res.ok) {
+    return { projectId: null, candidates: [] };
+  }
+  const json = await res.json();
+  const projects = json.projects ?? [];
+  const matches = projects.filter(
+    (p) => p.repo && p.repo.toLowerCase() === repo.toLowerCase()
+  );
+  return {
+    projectId: matches.length === 1 ? matches[0].id : null,
+    candidates: projects
+  };
+}
+
+export {
+  genPkce,
+  startLogin,
+  detectGitRemote,
+  pickProjectIdForRepo
+};

package/dist/cloud/config.js

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

package/dist/cloud/login.js

@@ -0,0 +1,12 @@
+import {
+  detectGitRemote,
+  genPkce,
+  pickProjectIdForRepo,
+  startLogin
+} from "../chunk-RS3B7P4N.js";
+export {
+  detectGitRemote,
+  genPkce,
+  pickProjectIdForRepo,
+  startLogin
+};

package/dist/cloud-cli.js

@@ -0,0 +1,204 @@
+import {
+  resolveProjectDir
+} from "./chunk-UNMH2DN4.js";
+import {
+  loadAuth,
+  loadProjectId,
+  resolveHost,
+  saveAuth,
+  saveProjectLink
+} from "./chunk-B3HSTDGI.js";
+import {
+  detectGitRemote,
+  pickProjectIdForRepo,
+  startLogin
+} from "./chunk-RS3B7P4N.js";
+
+// src/cloud-cli.ts
+import { hostname } from "os";
+import { resolve } from "path";
+function parseArgs(argv) {
+  const positional = [];
+  const flags = /* @__PURE__ */ new Map();
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith("--")) {
+      positional.push(a);
+      continue;
+    }
+    const eq = a.indexOf("=");
+    if (eq !== -1) {
+      flags.set(a.slice(2, eq), a.slice(eq + 1));
+    } else if (i + 1 < argv.length && !argv[i + 1].startsWith("--")) {
+      flags.set(a.slice(2), argv[++i]);
+    } else {
+      flags.set(a.slice(2), true);
+    }
+  }
+  return { positional, flags };
+}
+async function cmdLogin(argv) {
+  const { flags } = parseArgs(argv);
+  const tokenFlag = flags.get("token");
+  if (typeof tokenFlag === "string") {
+    const hostFlag = flags.get("host");
+    const auth2 = loadAuth();
+    const host2 = typeof hostFlag === "string" ? hostFlag : resolveHost(auth2);
+    saveAuth({ token: tokenFlag, host: host2 });
+    process.stdout.write(
+      `Saved token to ~/.insitue/auth.json (host: ${host2})
+`
+    );
+    return 0;
+  }
+  const auth = loadAuth();
+  const host = resolveHost(auth);
+  const projectDir = resolveProjectDir();
+  const repo = detectGitRemote(projectDir.dir);
+  process.stdout.write("Opening your browser to sign in to InSitue\u2026\n");
+  let flow;
+  try {
+    flow = await startLogin({ host, label: hostname(), ...repo ? { repo } : {} });
+  } catch (err) {
+    process.stderr.write(
+      `error: could not start login: ${err.message}
+`
+    );
+    return 1;
+  }
+  process.stdout.write(
+    `
+  Browser URL: ${flow.authorizeUrl}
+  Pairing code (confirm your browser shows this): ${flow.userCode}
+
+Waiting for approval\u2026
+`
+  );
+  let result;
+  try {
+    result = await flow.wait();
+  } catch (err) {
+    const msg = err.message ?? String(err);
+    if (msg === "timeout") {
+      process.stderr.write("error: timed out waiting for browser approval\n");
+    } else {
+      process.stderr.write(`error: ${msg}
+`);
+    }
+    return 1;
+  }
+  saveAuth({ token: result.token, host: result.host, login: result.login });
+  process.stdout.write(`Signed in as ${result.login}.
+`);
+  const projectDir2 = resolveProjectDir();
+  let linkedProjectId = result.projectId ?? null;
+  if (!linkedProjectId && repo) {
+    const { projectId } = await pickProjectIdForRepo(
+      result.host,
+      result.token,
+      repo
+    ).catch(() => ({ projectId: null, candidates: [] }));
+    linkedProjectId = projectId;
+  }
+  if (linkedProjectId) {
+    saveProjectLink(projectDir2.dir, linkedProjectId);
+    process.stdout.write(`Linked to project ${linkedProjectId}.
+`);
+  } else {
+    process.stdout.write(
+      "Could not auto-link a project. Run `npx @insitue/claude-plugin link <projectId>` manually.\n"
+    );
+  }
+  return 0;
+}
+async function cmdLink(argv) {
+  const { positional, flags } = parseArgs(argv);
+  const projectFlag = flags.get("project");
+  const projectDir = resolveProjectDir(
+    typeof projectFlag === "string" ? ["--project-dir", resolve(projectFlag)] : []
+  );
+  const auth = loadAuth();
+  if (!auth.token) {
+    process.stderr.write(
+      "error: not signed in \u2014 run `npx @insitue/claude-plugin login` first\n"
+    );
+    return 1;
+  }
+  const host = resolveHost(auth);
+  const explicitId = positional[0];
+  if (explicitId) {
+    saveProjectLink(projectDir.dir, explicitId);
+    process.stdout.write(`Linked to project ${explicitId}.
+`);
+    return 0;
+  }
+  const repo = detectGitRemote(projectDir.dir);
+  if (!repo) {
+    process.stderr.write(
+      "error: could not detect git remote origin. Pass a projectId: `npx @insitue/claude-plugin link <projectId>`\n"
+    );
+    return 1;
+  }
+  process.stdout.write(`Detecting project for repo ${repo}\u2026
+`);
+  let projectId;
+  let candidates;
+  try {
+    ({ projectId, candidates } = await pickProjectIdForRepo(
+      host,
+      auth.token,
+      repo
+    ));
+  } catch (err) {
+    process.stderr.write(`error: ${err.message}
+`);
+    return 1;
+  }
+  if (projectId) {
+    saveProjectLink(projectDir.dir, projectId);
+    process.stdout.write(`Linked to project ${projectId}.
+`);
+    return 0;
+  }
+  if (candidates.length === 0) {
+    process.stderr.write(
+      `No projects found for this account. Visit https://app.insitue.com to create one.
+`
+    );
+  } else {
+    process.stdout.write(
+      `No project matched repo "${repo}". Available projects:
+`
+    );
+    for (const p of candidates) {
+      process.stdout.write(`  ${p.id}  ${p.name}${p.repo ? `  (${p.repo})` : ""}
+`);
+    }
+    process.stdout.write(
+      `
+Run: npx @insitue/claude-plugin link <projectId>
+`
+    );
+  }
+  return 1;
+}
+function cmdWhoami() {
+  const auth = loadAuth();
+  const projectDir = resolveProjectDir();
+  const projectId = loadProjectId(projectDir.dir);
+  if (!auth.token) {
+    process.stdout.write("Not signed in.\n");
+    return 1;
+  }
+  process.stdout.write(
+    `Signed in as ${auth.login ?? "(unknown login)"}  host: ${resolveHost(auth)}
+Project: ${projectId ?? "(not linked)"}
+`
+  );
+  return 0;
+}
+export {
+  cmdLink,
+  cmdLogin,
+  cmdWhoami
+};

package/dist/diagnose.js

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

package/dist/dispatcher.js

@@ -1,10 +1,29 @@
 #!/usr/bin/env node
 
 // src/dispatcher.ts
-var SUBCOMMANDS = /* @__PURE__ */ new Set(["setup", "diagnose", "help", "--help", "-h"]);
+var CLI_SUBCOMMANDS = /* @__PURE__ */ new Set(["setup", "diagnose", "help", "--help", "-h"]);
+var CLOUD_SUBCOMMANDS = /* @__PURE__ */ new Set(["login", "link", "whoami"]);
 var first = process.argv[2];
-if (first && SUBCOMMANDS.has(first)) {
+if (first && CLI_SUBCOMMANDS.has(first)) {
   await import("./setup-cli.js");
+} else if (first && CLOUD_SUBCOMMANDS.has(first)) {
+  const { cmdLogin, cmdLink, cmdWhoami } = await import("./cloud-cli.js");
+  const rest = process.argv.slice(3);
+  let code;
+  switch (first) {
+    case "login":
+      code = await cmdLogin(rest);
+      break;
+    case "link":
+      code = await cmdLink(rest);
+      break;
+    case "whoami":
+      code = cmdWhoami();
+      break;
+    default:
+      code = 0;
+  }
+  process.exit(code);
 } else {
   await import("./mcp-server.js");
 }

package/dist/mcp-server.js

@@ -5,7 +5,7 @@ import {
 } from "./chunk-UNMH2DN4.js";
 import {
   diagnose
-} from "./chunk-SGLSPTHD.js";
+} from "./chunk-KGRPDRYH.js";
 import {
   CloudApiError,
   claimIssue,
@@ -16,8 +16,15 @@ import {
 import {
   loadAuth,
   loadProjectId,
-  resolveHost
-} from "./chunk-5APYM634.js";
+  resolveHost,
+  saveAuth,
+  saveProjectLink
+} from "./chunk-B3HSTDGI.js";
+import {
+  detectGitRemote,
+  pickProjectIdForRepo,
+  startLogin
+} from "./chunk-RS3B7P4N.js";
 
 // src/mcp-server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -25,10 +32,12 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { spawn } from "child_process";
 import { existsSync as existsSync2, readFileSync as readFileSync3, rmSync } from "fs";
 import { request as httpRequest } from "http";
+import { hostname } from "os";
 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 +397,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 +495,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;
@@ -713,19 +741,124 @@ server.registerTool(
     };
   }
 );
+var pendingLoginFlow = null;
+server.registerTool(
+  "authenticate",
+  {
+    description: "Start a browser-based InSitue sign-in (PKCE). Opens your browser to the InSitue consent page and returns a `userCode` to visually confirm. After approving in the browser, call `complete_authentication` to finish.",
+    inputSchema: {}
+  },
+  async () => {
+    const auth = loadAuth();
+    const host = resolveHost(auth);
+    const repo = detectGitRemote(projectDir.dir);
+    const flow = await startLogin({
+      host,
+      label: hostname(),
+      ...repo ? { repo } : {}
+    });
+    pendingLoginFlow = flow;
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            status: "browser_opened",
+            url: flow.authorizeUrl,
+            userCode: flow.userCode,
+            message: "Approve in your browser; confirm the code matches, then call complete_authentication."
+          })
+        }
+      ]
+    };
+  }
+);
+server.registerTool(
+  "complete_authentication",
+  {
+    description: "Complete the in-progress InSitue sign-in started by `authenticate`. Waits for the browser approval (up to 5 minutes), saves credentials, and auto-links this repo to its cloud project when possible.",
+    inputSchema: {}
+  },
+  async () => {
+    const flow = pendingLoginFlow;
+    if (!flow) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              status: "error",
+              message: "No sign-in in progress. Call authenticate first."
+            })
+          }
+        ]
+      };
+    }
+    try {
+      let result;
+      try {
+        result = await flow.wait();
+      } catch (err) {
+        const msg = err.message ?? String(err);
+        const status = msg === "timeout" ? "timeout" : "error";
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ status, message: msg })
+            }
+          ]
+        };
+      }
+      saveAuth({ token: result.token, host: result.host, login: result.login });
+      let linkedProjectId = result.projectId ?? null;
+      let linked = false;
+      if (!linkedProjectId) {
+        const repo = detectGitRemote(projectDir.dir);
+        if (repo) {
+          const { projectId } = await pickProjectIdForRepo(
+            result.host,
+            result.token,
+            repo
+          ).catch(() => ({ projectId: null, candidates: [] }));
+          linkedProjectId = projectId;
+        }
+      }
+      if (linkedProjectId) {
+        saveProjectLink(projectDir.dir, linkedProjectId);
+        linked = true;
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              status: "ok",
+              login: result.login,
+              projectId: linkedProjectId,
+              linked
+            })
+          }
+        ]
+      };
+    } finally {
+      pendingLoginFlow = null;
+    }
+  }
+);
 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."
+      message: "Not signed in to InSitue. Run `/insitue:login` (Code) to sign in via browser, or `npx @insitue/claude-plugin login` in your terminal."
     };
   }
   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)."
+      message: "This repo is not linked to an InSitue cloud project. Run `/insitue:login` (Code) to sign in and auto-link, or `npx @insitue/claude-plugin link <projectId>` in your terminal."
     };
   }
   return { token: auth.token, host: resolveHost(auth), projectId };
@@ -921,6 +1054,32 @@ server.registerPrompt(
     ]
   })
 );
+server.registerPrompt(
+  "login",
+  {
+    title: "Sign in to InSitue",
+    description: "Browser-based sign-in to InSitue Cloud via PKCE. Opens your browser, confirms a pairing code, then saves credentials and auto-links the repo."
+  },
+  () => ({
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: readPkgFile("commands/login.md") ?? loginInstructions()
+        }
+      }
+    ]
+  })
+);
+function loginInstructions() {
+  return `# Sign in to InSitue
+
+Call \`mcp__insitue__authenticate\` to start the browser sign-in flow.
+Show the user the returned URL and userCode, then call
+\`mcp__insitue__complete_authentication\` once they approve in the browser.
+Confirm the result with "Signed in as <login>" and linked project if any.`;
+}
 function readPkgFile(rel) {
   const here = dirname3(fileURLToPath2(import.meta.url));
   for (const base of [join3(here, ".."), here]) {

package/dist/setup-cli.js

@@ -4,7 +4,8 @@ import {
 } from "./chunk-UNMH2DN4.js";
 import {
   diagnose
-} from "./chunk-SGLSPTHD.js";
+} from "./chunk-KGRPDRYH.js";
+import "./chunk-B3HSTDGI.js";
 
 // src/setup-cli.ts
 import {
@@ -189,6 +190,8 @@ async function cmdDiagnose(flags2) {
     "InSitue diagnostics",
     "\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500",
     `Project:    ${report.projectDir.dir} (via ${report.projectDir.source})`,
+    `Auth:       ${tick(report.authenticated)} ${report.authenticated ? `signed in as ${report.login ?? "(unknown)"}` : "not signed in"}`,
+    `Project ID: ${report.linkedProjectId ?? "(not linked)"}`,
     `Session:    ${tick(report.hasSessionFile)} .insitue/session.json ${report.hasSessionFile ? "exists" : "missing"}`,
     `Companion:  ${tick(report.companionReachable)} ${report.companionReachable ? `reachable on port ${report.companionPort}` : "not reachable"}`,
     `@insitue/sdk:              ${report.sdkVersion ?? "(not installed)"}`,
@@ -206,7 +209,7 @@ async function cmdDiagnose(flags2) {
 }
 function cmdHelp() {
   process.stdout.write(
-    "Usage: insitue <command> [flags]\n\nCommands:\n  setup       Wire the InSitue MCP into Claude Desktop / Code\n  diagnose    Health-check the local InSitue setup\n  help        Show this message\n\nFlags (setup):\n  --desktop                  Configure Claude Desktop\n  --code                     Print the Claude Code install hint\n  --both                     Configure both\n  --project=PATH             Project directory (default: cwd)\n  --name=NAME                Desktop MCP entry name (default: insitue-<dirname>)\n  --dry-run                  Show what would change without writing\n\nFlags (diagnose):\n  --project=PATH             Project directory (default: walk-up from cwd)\n"
+    "Usage: npx @insitue/claude-plugin <command> [flags]\n\nCommands:\n  login       Sign in to InSitue Cloud via browser (PKCE)\n  link        Link this repo to an InSitue cloud project\n  whoami      Show current auth + linked project\n  setup       Wire the InSitue MCP into Claude Desktop / Code\n  diagnose    Health-check the local InSitue setup\n  help        Show this message\n\nFlags (login):\n  --token=PAT                Use a pre-created token instead of browser sign-in\n  --host=URL                 Override the InSitue host (default: https://app.insitue.com)\n\nFlags (link):\n  [projectId]                Project id to link (auto-detected from git remote if omitted)\n  --project=PATH             Project directory (default: walk-up from cwd)\n\nFlags (setup):\n  --desktop                  Configure Claude Desktop\n  --code                     Print the Claude Code install hint\n  --both                     Configure both\n  --project=PATH             Project directory (default: cwd)\n  --name=NAME                Desktop MCP entry name (default: insitue-<dirname>)\n  --dry-run                  Show what would change without writing\n\nFlags (diagnose):\n  --project=PATH             Project directory (default: walk-up from cwd)\n"
   );
   return 0;
 }

package/package.json

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

package/dist/chunk-5APYM634.js

@@ -1,31 +0,0 @@
-// 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
-};