backthread 0.3.1 → 0.4.0

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "backthread",
   "displayName": "Backthread",
   "description": "Backthread helps you understand your codebase while AI ships features. It captures the why behind every Claude Code session so you can ask \"how does X work?\" without digging through PRs.",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "author": {
     "name": "Backthread"
   },

package/dist-bundle/backthread.js

@@ -7746,7 +7746,7 @@ async function maybeNudge(status, repo, sessionId, deps = {}) {
 
 // src/firstRun.ts
 import { join as join9 } from "node:path";
-import { readFile as readFile7, writeFile as writeFile6, mkdir as mkdir6, chmod as chmod4 } from "node:fs/promises";
+import { readFile as readFile7, writeFile as writeFile6, mkdir as mkdir6, chmod as chmod5 } from "node:fs/promises";
 
 // src/install.ts
 import { readFile as readFile6, writeFile as writeFile5, mkdir as mkdir5 } from "node:fs/promises";
@@ -8211,7 +8211,7 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { homedir as homedir4 } from "node:os";
 import { join as join7, dirname as dirname3 } from "node:path";
-import { readFile as readFile5, writeFile as writeFile4, mkdir as mkdir4 } from "node:fs/promises";
+import { readFile as readFile5, writeFile as writeFile4, mkdir as mkdir4, chmod as chmod4 } from "node:fs/promises";
 var execFileP = promisify(execFile);
 var MCP_COMMAND = "npx";
 var MCP_ARGS = ["-y", "backthread", "mcp"];
@@ -8325,28 +8325,97 @@ args = [${MCP_ARGS.map((a) => `"${a}"`).join(", ")}]
 }
 async function installCursor(home, deps) {
   const doRead = deps.readFileImpl ?? ((p) => readFile5(p, "utf8"));
+  const nodeBinDir = deps.nodeBinDir ?? dirname3(process.execPath);
   const writes = [];
+  const scriptDir = join7(home, ".cursor", "hooks");
+  const captureScriptPath = join7(scriptDir, "backthread-capture.sh");
+  const mcpScriptPath = join7(scriptDir, "backthread-mcp.sh");
+  writes.push(
+    await writeCursorScript(
+      deps,
+      captureScriptPath,
+      cursorWrapperScript(nodeBinDir, "capture --from-hook --agent cursor --detach")
+    )
+  );
+  writes.push(await writeCursorScript(deps, mcpScriptPath, cursorWrapperScript(nodeBinDir, "mcp")));
   const mcpPath = join7(home, ".cursor", "mcp.json");
   const mcpCurrent = await loadJsonObject(doRead, mcpPath);
-  const m = withMcpServer(mcpCurrent);
+  const m = withCursorMcpServer(mcpCurrent, mcpScriptPath);
   if (m.changed) await writeJson(deps, mcpPath, m.next);
   writes.push({ path: mcpPath, wrote: m.changed });
   const hooksPath = join7(home, ".cursor", "hooks.json");
   const hooksCurrent = await loadJsonObject(doRead, hooksPath);
-  const c = withCursorStopHook(hooksCurrent);
+  const c = withCursorStopHook(hooksCurrent, captureScriptPath);
   if (c.changed) await writeJson(deps, hooksPath, c.next);
   writes.push({ path: hooksPath, wrote: c.changed });
   return writes;
 }
