context-mode 1.0.111 → 1.0.113

package/build/cli.js

@@ -20,6 +20,22 @@ import { resolve, dirname, join } from "node:path";
 import { tmpdir, devNull, homedir } from "node:os";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { detectRuntimes, getRuntimeSummary, hasBunRuntime, getAvailableLanguages, } from "./runtime.js";
+import { getHookScriptPaths } from "./util/hook-config.js";
+import { resolveClaudeConfigDir } from "./util/claude-config.js";
+// Private 16-LOC copy of browserOpenArgv. Canonical version lives in src/server.ts;
+// duplicated here so the cli bundle does not pull server.ts top-level boot side effects.
+// Keep in sync — pure data, no I/O.
+function browserOpenArgv(url, platform) {
+    if (platform === "darwin")
+        return [{ cmd: "open", args: [url] }];
+    if (platform === "win32") {
+        return [{ cmd: "cmd", args: ["/c", "start", "", url] }];
+    }
+    return [
+        { cmd: "xdg-open", args: [url] },
+        { cmd: "sensible-browser", args: [url] },
+    ];
+}
 // ── Adapter imports ──────────────────────────────────────
 import { detectPlatform, getAdapter } from "./adapters/detect.js";
 /* -------------------------------------------------------
@@ -55,6 +71,7 @@ const HOOK_MAP = {
     "codex": {
         pretooluse: "hooks/codex/pretooluse.mjs",
         posttooluse: "hooks/codex/posttooluse.mjs",
+        precompact: "hooks/codex/precompact.mjs",
         sessionstart: "hooks/codex/sessionstart.mjs",
         userpromptsubmit: "hooks/codex/userpromptsubmit.mjs",
         stop: "hooks/codex/stop.mjs",
@@ -104,7 +121,11 @@ if (args[0] === "doctor") {
     doctor().then((code) => process.exit(code));
 }
 else if (args[0] === "upgrade") {
-    upgrade();
+    upgrade().catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        p.log.error(color.red(message));
+        process.exit(1);
+    });
 }
 else if (args[0] === "hook") {
     hookDispatch(args[1], args[2]);
@@ -151,33 +172,20 @@ export function npmExec(command, opts = {}) {
 export function openInBrowser(url, platform = process.platform, runner = nodeExecFile) {
     const opts = { stdio: "ignore" };
     const hint = () => console.error(`\nCould not auto-open browser. Open manually: ${url}`);
-    try {
-        if (platform === "darwin") {
-            runner("open", [url], opts);
-        }
-        else if (platform === "win32") {
-            // `start` is a cmd.exe builtin; first arg after `start` is the
-            // window title — pass empty so the URL isn't consumed as a title.
-            runner("cmd", ["/c", "start", "", url], opts);
-        }
-        else {
-            // linux/bsd: try xdg-open, fall back to sensible-browser.
-            try {
-                runner("xdg-open", [url], opts);
-            }
-            catch {
-                try {
-                    runner("sensible-browser", [url], opts);
-                }
-                catch {
-                    hint();
-                }
-            }
+    // Platform→argv mapping is canonical in src/server.ts; mirrored privately
+    // above to avoid pulling server boot side effects into the cli bundle.
+    const attempts = browserOpenArgv(url, platform);
+    let opened = false;
+    for (const { cmd, args } of attempts) {
+        try {
+            runner(cmd, args, opts);
+            opened = true;
+            break;
         }
+        catch { /* try next fallback */ }
     }
