fix: block Node 24 WASM crash path

[zaidazmi]

Summary

• block Node.js 24+ before CodeGraph starts tree-sitter WASM grammar compilation
• reuse the compatibility check for both CLI startup and library init/open paths
• narrow package engine metadata and README guidance to supported Node 18/20/22
• add unit coverage for version parsing, unsafe-runtime blocking, override behavior, and the recovery banner

Repro

On Node v24.13.0, before this fix, the extraction suite crashed during grammar compilation with Fatal process out of memory: Zone. Node v20.19.4 completes the same extraction suite successfully.

Test plan

• npx vitest run __tests__/node-version-check.test.ts
• npm run build
• node dist/bin/codegraph.js --version on Node v24.13.0 exits with the unsupported-runtime banner
• CODEGRAPH_ALLOW_UNSAFE_NODE=1 node dist/bin/codegraph.js --version on Node v24.13.0 prints the banner and version
• direct library construction on Node v24.13.0 throws the unsupported-runtime banner before grammar compilation
• PATH="/Users/zaidazmi/.nvm/versions/node/v20.19.4/bin:/Users/zaidazmi/.codex/tmp/arg0/codex-arg0N0CH7a:/Users/zaidazmi/.bun/bin:/Users/zaidazmi/.antigravity/antigravity/bin:/Users/zaidazmi/.opencode/bin:/Users/zaidazmi/.nvm/versions/node/v24.13.0/bin:/Users/zaidazmi/.rbenv/shims:/Users/zaidazmi/.local/pipx/venvs/pip/bin:/opt/homebrew/bin:/opt/homebrew/sbin:/Users/zaidazmi/.rbenv/shims:/usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/local/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/appleinternal/bin:/opt/pkg/env/active/bin:/opt/pmk/env/global/bin:/Library/Apple/usr/bin:/usr/local/share/dotnet:~/.dotnet/tools:/Library/Frameworks/Mono.framework/Versions/Current/Commands:/Users/zaidazmi/.cargo/bin:/Users/zaidazmi/.local/bin:/Users/zaidazmi/Library/Android/sdk/emulator:/Users/zaidazmi/Library/Android/sdk/platform-tools:/Users/zaidazmi/.local/bin:/opt/homebrew/opt/fzf/bin:/Users/zaidazmi/.lmstudio/bin:/Applications/Codex.app/Contents/Resources" npm run build
• PATH="/Users/zaidazmi/.nvm/versions/node/v20.19.4/bin:/Users/zaidazmi/.codex/tmp/arg0/codex-arg0N0CH7a:/Users/zaidazmi/.bun/bin:/Users/zaidazmi/.antigravity/antigravity/bin:/Users/zaidazmi/.opencode/bin:/Users/zaidazmi/.nvm/versions/node/v24.13.0/bin:/Users/zaidazmi/.rbenv/shims:/Users/zaidazmi/.local/pipx/venvs/pip/bin:/opt/homebrew/bin:/opt/homebrew/sbin:/Users/zaidazmi/.rbenv/shims:/usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/local/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/appleinternal/bin:/opt/pkg/env/active/bin:/opt/pmk/env/global/bin:/Library/Apple/usr/bin:/usr/local/share/dotnet:~/.dotnet/tools:/Library/Frameworks/Mono.framework/Versions/Current/Commands:/Users/zaidazmi/.cargo/bin:/Users/zaidazmi/.local/bin:/Users/zaidazmi/Library/Android/sdk/emulator:/Users/zaidazmi/Library/Android/sdk/platform-tools:/Users/zaidazmi/.local/bin:/opt/homebrew/opt/fzf/bin:/Users/zaidazmi/.lmstudio/bin:/Applications/Codex.app/Contents/Resources" npm test

[akrueger74]

I am relatively new to working with WASM in Node, but blocking this crash path makes sense as a safety measure. Just curious, why did you choose to handle the Node 24 crash path this specific way? Either way, I agree with the approach here.

[colbymchenry]

Thanks for the thorough work here, @zaidazmi — the repro, the override env var, and the unit coverage were all solid. Unfortunately this has been overtaken by a different architecture for the same crash, and the specific direction (block Node 24+) now conflicts with how CodeGraph ships.

What changed: the Node-24 turboshaft WASM Zone OOM is now solved with the V8 flag --liftoff-only (the only flag that actually prevents it), applied at every launch path — the CLI re-exec (relaunchWithWasmRuntimeFlagsIfNeeded), the bundled launcher (scripts/build-bundle.sh), and the npm shim (scripts/npm-shim.js). CodeGraph also now bundles its own Node runtime and uses node:sqlite.

Why blocking Node 24+ no longer works:

• The bundled runtime is Node 24.16.0, so a >= 24 block would make the shipped product refuse to run itself.
• Narrowing engines to 18/20/22 conflicts with node:sqlite, which doesn't exist in Node 18.
• Node 24 is now a supported, working target via --liftoff-only, not something to block.

Closing as superseded — this reflects the architecture shift, not the quality of the PR. Genuinely appreciate the contribution and hope you'll send more. 🙏