-function withCursorStopHook(settings) {
-  const command = hookCommand("cursor");
+function shSingleQuote(s) {
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+function cursorWrapperScript(nodeBinDir, backthreadArgs) {
+  return [
+    "#!/bin/sh",
+    "# Backthread wrapper for Cursor \u2014 generated by `backthread install --agent cursor` (ARP-692).",
+    "#",
+    "# Cursor is a GUI app and does NOT inherit your login/nvm shell PATH, so a bare",
+    "# `npx`/`node` here may be missing or resolve to a too-old system Node (Backthread",
+    "# needs Node >= 22.18). Prepend the Node bin dir detected at install time so capture",
+    "# and the MCP server always run on a new-enough Node. (npx's `#!/usr/bin/env node`",
+    "# shebang re-resolves node from PATH, so pinning PATH \u2014 not just an absolute npx \u2014 is",
+    "# what actually guarantees the right Node.)",
+    "#",
+    "# If your Node later moves (a new nvm version, an uninstall), re-run:",
+    "#   npx backthread install --agent cursor",
+    `NODE_BIN_DIR=${shSingleQuote(nodeBinDir)}`,
+    'if [ -d "$NODE_BIN_DIR" ]; then',
+    '  PATH="$NODE_BIN_DIR:$PATH"',
+    "  export PATH",
+    "fi",
+    `exec npx -y backthread ${backthreadArgs}`
+  ].join("\n") + "\n";
+}
+async function writeCursorScript(deps, path, content) {
+  const doRead = deps.readFileImpl ?? ((p) => readFile5(p, "utf8"));
+  const doChmod = deps.chmodImpl ?? ((p, mode) => chmod4(p, mode));
+  let existing = null;
+  try {
+    existing = await doRead(path);
+  } catch (e) {
+    if (!isNotFound2(e)) throw e;
+  }
+  if (existing === content) {
+    await doChmod(path, 493).catch(() => {
+    });
+    return { path, wrote: false };
+  }
+  const doMkdir = deps.mkdirImpl ?? (async (d) => void await mkdir4(d, { recursive: true }));
+  const doWrite = deps.writeFileImpl ?? ((p, d) => writeFile4(p, d));
+  await doMkdir(dirname3(path));
+  await doWrite(path, content);
+  await doChmod(path, 493);
+  return { path, wrote: true };
+}
+function withCursorMcpServer(settings, mcpScriptPath) {
+  const mcpServers = asObject(settings.mcpServers);
+  const desired = { command: mcpScriptPath, args: [] };
+  if (JSON.stringify(mcpServers.backthread) === JSON.stringify(desired)) {
+    return { next: settings, changed: false };
+  }
+  mcpServers.backthread = desired;
+  return { next: { ...settings, mcpServers }, changed: true };
+}
+function withCursorStopHook(settings, captureScriptPath) {
+  const legacyInline = hookCommand("cursor");
   const hooks = asObject(settings.hooks);
   const stop = Array.isArray(hooks.stop) ? [...hooks.stop] : [];
-  const present = stop.some((h) => h?.command === command);
+  const hadDesired = stop.some((h) => h?.command === captureScriptPath);
+  const next = stop.filter((h) => h?.command !== legacyInline);
+  const removedLegacy = next.length !== stop.length;
+  if (!hadDesired) next.push({ command: captureScriptPath });
   const hasVersion = typeof settings.version === "number";
-  if (present && hasVersion) return { next: settings, changed: false };
-  if (!present) stop.push({ command });
-  hooks.stop = stop;
+  if (hadDesired && !removedLegacy && hasVersion) return { next: settings, changed: false };
+  hooks.stop = next;
   return { next: { ...settings, version: hasVersion ? settings.version : 1, hooks }, changed: true };
 }
 function cursorDeeplink() {
@@ -8502,6 +8571,67 @@ function rewriteLegacyCommand(group) {
   });
   return changed ? { ...group, hooks: nextInner } : group;
 }
+function stripSessionEndHook(settings) {
+  const hooksVal = settings.hooks;
+  if (!hooksVal || typeof hooksVal !== "object" || Array.isArray(hooksVal)) return null;
+  const seVal = hooksVal.SessionEnd;
+  if (!Array.isArray(seVal)) return null;
+  let changed = false;
+  const nextSessionEnd = [];
+  for (const group of seVal) {
+    const inner = group?.hooks;
+    if (!group || typeof group !== "object" || !Array.isArray(inner)) {
+      nextSessionEnd.push(group);
+      continue;
+    }
+    const keptInner = inner.filter((h) => {
+      const cmd = h?.command;
+      const isOurs = typeof cmd === "string" && OUR_HOOK_COMMANDS.has(cmd);
+      if (isOurs) changed = true;
+      return !isOurs;
+    });
+    if (keptInner.length === 0) continue;
+    if (keptInner.length !== inner.length) {
+      nextSessionEnd.push({ ...group, hooks: keptInner });
+    } else {
+      nextSessionEnd.push(group);
+    }
+  }
+  if (!changed) return null;
+  const hooks = { ...hooksVal };
+  if (nextSessionEnd.length === 0) delete hooks.SessionEnd;
+  else hooks.SessionEnd = nextSessionEnd;
+  const next = { ...settings, hooks };
+  if (Object.keys(hooks).length === 0) delete next.hooks;
+  return next;
+}
+async function unregisterProjectHook(cwd, deps = {}) {
+  const doReadFile = deps.readFileImpl ?? ((p) => readFile6(p, "utf8"));
+  const doWriteFile = deps.writeFileImpl ?? ((p, d) => writeFile5(p, d));
+  const settingsPath = join8(cwd, ".claude", "settings.json");
+  let raw;
+  try {
+    raw = await doReadFile(settingsPath);
+  } catch (e) {
+    if (isNotFound3(e)) return { stripped: false, path: settingsPath };
+    throw e;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(
+      `${settingsPath} exists but is not valid JSON \u2014 refusing to modify it. Remove the stale SessionEnd hook manually if present.`
+    );
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`${settingsPath} is not a JSON object \u2014 refusing to modify it.`);
+  }
+  const stripped = stripSessionEndHook(parsed);
+  if (stripped === null) return { stripped: false, path: settingsPath };
+  await doWriteFile(settingsPath, JSON.stringify(stripped, null, 2) + "\n");
+  return { stripped: true, path: settingsPath };
+}
 async function runInstall(opts = {}, deps = {}) {
   const env = opts.env ?? process.env;
   const log = opts.log ?? ((m) => console.error(m));
@@ -8551,6 +8681,7 @@ Backthread is set up for ${targetAgent}. New sessions are captured automatically
     return { exitCode: exitCode2, authed, hookRegistered: agentResult !== null, backfill: null, agentResult };
   }
   let hookRegistered = false;
