@mxalbert/context-mode 2.0.0

package/scripts/heal-better-sqlite3.mjs

@@ -0,0 +1,430 @@
+/**
+ * Self-heal a missing better-sqlite3 native binding (#408).
+ *
+ * Single source of truth for the 3-layer heal used by both
+ * `scripts/postinstall.mjs` (install-time) and `hooks/ensure-deps.mjs`
+ * (runtime). Keeping one implementation avoids the duplicated logic the
+ * maintainer flagged on PR #410.
+ *
+ * Background:
+ *   On Windows, `npm rebuild better-sqlite3` falls through to `node-gyp`
+ *   when prebuild-install is not on cmd.exe PATH, then dies for users
+ *   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`).
+ *   C. Write actionable stderr message naming `npm install better-sqlite3`
+ *      and the Windows / #408 context.
+ *
+ * Best-effort posture: every layer is wrapped in try/catch and the
+ * function never throws. Caller will fail naturally on first DB open if
+ * heal could not produce a working binding.
+ *
+ * @see https://github.com/mxalbert1996/context-mode/issues/408
+ * @see https://github.com/mxalbert1996/context-mode/issues/533
+ *
+ * Windows VS 2026+ detection:
+ *   node-gyp has a hardcoded internal-version→year map. VS 2026 (internal
+ *   major 18) was absent from older node-gyp builds, causing "unknown version"
+ *   failures on machines that only have VS 2026 installed. Rather than
+ *   extending the map (which would break again with VS 2029, etc.), we query
+ *   vswhere's `displayName` property ("Visual Studio Community 2026") and
+ *   extract the 4-digit year with a regex. `catalog_productLineVersion` is NOT
+ *   used — it returns the internal major ("18") on VS 2026, not the year.
+ */
+
+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"));
+}
+
+/**
+ * Detect the installed Visual Studio year string via vswhere.exe.
+ *
+ * Uses the `displayName` property (e.g. "Visual Studio Community 2026")
+ * and extracts the 4-digit year with a regex. This is more reliable than
+ * `catalog_productLineVersion`, which returns the internal major version
+ * number ("18") on VS 2026 instead of the year — making it useless as a
+ * direct msvs_version value without a mapping table.
+ *
+ * `displayName` has consistently included the branded year across every
+ * VS release (2017, 2019, 2022, 2026) and will continue to do so because
+ * it is the user-visible product name Microsoft ships.
+ *
+ * Dependency-injected so unit tests can exercise all branches without
+ * spawning a real process or requiring vswhere to be present on the host.
+ *
+ * Returns null on non-Windows, when vswhere is absent, or on any error.
+ *
+ * Timeout: 15s. Cold-disk vswhere queries on HDD-backed Windows CI runners
+ * with multiple VS installs have been observed to exceed the previous 5s
+ * budget (see ARCH-REVIEW #571 Part B). 15s comfortably covers slow-disk
+ * scenarios without freezing /ctx-upgrade.
+ *
+ * Year sanity cap: the regex matches any 21st-century 4-digit year, but
+ * we additionally reject anything > currentYear+5. Corrupted vswhere
+ * output or a future MS rebrand could surface a bogus "2099"; passing
+ * that through to `npm_config_msvs_version` would fail node-gyp
+ * silently. Cap-and-null lets the caller fall back to node-gyp's own
+ * detection and we log a single stderr breadcrumb for support triage.
+ *
+ * @param {object} [deps]
+ * @param {string} [deps.platform] - process.platform override
+ * @param {(p: string) => boolean} [deps.existsSync] - fs probe override
+ * @param {(cmd: string, opts: object) => string} [deps.exec] - execSync override
+ * @param {() => number} [deps.now] - clock override for sanity cap (test seam)
+ * @returns {string | null}
+ */
+export function detectWindowsVsYear({
+  platform = process.platform,
+  existsSync = fsExistsSync,
+  exec = execSync,
+  now = () => new Date().getFullYear(),
+} = {}) {
+  if (platform !== "win32") return null;
+  try {
+    const vswhere =
+      "C:\\Program Files (x86)\\Microsoft Visual Studio\\Installer\\vswhere.exe";
+    if (!existsSync(vswhere)) return null;
+    const displayName = exec(
+      `"${vswhere}" -latest -property displayName`,
+      { encoding: "utf-8", stdio: "pipe", timeout: 15000 },
+    ).trim();
+    // "Visual Studio Community 2026" → "2026"
+    const match = displayName.match(/\b(20\d{2})\b/);
+    if (!match) return null;
+    const year = Number(match[1]);
+    const ceiling = now() + 5;
+    if (year > ceiling) {
+      // Fail LOUD, not silent: poisoning npm_config_msvs_version with
+      // a bogus year would manifest as opaque node-gyp errors deep in
+      // the rebuild. Surface a breadcrumb and return null so the caller
+      // falls back to node-gyp's own version detection.
+      try {
+        process.stderr.write(
+          `[context-mode] vswhere displayName reports VS year ${year} ` +
+          `(> ${ceiling}); ignoring as likely corrupted output. ` +
+          `Falling back to node-gyp default detection.\n`,
+        );
+      } catch { /* stderr unavailable — proceed silently */ }
+      return null;
+    }
+    return match[1];
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build the child-process env for an npm/node-gyp invocation. Pins
+ * PYTHON + npm_config_python to the resolved safe interpreter, strips
+ * CONDA_* keys, prepends /usr/bin to PATH on darwin so any downstream
+ * PATH-based python3 lookup resolves to system python, and on Windows
+ * injects npm_config_msvs_version from vswhere so node-gyp finds VS
+ * regardless of which major version is installed.
+ *
+ * @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(":");
+    }
+  }
+  // ── Windows: pin npm_config_msvs_version via vswhere (#VS2026) ───────
+  // node-gyp defaults to VS 2022. On machines that only have VS 2026 (or
+  // a later release) installed the build fails with "unknown version" or
+  // "msvs_version does not match". Querying vswhere directly gives us the
+  // correct year string without a hardcoded mapping table.
+  if (process.platform === "win32" && !env.npm_config_msvs_version) {
+    const year = detectWindowsVsYear();
+    if (year) env.npm_config_msvs_version = year;
+  }
+  return env;
+}
+
+/**
+ * Self-heal a missing better_sqlite3.node binding.
+ *
+ * @param {string} pkgRoot - the directory containing node_modules/better-sqlite3
+ * @returns {{ healed: boolean, reason?: string }}
+ */
+export function healBetterSqlite3Binding(pkgRoot) {
+  try {
+    const bsqRoot = resolve(pkgRoot, "node_modules", "better-sqlite3");
+    const bindingPath = resolve(bsqRoot, "build", "Release", "better_sqlite3.node");
+    const npmBin = process.platform === "win32" ? "npm.cmd" : "npm";
+
+    // ── 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
+      // better-sqlite3@12.x → silent skip, package never written).
+      // Even after promoting the package back to dependencies, an
+      // existing install where the package directory was previously
+      // skipped will still have an empty slot. Take ownership and
+      // 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,
+          [
+            "install",
+            "better-sqlite3",
+            "--no-optional",
+            "--no-save",
+            "--no-audit",
+            "--no-fund",
+          ],
+          {
+            cwd: pkgRoot,
+            stdio: "pipe",
+            timeout: 180000,
+            shell: process.platform === "win32",
+            env: childEnv,
+          },
+        );
+      } catch {
+        // Install failed — surface the cause via the manual-required
+        // exit so the caller (cli.ts upgrade verifier) reports it.
+        return { healed: false, reason: "package-missing" };
+      }
+      // 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 (fsExistsSync(bindingPath)) {
+        return { healed: true, reason: "package-installed" };
+      }
+      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).
+        return { healed: false, reason: "package-missing" };
+      }
+      // Package present but binding still missing — recurse into
+      // the existing 3-layer heal that owns prebuild-install / npm
+      // install / actionable-stderr.
+    }
+
+    if (fsExistsSync(bindingPath)) {
+      return { healed: true, reason: "binding-present" };
+    }
+
+    // ── Layer A: spawn prebuild-install directly via process.execPath ──
+    // Bypasses cmd.exe PATH and MSVC requirement.
+    try {
+      let prebuildBin = null;
+      try {
+        const req = createRequire(resolve(bsqRoot, "package.json"));
+        prebuildBin = req.resolve("prebuild-install/bin");
+      } catch { /* fall through to manual walk */ }
+      if (!prebuildBin) {
+        const candidates = [
+          resolve(bsqRoot, "node_modules", "prebuild-install", "bin.js"),
+          resolve(pkgRoot, "node_modules", "prebuild-install", "bin.js"),
+        ];
+        for (const c of candidates) {
+          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: childEnv },
+        );
+        if (r.status === 0 && fsExistsSync(bindingPath)) {
+          return { healed: true, reason: "prebuild-install" };
+        }
+      }
+    } catch { /* best effort — try Layer B */ }
+
+    // ── Layer B: `npm install better-sqlite3` — NOT `npm rebuild` ──
+    // Re-resolves tree and re-runs prebuild-install via the package's
+    // own install script. Avoids the rebuild → node-gyp fall-through.
+    try {
+      execSync(
+        `${npmBin} install better-sqlite3 --no-package-lock --no-save --silent`,
+        { cwd: pkgRoot, stdio: "pipe", timeout: 120000, shell: true, env: childEnv },
+      );
+      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.
+    return { healed: false, reason: "manual-required" };
+  }
+}