@gjsify/node-gi 0.36.0 → 0.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/node-gi",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "description": "GObject-Introspection runtime for Node.js — load gi:// namespaces (GLib/GObject/Gio/…) with GJS-compatible semantics. Vendored + rewritten from node-gtk under MIT.",
   "type": "module",
   "license": "MIT",

package/scripts/install.mjs

@@ -1,72 +1,49 @@
 #!/usr/bin/env node
 // SPDX-License-Identifier: MIT
 // @gjsify/node-gi — the `install` lifecycle script. Use the SHIPPED PREBUILD when
-// this package carries one for the host, and run the node-gyp source build only
-// when it does not. The source build is the FALLBACK, not the default.
+// this package carries one for the host; the node-gyp source build is the FALLBACK.
 //
-// THE FAILURE THIS REPLACES. Until this script existed, `package.json` declared
+// THE FAILURE THIS REPLACES. `package.json` used to declare
 // `"install": "node-gyp rebuild"`, which npm/yarn/pnpm run on EVERY install — a
-// shipped prebuild could not prevent it. Measured on a `windows-latest` runner
-// against `@gjsify/node-gi@0.26.1`, whose tarball DOES contain
-// `prebuilds/win32-x64/node_gi.node`:
-//
-//     win-gi-gyp-flags: import lib for 'girepository-2.0' not found
-//     gyp ERR! configure error
-//     → npm rolls the install back; the package is not installed at all
-//
-// So on any machine without the GTK/GObject-Introspection development toolchain
-// — i.e. every end user — `npm install @gjsify/node-gi` FAILED, prebuild or not,
-// and it failed by uninstalling the package rather than by degrading. The
-// prebuild was reachable only through `gjsify install`, which deliberately runs
-// no lifecycle scripts; that asymmetry is the whole reason
-// `gjsify showcase --runtime node` worked on Windows while a plain npm
-// dependency on the same version could not be installed.
+// shipped prebuild could not prevent it. So on any machine without the
+// GTK/GObject-Introspection development toolchain (i.e. every end user)
+// `npm install @gjsify/node-gi` FAILED even when the tarball carried the right
+// prebuild, and it failed by npm rolling the install back rather than by degrading.
+// The prebuild was reachable only through `gjsify install`, which deliberately runs
+// no lifecycle scripts — which is why `gjsify showcase --runtime node` worked on
+// Windows while a plain npm dependency on the same version could not be installed.
 //
 // WHY EXISTENCE, NOT LOADABILITY, IS THE GATE. The obvious-looking alternative
-// (`node-gyp-build`) gates on its `node-gyp-build-test` bin, which `require()`s
-// the addon and falls back to a source build if the load throws. On exactly the
-// platforms whose whole point is the prebuild that is a FALSE NEGATIVE: the
-// win32/darwin addon's DLL/dylib closure is only findable after
-// `gtk-runtime.js` has wired the batteries-included GTK bundle into `PATH` /
-// `DYLD_FALLBACK_LIBRARY_PATH`, which `index.js` does at import time and a bare
-// install-time `require()` of the `.node` never does. A load-based gate would
-// therefore call a perfectly good prebuild broken and rebuild — reproducing the
-// exact failure above. Existence of the file the loader actually probes is the
-// honest question at install time; whether it LOADS is what the release
-// workflow's per-target load test answers (release.yml runs
-// `NODE_GI_NATIVE=prebuild node --test test/smoke.test.mjs` on every leg), where
-// there is a real GTK to load against.
+// (`node-gyp-build`) gates on a bin that `require()`s the addon and falls back to a
+// source build if the load throws. On exactly the platforms whose whole point is the
+// prebuild that is a FALSE NEGATIVE: the win32/darwin addon's DLL/dylib closure is
+// only findable after `gtk-runtime.js` has wired the batteries-included GTK bundle
+// into `PATH` / `DYLD_FALLBACK_LIBRARY_PATH`, which `index.js` does at import time
+// and a bare install-time `require()` of the `.node` never does. A load-based gate
+// would therefore call a perfectly good prebuild broken and rebuild. Existence of the
+// file the loader actually probes is the honest question at install time; whether it
+// LOADS is what release.yml's per-target load test answers, against a real GTK.
 //
