shieldcortex 4.31.2 → 4.32.1

package/dist/setup/copilot.js

@@ -9,44 +9,108 @@ import fs from 'fs';
 import path from 'path';
 import os from 'os';
 import { fileURLToPath } from 'url';
+import { readJsonConfigOrAbort, writeJsonConfigWithBackup, looksLikeShieldcortex, resolveMcpServerCommand, } from './json-config.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const SERVER_NAME = 'shieldcortex-memory';
 // MCP entry point: dist/index.js (one level up from dist/setup/)
 const MCP_ENTRY = path.resolve(__dirname, '..', 'index.js');
 /**
- * Read a JSON file, returning {} if it doesn't exist or is invalid.
+ * Read a JSON config file. Missing → {}; existing-but-unparseable → THROWS.
+ *
+ * VS Code / Cursor `mcp.json` files are JSONC and may contain `//` comments
+ * and trailing commas, which `JSON.parse` rejects. Aborting on that is the
+ * CORRECT safe behaviour — silently treating an unparseable-but-present file
+ * as `{}` and writing it back would delete every OTHER MCP server the user
+ * configured. The thrown error (from readJsonConfigOrAbort) explains that
+ * JSONC isn't supported so the user knows why the install stopped.
  */
 function readJson(filePath) {
+    return readJsonConfigOrAbort(filePath);
+}
+/**
+ * Write a JSON config file, backing up any existing file first and creating
+ * parent directories as needed.
+ */
+function writeJson(filePath, data) {
+    writeJsonConfigWithBackup(filePath, data);
+}
+/**
+ * Read for the informational `status` command only: never throw. A JSONC/
+ * unparseable file is reported as unreadable (null) instead of aborting the
+ * whole status run. Mutating paths use readJson (which throws to abort).
+ */
+function readJsonForStatus(filePath) {
     try {
-        if (!fs.existsSync(filePath))
-            return {};
-        const raw = fs.readFileSync(filePath, 'utf-8').trim();
-        if (!raw)
-            return {};
-        return JSON.parse(raw);
+        return readJson(filePath);
     }
     catch {
-        return {};
+        return null;
     }
 }
 /**
- * Write a JSON file, creating parent directories as needed.
+ * Uninstall-side read: returns the parsed config, or `null` if the file is
+ * unparseable. When it returns `null` for a file that ACTUALLY EXISTS (JSONC /
+ * trailing comma), print a warning naming the path — otherwise a real
+ * `shieldcortex` entry that can't be parsed is silently left in place while
+ * uninstall reports "not configured." An absent file is silent (normal). The
+ * caller treats `null` as a no-op (we never corrupt on parse failure).
  */
