fix(doctor,hooks): resolve better-sqlite3 via require.resolve to follow npm hoisting (v4.2.6)

kevintseng · kevintseng · commit 0efddc9b6c97 · 2026-05-13T13:49:45.000+08:00
The v4.2.5 native-binding probe regressed every fresh `npm install
@pcircle/memesh` install: it pre-checked
`&lt;packageRoot&gt;/node_modules/better-sqlite3` literally, but npm hoists
dependencies to the consumer's top-level node_modules. So when memesh
is installed as a dependency the directory at the literal path doesn't
exist even though `require('better-sqlite3')` works correctly via
Node's normal resolution.

Found this by verifying the v4.2.5 release with a clean-room install:

    $ mkdir /tmp/verify &amp;&amp; cd /tmp/verify
    $ npm install @pcircle/memesh@4.2.5
    $ ./node_modules/.bin/memesh doctor
    Overall: FAIL
    [FAIL] Native SQLite binding   ← false negative on a working install

The fix in both surfaces (doctor.ts and _shared.js) is to drop the
existence-precheck and call `require.resolve('better-sqlite3',
{ paths: [pkgRoot] })`. Node's resolver walks the same path the
runtime uses (current dir → parent → ancestor's node_modules) and
returns the resolved module path, which we walk back to the package
root. A MODULE_NOT_FOUND error from the probe surfaces as a clean
"run `npm install`" hint; a `bindings file` error still surfaces as
the rebuild hint from v4.2.5.

The hook self-heal also retargets `npm rebuild`'s cwd to the project
that owns the hoisted node_modules tree (walking up until a
non-node_modules package.json appears). Running rebuild from memesh's
own pkgRoot would no-op when the binary is hoisted elsewhere.

Validation:
- Local clean-room install: smoke test confirms 4.2.6 doctor PASSes
  on a hoisted install
- npm test --run: 1036/1038 (same 2 pre-existing failures as v4.2.5)
- memesh doctor: Overall: PASS_WITH_CONCERNS, native-binding PASS
- npm run lint: clean

Version bumped 4.2.5 -&gt; 4.2.6 across all 7 anchor files. The CodeQL
config and TOCTOU fix from v4.2.5 carry forward unchanged.
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -8,7 +8,7 @@
       "name": "memesh",
       "source": "./",
       "description": "MeMesh — Local memory for Claude Code and MCP coding agents. One SQLite file, zero cloud required.",
-      "version": "4.2.5",
+      "version": "4.2.6",
       "author": {
         "name": "PCIRCLE AI"
       },
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -4,7 +4,7 @@
   "author": {
     "name": "PCIRCLE AI"
   },
-  "version": "4.2.5",
+  "version": "4.2.6",
   "homepage": "https://pcircle.ai/memesh-llm-memory",
   "repository": "https://github.com/PCIRCLE-AI/memesh-llm-memory",
   "license": "MIT",
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,12 @@
 
 All notable changes to MeMesh are documented here.
 
+## [4.2.6] — 2026-05-13
+
+### Fixed
+- **`memesh doctor` and hook self-heal now follow npm hoisting** (`src/core/doctor.ts`, `scripts/hooks/_shared.js`) — the v4.2.5 native-binding check pre-checked `<packageRoot>/node_modules/better-sqlite3` literally, but when memesh is installed as a dependency npm hoists `better-sqlite3` to the consumer's top-level `node_modules/`. Result: every fresh `npm install @pcircle/memesh` saw a FAIL on the native-binding check even though the binding worked correctly. Both surfaces now resolve via `require.resolve('better-sqlite3', { paths: [pkgRoot] })`, which follows Node's normal resolution algorithm and finds hoisted packages. The hook's `npm rebuild` self-heal also targets the correct project root now (the package that owns the hoisted `node_modules`), not memesh's own pkgRoot.
+- Doctor test `reports FAIL when node_modules/better-sqlite3 is entirely missing` updated to `reports FAIL with npm install hint when better-sqlite3 is not resolvable` — exercises the MODULE_NOT_FOUND probe response now that the existence-check branch is gone.
+
 ## [4.2.5] — 2026-05-13
 
 ### Added
diff --git a/dist/core/doctor.d.ts.map b/dist/core/doctor.d.ts.map
diff --git a/dist/core/doctor.js b/dist/core/doctor.js
diff --git a/dist/core/doctor.js.map b/dist/core/doctor.js.map
diff --git a/dist/skills-manifest.json b/dist/skills-manifest.json
@@ -1,10 +1,10 @@
 {
   "schema": "memesh.skills-manifest/v1",
-  "generated_at": "2026-05-13T05:09:42.706Z",
+  "generated_at": "2026-05-13T05:46:34.185Z",
   "entries": [
     {
       "path": ".claude-plugin/plugin.json",
-      "sha256": "c42ed9693fcd5e37af60769b6f0dabc9061e416be2148b4a87ee38242c0f4645",
+      "sha256": "34a93efe40e01daa689670b91ce9937c9cf018b6cf60de15bab89534625d215f",
       "bytes": 441
     },
     {
@@ -19,8 +19,8 @@
     },
     {
       "path": "scripts/hooks/_shared.js",
-      "sha256": "247f6cac1ff3615b121f7419b9824cab8cb2e8a835d06ae6dcdca39aba92706f",
-      "bytes": 32902
+      "sha256": "392c1ea45952197d1c65ce92c5e5d80623b635322fb3f446a0b58a055abbac25",
+      "bytes": 33970
     },
     {
       "path": "scripts/hooks/post-commit.js",
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -1,6 +1,6 @@
 # MeMesh Plugin Architecture
 
-**Version**: 4.2.5
+**Version**: 4.2.6
 
 ---
 
diff --git a/docs/api/API_REFERENCE.md b/docs/api/API_REFERENCE.md
@@ -1,7 +1,7 @@
 # MeMesh Plugin -- API Reference
 
 **Protocol**: Model Context Protocol (MCP) over stdio
-**Version**: 4.2.5
+**Version**: 4.2.6
 **Compatibility**: Works with Claude Code plugins, Claude Managed Agents (via MCP connector), and any MCP-compatible client.
 
 ---
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@pcircle/memesh",
-  "version": "4.2.5",
+  "version": "4.2.6",
   "description": "MeMesh — Local memory for Claude Code and MCP coding agents. One SQLite file, zero cloud required.",
   "main": "dist/index.js",
   "type": "module",
diff --git a/scripts/hooks/_shared.js b/scripts/hooks/_shared.js
@@ -387,23 +387,42 @@ export function tryRequireBetterSqlite() {
 function _attemptBetterSqliteRebuild() {
   try {
     // Package root = parent of the scripts/hooks/ directory that contains
-    // this file. That's where `package.json` + `node_modules/` live.
+    // this file. That's where memesh's own `package.json` lives.
     const here = dirname(fileURLToPath(import.meta.url));
     const pkgRoot = dirname(dirname(here));
     if (!existsSync(join(pkgRoot, 'package.json'))) return;
-    if (!existsSync(join(pkgRoot, 'node_modules', 'better-sqlite3'))) {
-      // No better-sqlite3 directory at all (npm install never ran).
-      // `npm rebuild` would no-op; the right fix is a full install,
-      // which we don't trigger here (could pull arbitrary packages).
-      // Surface a clear actionable line instead.
+    // Resolve better-sqlite3's actual install location via Node's normal
+    // resolution algorithm, which follows hoisting (the consumer's
+    // top-level node_modules holds the package when memesh is installed
+    // as a dependency). Looking at `<pkgRoot>/node_modules/better-sqlite3`
+    // directly would false-negative on every hoisted install.
+    let bsqliteDir;
+    try {
+      // `require.resolve` returns the path to `lib/index.js` inside the
+      // package. Walk up to the package directory.
+      const entry = require.resolve('better-sqlite3', { paths: [pkgRoot] });
+      // `<bsqliteDir>/lib/index.js` → walk back twice to the package root.
+      bsqliteDir = dirname(dirname(entry));
+    } catch {
+      // Genuinely not installed anywhere on the resolution path. `npm
+      // rebuild` cannot help; the user needs a full install.
       try {
         process.stderr.write(
-          `[memesh hook] No better-sqlite3 in ${join(pkgRoot, 'node_modules')}. `
-          + `Run: cd "${pkgRoot}" && npm install --omit=dev\n`,
+          `[memesh hook] better-sqlite3 is not installed (Node could not resolve from ${pkgRoot}). `
+          + `Run: cd to the project that depends on @pcircle/memesh and run \`npm install\`.\n`,
         );
       } catch {}
       return;
     }
+    // The hoisted install location's package root — npm rebuild needs to
+    // be run from a project that owns this node_modules tree. Walking
+    // up to the nearest directory that has its own package.json gives
+    // us the right cwd.
+    let rebuildCwd = dirname(bsqliteDir);
+    while (rebuildCwd !== dirname(rebuildCwd)) {
+      if (existsSync(join(rebuildCwd, 'package.json')) && !rebuildCwd.endsWith('node_modules')) break;
+      rebuildCwd = dirname(rebuildCwd);
+    }
     const memesh = join(homedir(), '.memesh');
     try { mkdirSync(memesh, { recursive: true, mode: 0o700 }); } catch {}
     const markerPath = join(memesh, 'last-rebuild-attempt.lock');
@@ -429,13 +448,13 @@ function _attemptBetterSqliteRebuild() {
     }
     process.stderr.write(
       `[memesh hook] Attempting to rebuild better-sqlite3 in background — `
-      + `next session should capture normally. (pkgRoot: ${pkgRoot})\n`
+      + `next session should capture normally. (rebuildCwd: ${rebuildCwd})\n`
       + `[memesh hook] To retry later, manually: rm "${markerPath}" && `
-      + `cd "${pkgRoot}" && npm rebuild better-sqlite3\n`,
+      + `cd "${rebuildCwd}" && npm rebuild better-sqlite3\n`,
     );
     const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
     const child = spawn(npm, ['rebuild', 'better-sqlite3'], {
-      cwd: pkgRoot,
+      cwd: rebuildCwd,
       detached: true,
       stdio: 'ignore',
       windowsHide: true,
diff --git a/src/core/doctor.ts b/src/core/doctor.ts
@@ -669,22 +669,19 @@ function defaultNativeBindingProbe(packageRoot: string): { ok: true } | { ok: fa
 
 function inspectNativeBinding(
   packageRoot: string,
-  existsSyncImpl: typeof fs.existsSync,
+  _existsSyncImpl: typeof fs.existsSync,
   probeImpl: (packageRoot: string) => { ok: true } | { ok: false; message: string } = defaultNativeBindingProbe,
 ): DoctorCheck {
-  const pkgDir = path.join(packageRoot, 'node_modules', 'better-sqlite3');
-  if (!existsSyncImpl(pkgDir)) {
-    return createCheck(
-      'native-binding',
-      'Native SQLite binding',
-      'fail',
-      `better-sqlite3 is not installed in ${pkgDir}.`,
-      `Run: cd "${packageRoot}" && npm install --omit=dev`,
-    );
-  }
-  // Probe via dynamic require + actual instantiation. A bare require()
-  // is not enough — the JS wrapper succeeds even when the binding is
-  // missing; only `new Database()` triggers the binding load.
+  // DO NOT pre-check `<packageRoot>/node_modules/better-sqlite3` for
+  // existence — npm hoists dependencies, so when memesh is installed as
+  // a dependency the better-sqlite3 directory lives at the consumer's
+  // top-level node_modules, not nested under memesh's packageRoot. The
+  // probe below uses Node's normal `require.resolve` which follows the
+  // resolution algorithm (current dir → parent → ancestor's node_modules)
+  // and correctly finds hoisted packages. If better-sqlite3 is genuinely
+  // not installed anywhere on the resolution path, `require()` throws
+  // MODULE_NOT_FOUND and the probe returns ok=false with that message,
+  // which we surface below with a clean reinstall instruction.
   const result = probeImpl(packageRoot);
   if (result.ok) {
     return createCheck(
@@ -695,6 +692,17 @@ function inspectNativeBinding(
     );
   }
   const isMissingBinding = /bindings file|locate the bindings/i.test(result.message);
+  const isMissingPackage = /MODULE_NOT_FOUND|Cannot find module/i.test(result.message);
+  if (isMissingPackage) {
+    return createCheck(
+      'native-binding',
+      'Native SQLite binding',
+      'fail',
+      'better-sqlite3 is not installed (Node could not resolve the module from any '
+        + 'parent node_modules). Memesh hooks and database operations will not work.',
+      `Run: npm install   (in the directory that depends on @pcircle/memesh)`,
+    );
+  }
   if (isMissingBinding) {
     return createCheck(
       'native-binding',
diff --git a/tests/core/doctor.test.ts b/tests/core/doctor.test.ts
@@ -1167,10 +1167,9 @@ describe('native binding probe (plugin-marketplace silent-dropout guard)', () =>
     expect(result.status).toBe('FAIL');
   });
 
-  it('reports FAIL when node_modules/better-sqlite3 is entirely missing', async () => {
+  it('reports FAIL with `npm install` hint when better-sqlite3 is not resolvable', async () => {
     const packageRoot = createPackageRoot();
     tempRoots.push(packageRoot);
-    fs.rmSync(path.join(packageRoot, 'node_modules', 'better-sqlite3'), { recursive: true, force: true });
 
     const result = await runDoctor({
       packageRoot,
@@ -1185,6 +1184,10 @@ describe('native binding probe (plugin-marketplace silent-dropout guard)', () =>
         channel: 'npm-global', label: 'npm global', canSelfUpdate: true,
         recommendedCommand: 'memesh update', guidance: '',
       }),
+      nativeBindingProbeImpl: () => ({
+        ok: false,
+        message: "Cannot find module 'better-sqlite3' — code: MODULE_NOT_FOUND",
+      }),
     });
 
     const bindingCheck = result.checks.find((c) => c.id === 'native-binding');

Original file line number	Diff line number	Diff line change
`@@ -1,10 +1,10 @@`
`1`	`1`	`{`
`2`	`2`	`"schema": "memesh.skills-manifest/v1",`
`3`		`- "generated_at": "2026-05-13T05:09:42.706Z",`
	`3`	`+ "generated_at": "2026-05-13T05:46:34.185Z",`
`4`	`4`	`"entries": [`
`5`	`5`	`{`
`6`	`6`	`"path": ".claude-plugin/plugin.json",`
`7`		`- "sha256": "c42ed9693fcd5e37af60769b6f0dabc9061e416be2148b4a87ee38242c0f4645",`
	`7`	`+ "sha256": "34a93efe40e01daa689670b91ce9937c9cf018b6cf60de15bab89534625d215f",`
`8`	`8`	`"bytes": 441`
`9`	`9`	`},`
`10`	`10`	`{`
`@@ -19,8 +19,8 @@`
`19`	`19`	`},`
`20`	`20`	`{`
`21`	`21`	`"path": "scripts/hooks/_shared.js",`
`22`		`- "sha256": "247f6cac1ff3615b121f7419b9824cab8cb2e8a835d06ae6dcdca39aba92706f",`
`23`		`- "bytes": 32902`
	`22`	`+ "sha256": "392c1ea45952197d1c65ce92c5e5d80623b635322fb3f446a0b58a055abbac25",`
	`23`	`+ "bytes": 33970`
`24`	`24`	`},`
`25`	`25`	`{`
`26`	`26`	`"path": "scripts/hooks/post-commit.js",`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@pcircle/memesh",`
`3`		`- "version": "4.2.5",`
	`3`	`+ "version": "4.2.6",`
`4`	`4`	`"description": "MeMesh — Local memory for Claude Code and MCP coding agents. One SQLite file, zero cloud required.",`
`5`	`5`	`"main": "dist/index.js",`
`6`	`6`	`"type": "module",`