fix(cli): doctor detects prebuilt better-sqlite3 binaries (#10090)

checkNativeBinary only probed the node-gyp layout
(build/Release/better_sqlite3.node), which exists only when better-sqlite3 is
compiled locally. Installs that resolve a prebuilt binary — the normal case for
`npm i -g omniroute` — ship prebuilds/<platform>-<arch>.node instead, so the
check never found a binary and warned "better-sqlite3 native binary was not
found" on every such install, next to real warnings.

Probe both layouts and report both in the failure details. prebuiltBinaryName()
mirrors the prebuild-install lookup, including the linuxmusl- prefix for
musl-based Linux.

Closes #10083

bin/cli/commands/doctor.mjs

@@ -288,27 +288,44 @@ async function checkNodeRuntime(rootDir) {
   }
 }
 
+/**
+ * Name of the prebuilt binary better-sqlite3 ships for this platform, e.g.
+ * `linux-x64.node`. Musl-based Linux uses a distinct `linuxmusl-` prefix.
+ * Mirrors the lookup `prebuild-install`/`node-gyp-build` perform at require time.
+ */
+export function prebuiltBinaryName(
+  platform = process.platform,
+  arch = process.arch,
+  report = process.report
+) {
+  let prefix = platform;
+  if (platform === "linux") {
+    let isMusl = false;
+    try {
+      // glibc builds expose `glibcVersionRuntime`; musl builds do not.
+      isMusl = !report?.getReport?.()?.header?.glibcVersionRuntime;
+    } catch {
+      isMusl = false;
+    }
+    prefix = isMusl ? "linuxmusl" : "linux";
+  }
+  return `${prefix}-${arch}.node`;
+}
+
 async function checkNativeBinary(rootDir) {
+  // node-gyp layout — present only when better-sqlite3 was compiled locally.
+  const buildRoots = [
+    path.join(rootDir, "app", "node_modules", "better-sqlite3"),
+    path.join(rootDir, "dist", "node_modules", "better-sqlite3"),
+    path.join(rootDir, "node_modules", "better-sqlite3"),
+  ];
+  const prebuildName = prebuiltBinaryName();
   const candidates = [
-    path.join(
-      rootDir,
-      "app",
-      "node_modules",
-      "better-sqlite3",
-      "build",
-      "Release",
-      "better_sqlite3.node"
-    ),
-    path.join(
-      rootDir,
-      "dist",
-      "node_modules",
-      "better-sqlite3",
-      "build",
-      "Release",
-      "better_sqlite3.node"
-    ),
-    path.join(rootDir, "node_modules", "better-sqlite3", "build", "Release", "better_sqlite3.node"),
+    ...buildRoots.map((root) => path.join(root, "build", "Release", "better_sqlite3.node")),
+    // Prebuilt layout — what `npm i -g omniroute` actually installs. Without
+    // these, doctor warns on every prebuilt install even though the binary is
+    // present and loading fine.
+    ...buildRoots.map((root) => path.join(root, "prebuilds", prebuildName)),
   ];
   const binaryPath = candidates.find((candidate) => fs.existsSync(candidate));
   if (!binaryPath) {

package-lock.json

@@ -13670,6 +13670,7 @@
       "version": "13.0.3",
       "resolved": "https://registry.npmjs.org/better-sqlite3/-/better-sqlite3-13.0.3.tgz",
       "integrity": "sha512-RbOBxmLBG8uvFUc15X9+9SFemKcQ0WBuISBVkpuiaUB2qblC8UWlHEjdWVoZ8AdhSwmoEgsiXKfopX0CQxaACQ==",
+      "hasInstallScript": true,
       "license": "MIT",
       "optional": true,
       "dependencies": {
@@ -24387,17 +24388,6 @@
         "node": ">= 14"
       }
     },
-    "node_modules/libxmljs2/node_modules/brace-expansion": {
-      "version": "2.1.4",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.1.4.tgz",
-      "integrity": "sha512-hGfVzPxthbf3+2yjg/RBs60cB0FhqBS/zvdV/4wn4/BmN0bNMMHPc4V/BbFieqf1TKAGGAHnY4eSjajCl0f2Xg==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "balanced-match": "^1.0.0"
-      }
-    },
     "node_modules/libxmljs2/node_modules/cacache": {
       "version": "19.0.1",
       "resolved": "https://registry.npmjs.org/cacache/-/cacache-19.0.1.tgz",

tests/unit/cli-doctor-prebuilt-native-binary-10083.test.ts

@@ -0,0 +1,91 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// #10083 — `doctor` only looked for the node-gyp layout
+// (build/Release/better_sqlite3.node), so every install that resolves a
+// prebuilt binary (`npm i -g omniroute`) warned "better-sqlite3 native binary
+// was not found" even though the binary was present and loading fine.
+
+const ORIGINAL_DATA_DIR = process.env.DATA_DIR;
+
+interface DoctorCheck {
+  name: string;
+  status: string;
+  message: string;
+  details: Record<string, unknown>;
+}
+
+function nativeBinaryCheck(result: { checks: DoctorCheck[] }) {
+  const check = result.checks.find((c) => c.name === "Native binary");
+  assert.ok(check, "expected a 'Native binary' check");
+  return check;
+}
+
+async function withTempRoot(fn: (rootDir: string) => Promise<void>) {
+  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "omniroute-prebuild-data-"));
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), "omniroute-prebuild-root-"));
+  process.env.DATA_DIR = dataDir;
+  try {
+    await fn(rootDir);
+  } finally {
+    fs.rmSync(dataDir, { recursive: true, force: true });
+    fs.rmSync(rootDir, { recursive: true, force: true });
+    if (ORIGINAL_DATA_DIR === undefined) delete process.env.DATA_DIR;
+    else process.env.DATA_DIR = ORIGINAL_DATA_DIR;
+  }
+}
+
+test("prebuiltBinaryName maps platform/arch the way better-sqlite3 ships them", async () => {
+  const { prebuiltBinaryName } = await import("../../bin/cli/commands/doctor.mjs");
+
+  assert.equal(prebuiltBinaryName("darwin", "arm64"), "darwin-arm64.node");
+  assert.equal(prebuiltBinaryName("win32", "x64"), "win32-x64.node");
+
+  // glibc Linux keeps the plain `linux-` prefix …
+  const glibcReport = { getReport: () => ({ header: { glibcVersionRuntime: "2.39" } }) };
+  assert.equal(prebuiltBinaryName("linux", "x64", glibcReport), "linux-x64.node");
+
+  // … while musl builds (no glibcVersionRuntime) use `linuxmusl-`.
+  const muslReport = { getReport: () => ({ header: {} }) };
+  assert.equal(prebuiltBinaryName("linux", "arm64", muslReport), "linuxmusl-arm64.node");
+});
+
+test("doctor finds a prebuilt better-sqlite3 binary instead of warning 'not found'", async () => {
+  await withTempRoot(async (rootDir) => {
+    const { collectDoctorChecks, prebuiltBinaryName } =
+      await import("../../bin/cli/commands/doctor.mjs");
+
+    const prebuildDir = path.join(rootDir, "node_modules", "better-sqlite3", "prebuilds");
+    fs.mkdirSync(prebuildDir, { recursive: true });
+    const binaryPath = path.join(prebuildDir, prebuiltBinaryName());
+    fs.writeFileSync(binaryPath, Buffer.alloc(64));
+
+    const result = await collectDoctorChecks({ rootDir }, { skipLiveness: true });
+    const check = nativeBinaryCheck(result);
+
+    assert.ok(
+      !/was not found/.test(check.message),
+      `expected the prebuild to be discovered, got: ${check.message}`
+    );
+    assert.equal(check.details.binaryPath, binaryPath);
+  });
+});
+
+test("doctor still warns when neither layout has a binary", async () => {
+  await withTempRoot(async (rootDir) => {
+    const { collectDoctorChecks } = await import("../../bin/cli/commands/doctor.mjs");
+
+    const result = await collectDoctorChecks({ rootDir }, { skipLiveness: true });
+    const check = nativeBinaryCheck(result);
+
+    assert.equal(check.status, "warn");
+    assert.match(check.message, /was not found/);
+    // Both layouts should be reported so the warning is actionable.
+    const candidates = check.details.candidates as string[];
+    assert.ok(candidates.some((c) => c.includes(path.join("build", "Release"))));
+    assert.ok(candidates.some((c) => c.includes("prebuilds")));
+  });
+});