fix(cli): translate missing sqlite bindings error into actionable guidance (#7868) (#7963)

createSqliteNativeError() in bin/cli/sqlite.mjs only recognized the ABI-mismatch
native error class (NODE_MODULE_VERSION/ERR_DLOPEN_FAILED). It silently passed through
the 'Could not locate the bindings file' class thrown by the bindings package when the
better-sqlite3 native addon was never built/downloaded - the exact case hit by
'npx omniroute reset-password', since npx runs a fresh ephemeral install that never
builds the addon. Users got a raw multi-line path dump instead of guidance.

Widen the condition to also match 'Could not locate the bindings file',
MODULE_NOT_FOUND, and "Cannot find module 'better-sqlite3'", and point users at the
existing self-heal command `omniroute runtime repair`, same as the ABI-mismatch branch
already does.

Regression test: tests/unit/cli-sqlite-bindings-not-found-7868.test.ts - RED against the
reporter's exact error text before the fix, GREEN after.

bin/cli/sqlite.mjs

@@ -21,6 +21,18 @@ export function createSqliteNativeError(error) {
         "(rebuilds into a user-writable runtime; works without a C++ toolchain)."
     );
   }
+  if (
+    message.includes("Could not locate the bindings file") ||
+    message.includes("MODULE_NOT_FOUND") ||
+    message.includes("Cannot find module 'better-sqlite3'")
+  ) {
+    return new Error(
+      "better-sqlite3 native binding could not be found (no prebuilt addon for this platform). " +
+        "This is common under `npx`, which runs a fresh, ephemeral install that never built the addon. " +
+        "Run: omniroute runtime repair  " +
+        "(rebuilds into a user-writable runtime; works without a C++ toolchain)."
+    );
+  }
   return error;
 }
 

changelog.d/fixes/7868-reset-password-sqlite-bindings.md

@@ -0,0 +1 @@
+- fix(cli): translate missing better-sqlite3 native bindings error into actionable `omniroute runtime repair` guidance in `reset-password`/setup CLI commands (#7868)

tests/unit/cli-sqlite-bindings-not-found-7868.test.ts

@@ -0,0 +1,31 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createSqliteNativeError } from "../../bin/cli/sqlite.mjs";
+
+test("#7868: createSqliteNativeError() gives actionable guidance for a missing-bindings-file error", () => {
+  const rawBindingsError = new Error(
+    "Could not locate the bindings file. Tried:\n" +
+      " → /Users/agent_user/.npm/_npx/44b85dff014d9ceb/node_modules/better-sqlite3/build/better_sqlite3.node\n" +
+      " → /Users/agent_user/.npm/_npx/44b85dff014d9ceb/node_modules/better-sqlite3/build/Release/better_sqlite3.node\n" +
+      " → /Users/agent_user/.npm/_npx/44b85dff014d9ceb/node_modules/better-sqlite3/lib/binding/node-v147-darwin-arm64/better_sqlite3.node"
+  );
+
+  const translated = createSqliteNativeError(rawBindingsError);
+
+  assert.notStrictEqual(
+    translated.message,
+    rawBindingsError.message,
+    "createSqliteNativeError() passed the raw 'Could not locate the bindings file' dump through " +
+      "unchanged instead of translating it into actionable guidance (#7868)"
+  );
+  assert.match(
+    translated.message,
+    /runtime repair/i,
+    "translated error should point the user at the existing self-heal command " +
+      "(`omniroute runtime repair`), same as the ABI-mismatch branch already does"
+  );
+  assert.ok(
+    !translated.message.includes("Tried:"),
+    "a raw path dump reaching the user is itself a signal the fix regressed"
+  );
+});