-    catch {
+    if (!opened)
         hint();
-    }
 }
 function defaultPluginRoot() {
     const __filename = fileURLToPath(import.meta.url);
@@ -331,22 +339,35 @@ async function doctor() {
         if (result.status === "pass") {
             p.log.success(color.green(`${result.check}: PASS`) + ` — ${result.message}`);
         }
+        else if (result.status === "warn") {
+            p.log.warn(color.yellow(`${result.check}: WARN`) +
+                ` — ${result.message}` +
+                (result.fix ? color.dim(`\n  Run: ${result.fix}`) : ""));
+        }
         else {
             p.log.error(color.red(`${result.check}: FAIL`) +
                 ` — ${result.message}` +
                 (result.fix ? color.dim(`\n  Run: ${result.fix}`) : ""));
         }
     }
-    // Hook script exists
-    p.log.step("Checking hook script...");
-    const hookScriptPath = resolve(pluginRoot, "hooks", "pretooluse.mjs");
-    try {
-        accessSync(hookScriptPath, constants.R_OK);
-        p.log.success(color.green("Hook script exists: PASS") + color.dim(` — ${hookScriptPath}`));
+    // Hook scripts exist
+    p.log.step("Checking hook scripts...");
+    const hookScriptPaths = getHookScriptPaths(adapter, pluginRoot);
+    if (hookScriptPaths.length === 0) {
+        p.log.success(color.green("Hook scripts: PASS") + color.dim(" — no direct .mjs script paths to verify"));
     }
-    catch {
-        p.log.error(color.red("Hook script exists: FAIL") +
-            color.dim(` — not found at ${hookScriptPath}`));
+    else {
+        for (const scriptPath of hookScriptPaths) {
+            const absolutePath = resolve(pluginRoot, scriptPath);
+            try {
+                accessSync(absolutePath, constants.R_OK);
+                p.log.success(color.green("Hook script exists: PASS") + color.dim(` — ${absolutePath}`));
+            }
+            catch {
+                p.log.error(color.red("Hook script exists: FAIL") +
+                    color.dim(` — not found at ${absolutePath}`));
+            }
+        }
     }
     // Plugin registration — adapter-aware
     p.log.step(`Checking ${adapter.name} plugin registration...`);
@@ -568,7 +589,9 @@ async function upgrade() {
     // commit and CC keeps reporting the old version even after our cache dir is
     // updated — users then see "ctx-upgrade succeeded" but nothing actually
     // changed at the plugin-system level.
-    const marketplaceDir = resolve(homedir(), ".claude", "plugins", "marketplaces", "context-mode");
+    // Issue #460 round-3: route through resolveClaudeConfigDir so users who
+    // relocate their CC config root keep the marketplace clone in the same tree.
+    const marketplaceDir = resolve(resolveClaudeConfigDir(), "plugins", "marketplaces", "context-mode");
     if (existsSync(join(marketplaceDir, ".git"))) {
         s.start("Syncing marketplace clone");
         try {
@@ -606,156 +629,140 @@ async function upgrade() {
         if (newVersion === localVersion) {
             p.log.success(color.green("Already on latest") + ` — v${localVersion}`);
             rmSync(tmpDir, { recursive: true, force: true });
-            return;
         }
         else {
             p.log.info(`Update available: ${color.yellow("v" + localVersion)} → ${color.green("v" + newVersion)}`);
-        }
-        // Step 2: Install dependencies + build
-        s.start("Installing dependencies & building");
-        npmExecFile(["install", "--no-audit", "--no-fund"], {
-            cwd: srcDir,
-            stdio: "pipe",
-            timeout: 120000,
-        });
-        npmExecFile(["run", "build"], {
-            cwd: srcDir,
-            stdio: "pipe",
-            timeout: 60000,
-        });
-        s.stop("Built successfully");
-        // Step 3: Update in-place
-        s.start("Updating files in-place");
-        // Old version dirs are cleaned lazily by sessionstart.mjs (age-gated >1h)
-        // to avoid breaking active sessions that still reference them (#181).
-        // Read files list from cloned repo's package.json so new directories
-        // (like insight/) are automatically included without chicken-and-egg issues
-        // where the old CLI doesn't know about new directories.
-        const clonedPkg = JSON.parse(readFileSync(resolve(srcDir, "package.json"), "utf-8"));
-        const items = [
-            ...(clonedPkg.files || []),
-            "src", "package.json",
-        ];
-        for (const item of items) {
-            try {
-                rmSync(resolve(pluginRoot, item), { recursive: true, force: true });
-                cpSync(resolve(srcDir, item), resolve(pluginRoot, item), { recursive: true });
+            // Step 2: Install dependencies + build
+            s.start("Installing dependencies & building");
+            npmExecFile(["install", "--no-audit", "--no-fund"], {
+                cwd: srcDir,
+                stdio: "pipe",
+                timeout: 120000,
+            });
+            npmExecFile(["run", "build"], {
+                cwd: srcDir,
+                stdio: "pipe",
+                timeout: 60000,
+            });
+            s.stop("Built successfully");
+            // Step 3: Update in-place
+            s.start("Updating files in-place");
+            // Old version dirs are cleaned lazily by sessionstart.mjs (age-gated >1h)
+            // to avoid breaking active sessions that still reference them (#181).
+            // Read files list from cloned repo's package.json so new directories
+            // (like insight/) are automatically included without chicken-and-egg issues
+            // where the old CLI doesn't know about new directories.
+            const clonedPkg = JSON.parse(readFileSync(resolve(srcDir, "package.json"), "utf-8"));
+            const items = [
+                ...(clonedPkg.files || []),
+                "src", "package.json",
+            ];
+            for (const item of items) {
+                try {
+                    rmSync(resolve(pluginRoot, item), { recursive: true, force: true });
+                    cpSync(resolve(srcDir, item), resolve(pluginRoot, item), { recursive: true });
+                }
+                catch { /* some files may not exist in source */ }
             }
-            catch { /* some files may not exist in source */ }
-        }
-        // Write .mcp.json with CLAUDE_PLUGIN_ROOT placeholder (fixes #411).
-        // Absolute paths bake-in the current pluginRoot dir, which sessionstart.mjs
-        // (#181) deletes after upgrade — breaking MCP server resolution. The literal
-        // ${CLAUDE_PLUGIN_ROOT} placeholder is resolved by Claude at load-time and
-        // stays valid across version cleanups. Matches .claude-plugin/plugin.json.
-        const mcpConfig = {
-            mcpServers: {
-                "context-mode": {
-                    command: "node",
-                    args: ["${CLAUDE_PLUGIN_ROOT}/start.mjs"],
+            // Write .mcp.json with CLAUDE_PLUGIN_ROOT placeholder (fixes #411).
+            // Absolute paths bake-in the current pluginRoot dir, which sessionstart.mjs
+            // (#181) deletes after upgrade — breaking MCP server resolution. The literal
+            // ${CLAUDE_PLUGIN_ROOT} placeholder is resolved by Claude at load-time and
+            // stays valid across version cleanups. Matches .claude-plugin/plugin.json.
+            const mcpConfig = {
+                mcpServers: {
+                    "context-mode": {
+                        command: "node",
+                        args: ["${CLAUDE_PLUGIN_ROOT}/start.mjs"],
+                    },
                 },
-            },
-        };
-        writeFileSync(resolve(pluginRoot, ".mcp.json"), JSON.stringify(mcpConfig, null, 2) + "\n");
-        s.stop(color.green(`Updated in-place to v${newVersion}`));
-        // Fix registry — adapter-aware
-        adapter.updatePluginRegistry(pluginRoot, newVersion);
-        p.log.info(color.dim("  Registry synced to " + pluginRoot));
-        // Install production deps
-        s.start("Installing production dependencies");
-        npmExecFile(["install", "--production", "--no-audit", "--no-fund"], {
-            cwd: pluginRoot,
-            stdio: "pipe",
-            timeout: 60000,
-        });
-        s.stop("Dependencies ready");
-        if (detection.platform !== 'opencode' && detection.platform !== 'kilo') {
-            // Rebuild native addons for current Node.js ABI (fixes #131)
-            s.start("Rebuilding native addons");
-            const bsqBindingPath = resolve(pluginRoot, "node_modules", "better-sqlite3", "build", "Release", "better_sqlite3.node");
-            // Skip rebuild when the binding from `npm install --production` is
-            // already present. Earlier code ran `npm rebuild better-sqlite3`
-            // unconditionally — its internal prebuild-install spawn raced with
-            // the prior install's tree-prune, intermittently failing to resolve
-            // `rc/index.js` and printing a scary "rebuild warning" even though
-            // the binding was healthy. Pre-check eliminates the race for the
-            // 99% case (binding survived install).
-            if (existsSync(bsqBindingPath)) {
-                s.stop(color.green("Native addons OK") + color.dim(" — binding present"));
-                changes.push("better-sqlite3 binding already present (no rebuild needed)");
-            }
-            else {
-                // Binding actually missing — delegate to the shared 3-layer heal
-                // (scripts/heal-better-sqlite3.mjs, PR #410) instead of raw
-                // `npm rebuild`. Single source of truth across postinstall +
-                // ensure-deps + cli upgrade. Layer A spawns prebuild-install
-                // directly via process.execPath, bypassing PATH/MSVC and the
-                // npm-internal rc-resolution race that bit `npm rebuild`.
+            };
+            writeFileSync(resolve(pluginRoot, ".mcp.json"), JSON.stringify(mcpConfig, null, 2) + "\n");
+            s.stop(color.green(`Updated in-place to v${newVersion}`));
+            // Fix registry — adapter-aware
+            adapter.updatePluginRegistry(pluginRoot, newVersion);
+            p.log.info(color.dim("  Registry synced to " + pluginRoot));
+            // Install production deps
+            s.start("Installing production dependencies");
+            npmExecFile(["install", "--production", "--no-audit", "--no-fund"], {
+                cwd: pluginRoot,
+                stdio: "pipe",
+                timeout: 60000,
+            });
+            s.stop("Dependencies ready");
+            if (detection.platform !== 'opencode' && detection.platform !== 'kilo') {
+                // Verify native addons through the same bootstrap start.mjs imports.
+                // On modern Node, the ABI-specific cache file is the compatibility marker;
+                // the active binding alone may be stale from a previous Node ABI.
+                s.start("Verifying native addon ABI");
+                const bsqAbiCachePath = resolve(pluginRoot, "node_modules", "better-sqlite3", "build", "Release", `better_sqlite3.abi${process.versions.modules}.node`);
                 try {
-                    const healUrl = pathToFileURL(resolve(pluginRoot, "scripts", "heal-better-sqlite3.mjs")).href;
-                    const { healBetterSqlite3Binding } = await import(healUrl);
-                    const result = healBetterSqlite3Binding(pluginRoot);
-                    if (result?.healed) {
-                        s.stop(color.green("Native addons healed") + color.dim(` (${result.reason})`));
-                        changes.push(`Healed better-sqlite3 binding via ${result.reason}`);
+                    const ensureDepsPath = resolve(pluginRoot, "hooks", "ensure-deps.mjs");
+                    if (!existsSync(ensureDepsPath)) {
+                        throw new Error(`missing ${ensureDepsPath}`);
+                    }
+                    await import(`${pathToFileURL(ensureDepsPath).href}?upgrade=${Date.now()}`);
+                    if (existsSync(bsqAbiCachePath)) {
+                        s.stop(color.green("Native addons OK") + color.dim(" — ABI cache present"));
+                        changes.push(`better-sqlite3 ABI ${process.versions.modules} cache ready`);
                     }
                     else {
-                        s.stop(color.yellow("Native addon heal needs manual step"));
-                        p.log.warn(color.dim(`  Run: cd "${pluginRoot}" && npm install better-sqlite3`));
+                        s.stop(color.yellow("Native addon ABI cache missing"));
+                        p.log.warn(color.dim(`  Try manually: cd "${pluginRoot}" && npm rebuild better-sqlite3`));
                     }
                 }
                 catch (err) {
                     const message = err instanceof Error ? err.message : String(err);
-                    s.stop(color.yellow("Native addon heal unavailable"));
-                    p.log.warn(color.yellow("better-sqlite3 heal helper missing") +
+                    s.stop(color.yellow("Native addon ABI bootstrap unavailable"));
+                    p.log.warn(color.yellow("better-sqlite3 ABI repair did not run") +
                         ` — ${message}` +
                         color.dim(`\n  Try manually: cd "${pluginRoot}" && npm rebuild better-sqlite3`));
                 }
             }
-        }
-        // Update global npm
-        s.start("Updating npm global package");
-        try {
-            npmExecFile(["install", "-g", pluginRoot, "--no-audit", "--no-fund"], {
-                stdio: "pipe",
-                timeout: 30000,
-            });
-            s.stop(color.green("npm global updated"));
-            changes.push("Updated npm global package");
-        }
-        catch {
-            s.stop(color.yellow("npm global update skipped"));
-            p.log.info(color.dim("  Could not update global npm — may need sudo or standalone install"));
-        }
-        // Cleanup
-        rmSync(tmpDir, { recursive: true, force: true });
-        // Sync skills to the active install path from installed_plugins.json (#228).
-        // Only targets the ACTUAL directory Claude Code reads from — not spraying everywhere.
-        try {
-            const registryPath = resolve(homedir(), ".claude", "plugins", "installed_plugins.json");
-            if (existsSync(registryPath)) {
-                const registry = JSON.parse(readFileSync(registryPath, "utf-8"));
-                const entries = registry?.plugins?.["context-mode@context-mode"];
-                if (Array.isArray(entries)) {
-                    for (const entry of entries) {
-                        const installPath = entry.installPath;
-                        if (installPath && installPath !== pluginRoot && existsSync(installPath)) {
-                            const srcSkills = resolve(srcDir, "skills");
-                            if (existsSync(srcSkills)) {
-                                cpSync(srcSkills, resolve(installPath, "skills"), { recursive: true });
-                                changes.push(`Synced skills to active install path`);
+            // Update global npm
+            s.start("Updating npm global package");
+            try {
+                npmExecFile(["install", "-g", pluginRoot, "--no-audit", "--no-fund"], {
+                    stdio: "pipe",
+                    timeout: 30000,
+                });
+                s.stop(color.green("npm global updated"));
+                changes.push("Updated npm global package");
+            }
+            catch {
+                s.stop(color.yellow("npm global update skipped"));
+                p.log.info(color.dim("  Could not update global npm — may need sudo or standalone install"));
+            }
+            // Cleanup
+            rmSync(tmpDir, { recursive: true, force: true });
+            // Sync skills to the active install path from installed_plugins.json (#228).
+            // Only targets the ACTUAL directory Claude Code reads from — not spraying everywhere.
+            // Issue #460 round-3: honor $CLAUDE_CONFIG_DIR so the registry lookup
+            // tracks relocated CC config trees.
+            try {
+                const registryPath = resolve(resolveClaudeConfigDir(), "plugins", "installed_plugins.json");
+                if (existsSync(registryPath)) {
+                    const registry = JSON.parse(readFileSync(registryPath, "utf-8"));
+                    const entries = registry?.plugins?.["context-mode@context-mode"];
+                    if (Array.isArray(entries)) {
+                        for (const entry of entries) {
+                            const installPath = entry.installPath;
+                            if (installPath && installPath !== pluginRoot && existsSync(installPath)) {
+                                const srcSkills = resolve(srcDir, "skills");
+                                if (existsSync(srcSkills)) {
+                                    cpSync(srcSkills, resolve(installPath, "skills"), { recursive: true });
+                                    changes.push(`Synced skills to active install path`);
+                                }
                             }
                         }
                     }
                 }
             }
+            catch { /* best effort — registry may not exist or be malformed */ }
+            changes.push(`Updated v${localVersion} → v${newVersion}`);
+            p.log.success(color.green("Plugin reinstalled from GitHub!") +
+                color.dim(` — v${newVersion}`));
         }
-        catch { /* best effort — registry may not exist or be malformed */ }
-        changes.push(newVersion !== localVersion
-            ? `Updated v${localVersion} → v${newVersion}`
-            : `Reinstalled v${localVersion} from GitHub`);
-        p.log.success(color.green("Plugin reinstalled from GitHub!") +
-            color.dim(` — v${newVersion}`));
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
@@ -783,12 +790,18 @@ async function upgrade() {
     }
     // Step 4: Configure hooks — adapter-aware
     p.log.step(`Configuring ${adapter.name} hooks...`);
-    const hookChanges = adapter.configureAllHooks(pluginRoot);
-    for (const change of hookChanges) {
-        p.log.info(color.dim(`  ${change}`));
-        changes.push(change);
+    try {
+        const hookChanges = adapter.configureAllHooks(pluginRoot);
+        for (const change of hookChanges) {
+            p.log.info(color.dim(`  ${change}`));
+            changes.push(change);
+        }
+        p.log.success(color.green("Hooks configured") + color.dim(` — ${adapter.name}`));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Hook configuration failed: ${message}`);
     }
-    p.log.success(color.green("Hooks configured") + color.dim(` — ${adapter.name}`));
     // Step 5: Set hook script permissions — adapter-aware
     p.log.step("Setting hook script permissions...");
     const permSet = adapter.setHookPermissions(pluginRoot);
@@ -854,14 +867,17 @@ function statuslineForward() {
     // marketplace clone (#418-synced, stable across upgrades) and to the path
     // Claude Code itself loads from (installed_plugins.json) keeps the bar
     // alive instead of silently going blank.
+    // Issue #460 round-3: marketplace + registry paths must follow
+    // $CLAUDE_CONFIG_DIR so relocated CC trees still find the statusline binary.
+    const claudeRoot = resolveClaudeConfigDir();
     const candidates = [
         resolve(getPluginRoot(), "bin", "statusline.mjs"),
-        resolve(homedir(), ".claude", "plugins", "marketplaces", "context-mode", "bin", "statusline.mjs"),
+        resolve(claudeRoot, "plugins", "marketplaces", "context-mode", "bin", "statusline.mjs"),
     ];
     // installed_plugins.json may list one or more install paths CC actually
     // loads from. Prefer those if they exist.
     try {
-        const registryPath = resolve(homedir(), ".claude", "plugins", "installed_plugins.json");
+        const registryPath = resolve(claudeRoot, "plugins", "installed_plugins.json");
         if (existsSync(registryPath)) {
             const registry = JSON.parse(readFileSync(registryPath, "utf-8"));
             const entries = registry?.plugins?.["context-mode@context-mode"];

package/build/db-base.d.ts

@@ -48,11 +48,24 @@ export declare class NodeSQLiteAdapter {
     transaction(fn: (...args: any[]) => any): any;
     close(): void;
 }
+/**
+ * Probe whether the supplied node:sqlite DatabaseSync constructor links a
+ * SQLite build that includes the FTS5 module. Some Node.js Linux builds
+ * (e.g. v22.14.0 on Ubuntu) ship node:sqlite without FTS5 even though the
+ * import succeeds, which silently breaks ctx_search/ctx_batch_execute and
+ * the doctor's FTS5 check (issue #461).
+ *
+ * Returns true only when a `CREATE VIRTUAL TABLE … USING fts5(x)` statement
+ * succeeds. Always returns false on any failure (constructor throw, missing
+ * module, etc.) so the caller can fall through to better-sqlite3, whose
+ * bundled SQLite always ships with FTS5.
+ */
+export declare function nodeSqliteHasFts5(DatabaseSync: any): boolean;
 /**
  * Lazy-load the SQLite driver for the current runtime.
  * Bun → bun:sqlite via BunSQLiteAdapter (issue #45).
- * Linux Node → node:sqlite via NodeSQLiteAdapter (issue #228).
- * Other Node → better-sqlite3 (native addon).
+ * Linux Node → node:sqlite via NodeSQLiteAdapter when it ships FTS5 (#228, #461).
+ * Other Node (or Linux Node without FTS5) → better-sqlite3 (native addon).
  */
 export declare function loadDatabase(): typeof DatabaseConstructor;
 /**

package/build/db-base.js

@@ -155,11 +155,40 @@ export class NodeSQLiteAdapter {
 // Lazy loader
 // ─────────────────────────────────────────────────────────
 let _Database = null;
+/**
+ * Probe whether the supplied node:sqlite DatabaseSync constructor links a
+ * SQLite build that includes the FTS5 module. Some Node.js Linux builds
+ * (e.g. v22.14.0 on Ubuntu) ship node:sqlite without FTS5 even though the
+ * import succeeds, which silently breaks ctx_search/ctx_batch_execute and
+ * the doctor's FTS5 check (issue #461).
+ *
+ * Returns true only when a `CREATE VIRTUAL TABLE … USING fts5(x)` statement
+ * succeeds. Always returns false on any failure (constructor throw, missing
+ * module, etc.) so the caller can fall through to better-sqlite3, whose
+ * bundled SQLite always ships with FTS5.
+ */
+export function nodeSqliteHasFts5(DatabaseSync) {
+    let probe = null;
+    try {
+        probe = new DatabaseSync(":memory:");
+        probe.exec("CREATE VIRTUAL TABLE __fts5_probe USING fts5(x)");
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        try {
+            probe?.close();
+        }
+        catch { /* probe never opened or already closed */ }
+    }
+}
 /**
  * Lazy-load the SQLite driver for the current runtime.
  * Bun → bun:sqlite via BunSQLiteAdapter (issue #45).
- * Linux Node → node:sqlite via NodeSQLiteAdapter (issue #228).
- * Other Node → better-sqlite3 (native addon).
+ * Linux Node → node:sqlite via NodeSQLiteAdapter when it ships FTS5 (#228, #461).
+ * Other Node (or Linux Node without FTS5) → better-sqlite3 (native addon).
  */
 export function loadDatabase() {
     if (!_Database) {
@@ -185,8 +214,20 @@ export function loadDatabase() {
         else if (process.platform === "linux") {
             // Linux — try node:sqlite to avoid native addon SIGSEGV (nodejs/node#62515).
             // node:sqlite is built into Node >= 22.5, no flag needed since 22.13.
+            // Probe FTS5 support before committing — some Linux Node builds ship
+            // node:sqlite without FTS5, which would silently break ctx_search (#461).
+            // The probe runs at most once per process (cached via _Database below),
+            // so the cost of opening an in-memory DatabaseSync is negligible.
+            let DatabaseSync = null;
             try {
-                const { DatabaseSync } = require(["node", "sqlite"].join(":"));
+                // Array.join() prevents esbuild from resolving the specifier at bundle time
+                // (mirrors the bun:sqlite branch above).
+                ({ DatabaseSync } = require(["node", "sqlite"].join(":")));
+            }
+            catch {
+                DatabaseSync = null;
+            }
+            if (DatabaseSync && nodeSqliteHasFts5(DatabaseSync)) {
                 _Database = function NodeDatabaseFactory(path, opts) {
                     const raw = new DatabaseSync(path, {
                         readOnly: opts?.readonly ?? false,
@@ -194,8 +235,12 @@ export function loadDatabase() {
                     return new NodeSQLiteAdapter(raw);
                 };
             }
-            catch {
-                // node:sqlite not available — fall through to better-sqlite3
+            else {
+                // node:sqlite missing or built without FTS5 — fall through to better-sqlite3.
+                // Trade-off: this reintroduces the native-addon path that #228 routed
+                // around (Linux SIGSEGV per nodejs/node#62515). Deliberate — a visible
+                // crash on the rare unstable build is preferable to a silent
+                // "no such module: fts5" on every ctx_search call.
                 _Database = require("better-sqlite3");
             }
         }

package/build/executor.d.ts

@@ -11,6 +11,8 @@ export declare function buildScriptFilename(language: Language, platform: NodeJS
 export declare function buildSpawnOptions(platform: NodeJS.Platform): {
     windowsHide: boolean;
 };
+/** Pure helper — exported for unit testing. Restores parent PATH after shell startup. */
+export declare function buildShellScriptContent(code: string, inheritedPath: string | undefined, platform: NodeJS.Platform): string;
 interface ExecuteOptions {
     language: Language;
     code: string;

package/build/executor.js

@@ -42,6 +42,15 @@ export function buildScriptFilename(language, platform, shellPath) {
 export function buildSpawnOptions(platform) {
     return { windowsHide: platform === "win32" };
 }
+function quoteForPosixShell(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** Pure helper — exported for unit testing. Restores parent PATH after shell startup. */
+export function buildShellScriptContent(code, inheritedPath, platform) {
+    if (platform === "win32" || !inheritedPath)
+        return code;
+    return `export PATH=${quoteForPosixShell(inheritedPath)}\n${code}`;
+}
 /**
  * Resolve the real OS temp directory, bypassing any TMPDIR env override.
  * os.tmpdir() reads TMPDIR from the environment, which some shells/tools
@@ -173,7 +182,7 @@ export class PolyglotExecutor {
         }
         const fp = join(tmpDir, buildScriptFilename(language, process.platform, language === "shell" ? this.#runtimes.shell : null));
         if (language === "shell") {
-            writeFileSync(fp, code, { encoding: "utf-8", mode: 0o700 });
+            writeFileSync(fp, buildShellScriptContent(code, process.env.PATH, process.platform), { encoding: "utf-8", mode: 0o700 });
         }
         else {
             writeFileSync(fp, code, "utf-8");
@@ -210,7 +219,11 @@ export class PolyglotExecutor {
         return new Promise((res) => {
             // Only .cmd/.bat shims need shell on Windows; real executables don't.
             // Using shell: true globally causes process-tree kill issues with MSYS2/Git Bash.
-            const needsShell = isWin && ["tsx", "ts-node", "elixir"].includes(cmd[0]);
+            // "bun" is included as defense-in-depth: bunCommand() prefers absolute
+            // .exe paths now (#506), but if it falls back to the bare "bun" string
+            // on Windows that resolution typically goes through a `bun.cmd` shim
+            // (npm i -g bun) which CreateProcess can't execute without cmd.exe.
+            const needsShell = isWin && ["tsx", "ts-node", "elixir", "bun"].includes(cmd[0]);
             // On Windows with Git Bash, pass the script as `bash -c "source /posix/path"`
             // rather than `bash /path/to/script.sh`. This avoids MSYS2 path mangling
             // while still allowing MSYS_NO_PATHCONV to protect non-ASCII paths in commands.