Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

fix(cli): select a Node runtime matching native bindings

Yuting Zhongd3bc50a8faea
diff --git a/notfair/bin/cli.mjs b/notfair/bin/cli.mjs
index dd9d1bd5..b2d00d01 100755
--- a/notfair/bin/cli.mjs
+++ b/notfair/bin/cli.mjs
@@ -27,7 +27,10 @@ import { createServer } from "node:net";
import { Command } from "commander";
import open from "open";
-import { syncStandaloneNativeBindings } from "./native-bindings.mjs";
+import {
+ resolveCompatibleNodeRuntime,
+ syncStandaloneNativeBindings,
+} from "./native-bindings.mjs";
const CLI_PATH = fileURLToPath(import.meta.url);
const __dirname = dirname(CLI_PATH);
@@ -94,6 +97,7 @@ program
// Next.js standalone output omits .next/static and public by default; copy
// them in if they're missing so the server can serve CSS/JS chunks.
ensureStandaloneAssets();
+ const serverNode = resolveCompatibleNodeRuntime(PKG_ROOT);
syncStandaloneNativeBindings(PKG_ROOT);
const url = `http://127.0.0.1:${port}`;
@@ -110,7 +114,7 @@ program
};
if (opts.foreground) {
- const child = spawn("node", [standalonePath], { stdio: "inherit", env });
+ const child = spawn(serverNode, [standalonePath], { stdio: "inherit", env });
writeState(opts.dataDir, {
pid: child.pid,
port,
@@ -147,7 +151,7 @@ program
// the server actually answers HTTP.
mkdirSync(dirname(logFile(opts.dataDir)), { recursive: true });
const fd = openSync(logFile(opts.dataDir), "a");
- const child = spawn("node", [standalonePath], {
+ const child = spawn(serverNode, [standalonePath], {
detached: true,
stdio: ["ignore", fd, fd],
env,
diff --git a/notfair/bin/native-bindings.mjs b/notfair/bin/native-bindings.mjs
index 353b2f60..3cc5d8c7 100644
--- a/notfair/bin/native-bindings.mjs
+++ b/notfair/bin/native-bindings.mjs
@@ -1,13 +1,9 @@
+import { spawnSync } from "node:child_process";
import { copyFileSync, existsSync, readdirSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
-/**
- * npm builds the top-level better-sqlite3 dependency for the Node.js version
- * that installed NotFair. Next.js also ships traced copies compiled on the
- * release builder, so refresh those copies before every server start.
- */
-export function syncStandaloneNativeBindings(packageRoot) {
- const runtimeBinding = join(
+function runtimeBindingPath(packageRoot) {
+ return join(
packageRoot,
"node_modules",
"better-sqlite3",
@@ -15,6 +11,59 @@ export function syncStandaloneNativeBindings(packageRoot) {
"Release",
"better_sqlite3.node",
);
+}
+
+function packagePrefixNode(packageRoot, platform = process.platform) {
+ const prefix = dirname(dirname(dirname(packageRoot)));
+ return platform === "win32" ? join(prefix, "node.exe") : join(prefix, "bin", "node");
+}
+
+function probeNativeBinding(nodePath, bindingPath) {
+ const result = spawnSync(
+ nodePath,
+ ["-e", "require(process.argv[1])", bindingPath],
+ { stdio: "ignore", timeout: 5_000 },
+ );
+ return result.status === 0 && !result.error;
+}
+
+/**
+ * A globally installed CLI can be launched through a different Node manager
+ * than the one npm used for installation. Native addons belong to the
+ * installing Node ABI, so run the standalone server with a Node executable
+ * that can actually load the installed binding.
+ */
+export function resolveCompatibleNodeRuntime(
+ packageRoot,
+ {
+ execPath = process.execPath,
+ platform = process.platform,
+ probe = probeNativeBinding,
+ } = {},
+) {
+ const binding = runtimeBindingPath(packageRoot);
+ if (!existsSync(binding)) return execPath;
+
+ const candidates = [
+ ...new Set([execPath, packagePrefixNode(packageRoot, platform)]),
+ ];
+ for (const candidate of candidates) {
+ if (existsSync(candidate) && probe(candidate, binding)) return candidate;
+ }
+
+ throw new Error(
+ `The installed better-sqlite3 binding is incompatible with the available Node.js runtimes. ` +
+ `Reinstall NotFair with the active Node.js version: npm install -g notfair@latest`,
+ );
+}
+
+/**
+ * npm builds the top-level better-sqlite3 dependency for the Node.js version
+ * that installed NotFair. Next.js also ships traced copies compiled on the
+ * release builder, so refresh those copies before every server start.
+ */
+export function syncStandaloneNativeBindings(packageRoot) {
+ const runtimeBinding = runtimeBindingPath(packageRoot);
if (!existsSync(runtimeBinding)) return 0;
const targets = [];
diff --git a/notfair/src/server/native-bindings.test.ts b/notfair/src/server/native-bindings.test.ts
index da5fcd61..3a331a7e 100644
--- a/notfair/src/server/native-bindings.test.ts
+++ b/notfair/src/server/native-bindings.test.ts
@@ -1,9 +1,12 @@
import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
import { describe, expect, it } from "vitest";
-import { syncStandaloneNativeBindings } from "../../bin/native-bindings.mjs";
+import {
+ resolveCompatibleNodeRuntime,
+ syncStandaloneNativeBindings,
+} from "../../bin/native-bindings.mjs";
describe("syncStandaloneNativeBindings", () => {
it("refreshes release-built bindings before a fresh CLI start", async () => {
@@ -45,4 +48,117 @@ describe("syncStandaloneNativeBindings", () => {
await rm(packageRoot, { recursive: true, force: true });
}
});
+
+ it("uses the package prefix Node when the shell Node cannot load the installed binding", async () => {
+ const prefix = await mkdtemp(join(tmpdir(), "notfair-cli-runtime-"));
+ const packageRoot = join(prefix, "lib", "node_modules", "notfair");
+ const binding = join(
+ packageRoot,
+ "node_modules",
+ "better-sqlite3",
+ "build",
+ "Release",
+ "better_sqlite3.node",
+ );
+ const shellNode = join(prefix, "shell", "node");
+ const installedNode = join(prefix, "bin", "node");
+
+ try {
+ await Promise.all([
+ mkdir(dirname(binding), { recursive: true }),
+ mkdir(dirname(shellNode), { recursive: true }),
+ mkdir(dirname(installedNode), { recursive: true }),
+ ]);
+ await Promise.all([
+ writeFile(binding, "node-25-binding"),
+ writeFile(shellNode, "node-24"),
+ writeFile(installedNode, "node-25"),
+ ]);
+
+ expect(
+ resolveCompatibleNodeRuntime(packageRoot, {
+ execPath: shellNode,
+ probe: (candidate: string) => candidate === installedNode,
+ }),
+ ).toBe(installedNode);
+ } finally {
+ await rm(prefix, { recursive: true, force: true });
+ }
+ });
+
+ it("keeps the active Node when it can load the installed binding", async () => {
+ const prefix = await mkdtemp(join(tmpdir(), "notfair-cli-runtime-"));
+ const packageRoot = join(prefix, "lib", "node_modules", "notfair");
+ const binding = join(
+ packageRoot,
+ "node_modules",
+ "better-sqlite3",
+ "build",
+ "Release",
+ "better_sqlite3.node",
+ );
+ const shellNode = join(prefix, "shell", "node");
+ const probed: string[] = [];
+
+ try {
+ await Promise.all([
+ mkdir(dirname(binding), { recursive: true }),
+ mkdir(dirname(shellNode), { recursive: true }),
+ ]);
+ await Promise.all([
+ writeFile(binding, "node-25-binding"),
+ writeFile(shellNode, "node-25"),
+ ]);
+
+ expect(
+ resolveCompatibleNodeRuntime(packageRoot, {
+ execPath: shellNode,
+ probe: (candidate: string) => {
+ probed.push(candidate);
+ return candidate === shellNode;
+ },
+ }),
+ ).toBe(shellNode);
+ expect(probed).toEqual([shellNode]);
+ } finally {
+ await rm(prefix, { recursive: true, force: true });
+ }
+ });
+
+ it("fails with reinstall guidance when no available Node can load the binding", async () => {
+ const prefix = await mkdtemp(join(tmpdir(), "notfair-cli-runtime-"));
+ const packageRoot = join(prefix, "lib", "node_modules", "notfair");
+ const binding = join(
+ packageRoot,
+ "node_modules",
+ "better-sqlite3",
+ "build",
+ "Release",
+ "better_sqlite3.node",
+ );
+ const shellNode = join(prefix, "shell", "node");
+ const installedNode = join(prefix, "bin", "node");
+
+ try {
+ await Promise.all([
+ mkdir(dirname(binding), { recursive: true }),
+ mkdir(dirname(shellNode), { recursive: true }),
+ mkdir(dirname(installedNode), { recursive: true }),
+ ]);
+ await Promise.all([
+ writeFile(binding, "node-25-binding"),
+ writeFile(shellNode, "node-24"),
+ writeFile(installedNode, "node-23"),
+ ]);
+
+ expect(() =>
+ resolveCompatibleNodeRuntime(packageRoot, {
+ execPath: shellNode,
+ probe: () => false,
+ }),
+ ).toThrow("npm install -g notfair@latest");
+ } finally {
+ await rm(prefix, { recursive: true, force: true });
+ }
+ });
});