npm install fails on Node 26 — better-sqlite3 11.x can't compile against current V8

[SuspiciousStank]

Installing from source on macOS (arm64, Node 26.7.0) fails at
better-sqlite3@11.10.0. There is no prebuilt binary for this ABI, so it falls
back to node-gyp rebuild, and the compile fails on V8 API removals:

prebuild-install warn install No prebuilt binaries found
  (target=26.7.0 runtime=node arch=arm64 libc= platform=darwin)

./src/util/binder.lzz:40:37: error: no member named 'GetPrototype' in 'v8::Object'
./src/better_sqlite3.lzz:68:34: error: no member named 'GetIsolate' in 'v8::Context'
./src/objects/database.lzz:416:89: error: no member named 'This' in
                                   'v8::PropertyCallbackInfo<v8::Value>'
gyp ERR! stack Error: `make` failed with exit code: 2

v8::Object::GetPrototype(), v8::Context::GetIsolate() and
PropertyCallbackInfo::This() have all been removed, so 11.x cannot build on
Node 26 at all.

The knock-on is confusing: the install failure means devDependencies never land
either, so the next thing you see is sh: tsc: command not found from
npm run build, which looks like a separate problem.

Fix

server/package.json currently pins:

"better-sqlite3": "^11.7.0"

^11 can't reach a compatible release. Bumping to ^13.0.0 resolves it —
13.0.3 installs and runs clean here (its engines is node: >=22):

better-sqlite3 OK -> { a: 42 }
version: 13.0.3

Worth verifying on Node 22/24 before taking it, since I've only tested 26.

One note in case it bites someone else: npm 11 now blocks lifecycle scripts by
default, so a native module can appear to install and then fail at runtime.
Worth a require('better-sqlite3') smoke check rather than trusting a clean
npm install.

Reporting note

Not a developer — Claude (Anthropic's coding agent) diagnosed this in my
checkout while helping me get the portal running without Docker. I've confirmed
the bumped version builds and the portal works; I can't vouch for the change
beyond that.

[SuspiciousStank]

Correction to my own suggestion — bumping to ^13.0.0 on its own breaks the
Docker build, and I should flag that before anyone acts on it.

better-sqlite3 13.x publishes no prebuilt binary for node 22 on linux/x64, so
npm install falls through to node-gyp, and node:22-slim carries no
toolchain. The failure surfaces a long way from the cause:

npm error path /app/node_modules/better-sqlite3
npm error gyp ERR! find Python
npm error gyp ERR! find Python Python is not set from command line or npm configuration

Adding the toolchain to the Dockerfile fixes it, and it is needed in both
stages — the runtime stage runs its own npm install --omit=dev -w server:

RUN apt-get update && apt-get install -y --no-install-recommends \
      python3 make g++ \
    && rm -rf /var/lib/apt/lists/*

So the full picture is a trade rather than a clean win:

• staying on 11.x — Docker builds fine, native install is impossible on Node 26
• moving to 13.x — native works on Node 26, Docker needs a toolchain and a fatter image

If most people run this in Docker, pinning 11.x and documenting "Node 22 only,
outside a container" may well be the better call. I only hit it because I run
the portal natively on macOS, where the host Node is 26.

Verified both ways on my side: 13.x + toolchain builds and runs clean on x86_64
Linux, and 13.x runs natively on macOS/Node 26.