@threadbase-sh/scanner 0.13.0 → 0.14.0

package/README.md

@@ -3,7 +3,7 @@
 Unified Claude Code conversation history scanner.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D20.12-brightgreen.svg)](https://nodejs.org)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org)
 
 Combines the best parts of four independent scanner implementations (VS Code, Electron, IntelliJ, CLI) into a single TypeScript package.
 
@@ -31,7 +31,7 @@ Combines the best parts of four independent scanner implementations (VS Code, El
 npm install @threadbase-sh/scanner
 ```
 
-**Requires Node.js 20.12 or later.** The package uses `better-sqlite3` (a native module) for its persistent index; prebuilt binaries are downloaded for common platforms, with a node-gyp fallback otherwise.
+**Requires Node.js 22 or later.** The package uses `better-sqlite3` (a native module) for its persistent index. Prebuilt binaries ship inside the package for common platforms, so a normal `npm install` needs no compiler and no install script. If the binary is somehow unavailable, `openDatabase()` says so explicitly and points at `npm rebuild better-sqlite3` — or you can skip SQLite entirely with `persistent: false`.
 
 ### Persistent vs. in-memory
 

package/dist/cli.js

@@ -5,7 +5,7 @@ import { Command } from "commander";
 import pino2 from "pino";
 
 // package.json
-var version = "0.13.0";
+var version = "0.14.0";
 
 // src/logger.ts
 import pino from "pino";
@@ -1872,7 +1872,13 @@ function openDatabase(dbPath) {
   if (dbPath !== ":memory:") {
     mkdirSync(dirname3(dbPath), { recursive: true });
   }
-  const db = new Database(dbPath);
+  let db;
+  try {
+    db = new Database(dbPath);
+  } catch (err) {
+    if (isNativeBindingFailure(err)) throw nativeBindingError(err, dbPath);
+    throw err;
+  }
   db.pragma("journal_mode = WAL");
   db.pragma("synchronous = NORMAL");
   db.pragma("temp_store = MEMORY");
@@ -1882,6 +1888,30 @@ function openDatabase(dbPath) {
   getLogger().debug({ dbPath }, "db: opened");
   return db;
 }
+function isNativeBindingFailure(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  return /could not locate the bindings file|NODE_MODULE_VERSION|was compiled against|\.node['"\s]/i.test(
+    message
+  );
+}
+function nativeBindingError(err, dbPath) {
+  const detail = err instanceof Error ? err.message : String(err);
+  return new Error(
+    [
+      `Could not load better-sqlite3's native binary, so the persistent index at ${dbPath} cannot be opened.`,
+      "This usually means the binary was never built or downloaded \u2014 not that your Node version is wrong.",
+      "",
+      "Try, in order:",
+      "  1. npm rebuild better-sqlite3",
+      "  2. rm -rf node_modules && npm install",
+      "     (npm 12 blocks package install scripts by default; approve better-sqlite3 if asked)",
+      "  3. Run without SQLite entirely: new ConversationScanner({ persistent: false })",
+      "     or pass --no-persist on the CLI. Search falls back to the in-memory index.",
+      "",
+      `Original error: ${detail}`
+    ].join("\n")
+  );
+}
 
 // src/persistent/dir-watermark.ts
 import { readdir, stat as stat3 } from "fs/promises";