-// WHY NOT DEPEND ON `node-gyp-build` (verified, not assumed):
-//   • its skip gate is that false-negative load test (above) — the disqualifier;
-//   • its probe order is `build/` FIRST, then the prebuild, the OPPOSITE of
-//     node-gi's deliberate consumer default (see native-paths.js
-//     `nativeCandidates`), so the two would disagree about which binary matters;
-//   • it cannot produce ONE actionable diagnosis — on failure it propagates a
-//     bare node-gyp exit code, which is the status quo this change removes;
-//   • it would add a runtime `dependencies` entry to a Tier-2 package whose dep
-//     surface is otherwise just `node-addon-api`, to make a decision this
-//     package can make from its own already-shared probe.
-//   (It would, contrary to first assumption, MATCH the `node_gi.node` filename:
-//   node-gyp-build 4.8.4's `matchTags` treats a missing runtime tag as
-//   permissive — checked against the installed copy. The filename was not the
-//   blocker; the gate and the message are.)
+// WHY NOT DEPEND ON `node-gyp-build` (verified, not assumed): that false-negative
+// load gate; its probe order is `build/` FIRST then the prebuild, the OPPOSITE of
+// node-gi's deliberate consumer default (`native-paths.js` `nativeCandidates`), so
+// the two would disagree about which binary matters; it propagates a bare node-gyp
+// exit code instead of one actionable diagnosis; and it would add a runtime
+// dependency to a package whose dep surface is otherwise just `node-addon-api`. (It
+// WOULD match the `node_gi.node` filename — node-gyp-build 4.8.4's `matchTags` treats
+// a missing runtime tag as permissive. The filename was never the blocker.)
 //
-// THE SOURCE BUILD MUST KEEP WORKING, and does. `prebuilds/` is gitignored
-// (packages/node-gi/node-gi/.gitignore), so a fresh checkout has none and this
-// script builds exactly as before — which is what the ~12 `npm install
-// --foreground-scripts` steps in node-gi.yml and the three
-// `node-gi-prebuild-*` legs in release.yml rely on to produce
-// `build/Release/node_gi.node` for `scripts/stage-prebuild.mjs`. Depending on a
-// directory being ABSENT is too implicit to be the only guarantee, so the build
-// is also forceable: `NODE_GI_BUILD_FROM_SOURCE=1` (or npm's own
-// `--build-from-source`, which sets `npm_config_build_from_source=true`) skips
-// the prebuild check entirely. `npm run build:native` / `build:prebuild` /
-// `rebuild` still invoke `node-gyp` directly and are untouched by this script.
+// THE SOURCE BUILD MUST KEEP WORKING, and does. `prebuilds/` is gitignored, so a
+// fresh checkout has none and this script builds exactly as before — which is what
+// node-gi.yml's `npm install --foreground-scripts` steps and release.yml's
+// `node-gi-prebuild-*` legs rely on to produce `build/Release/node_gi.node` for
+// `scripts/stage-prebuild.mjs`. Depending on a directory being ABSENT is too implicit
+// to be the only guarantee, so the build is also forceable:
+// `NODE_GI_BUILD_FROM_SOURCE=1`, or npm's own `--build-from-source`.
 //
