context-mode 1.0.120 → 1.0.122

package/scripts/heal-better-sqlite3.mjs

@@ -12,6 +12,12 @@
  *   without Visual Studio C++ tooling. We bypass that by spawning
  *   prebuild-install JS directly with `process.execPath`.
  *
+ *   On macOS / Linux, when conda's `python3` is first on PATH (very
+ *   common data-science setup), node-gyp picks it up via its `python3`
+ *   PATH fallback and fails to build on Node 26 (arm64). We defend by
+ *   pinning PYTHON + npm_config_python to a "safe" interpreter and
+ *   stripping CONDA_* keys before shelling out to npm / node-gyp (#533).
+ *
  * Layered heal:
  *   A. Spawn prebuild-install via process.execPath — bypasses PATH/MSVC.
  *   B. `npm install better-sqlite3` (re-resolves tree, NOT `npm rebuild`).
@@ -23,13 +29,151 @@
  * heal could not produce a working binding.
  *
  * @see https://github.com/mksglu/context-mode/issues/408
+ * @see https://github.com/mksglu/context-mode/issues/533
  */
 
-import { existsSync } from "node:fs";
+import { existsSync as fsExistsSync } from "node:fs";
 import { execSync, execFileSync, spawnSync } from "node:child_process";
 import { resolve } from "node:path";
 import { createRequire } from "node:module";
 
+/**
+ * Conda installation path prefixes that must NEVER be selected as the
+ * Python interpreter for node-gyp. Conda's Python ships environment
+ * activation hooks and a custom site-packages layout that breaks
+ * better-sqlite3's native build on Node 26 arm64 (#533).
+ */
+const CONDA_PATH_PATTERNS = [
+  /^\/opt\/anaconda/i,
+  /^\/opt\/miniconda/i,
+  /\/miniforge\d*\//i,
+  /\/anaconda\d*\//i,
+  /\/miniconda\d*\//i,
+  /\/\.conda\//i,
+  /\/conda\//i,
+];
+
+/**
+ * CONDA_* environment keys that must be stripped from the child env
+ * before spawning npm / node-gyp. Even after pinning PYTHON, leaving
+ * CONDA_PREFIX intact causes npm lifecycle scripts to re-activate
+ * conda's shims via .npmrc / shell rc files.
+ */
+const CONDA_ENV_KEYS = [
+  "CONDA_PREFIX",
+  "CONDA_DEFAULT_ENV",
+  "CONDA_EXE",
+  "CONDA_PROMPT_MODIFIER",
+  "CONDA_SHLVL",
+  "CONDA_PYTHON_EXE",
+];
+
+/**
+ * Decide whether a candidate python path is "safe" — i.e. not under
+ * any known conda installation prefix.
+ *
+ * @param {string} candidate - absolute path to a python interpreter
+ * @returns {boolean}
+ */
+function isSafePythonPath(candidate) {
+  if (!candidate) return false;
+  return !CONDA_PATH_PATTERNS.some((rx) => rx.test(candidate));
+}
+
+/**
+ * Resolve a "safe" python interpreter that node-gyp can drive without
+ * conda activation noise. Pure / side-effect-free / dependency-injected
+ * so the unit test can exercise it on any host.
+ *
+ * Strategy:
+ *   - darwin: prefer /usr/bin/python3 (Apple's system Python, ships
+ *     with every macOS 10.15+ install). If absent, return null.
+ *   - linux:  scan PATH for the first python3 that is not under a
+ *     conda prefix. If none, return null.
+ *   - win32:  not affected — node-gyp uses the py launcher, not PATH.
+ *
+ * @param {object} [deps]
+ * @param {string} [deps.platform] - process.platform override
+ * @param {NodeJS.ProcessEnv} [deps.env] - environment to inspect
+ * @param {(p: string) => boolean} [deps.existsSync] - fs probe override
+ * @returns {string | null}
+ */
+export function resolveSafePython({
+  platform = process.platform,
+  env = process.env,
+  existsSync = fsExistsSync,
+} = {}) {
+  if (platform === "darwin") {
+    // Apple-shipped Python is the safe choice — it is outside any
+    // conda prefix by definition and node-gyp builds against it
+    // cleanly on arm64.
+    return existsSync("/usr/bin/python3") ? "/usr/bin/python3" : null;
+  }
+  if (platform === "linux") {
+    const pathEntries = (env.PATH || "").split(":").filter(Boolean);
+    for (const dir of pathEntries) {
+      const candidate = `${dir}/python3`;
+      if (existsSync(candidate) && isSafePythonPath(candidate)) {
+        return candidate;
+      }
+    }
+    return null;
+  }
+  // Windows / other — no override needed.
+  return null;
+}
+
+/**
+ * Detect whether the current environment is conda-activated. Used to
+ * decide whether to emit the override breadcrumb (we don't spam stderr
+ * for users who never had conda interference).
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {boolean}
+ */
+function isCondaActive(env = process.env) {
+  if (env.CONDA_PREFIX || env.CONDA_DEFAULT_ENV) return true;
+  const pathEntries = (env.PATH || "").split(process.platform === "win32" ? ";" : ":");
+  return pathEntries.some((dir) => !isSafePythonPath(dir + "/python3"));
+}
+
+/**
+ * Build the child-process env for an npm/node-gyp invocation. Pins
+ * PYTHON + npm_config_python to the resolved safe interpreter, strips
+ * CONDA_* keys, and prepends /usr/bin to PATH on darwin so any
+ * downstream PATH-based python3 lookup also resolves to system python.
+ *
+ * @param {string | null} safePython - output of resolveSafePython()
+ * @param {NodeJS.ProcessEnv} [base] - starting env (defaults to process.env)
+ * @returns {NodeJS.ProcessEnv}
+ */
+function buildSafeEnv(safePython, base = process.env) {
+  const env = { ...base };
+  if (safePython) {
+    // node-gyp reads env.PYTHON (see lib/find-python.js — second slot in
+    // its `checks` array, before any PATH-based fallback).
+    env.PYTHON = safePython;
+    // npm passes npm_config_python through to node-gyp as --python,
+    // which sits in the FIRST slot of node-gyp's `checks` array — even
+    // higher priority than env.PYTHON. Set both for belt-and-suspenders.
+    env.npm_config_python = safePython;
+  }
+  // Wipe every CONDA_* key so npm lifecycle scripts can't re-shim
+  // python3 via shell activation hooks.
+  for (const key of CONDA_ENV_KEYS) {
+    delete env[key];
+  }
+  // Prepend /usr/bin on darwin so any sub-script that does `python3`
+  // unqualified still resolves to /usr/bin/python3.
+  if (process.platform === "darwin" && env.PATH) {
+    const parts = env.PATH.split(":");
+    if (parts[0] !== "/usr/bin") {
+      env.PATH = "/usr/bin:" + parts.filter((p) => p !== "/usr/bin").join(":");
+    }
+  }
+  return env;
+}
+
 /**
  * Self-heal a missing better_sqlite3.node binding.
  *
@@ -42,7 +186,26 @@ export function healBetterSqlite3Binding(pkgRoot) {
     const bindingPath = resolve(bsqRoot, "build", "Release", "better_sqlite3.node");
     const npmBin = process.platform === "win32" ? "npm.cmd" : "npm";
 
-    if (!existsSync(bsqRoot)) {
+    // ── Conda defense (#533) ─────────────────────────────────────────
+    // Resolve once up front; reuse across all child spawns. The probe
+    // is cheap (one stat call on darwin, a PATH walk on linux).
+    const safePython = resolveSafePython();
+    const condaActive = isCondaActive();
+    const childEnv = buildSafeEnv(safePython, process.env);
+
+    if (condaActive && safePython) {
+      // Emit a single breadcrumb so support requests are
+      // self-diagnosing. Best-effort: stderr may be unavailable in
+      // postinstall captured by npm logs.
+      try {
+        process.stderr.write(
+          `[context-mode] conda python detected on PATH — overriding with ` +
+          `PYTHON=${safePython} for better-sqlite3 build (#533).\n`,
+        );
+      } catch { /* stderr unavailable — proceed silently */ }
+    }
+
+    if (!fsExistsSync(bsqRoot)) {
       // ── Package itself missing (#514) ───────────────────────────────
       // npm@7+ silently drops optionalDependencies whose engines field
       // does not match the running Node version (Node 26 vs
@@ -53,6 +216,12 @@ export function healBetterSqlite3Binding(pkgRoot) {
       // install the package by name with --no-optional, which forces
       // npm to install the named package even if it would otherwise
       // be filtered out as an optional dep.
+      if (condaActive && !safePython) {
+        // Conda is active AND we couldn't find a system fallback. The
+        // install will almost certainly fail. Surface a distinct reason
+        // code so /ctx-upgrade can print conda-specific remediation.
+        return { healed: false, reason: "python-conda-blocked" };
+      }
       try {
         execFileSync(
           npmBin,
@@ -69,6 +238,7 @@ export function healBetterSqlite3Binding(pkgRoot) {
             stdio: "pipe",
             timeout: 180000,
             shell: process.platform === "win32",
+            env: childEnv,
           },
         );
       } catch {
@@ -79,10 +249,10 @@ export function healBetterSqlite3Binding(pkgRoot) {
       // Re-check after install. If npm wrote the package AND its
       // postinstall produced the binding, we're done. Otherwise fall
       // through into the binding-missing flow below.
-      if (existsSync(bindingPath)) {
+      if (fsExistsSync(bindingPath)) {
         return { healed: true, reason: "package-installed" };
       }
-      if (!existsSync(bsqRoot)) {
+      if (!fsExistsSync(bsqRoot)) {
         // npm reported success but the directory is still absent.
         // This indicates the engine-mismatch silent-skip is still in
         // effect (e.g. npm < 7 or pnpm without --shamefully-hoist).
@@ -93,7 +263,7 @@ export function healBetterSqlite3Binding(pkgRoot) {
       // install / actionable-stderr.
     }
 
-    if (existsSync(bindingPath)) {
+    if (fsExistsSync(bindingPath)) {
       return { healed: true, reason: "binding-present" };
     }
 
@@ -111,16 +281,16 @@ export function healBetterSqlite3Binding(pkgRoot) {
           resolve(pkgRoot, "node_modules", "prebuild-install", "bin.js"),
         ];
         for (const c of candidates) {
-          if (existsSync(c)) { prebuildBin = c; break; }
+          if (fsExistsSync(c)) { prebuildBin = c; break; }
         }
       }
       if (prebuildBin) {
         const r = spawnSync(
           process.execPath,
           [prebuildBin, "--target", process.versions.node, "--runtime", "node"],
-          { cwd: bsqRoot, stdio: "pipe", timeout: 120000, env: { ...process.env } },
+          { cwd: bsqRoot, stdio: "pipe", timeout: 120000, env: childEnv },
         );
-        if (r.status === 0 && existsSync(bindingPath)) {
+        if (r.status === 0 && fsExistsSync(bindingPath)) {
           return { healed: true, reason: "prebuild-install" };
         }
       }
@@ -132,21 +302,29 @@ export function healBetterSqlite3Binding(pkgRoot) {
     try {
       execSync(
         `${npmBin} install better-sqlite3 --no-package-lock --no-save --silent`,
-        { cwd: pkgRoot, stdio: "pipe", timeout: 120000, shell: true },
+        { cwd: pkgRoot, stdio: "pipe", timeout: 120000, shell: true, env: childEnv },
       );
-      if (existsSync(bindingPath)) {
+      if (fsExistsSync(bindingPath)) {
         return { healed: true, reason: "npm-install" };
       }
     } catch { /* best effort — fall through to Layer C */ }
 
     // ── Layer C: actionable stderr — give the user a real next step ──
     try {
+      const condaHint = condaActive && !safePython
+        ? "  Conda python detected on PATH and no system /usr/bin/python3 fallback found (#533).\n" +
+          "  Deactivate conda (`conda deactivate`) or install system python3, then retry.\n"
+        : "";
       process.stderr.write(
         "\n[context-mode] better-sqlite3 native binding could not be installed automatically.\n" +
         "  This is a known issue on Windows when prebuild-install is not on PATH (#408).\n" +
+        condaHint +
         "  Workaround: run `npm install better-sqlite3` from the plugin directory.\n\n",
       );
     } catch { /* stderr unavailable — give up silently */ }
+    if (condaActive && !safePython) {
+      return { healed: false, reason: "python-conda-blocked" };
+    }
     return { healed: false, reason: "manual-required" };
   } catch {
     // Outermost guard — never throw, never block the caller.

package/scripts/heal-installed-plugins.mjs

@@ -283,3 +283,114 @@ export function healPluginJsonMcpServers({ pluginRoot, pluginCacheRoot, pluginKe
 
   return { healed };
 }
+
+// ─────────────────────────────────────────────────────────────────────────
+// Issue #531 (v1.0.122) — Layer 6 heal: .mcp.json mcpServers args
+//
+// Asymmetric-heal sibling of healPluginJsonMcpServers (#523). The regression
+// that broke `.mcp.json` was commit aea633c (PR #253, 2026-04-13): the shipped
+// `.mcp.json` template at repo root used a bare relative `./start.mjs` arg.
+// Claude Code spawns the MCP child with session CWD inherited (not pluginRoot)
+// so fresh npm marketplace installs throw MODULE_NOT_FOUND on every ctx_* tool.
+// v1.0.119 added healPluginJsonMcpServers for the `.claude-plugin/plugin.json`
+// sibling but missed `.mcp.json` — same plugin, same drift class, different
+// file. This module is the asymmetric-heal sibling.
+//
+// Same regex, same placeholder, same traversal guard as #523. Only difference:
+//   - Target: `<pluginRoot>/.mcp.json` (flat shape, no `.claude-plugin/` subdir)
+//   - Structure: `.mcpServers.<pluginName>.args[]`
+//   - Additional drift shape: bare relative `./start.mjs` (the #253 regression)
+//     that healPluginJsonMcpServers's tmpdir-only check would not catch.
+//
+// Single source of truth shared by:
+//   - `start.mjs` HEAL 5b (every MCP boot)
+//   - `scripts/postinstall.mjs` (every `npm install -g context-mode`)
+//   - `src/cli.ts` upgrade() (post-bump)
+// ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * Heal `<pluginRoot>/.mcp.json` mcpServers args.
+ *
+ * Detects two drift shapes:
+ *   1. Bare relative `./start.mjs` (#253 regression — fresh-install class).
+ *   2. Tmpdir-prefixed `<...>/context-mode-upgrade-<digits>/start.mjs`
+ *      (mirrors healPluginJsonMcpServers's #523 tmpdir class).
+ * Both rewrite to the literal `${CLAUDE_PLUGIN_ROOT}/start.mjs` placeholder
+ * Claude Code resolves at load-time.
+ *
+ * @param {{
+ *   pluginRoot: string,
+ *   pluginCacheRoot: string,
+ *   pluginKey: string,
+ * }} opts
+ * @returns {HealResult}
+ */
+export function healMcpJsonArgs({ pluginRoot, pluginCacheRoot, pluginKey }) {
+  if (!pluginRoot || !pluginCacheRoot || !pluginKey) {
+    return { healed: [], skipped: "missing-args" };
+  }
+
+  // Path-traversal guard: refuse to touch a plugin root that escapes the
+  // declared cache root. Mirrors healPluginJsonMcpServers + HEAL 3.
+  const resolvedRoot = resolve(pluginRoot);
+  const cacheRootWithSep = resolve(pluginCacheRoot) + sep;
+  if (!resolvedRoot.startsWith(cacheRootWithSep)) {
+    return { healed: [], skipped: "outside-cache-root" };
+  }
+
+  // `.mcp.json` lives at pluginRoot/.mcp.json (flat), NOT under .claude-plugin/.
+  const mcpJsonPath = resolve(pluginRoot, ".mcp.json");
+  if (!existsSync(mcpJsonPath)) {
+    return { healed: [], skipped: "no-mcp-json" };
+  }
+
+  let raw;
+  try { raw = readFileSync(mcpJsonPath, "utf-8"); }
+  catch (err) { return { healed: [], error: `read-failed: ${(err && err.message) || err}` }; }
+
+  let parsed;
+  try { parsed = JSON.parse(raw); }
+  catch (err) { return { healed: [], error: `parse-failed: ${(err && err.message) || err}` }; }
+
+  const servers = parsed && parsed.mcpServers;
+  if (!servers || typeof servers !== "object") {
+    return { healed: [], skipped: "no-mcp-servers" };
+  }
+
+  // Derive our server name from pluginKey ("context-mode@context-mode" → "context-mode").
+  const ourServerName = pluginKey.split("@")[0];
+  const ours = servers[ourServerName];
+  if (!ours || typeof ours !== "object" || !Array.isArray(ours.args)) {
+    return { healed: [], skipped: "no-our-server" };
+  }
+
+  /** @type {string[]} */
+  const healed = [];
+  const before = ours.args;
+  const after = before.map((a) => {
+    if (typeof a !== "string") return a;
+    // Drift shape #1 (issue #531 / commit aea633c): bare relative `./start.mjs`.
+    // Resolved against session CWD (not pluginRoot) → MODULE_NOT_FOUND.
+    if (a === "./start.mjs" || a === "start.mjs") {
+      return PLACEHOLDER_ARG;
+    }
+    // Drift shape #2 (mirror of healPluginJsonMcpServers / #523):
+    // tmpdir-prefixed `<...>/context-mode-upgrade-<digits>/start.mjs`.
+    if (TMPDIR_UPGRADE_RE.test(a) && /[/\\]start\.mjs$/.test(a)) {
+      return PLACEHOLDER_ARG;
+    }
+    return a;
+  });
+  const changed = after.some((v, i) => v !== before[i]);
+  if (changed) {
+    ours.args = after;
+    healed.push("mcp-json-args");
+    try {
+      writeFileSync(mcpJsonPath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+    } catch (err) {
+      return { healed: [], error: `write-failed: ${(err && err.message) || err}` };
+    }
+  }
+
+  return { healed };
+}

package/scripts/postinstall.mjs

@@ -14,7 +14,7 @@ import { dirname, resolve, join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import { healBetterSqlite3Binding } from "./heal-better-sqlite3.mjs";
-import { healInstalledPlugins, healSettingsEnabledPlugins, healPluginJsonMcpServers } from "./heal-installed-plugins.mjs";
+import { healInstalledPlugins, healSettingsEnabledPlugins, healPluginJsonMcpServers, healMcpJsonArgs } from "./heal-installed-plugins.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkgRoot = resolve(__dirname, "..");
@@ -123,10 +123,26 @@ if (isGlobalInstall()) {
               healedAny = true;
             }
           } catch { /* per-entry best effort */ }
+          // v1.0.122 — Issue #531 — Layer 6: asymmetric-heal sibling for
+          // .mcp.json. The #253/aea633c regression shipped a bare `./start.mjs`
+          // arg that Claude Code resolves against session CWD (not pluginRoot)
+          // → MODULE_NOT_FOUND on every ctx_* tool. When MCP is dead, the
+          // only escape hatch is `npm install -g context-mode` whose
+          // postinstall MUST run this heal too.
+          try {
+            const r = healMcpJsonArgs({
+              pluginRoot: installPath,
+              pluginCacheRoot: cacheRoot,
+              pluginKey: "context-mode@context-mode",
+            });
+            if (r && Array.isArray(r.healed) && r.healed.length > 0) {
+              healedAny = true;
+            }
+          } catch { /* per-entry best effort */ }
         }
       }
       if (healedAny) {
-        process.stderr.write("context-mode: healed plugin.json mcpServers args (Issue #523)\n");
+        process.stderr.write("context-mode: healed mcpServers args (Issues #523 + #531)\n");
       }
     }
   } catch { /* never block install */ }
@@ -271,11 +287,22 @@ try { healBetterSqlite3Binding(pkgRoot); } catch { /* best effort — don't bloc
 // PATH lookup failure). start.mjs normalizes on every MCP boot, but normalizing
 // here too closes the gap for the very first hook fire after a fresh install
 // (before any MCP server has run).
-try {
-  const { normalizeHooksOnStartup } = await import("../hooks/normalize-hooks.mjs");
-  normalizeHooksOnStartup({
-    pluginRoot: pkgRoot,
-    nodePath: process.execPath,
-    platform: process.platform,
-  });
-} catch { /* best effort — never block install */ }
+//
+// Guard: /ctx-upgrade clones the repo to `<tmpdir>/context-mode-upgrade-<epoch>/`
+// and runs `npm install` there before `cpSync`-ing files into the real pluginRoot
+// (src/cli.ts). If we normalize here, pkgRoot is the tmpdir → hooks.json gets
+// the tmpdir's absolute paths baked in → cpSync copies that poisoned hooks.json
+// into the real plugin dir → tmpdir is later cleaned → every hook fires with
+// `MODULE_NOT_FOUND`. Detect the upgrade staging path and skip; start.mjs will
+// normalize correctly on the next MCP boot from the real pluginRoot.
+const TMPDIR_UPGRADE_RE = /[/\\]context-mode-upgrade-\d+[/\\]?$/;
+if (!TMPDIR_UPGRADE_RE.test(pkgRoot)) {
+  try {
+    const { normalizeHooksOnStartup } = await import("../hooks/normalize-hooks.mjs");
+    normalizeHooksOnStartup({
+      pluginRoot: pkgRoot,
+      nodePath: process.execPath,
+      platform: process.platform,
+    });
+  } catch { /* best effort — never block install */ }
+}