+  let projectHookMigrated = false;
   if (opts.skipHook) {
     log("[2/3] Hook: skipped (registered by the plugin manifest).");
   } else {
@@ -8564,6 +8695,17 @@ Backthread is set up for ${targetAgent}. New sessions are captured automatically
       log(`[2/3] Hook: not registered \u2014 ${e.message}`);
       log("      You can add it manually (see the README \u203A Registering the hook).");
     }
+    if (hookRegistered) {
+      try {
+        const { stripped, path } = await unregisterProjectHook(cwd, deps);
+        if (stripped) {
+          projectHookMigrated = true;
+          log(`      Migrated: removed the stale project-scope SessionEnd hook from ${path} (it now lives at user scope).`);
+        }
+      } catch (e) {
+        log(`      Note: left the project-scope settings.json untouched \u2014 ${e.message}`);
+      }
+    }
   }
   let backfill = null;
   if (opts.skipBackfill) {
@@ -8580,7 +8722,7 @@ Backthread is set up for ${targetAgent}. New sessions are captured automatically
   }
   log("\nBackthread is set up. New sessions are captured automatically when they end.");
   const exitCode = !authed && !opts.skipAuth ? 1 : 0;
-  return { exitCode, authed, hookRegistered, backfill, agentResult: null };
+  return { exitCode, authed, hookRegistered, backfill, agentResult: null, projectHookMigrated };
 }
 
 // src/entry.ts
@@ -8761,11 +8903,11 @@ async function updateFirstRunState(patch, env = process.env) {
     const next = { ...current, ...patch };
     const dir = configDir(env);
     await mkdir6(dir, { recursive: true, mode: DIR_MODE });
-    await chmod4(dir, DIR_MODE).catch(() => {
+    await chmod5(dir, DIR_MODE).catch(() => {
     });
     const path = firstRunStatePath(env);
     await writeFile6(path, JSON.stringify(next) + "\n", { mode: CONFIG_MODE });
-    await chmod4(path, CONFIG_MODE).catch(() => {
+    await chmod5(path, CONFIG_MODE).catch(() => {
     });
   } catch {
   }
@@ -9101,7 +9243,7 @@ async function persistDerived(decisions, repo, config2, decidedAt, ctx) {
 // src/fromHook.ts
 import { spawn as spawn2 } from "node:child_process";
 import { join as join10 } from "node:path";
-import { readFile as readFile9, writeFile as writeFile7, mkdir as mkdir7, chmod as chmod5 } from "node:fs/promises";
+import { readFile as readFile9, writeFile as writeFile7, mkdir as mkdir7, chmod as chmod6 } from "node:fs/promises";
 var KNOWN_AGENTS = /* @__PURE__ */ new Set([
   "claude-code",
   "codex",
@@ -9174,11 +9316,11 @@ async function writeState2(state, env) {
   try {
     const dir = configDir(env);
     await mkdir7(dir, { recursive: true, mode: DIR_MODE });
-    await chmod5(dir, DIR_MODE).catch(() => {
+    await chmod6(dir, DIR_MODE).catch(() => {
     });
     const path = captureStatePath(env);
     await writeFile7(path, JSON.stringify(state) + "\n", { mode: CONFIG_MODE });
-    await chmod5(path, CONFIG_MODE).catch(() => {
+    await chmod6(path, CONFIG_MODE).catch(() => {
     });
   } catch {
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backthread",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Backthread helps you understand your codebase while AI ships features. The CLI captures the why behind every AI session and lets you ask how your codebase works, right from the terminal.",
   "license": "MIT",
   "author": "Backthread",