-function writeJson(filePath, data) {
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n');
+function readJsonForRemoval(filePath) {
+    const config = readJsonForStatus(filePath);
+    if (config === null && fs.existsSync(filePath)) {
+        console.warn(`  ! ${filePath} is JSONC/unparseable — could not auto-remove; ` +
+            `remove the shieldcortex entry manually.`);
+    }
+    return config;
 }
 /**
- * Build the server entry for ShieldCortex MCP.
+ * Build the VS Code server entry for ShieldCortex MCP.
+ *
+ * Resolves to the absolute global binary (or `node <absolute dist/index.js>`),
+ * never `npx -y` — see resolveMcpServerCommand for why a re-resolving command
+ * thrashes the editor's MCP-config hash. VS Code format includes `type`.
  */
 function serverEntry() {
+    const { command, args } = resolveMcpServerCommand(MCP_ENTRY);
     return {
         type: 'stdio',
-        command: 'node',
-        args: [MCP_ENTRY],
+        command,
+        args,
     };
 }
+/**
+ * Build the Cursor server entry. Same resolved command as VS Code, but Cursor's
+ * schema omits the `type` field.
+ */
+function cursorServerEntry() {
+    const { command, args } = resolveMcpServerCommand(MCP_ENTRY);
+    return { command, args };
+}
+/**
+ * Decide what to do with an EXISTING entry under our server name.
+ *
+ *  - not ours (looksLikeShieldcortex false) → leave it alone (`'foreign'`)
+ *  - ours but the command/args already match the desired entry → `'current'`
+ *  - ours but stale (old `node dist/index.js`, `npx -y shieldcortex`, a stale
+ *    absolute path, …) → `'stale'`, caller refreshes it
+ *
+ * `SERVER_NAME` is ShieldCortex-specific (unlike the generic `memory` key in
+ * ~/.claude.json), so a present entry under it is almost always ours — but we
+ * still guard with looksLikeShieldcortex so a user who parked an unrelated
+ * server under the same name isn't clobbered.
+ */
+function classifyExisting(existing, desired) {
+    if (!looksLikeShieldcortex(existing))
+        return 'foreign';
+    const e = existing;
+    const sameCommand = e.command === desired.command;
+    const desiredArgs = desired.args ?? [];
+    const sameArgs = Array.isArray(e.args) &&
+        e.args.length === desiredArgs.length &&
+        e.args.every((v, i) => v === desiredArgs[i]);
+    return sameCommand && sameArgs ? 'current' : 'stale';
+}
 // ── VS Code ──
 /**
  * Find VS Code user config directories (supports standard + Insiders).
@@ -75,8 +139,14 @@ function findVsCodeDirs() {
     return dirs;
 }
 /**
- * Add ShieldCortex to a VS Code mcp.json file.
+ * Add (or refresh) ShieldCortex in a VS Code mcp.json file.
  * VS Code format: { "servers": { "name": { ... } } }
+ *
+ * On re-install, a stale ShieldCortex entry (e.g. an old `node dist/index.js`
+ * path or an `npx -y` command from a previous version) is UPDATED to the
+ * currently-resolved command rather than left in place — otherwise the editor
+ * keeps launching the wrong/old server forever. A foreign entry parked under
+ * our name is never touched.
  */
 function addToVsCode(configDir) {
     const mcpPath = path.join(configDir, 'mcp.json');
@@ -85,19 +155,36 @@ function addToVsCode(configDir) {
         config.servers = {};
     }
     const servers = config.servers;
+    const desired = serverEntry();
     if (servers[SERVER_NAME]) {
-        return false; // already configured
+        const verdict = classifyExisting(servers[SERVER_NAME], desired);
+        if (verdict === 'foreign')
+            return 'foreign';
+        if (verdict === 'current')
+            return 'unchanged';
+        servers[SERVER_NAME] = desired; // stale → refresh
+        writeJson(mcpPath, config);
+        return 'refreshed';
     }
-    servers[SERVER_NAME] = serverEntry();
+    servers[SERVER_NAME] = desired;
     writeJson(mcpPath, config);
-    return true;
+    return 'added';
 }
 /**
  * Remove ShieldCortex from a VS Code mcp.json file.
+ *
+ * If the file is unparseable (JSONC), leave it untouched and report nothing
+ * removed — same "don't corrupt on parse failure" stance as readJson, but on
+ * the uninstall side we degrade to a no-op rather than throwing through the
+ * uninstaller loop. A present-but-unparseable file warns (via
+ * readJsonForRemoval) so the user isn't told "not configured" while an entry
+ * silently lingers.
  */
 function removeFromVsCode(configDir) {
     const mcpPath = path.join(configDir, 'mcp.json');
-    const config = readJson(mcpPath);
+    const config = readJsonForRemoval(mcpPath);
+    if (config === null)
+        return false;
     if (!config.servers || typeof config.servers !== 'object')
         return false;
     const servers = config.servers;
@@ -127,23 +214,32 @@ function addToCursor(cursorDir) {
         config.mcpServers = {};
     }
     const servers = config.mcpServers;
+    const desired = cursorServerEntry(); // Cursor schema omits "type"
     if (servers[SERVER_NAME]) {
-        return false; // already configured
+        const verdict = classifyExisting(servers[SERVER_NAME], desired);
+        if (verdict === 'foreign')
+            return 'foreign';
+        if (verdict === 'current')
+            return 'unchanged';
+        servers[SERVER_NAME] = desired; // stale → refresh
+        writeJson(mcpPath, config);
+        return 'refreshed';
     }
-    // Cursor doesn't use "type" field
-    servers[SERVER_NAME] = {
-        command: 'node',
-        args: [MCP_ENTRY],
-    };
+    servers[SERVER_NAME] = desired;
     writeJson(mcpPath, config);
-    return true;
+    return 'added';
 }
 /**
  * Remove ShieldCortex from Cursor's mcp.json.
+ *
+ * Unparseable file → no-op (don't corrupt on parse failure), as in
+ * removeFromVsCode; a present-but-unparseable file warns via readJsonForRemoval.
  */
 function removeFromCursor(cursorDir) {
     const mcpPath = path.join(cursorDir, 'mcp.json');
-    const config = readJson(mcpPath);
+    const config = readJsonForRemoval(mcpPath);
+    if (config === null)
+        return false;
     if (!config.mcpServers || typeof config.mcpServers !== 'object')
         return false;
     const servers = config.mcpServers;
@@ -162,17 +258,31 @@ export async function installCopilot() {
         process.exit(1);
     }
     let installed = 0;
+    // Report an add/refresh/unchanged/foreign outcome with the right glyph + text,
+    // and count add+refresh toward `installed` (both mutate the config).
+    const report = (outcome, label, target) => {
+        switch (outcome) {
+            case 'added':
+                console.log(`  ✓ ${label} — added to ${target}`);
+                installed++;
+                break;
+            case 'refreshed':
+                console.log(`  ↑ ${label} — refreshed stale entry in ${target}`);
+                installed++;
+                break;
+            case 'unchanged':
+                console.log(`  · ${label} — already configured`);
+                break;
+            case 'foreign':
+                console.warn(`  ! ${label} — '${SERVER_NAME}' exists but is not ShieldCortex-owned; leaving it alone`);
+                break;
+        }
+    };
     // VS Code
     const vscodeDirs = findVsCodeDirs();
     for (const dir of vscodeDirs) {
         const variant = path.basename(path.dirname(dir)); // "Code" or "Code - Insiders"
-        if (addToVsCode(dir)) {
-            console.log(`  ✓ VS Code (${variant}) — added to ${path.join(dir, 'mcp.json')}`);
-            installed++;
-        }
-        else {
-            console.log(`  · VS Code (${variant}) — already configured`);
-        }
+        report(addToVsCode(dir), `VS Code (${variant})`, path.join(dir, 'mcp.json'));
     }
     if (vscodeDirs.length === 0) {
         console.log('  · VS Code — not found');
@@ -180,13 +290,7 @@ export async function installCopilot() {
     // Cursor
     const cursorDir = findCursorDir();
     if (cursorDir) {
-        if (addToCursor(cursorDir)) {
-            console.log(`  ✓ Cursor — added to ${path.join(cursorDir, 'mcp.json')}`);
-            installed++;
-        }
-        else {
-            console.log('  · Cursor — already configured');
-        }
+        report(addToCursor(cursorDir), 'Cursor', path.join(cursorDir, 'mcp.json'));
     }
     else {
         console.log('  · Cursor — not found');
@@ -248,7 +352,11 @@ export async function copilotStatus() {
     for (const dir of vscodeDirs) {
         const variant = path.basename(path.dirname(dir));
         const mcpPath = path.join(dir, 'mcp.json');
-        const config = readJson(mcpPath);
+        const config = readJsonForStatus(mcpPath);
+        if (config === null) {
+            console.log(`VS Code (${variant}):  unreadable (not valid JSON — JSONC/comments not supported)`);
+            continue;
+        }
         const servers = (config.servers ?? {});
         const installed = !!servers[SERVER_NAME];
         console.log(`VS Code (${variant}):  ${installed ? 'configured' : 'not configured'}`);
@@ -260,10 +368,15 @@ export async function copilotStatus() {
     }
     else {
         const mcpPath = path.join(cursorDir, 'mcp.json');
-        const config = readJson(mcpPath);
-        const servers = (config.mcpServers ?? {});
-        const installed = !!servers[SERVER_NAME];
-        console.log(`Cursor:   ${installed ? 'configured' : 'not configured'}`);
+        const config = readJsonForStatus(mcpPath);
+        if (config === null) {
+            console.log('Cursor:   unreadable (not valid JSON — JSONC/comments not supported)');
+        }
+        else {
+            const servers = (config.mcpServers ?? {});
+            const installed = !!servers[SERVER_NAME];
+            console.log(`Cursor:   ${installed ? 'configured' : 'not configured'}`);
+        }
     }
 }
 export async function handleCopilotCommand(subcommand) {

package/dist/setup/json-config.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Shared, dependency-free helpers for reading and writing user-owned JSON
+ * config files during install.
+ *
+ * The whole point: an installer must NEVER replace a user's config because a
+ * file was momentarily unparseable (trailing comma, JSONC `// comments` — VS
+ * Code / Cursor config files are JSONC — or a partial concurrent write by
+ * Claude Code itself). The historical bug: read with `catch { return {} }`,
+ * then unconditionally write the mutated object back, wiping everything the
+ * file held.
+ *
+ * This mirrors the discipline the uninstall path already follows
+ * (uninstall.ts: "aborting to avoid corruption"): if a file EXISTS but won't
+ * parse, abort — don't pretend it was empty.
+ */
+/** Suffix for the safety copy written before any mutating write. */
+export declare const BACKUP_SUFFIX = ".bak-shieldcortex";
+/**
+ * Read a JSON config file.
+ *
+ * - Missing file → `{}` (a fresh install legitimately starts from nothing).
+ * - Exists and parses → the parsed object.
+ * - Exists but does NOT parse → THROW (never silently return `{}`, which would
+ *   let the caller overwrite the file with only its own entries).
+ *
+ * VS Code / Cursor `mcp.json` files are JSONC and may contain `//` comments;
+ * `JSON.parse` rejects those. That rejection is the CORRECT safe outcome here
+ * (better to abort than wipe), so the thrown message says so explicitly rather
+ * than silently stripping comments and rewriting (which would still lose the
+ * user's formatting and comments).
+ */
+export declare function readJsonConfigOrAbort(filePath: string): Record<string, any>;
+/**
+ * Write a JSON config file atomically, backing up any existing file first.
+ *
+ * The torn-write hazard this guards against: an in-place `fs.writeFileSync`
+ * can leave a TRUNCATED file if the process dies mid-write — and the targets
+ * here include `~/.claude.json`, Claude Code's primary state file. So instead
+ * the new content is written to a sibling temp file and then `renameSync`d
+ * into place (atomic on the same filesystem); a reader never sees a partial
+ * file, and a crash between temp-write and rename leaves the ORIGINAL intact.
+ *
+ * Sequence:
+ *  1. Ensure the parent directory exists.
+ *  2. If the target already exists, copy it to `<path>${BACKUP_SUFFIX}` first.
+ *  3. Write the new JSON (2-space indent + trailing newline) to a temp file.
+ *  4. `renameSync` the temp file over the target.
+ *
+ * The original file is never deleted or overwritten before step 4 succeeds, so
+ * a failure during the temp-write leaves the live config untouched; the temp
+ * file is cleaned up on failure. Mirrors the tmp+rename precedent in
+ * `openclaw.ts`.
+ *
+ * Note: the backup is SINGLE-GENERATION — it captures the pre-write state and
+ * is overwritten on every run, so it only ever reflects the file as it was
+ * immediately before the most recent write.
+ */
+export declare function writeJsonConfigWithBackup(filePath: string, data: unknown): void;
+/**
+ * Ownership check: an `mcpServers` entry "looks like ShieldCortex" if its
+ * command path or any args string contains a `shieldcortex` / `shield-cortex`
+ * token.
+ *
+ * `mcpServers.memory` is a generic key — the official upstream
+ * `@modelcontextprotocol/server-memory` registers under the same name — so
+ * BOTH the install path (before overwriting an entry) and the uninstall path
+ * (before deleting one) MUST verify ownership or risk clobbering an unrelated
+ * MCP server the user installed. This is the single canonical definition;
+ * `claude-md.ts` and `uninstall.ts` import it rather than each holding a copy.
+ */
+export declare function looksLikeShieldcortex(entry: unknown): boolean;
+/** A resolved MCP stdio command: an executable plus its argv. */
+export interface McpServerCommand {
+    command: string;
+    args: string[];
+}
+/**
+ * Resolve the stdio command an editor (Codex / VS Code Copilot / Cursor) should
+ * launch to start the ShieldCortex MCP server.
+ *
+ * Mirrors `claude-md.ts setupGlobalMcp`'s v4.11.1 fix: prefer the installed
+ * GLOBAL binary, resolved to an ABSOLUTE path via `which`/`where`, and invoke
+ * it directly. The hazard being avoided is `npx -y shieldcortex` as the MCP
+ * command — `npx` re-resolves dynamically on every spawn, so a cache shift
+ * (version drift / fresh publish / cache miss) silently changes the effective
+ * command. Editors hash their MCP config; a changed command changes the hash
+ * and resets the active session, wiping context (the 2026-04-22 fleet "fresh
+ * session" bug). An absolute path never drifts.
+ *
+ * Fallback when no global binary is on PATH: `node <absoluteDistEntry>` — the
+ * bundled `dist/index.js` resolved to an absolute path from this module's
+ * location. That is ALSO stable (a fixed absolute path, not `npx`), so a
+ * single-shot install without a global binary still gets a hash-stable command
+ * rather than re-introducing the npx hash-thrash class.
+ *
+ * @param distEntry Absolute path to the package's `dist/index.js` (the caller
+ *   resolves it from its own `__dirname` so we don't guess the layout).
+ */
+export declare function resolveMcpServerCommand(distEntry: string): McpServerCommand;

package/dist/setup/json-config.js

@@ -0,0 +1,167 @@
+/**
+ * Shared, dependency-free helpers for reading and writing user-owned JSON
+ * config files during install.
+ *
+ * The whole point: an installer must NEVER replace a user's config because a
+ * file was momentarily unparseable (trailing comma, JSONC `// comments` — VS
+ * Code / Cursor config files are JSONC — or a partial concurrent write by
+ * Claude Code itself). The historical bug: read with `catch { return {} }`,
+ * then unconditionally write the mutated object back, wiping everything the
+ * file held.
+ *
+ * This mirrors the discipline the uninstall path already follows
+ * (uninstall.ts: "aborting to avoid corruption"): if a file EXISTS but won't
+ * parse, abort — don't pretend it was empty.
+ */
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+/** Suffix for the safety copy written before any mutating write. */
+export const BACKUP_SUFFIX = '.bak-shieldcortex';
+/**
+ * Read a JSON config file.
+ *
+ * - Missing file → `{}` (a fresh install legitimately starts from nothing).
+ * - Exists and parses → the parsed object.
+ * - Exists but does NOT parse → THROW (never silently return `{}`, which would
+ *   let the caller overwrite the file with only its own entries).
+ *
+ * VS Code / Cursor `mcp.json` files are JSONC and may contain `//` comments;
+ * `JSON.parse` rejects those. That rejection is the CORRECT safe outcome here
+ * (better to abort than wipe), so the thrown message says so explicitly rather
+ * than silently stripping comments and rewriting (which would still lose the
+ * user's formatting and comments).
+ */
+export function readJsonConfigOrAbort(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return {};
+    }
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    // An existing but empty/whitespace file is treated as empty config — there
+    // is no content to lose, so this is not the corruption case.
+    if (raw.trim() === '') {
+        return {};
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`ShieldCortex: refusing to overwrite ${filePath} — it exists but is not valid JSON ` +
+            `(${err.message}). Aborting to avoid corruption. ` +
+            `Note: JSON-with-comments (JSONC, // comments) and trailing commas are not supported here. ` +
+            `Fix or remove the file, then re-run the installer.`);
+    }
+}
+/**
+ * Write a JSON config file atomically, backing up any existing file first.
+ *
+ * The torn-write hazard this guards against: an in-place `fs.writeFileSync`
+ * can leave a TRUNCATED file if the process dies mid-write — and the targets
+ * here include `~/.claude.json`, Claude Code's primary state file. So instead
+ * the new content is written to a sibling temp file and then `renameSync`d
+ * into place (atomic on the same filesystem); a reader never sees a partial
+ * file, and a crash between temp-write and rename leaves the ORIGINAL intact.
+ *
+ * Sequence:
+ *  1. Ensure the parent directory exists.
+ *  2. If the target already exists, copy it to `<path>${BACKUP_SUFFIX}` first.
+ *  3. Write the new JSON (2-space indent + trailing newline) to a temp file.
+ *  4. `renameSync` the temp file over the target.
+ *
+ * The original file is never deleted or overwritten before step 4 succeeds, so
+ * a failure during the temp-write leaves the live config untouched; the temp
+ * file is cleaned up on failure. Mirrors the tmp+rename precedent in
+ * `openclaw.ts`.
+ *
+ * Note: the backup is SINGLE-GENERATION — it captures the pre-write state and
+ * is overwritten on every run, so it only ever reflects the file as it was
+ * immediately before the most recent write.
+ */
+export function writeJsonConfigWithBackup(filePath, data) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    if (fs.existsSync(filePath)) {
+        fs.copyFileSync(filePath, `${filePath}${BACKUP_SUFFIX}`);
+    }
+    const tmp = `${filePath}.tmp-shieldcortex`;
+    try {
+        fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+        fs.renameSync(tmp, filePath);
+    }
+    catch (err) {
+        // Leave the original file untouched; just clean up the temp file.
+        try {
+            if (fs.existsSync(tmp))
+                fs.unlinkSync(tmp);
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+        throw err;
+    }
+}
+/**
+ * Ownership check: an `mcpServers` entry "looks like ShieldCortex" if its
+ * command path or any args string contains a `shieldcortex` / `shield-cortex`
+ * token.
+ *
+ * `mcpServers.memory` is a generic key — the official upstream
+ * `@modelcontextprotocol/server-memory` registers under the same name — so
+ * BOTH the install path (before overwriting an entry) and the uninstall path
+ * (before deleting one) MUST verify ownership or risk clobbering an unrelated
+ * MCP server the user installed. This is the single canonical definition;
+ * `claude-md.ts` and `uninstall.ts` import it rather than each holding a copy.
+ */
+export function looksLikeShieldcortex(entry) {
+    if (!entry || typeof entry !== 'object')
+        return false;
+    const e = entry;
+    const tokens = [];
+    if (typeof e.command === 'string')
+        tokens.push(e.command);
+    if (Array.isArray(e.args))
+        for (const a of e.args)
+            if (typeof a === 'string')
+                tokens.push(a);
+    return tokens.some((t) => /shield[-]?cortex/i.test(t));
+}
+/**
+ * Resolve the stdio command an editor (Codex / VS Code Copilot / Cursor) should
+ * launch to start the ShieldCortex MCP server.
+ *
+ * Mirrors `claude-md.ts setupGlobalMcp`'s v4.11.1 fix: prefer the installed
+ * GLOBAL binary, resolved to an ABSOLUTE path via `which`/`where`, and invoke
+ * it directly. The hazard being avoided is `npx -y shieldcortex` as the MCP
+ * command — `npx` re-resolves dynamically on every spawn, so a cache shift
+ * (version drift / fresh publish / cache miss) silently changes the effective
+ * command. Editors hash their MCP config; a changed command changes the hash
+ * and resets the active session, wiping context (the 2026-04-22 fleet "fresh
+ * session" bug). An absolute path never drifts.
+ *
+ * Fallback when no global binary is on PATH: `node <absoluteDistEntry>` — the
+ * bundled `dist/index.js` resolved to an absolute path from this module's
+ * location. That is ALSO stable (a fixed absolute path, not `npx`), so a
+ * single-shot install without a global binary still gets a hash-stable command
+ * rather than re-introducing the npx hash-thrash class.
+ *
+ * @param distEntry Absolute path to the package's `dist/index.js` (the caller
+ *   resolves it from its own `__dirname` so we don't guess the layout).
+ */
+export function resolveMcpServerCommand(distEntry) {
+    try {
+        const whichCmd = process.platform === 'win32' ? 'where' : 'which';
+        const resolved = execSync(`${whichCmd} shieldcortex`, {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        })
+            .trim()
+            .split('\n')[0]
+            .trim();
+        if (resolved && fs.existsSync(resolved)) {
+            return { command: resolved, args: [] };
+        }
+    }
+    catch {
+        // No global install on PATH — fall through to the bundled entry.
+    }
+    return { command: 'node', args: [distEntry] };
+}

package/dist/setup/migrate.js

@@ -8,6 +8,7 @@ import fs from 'fs';
 import path from 'path';
 import os from 'os';
 import { execSync } from 'child_process';
+import Database from '../database/better-sqlite3-guard.js';
 const SETTINGS_PATH = path.join(os.homedir(), '.claude', 'settings.json');
 const CLAUDE_MD_PATH = path.join(os.homedir(), '.claude', 'CLAUDE.md');
 const NEW_DB_DIR = path.join(os.homedir(), '.shieldcortex');
@@ -224,7 +225,6 @@ export function migrateDatabase() {
     }
     // Target exists — merge memories that don't already exist
     try {
-        const Database = require('better-sqlite3');
         const db = new Database(targetPath);
         db.pragma('journal_mode = WAL');
         db.pragma('busy_timeout = 5000');

package/dist/setup/native-binding.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Self-healing for the better-sqlite3 native binding.
+ *
+ * better-sqlite3 ships prebuilt binaries for common platform/ABI combos; when
+ * none matches (e.g. a newer Node than the prebuilds, or arm64 with no prebuilt)
+ * it must compile from source, which needs a C/C++ toolchain. If that hasn't
+ * happened the binding is missing and every DB operation fails with
+ * "Could not locate the bindings file".
+ *
+ * The trap (observed on an arm64 fleet box): `npm rebuild better-sqlite3` only
+ * works when run IN THE PACKAGE'S INSTALL DIR. Run from anywhere else (e.g. the
+ * user's home dir) it matches nothing and reports "rebuilt dependencies
+ * successfully" — a no-op. So this module resolves the install dir from the
+ * running code's own location and rebuilds there.
+ *
+ * Used by: `shieldcortex update` (verify+heal step), `shieldcortex repair`,
+ * `shieldcortex doctor` (correct remediation text), and the postinstall guidance.
+ */
+export interface VerifyResult {
+    ok: boolean;
+    error?: string;
+}
+export type EnsureStatus = 'ok' | 'healed' | 'failed';
+export interface EnsureResult {
+    status: EnsureStatus;
+    /** Underlying load error, when the binding could not be loaded. */
+    error?: string;
+    /** Captured rebuild output, when a rebuild was attempted. */
+    rebuildOutput?: string;
+    /** Full copy-paste remediation, present when status is 'failed'. */
+    remediation?: string;
+}
+/** Injection seam so the heal orchestration is testable without a real failure. */
+export interface BindingDeps {
+    verify: () => VerifyResult;
+    rebuild: (dir: string) => Promise<{
+        ok: boolean;
+        output: string;
+    }>;
+    installDir: () => string;
+}
+/**
+ * The package's own install root — the directory whose `package.json` is this
+ * package, and which contains `node_modules/better-sqlite3`. Derived from the
+ * running module's location, NOT `npm root -g` (which points at the wrong tree
+ * when the package was installed under a custom prefix or via a registry shim).
+ *
+ * From `dist/setup/native-binding.js` → `../../` is the package root.
+ */
+export declare function resolveSelfInstallDir(): string;
+/**
+ * Smoke-test the native binding: load it, open an in-memory DB, run a probe.
+ * Synchronous (the load is sync) and never throws — returns a verdict.
+ */
+export declare function verifyNativeBinding(): VerifyResult;
+/**
+ * Run `npm rebuild better-sqlite3` in the install dir. Async (the rebuild can
+ * take tens of seconds) so callers can keep a spinner alive. Never throws.
+ */
+export declare function rebuildNativeBinding(installDir: string): Promise<{
+    ok: boolean;
+    output: string;
+}>;
+/**
+ * The correct copy-paste remediation — the install-dir `cd` is the bit users
+ * miss (a bare `npm rebuild better-sqlite3` from $HOME is a silent no-op).
+ */
+export declare function nativeBindingRemediation(installDir: string, rebuildOutput?: string): string;
+/**
+ * Verify the binding; if it fails, rebuild in the install dir and re-verify.
+ * - 'ok'     — loaded first try (no rebuild).
+ * - 'healed' — rebuilt and now loads.
+ * - 'failed' — still broken after a rebuild; `remediation` carries the fix.
+ */
+export declare function ensureNativeBinding(deps?: Partial<BindingDeps>): Promise<EnsureResult>;