Revive for modern Node.js: Node-API, vendored Lua, tests, CI

[mschmicking]

Why

The package did not build. Two independent reasons:

1. NAN no longer compiles. It tracks V8's unstable C++ API. On Node 26 the build fails with 20 errors inside nan.h itself — v8::String::REPLACE_INVALID_UTF8 and Isolate::IdleNotificationDeadline were removed, and GetAlignedPointerFromInternalField changed signature. No change to our own code could have fixed this.
2. It could not install on most machines. maclualib/lib/liblua.a was an x86_64-only Mach-O, so every Apple Silicon Mac failed. Linux hardcoded /usr/local/lib/libluajit-5.1.so, which the user had to build by hand. No ARM64 support anywhere. Only Windows x64 worked out of the box.

Goal: get it working, and back on npm so people can actually use Lua from Node.

What changed

Binding layer: NAN → Node-API (node-addon-api). Node-API is ABI-stable, so one build keeps working across future Node majors rather than needing a release every time Node ships one. This is the change that stops the maintenance treadmill.

Lua engine: vendored from source. Lua 5.1.5 (29 C files) and LuaFileSystem 1.8.0 now compile into the addon. maclualib/ and win64luajit/ are deleted. Builds on every platform and architecture, with no system dependency.

• LuaJIT is dropped. Only Windows ever had it — macOS already shipped stock Lua 5.1.5 despite what the README claimed. In exchange, Apple Silicon and ARM64 Linux work at all.
• require('lfs') now works everywhere. It used to be a Windows-only prebuilt DLL loaded through an LUA_CPATH hack in index.js. It is now compiled in and registered via package.preload.

Staying on the Lua 5.1 line is deliberate: LUA_GLOBALSINDEX is part of the public API here and 5.2+ removed it.

Bug fixes

All user-visible, which is why this is a major version.

Fix	Impact
SetField pushed its key as the value	Every SetField wrote the field name into the field
SetField did not resolve a relative index before pushing	SetField(-1, ...) indexed into the value → unprotected Lua error → aborted the process
LoadFile/LoadString were bound to the DoFile/DoString handlers	They executed instead of only compiling; the real implementations were dead code
AddPackagePath appended to package.path with no ; separator	Corrupted the last entry, so require usually failed — the lua_require example never worked
AddPackagePath interpolated the path into generated Lua source	A path containing a quote broke out of the string literal
Booleans converted with Nan::New((int)...)	Arrived in JS as 1/0 instead of true/false
Push used lua_pushinteger	Push(3.5) truncated to 3
Table conversion used a hardcoded relative index	Only worked when the table sat on top of the stack
get_str malloc'd and never freed	Leaked on every string argument
Six sprintf calls into a fixed char buf[1024]	Arbitrary-length Lua error messages overflowed a stack buffer
~LuaState never called lua_close; double Close	Leaked the interpreter; second Close was a use-after-free

Close is now idempotent and any later use of the state throws. SetField/GetField reject non-table targets rather than letting Lua abort the process.

Registered callbacks are now found through a closure upvalue instead of a global singleton — this was less code than porting the singleton across, and it means two LuaState instances no longer clash.

Tests and CI

• 62-case suite on node:test (zero new dependencies), with explicit regression tests pinning each fix above.
• GitHub Actions matrix: Linux / macOS / Windows × Node 20, 22, 24. macos-latest is arm64 — precisely the configuration that could not build before.

Verification

Locally on aarch64 Linux: 62/62 tests pass, all three examples run (including lua_lfs, which has never worked off Windows), and the packed tarball — 66 files, no build/, both third-party licenses included — unpacks, compiles and passes a smoke test in a clean directory.

Windows and macOS could not be tested locally. The CI matrix is the gate; do not publish until all nine cells are green.

Notes for the reviewer

• binding.gyp defaults android_ndk_path, which Node's common.gypi dereferences but never defines. Harmless off Android, and it makes Termux builds work.
• .npmignore is replaced by a files allowlist in package.json — getting this wrong is the likeliest way to publish a broken 2.0.0, so the tarball contents are asserted in CI via npm pack --dry-run.
• homepage/repository pointed at the old 0x7878 handle and rendered as broken links on npm. Fixed, and bugs added.
• Unrelated to this PR: npm 12 blocks install scripts by default, so users will need npm install-scripts approve node-lua-runner. This affects every native addon; the only real escape is shipping prebuilt binaries, deliberately left out of scope.

🤖 Generated with Claude Code