-// FAIL-SAFE DIRECTION: every uncertain branch builds. Only a positively
-// confirmed prebuild file for this exact host skips the build, so a bug here
-// degrades to the previous behaviour rather than to a package with no addon.
+// FAIL-SAFE DIRECTION: every uncertain branch builds. Only a positively confirmed
+// prebuild file for this exact host skips the build, so a bug here degrades to the
+// previous behaviour rather than to a package with no addon.
 import { existsSync, readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { createRequire } from 'node:module';
@@ -75,15 +52,13 @@ import { hostTarget, packageRoot, prebuildAddonPath } from '../native-paths.js';
 
 const target = hostTarget();
 
-/** `1`/`true` on an env var, tolerant of the shapes people actually type. */
 const isEnabled = (value) => value === '1' || value === 'true';
 
 /**
- * Did the user explicitly ask for a source build? `NODE_GI_BUILD_FROM_SOURCE` is
- * ours; `npm_config_build_from_source` is what npm exports for
- * `--build-from-source` (the flag every node-gyp-build package honours), so a CI
- * job or a maintainer can force the build without knowing node-gi's own name for
- * it.
+ * Did the user explicitly ask for a source build? `npm_config_build_from_source` is
+ * what npm exports for `--build-from-source` (the flag every node-gyp-build package
+ * honours), so CI or a maintainer can force the build without knowing node-gi's own
+ * env var name.
  */
 const buildFromSourceRequested = () =>
     isEnabled(process.env.NODE_GI_BUILD_FROM_SOURCE) || process.env.npm_config_build_from_source === 'true';
@@ -102,15 +77,14 @@ function declaredPlatforms() {
 }
 
 /**
- * Run `node-gyp rebuild` in the package root, inheriting stdio so the real
- * compiler output stays visible (it is the actual diagnosis; the framed message
- * below only tells the reader what to DO about it).
+ * Run `node-gyp rebuild` in the package root, inheriting stdio so the real compiler
+ * output stays visible — it is the actual diagnosis; the framed message below only
+ * tells the reader what to DO about it.
  *
- * node-gyp is resolved the way node-gyp-build's own bin does: prefer node-gyp's
- * JS entry if it happens to be resolvable, else the `node-gyp` shim that npm,
- * yarn and pnpm all put on `PATH` for lifecycle scripts (`node-gyp.cmd` on
- * Windows, hence `shell` there).
- * @returns {{ status: number, error?: Error }}
+ * node-gyp is resolved the way node-gyp-build's own bin does: prefer node-gyp's JS
+ * entry if it happens to be resolvable, else the `node-gyp` shim that npm, yarn and
+ * pnpm all put on `PATH` for lifecycle scripts (`node-gyp.cmd` on Windows, hence
+ * `shell` there).
  */
 function runNodeGyp() {
     const win32 = process.platform === 'win32';
@@ -118,11 +92,11 @@ function runNodeGyp() {
     let args = ['rebuild'];
     let shell = win32;
     try {
-        // Only succeeds when node-gyp is genuinely resolvable from here; npm's
-        // bundled copy lives in npm's own tree and is not, which is why the PATH
-        // shim above stays the normal path. `createRequire().resolve` rather than
-        // `import.meta.resolve` — the latter is only synchronous from Node 20.6,
-        // and `engines.node` is `>=20`.
+        // Only succeeds when node-gyp is genuinely resolvable from here; npm's bundled
+        // copy lives in npm's own tree and is not, which is why the PATH shim above
+        // stays the normal path. `createRequire().resolve` rather than
+        // `import.meta.resolve` — the latter is only synchronous from Node 20.6, and
+        // `engines.node` is `>=20`.
         const entry = createRequire(import.meta.url).resolve('node-gyp/bin/node-gyp.js');
         command = process.execPath;
         args = [entry, 'rebuild'];
@@ -135,12 +109,11 @@ function runNodeGyp() {
 }
 
 /**
- * Are we running inside a source CHECKOUT rather than an installed tarball?
- * Keyed on two paths `files` deliberately does not publish (`test/` and the
- * staging tool), because the distinction changes the advice: in a checkout
- * `prebuilds/` is gitignored, so its absence is expected and the source build IS
- * the path; in an installed copy a missing prebuild for a PROMISED target is a
- * packaging regression the consumer should report instead of debugging.
+ * Are we running inside a source CHECKOUT rather than an installed tarball? Keyed on
+ * two paths `files` deliberately does not publish (`test/` and the staging tool),
+ * because the distinction changes the advice: in a checkout `prebuilds/` is gitignored
+ * so its absence is expected and the source build IS the path; in an installed copy a
+ * missing prebuild for a PROMISED target is a packaging regression to report.
  */
 function isRepoCheckout() {
     return existsSync(join(packageRoot, 'test')) || existsSync(join(packageRoot, 'scripts', 'stage-prebuild.mjs'));
@@ -149,12 +122,11 @@ function isRepoCheckout() {
 /**
  * ONE actionable message for "no usable prebuild AND the source build did not
  * succeed" — the case that used to surface as nothing but a node-gyp stack. It
- * distinguishes the three very different reasons the prebuild was missing,
- * because the reader's next action differs each time: a checkout is SUPPOSED to
- * build; an undeclared platform means "build it yourself or use a supported
- * target"; and a DECLARED platform with no artifact in an installed copy is a
- * packaging regression that should be reported, not worked around (precisely how
- * 0.26.0 shipped `prebuilds/linux-*` only while promising four targets — and
+ * distinguishes the three reasons the prebuild was missing, because the reader's next
+ * action differs each time: a checkout is SUPPOSED to build; an undeclared platform
+ * means "build it yourself or use a supported target"; a DECLARED platform with no
+ * artifact in an installed copy is a packaging regression to report, not to work
+ * around (0.26.0 shipped `prebuilds/linux-*` only while promising four targets, and
  * nothing told the consumer).
  */
 function reportFailure(status, spawnError) {
@@ -204,8 +176,8 @@ function reportFailure(status, spawnError) {
 
 function main() {
     // Deliberately first: an explicit "do not build" wins over everything, so a
-    // consumer on an unsupported platform can complete an install and supply an
-    // addon via NODE_GI_NATIVE afterwards.
+    // consumer on an unsupported platform can complete an install and supply an addon
+    // via NODE_GI_NATIVE afterwards.
     if (isEnabled(process.env.NODE_GI_SKIP_NATIVE_BUILD)) {
         console.log(
             `@gjsify/node-gi: NODE_GI_SKIP_NATIVE_BUILD is set — skipping the native addon for ${target}. ` +
@@ -227,11 +199,10 @@ function main() {
     const { status, error } = runNodeGyp();
     if (status === 0 && !error) return 0;
     reportFailure(status, error);
-    // Fail the install rather than half-install. This package IS its native
-    // addon: a zero exit here would trade a clear install-time failure for a
-    // deferred `import` failure in the consumer's own code, and npm's rollback is
-    // the honest outcome. NODE_GI_SKIP_NATIVE_BUILD is the opt-in for anyone who
-    // wants the other trade.
+    // Fail the install rather than half-install. This package IS its native addon: a
+    // zero exit here would trade a clear install-time failure for a deferred `import`
+    // failure in the consumer's own code. NODE_GI_SKIP_NATIVE_BUILD is the opt-in for
+    // anyone who wants the other trade.
     return status === 0 ? 1 : status;
 }
 

package/src/addon.cc

@@ -74,6 +74,7 @@ static Napi::Object Init(Napi::Env env, Napi::Object exports) {
   exports.Set("getErrorDomain", Napi::Function::New(env, GetErrorDomain));
   exports.Set("setErrorBuilder", Napi::Function::New(env, SetErrorBuilder));
   exports.Set("prependSearchPath", Napi::Function::New(env, PrependSearchPath));
+  exports.Set("prependLibraryPath", Napi::Function::New(env, PrependLibraryPath));
   exports.Set("callFunction", Napi::Function::New(env, CallFunction));
   exports.Set("callMethod", Napi::Function::New(env, CallMethod));
   exports.Set("hasMethod", Napi::Function::New(env, HasMethod));

package/src/common.h

@@ -550,6 +550,7 @@ Napi::Value GetEnumValues(const Napi::CallbackInfo& info);
 Napi::Value GetErrorDomain(const Napi::CallbackInfo& info);
 Napi::Value SetErrorBuilder(const Napi::CallbackInfo& info);
 Napi::Value PrependSearchPath(const Napi::CallbackInfo& info);
+Napi::Value PrependLibraryPath(const Napi::CallbackInfo& info);
 
 // calls.cc
 Napi::Value CallFunction(const Napi::CallbackInfo& info);

package/src/repo.cc

@@ -295,4 +295,30 @@ Napi::Value PrependSearchPath(const Napi::CallbackInfo& info) {
   return env.Undefined();
 }
 
+// prependLibraryPath(path: string) -> void
+// The LIBRARY twin of PrependSearchPath: where GI looks for the shared object a
+// typelib names, as opposed to where it looks for the typelib itself.
+//
+// Native rather than `requireGi('GIRepository').…` because the bundled runtime
+// ships GIRepository 3.0, whose `Repository` this bridge exposes neither as
+// constructible nor with a `get_default()` static — measured, both throw. The C
+// entry point has no such gap and reuses the same `DupDefaultRepository()` handle.
+//
+// It is the env-free repair for a typelib backer named by BARE LEAF: no variable,
+// no re-exec, identical on node, bun and deno. See `gtk-runtime.js`
+// (`activateGiLibraryPath`) for the incident.
+Napi::Value PrependLibraryPath(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 1 || !info[0].IsString()) {
+    Napi::TypeError::New(env, "prependLibraryPath(path: string)")
+        .ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+  std::string path = info[0].As<Napi::String>().Utf8Value();
+  GIRepository* repo = DupDefaultRepository();
+  gi_repository_prepend_library_path(repo, path.c_str());
+  g_object_unref(repo);
+  return env.Undefined();
+}
+
 }  // namespace nodegi

package/system-gi.js

@@ -227,3 +227,43 @@ export function systemGiLibraryDirs({
 export function pathCovers(wanted, current) {
     return wanted.every((dir) => current.includes(dir));
 }
+
+/**
+ * dyld's OWN default fallback list, verbatim from `dyld(1)`:
+ * `$HOME/lib:/usr/local/lib:/lib:/usr/lib`.
+ *
+ * Load-bearing because `DYLD_FALLBACK_LIBRARY_PATH` REPLACES this list rather
+ * than extending it, so a composition that omits part of it hands the child a
+ * SMALLER search path than the same child would have had with the variable
+ * unset. MEASURED, and it cost a whole platform: both writers used to append a
+ * bare `/usr/lib`, dropping `/usr/local/lib` — where every Homebrew GTK library
+ * lives on Intel macOS — so every `gjsify` gjs command on such a Mac died in
+ * `dlopen(libsoup-3.0.0.dylib)` before it had downloaded anything (the CLI's own
+ * fetcher goes through Soup), and so did the Node-free bootstrap the Getting
+ * Started page prints. The tell that it was OURS: plain
+ * `gjs -c 'imports.gi.Soup'` loads fine with no DYLD variable set.
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {string[]}
+ */
+export function dyldDefaultFallbackDirs(env = process.env) {
+    const home = env['HOME'];
+    return [...(home ? [`${home}/lib`] : []), '/usr/local/lib', '/lib', '/usr/lib'];
+}
+
+/**
+ * Compose a `DYLD_FALLBACK_LIBRARY_PATH` value: `wanted`, then the launching
+ * environment's own value, then {@link dyldDefaultFallbackDirs} —
+ * unconditionally, because the target is a CHILD (a re-exec, or a spawned gjs)
+ * and it must never search less than one launched without gjsify. Deduplicated:
+ * `systemGiLibraryDirs()` can legitimately yield a directory the tail also
+ * names, and a repeat costs the loader a second stat on every miss. First
+ * occurrence wins everywhere, so dropping later repeats preserves behaviour.
+ * @param {readonly string[]} wanted
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {string}
+ */
+export function composeDyldFallback(wanted, env = process.env) {
+    return [
+        ...new Set([...wanted, ...splitSearchPath(env['DYLD_FALLBACK_LIBRARY_PATH']), ...dyldDefaultFallbackDirs(env)]),
+    ].join(':');
+}