Load addons through Hermes' hermes_napi_load_module

[kraenhansen]

The vendored Hermes ships a first-party addon loader we were not using. At the pinned commit, API/napi/hermes_napi.h exposes:

napi_status hermes_napi_load_module(napi_env env, const char *path, napi_value *result);

which does exactly what CxxNodeApiHostModule did by hand — dlopen(RTLD_NOW | RTLD_LOCAL), resolve napi_register_module_v1, create an exports object, call the init function — plus the two things we never implemented: falling back to the module recorded by a napi_module_register call, and reporting failures as real errors.

This hands the platform specific path to it instead. The host keeps deciding what to load (library name → @rpath/<name>.framework/<name> or lib<name>.so) and keeps creating one napi_env per addon; Hermes does the loading and initializing.

AddonLoaders.hpp goes with it — the PosixLoader policy was its only user, and the Win32Loader / WinRTLoader variants next to it were never referenced.

Behavior changes

• Addons registering via the deprecated napi_module_register now load. Previously the host only looked for a napi_register_module_v1 export and, finding none, logged a debug line and resolved the require to undefined. See the note on verification below — this addresses Support module registration via calls to napi_module_register #3, but I'd rather not close it until something exercises the path.
• A failing requireNodeAddon throws instead of resolving to undefined, with a message naming the addon, the path tried, and the underlying reason (the dlopen error, or "no napi_register_module_v1 export and no registered napi_module"). Related: Would be good to have a debug log for failed module resolution #369.
• node_api_get_module_file_name reports the path the addon was loaded from. It reads env->moduleFileName_, which only hermes_napi_load_module sets, so it returned an empty string for every addon before this.
• Calling requireNodeAddon with anything other than a single string now throws instead of resolving to undefined (the // TODO: Throw a meaningful error that sat in that branch).

Handle scope

Loading and initializing now happens inside a napi_open_handle_scope / napi_close_handle_scope pair.

hermes_napi_load_module requires one, but this was already a latent bug: every napi_value in Hermes is a slot handed out by napi_env__::addToCurrentScope, and napi_env__::markHandleScopes returns early when the scope stack is empty, so the exports object the host created on a fresh env and passed to the addon's init function was not a GC root. A collection triggered by the addon while it populated exports could free it. The env constructor pre-allocates the first handle block, so the empty-stack path did not read out of bounds — it just produced unrooted values (and tripped the "addToCurrentScope called with no open handle scope" assert in debug builds).

Verification

Syntax-checked for __APPLE__ and __ANDROID__, debug and release, under -Wall -Wextra, against stub JSI/TurboModule headers — the host C++ test target only compiles HermesNapiHost.cpp and Logger.cpp, so this file is not covered by host-cpp-tests. The real check is the label-gated iOS/Android test app runs, hence the labels on this PR.

Not verified: the deprecated napi_module_register path, because no fixture in the repo uses it. #104 added one (node-addon-examples/.../2_function_arguments_twisted) that could be salvaged for this.

Follow-ups, not in this PR

• Support Node-API modules declaring their "Node-API version" #4 (addon-declared Node-API version) is blocked upstream, and I've updated that issue with the detail: napi_env__::module_api_version is fixed at NAPI_VERSION, hermes_napi_create_env takes no version, and hermes_napi_load_module reads neither node_api_module_get_api_version_v1 nor nm_version. Detecting the version here is easy; there is nowhere to put the answer. Wants an issue on facebook/hermes.
• Moving the library-name mapping out of the Babel plugin (Extend requireNodeAddon(path) to support more use-cases #91, Refactor requireNodeAddon to take the package name and extension-less path of an addon #222, and the 3-argument requireNodeAddon in Refactor C++ loader: extract cache and addon registry, resolve TODOs #104) is deliberately untouched here. Worth noting for whoever picks it up: the mangled name is a build artifact, not just a lookup key — getLibraryName() also drives link-modules, which renames the .so/.framework to match — so any runtime-side mapping has to agree with the naming strategy the build used.

---

Generated by Claude Code