chore(deps,middleware): bump better-sqlite3 to 13.0.3 (N-API)

[Weegy]

Closes the last open Dependabot PR from the 2026-08-03 batch. Supersedes #596, which proposed 13.0.2 and failed CI on middleware (build, no push).

What this is

better-sqlite3 v13 is the N-API rewrite. The addon no longer targets a specific Node ABI, and prebuilt binaries now ship inside the package for linux-x64/arm64, linuxmusl-x64/arm64, darwin-x64/arm64 and win32-x64/arm64 — the deprecated prebuild-install dependency is gone.

Taking 13.0.3 rather than the proposed 13.0.2; it adds the arm64 prebuild CI fix.

That has two nice consequences beyond the version bump:

• The ABI-mismatch saga is structurally over. No more NODE_MODULE_VERSION 137 ... requires 127 after an install under the wrong Node major.
• The dependency tree shrinks: bindings and prebuild-install disappear entirely (−246 lockfile lines).

Why #596 failed — and why this doesn't

Not a version-compatibility problem. npm ci runs node-gyp rebuild on better-sqlite3 even though the package declares gypfile: false and ships a matching prebuild. npm install honors the field; npm ci does not.

Reduced to a 5-line reproduction in node:22.23.2-slim:

npm init -y
npm install --package-lock-only better-sqlite3@13.0.3
npm ci            # -> node-gyp rebuild -> gyp ERR! find Python

npm	npm install	npm ci
10.9.8 (image default)	clean	compiles
11.19.0	clean	compiles
12.0.2	clean	compiles

So upgrading npm is not a fix. The slim image has no Python, and the build dies at gyp ERR! find Python.

The fix

Both npm ci calls in the root Dockerfile now pass --ignore-scripts, which lets the bundled prebuild be used, followed by an explicit rebuild of the packages that genuinely need their install script:

npm ci --ignore-scripts --no-audit --no-fund
npm rebuild argon2 esbuild          # builder stage

npm ci --omit=dev --ignore-scripts --no-audit --no-fund
npm rebuild argon2                  # runtime stage; esbuild is dev-only

--ignore-scripts here is load-bearing, not hardening theatre — and it is not a blind sweep. The lockfile lists exactly 4 packages with install scripts:

Package	Handling
argon2@0.45.1	explicitly rebuilt (native, fetches a prebuilt binary)
esbuild@0.28.1	explicitly rebuilt in the builder stage (dev-only)
omadia-middleware (this package)	its preinstall is the Node-version guard; the docker base image is Node 22
fsevents@2.3.3	optional, macOS-only, never installed in the linux image

Neither rebuild needs a compiler — both pull prebuilt binaries.

Trade-off worth stating: a future dependency that needs an install script will not get it silently. That is the cost of this approach. The alternative — installing python3/make/g++ into both stages — trades that footgun for a permanently larger image and a source build on every CI run, to work around a bug that will presumably be fixed upstream. I went with the smaller runtime surface; happy to flip it if you'd rather have the toolchain.

ensure-native-abi.mjs had to be rewritten

This was a hard blocker, not cosmetics. The script probed a hardcoded path:

node_modules/better-sqlite3/build/Release/better_sqlite3.node

v13 never produces that file — the binary lives in prebuilds/<platform>-<arch>.node. So on a correct v13 install the script ran a pointless npm rebuild, then exited 1, which breaks npm run dev (the dev script is node scripts/ensure-native-abi.mjs && ...).

The ABI-mismatch class of bug it guarded cannot happen under N-API, so the rebuild path is gone — forcing --build-from-source would now only demand a toolchain nobody needs. What remains is a genuine end-to-end probe: load the module, open an in-memory DB, run a query. That still catches a corrupt install, a partially extracted node_modules, or a platform with no prebuild — and it catches them at npm run dev instead of at first DB access.

Verified in both directions: exit 0 healthy, exit 1 with an actionable message when prebuilds/ is removed.

check-node-version.mjs keeps its behavior unchanged; only its comment is corrected, because it justified itself with the now-impossible ABI clobber. The Node pin still stands on its own — engines declares a single supported major.

Verification

Check	Result
docker build --platform linux/amd64	succeeds, zero gyp/Python output (was: exit 1)
better-sqlite3 in the built runtime image	v13.0.3, opens DB, insert + select, pragma journal_mode=WAL
argon2 in the built runtime image	hashes and verifies, $argon2id$
sharp in the built runtime image	encodes a 96-byte PNG
middleware build / lint / typecheck	clean, 0 errors
middleware tests	6094 pass / 0 fail (4 skipped)
npm audit --audit-level=high	exits 0
both guard scripts	exit 0; native-abi guard also verified to fail correctly

The four builder-plugin modules backed by better-sqlite3 (draftStore, workaroundStateStore, builderTriageLog, githubIssueCache) are covered by the suite.

Not affected: web-ui/Dockerfile (no better-sqlite3) and middleware/sidecars/dev-runner/Dockerfile (installs only the shim's three devDeps, via npm install, not npm ci).

Test plan

• Reproduced the chore(deps,middleware)(deps): bump better-sqlite3 from 12.11.1 to 13.0.3 in /middleware #596 failure locally, then confirmed the fix by building the same image
• Functional check of all three native modules inside the built runtime image
• Full middleware suite, lint, typecheck, audit
• Both guard scripts, positive and negative
• CI green (9 checks green on c250332e, 0 failures)

Merge prep (2026-08-10)

origin/main merged into the branch (14 commits, incl. the consolidated
Dependabot batch #638 which also touches middleware/package.json +
package-lock.json). Branch protection is strict: true, so this was required.

• No conflicts. package.json kept both sides: main's @modelcontextprotocol/sdk
  • --test-timeout and this PR's better-sqlite3 ^13.0.3.
• Lockfile re-derived, zero drift. npm install --package-lock-only after the
  merge changes nothing, so the auto-merged lockfile is genuinely self-consistent.
• The --ignore-scripts allowlist re-verified against the merged tree — still
  exactly 4 install-script packages (root, argon2, esbuild, fsevents);
  better-sqlite3 has dropped out, bindings and prebuild-install are absent.
  Nothing main added since needs an install script.

Re-verified on the merged tree: npm ci exit 0 with no gyp invocation, build /
lint / typecheck clean, 6094 tests pass / 0 fail, both audit gates exit 0, and the
linux/amd64 image builds with zero gyp/Python output.

Follow-up (not in this PR)

.github/dependabot.yml justifies the Node major-ignore with "the middleware ABI guard hard-pins NODE_MODULE_VERSION 127 for better-sqlite3, so a major Node bump silently breaks the native binary". After this PR that reason no longer holds. The ignore itself should stay — engines pins the major — but the comment deserves the same correction applied to check-node-version.mjs.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}