@threadbase-sh/streamer 1.86.0 → 1.86.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@threadbase-sh/streamer",
-  "version": "1.86.0",
+  "version": "1.86.1",
   "description": "PTY session management, WebSocket streaming, and REST API server for Claude Code conversations",
   "license": "MIT",
   "author": "Ronen Mars",
@@ -37,7 +37,9 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "scripts/check-node-version.mjs",
+    "scripts/check-native-abi.mjs"
   ],
   "publishConfig": {
     "access": "public"

package/scripts/check-native-abi.mjs

@@ -0,0 +1,56 @@
+// Guards against a stale `better-sqlite3` native binary — one compiled for a
+// different Node ABI / OS / arch than the one running now (moved repo, upgraded
+// Node). Such a binary fails at require-time with a cryptic NODE_MODULE_VERSION
+// error deep in the server; this surfaces it up front with the fix command.
+//
+// Wired into `preinstall` (catch a no-op install that leaves a stale binary)
+// and `pretest` (fail fast instead of paying an unconditional rebuild).
+//
+// ponytail: only better-sqlite3 is checked. node-pty ships N-API prebuilds
+// (node-addon-api, .node files selected by platform-arch, ABI-stable across
+// Node versions) so it can't hit a NODE_MODULE_VERSION mismatch.
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// --warn downgrades the failure to a notice. Used by `preinstall`, because
+// `npm install` is one of the two remedies this check recommends — failing the
+// install hard makes the guard block its own fix, and the only escape becomes
+// `rm -rf node_modules` (the guard exits 0 when no binary exists at all).
+const warnOnly = process.argv.includes("--warn");
+
+const PKG = "better-sqlite3";
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const binary = join(root, "node_modules", PKG, "build", "Release", "better_sqlite3.node");
+
+// Fresh install (no node_modules yet, or package not installed): nothing to
+// compare against — a real install/rebuild will produce a matching binary.
+if (!existsSync(binary)) process.exit(0);
+
+// The authoritative test is whether *this* Node can dlopen the binary. A child
+// process isolates the (possibly fatal) load. dlopen failing on a binary that
+// exists means an ABI/OS/arch mismatch (NODE_MODULE_VERSION, wrong mach-o/ELF)
+// — exactly what this guard is for. exit 3 = dlopen threw; anything else (spawn
+// failure, unrelated crash) shouldn't block install/test.
+const probe = `try { process.dlopen({ exports: {} }, ${JSON.stringify(binary)}); }
+catch (e) { process.stderr.write(String(e && e.message || e)); process.exit(3); }`;
+const res = spawnSync(process.execPath, ["-e", probe], { encoding: "utf8" });
+
+if (res.status !== 3) process.exit(0);
+
+const err = (res.stderr || "").trim();
+console.error(`
+${warnOnly ? "⚠" : "✖"} ${PKG} native binary is incompatible with this Node.
+
+  Expected: Node ABI ${process.versions.modules}  ${process.platform}/${process.arch}  (node ${process.version})
+  Binary:   ${binary}
+  Loader error: ${err.replace(/\s+/g, " ").slice(0, 300)}
+
+The compiled binary was built for a different Node version, OS, or CPU arch.
+Fix it with one of:
+
+  npm rebuild ${PKG}
+  rm -rf node_modules && npm install
+`);
+process.exit(warnOnly ? 0 : 1);

package/scripts/check-node-version.mjs

@@ -0,0 +1,60 @@
+// Guards against running a build, test or deploy under a Node outside the
+// range this repo supports.
+//
+// The authority is `engines.node` in package.json — the same declaration npm
+// checks — because that is the range CI actually exercises. `.nvmrc` is the
+// exact version to develop against and is quoted as the suggestion, but it is
+// deliberately NOT the test: CI runs the matrix on several supported majors,
+// and a guard keyed to the single pinned version would reject them.
+//
+// Why this exists when `engines` already exists: npm only enforces it when the
+// consumer opts into `engine-strict`, and it never enforces it for a bare
+// `node scripts/…` invocation. `scripts/deploy.sh` runs in a subshell that does
+// not load nvm's lazy-init function, so its `node` is whatever the system
+// provides — which is how a deploy ends up building native modules for an ABI
+// the service cannot load, then "fixing" it with a rebuild that breaks the
+// other side. See docs/troubleshooting.md, "Native modules / ABI mismatches".
+//
+// ponytail: major-only bounds parsed from `>=A <B`, no semver dependency. Every
+// ABI break this guards against is a major change. If the range is ever written
+// in a shape this cannot parse, the check disables itself rather than guessing
+// — its absence is the status quo, a wrong verdict is not.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const warnOnly = process.argv.includes("--warn");
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+const read = (file) => {
+  try {
+    return readFileSync(join(root, file), "utf8");
+  } catch {
+    return null;
+  }
+};
+
+const pkg = read("package.json");
+const range = pkg ? (JSON.parse(pkg).engines?.node ?? "") : "";
+const min = range.match(/>=\s*(\d+)/)?.[1];
+const max = range.match(/<\s*(\d+)/)?.[1];
+if (!min && !max) process.exit(0); // Unparseable or absent — nothing to enforce.
+
+const major = Number(process.versions.node.split(".")[0]);
+if ((!min || major >= Number(min)) && (!max || major < Number(max))) process.exit(0);
+
+const suggested = read(".nvmrc")?.trim().replace(/^v/, "");
+console.error(`
+${warnOnly ? "⚠" : "✖"} Node ${process.version} is outside the range this repo supports (${range}).
+
+  Running: ${process.execPath}
+  Develop against: ${suggested ? `v${suggested} (.nvmrc)` : `Node ${min ?? "?"}.x`}
+
+Native modules are compiled per Node ABI, so building or deploying here produces
+binaries the supported Node cannot load — and the reverse. Switch before continuing:
+
+  nvm use            # or: fnm use / asdf install
+  nvm-windows: nvm use ${suggested?.split(".")[0] ?? min}   (no auto-cd hook — it must be explicit)
+`);
+
+process.exit(warnOnly ? 0 : 1);