@gjsify/node-gi 0.26.0 → 0.27.0

package/overrides/mainloop.js

@@ -18,43 +18,43 @@ const DEFAULT_IDLE_PRIORITY = 200; // GLib.PRIORITY_DEFAULT_IDLE
  * @returns {{ run(name?: string): void, quit(name?: string): void, idle_add: Function, timeout_add: Function, timeout_add_seconds: Function, source_remove: Function }}
  */
 export function createMainloop(GLib) {
-  const _mainLoops = Object.create(null);
+    const _mainLoops = Object.create(null);
 
-  function run(name = '') {
-    if (!_mainLoops[name]) _mainLoops[name] = GLib.MainLoop.new(null, false);
-    _mainLoops[name].run();
-  }
+    function run(name = '') {
+        if (!_mainLoops[name]) _mainLoops[name] = GLib.MainLoop.new(null, false);
+        _mainLoops[name].run();
+    }
 
-  function quit(name = '') {
-    if (!_mainLoops[name]) throw new Error('No main loop with this id');
+    function quit(name = '') {
+        if (!_mainLoops[name]) throw new Error('No main loop with this id');
 
-    const loop = _mainLoops[name];
-    _mainLoops[name] = null;
+        const loop = _mainLoops[name];
+        _mainLoops[name] = null;
 
-    if (!loop.is_running()) throw new Error('Main loop was stopped already');
+        if (!loop.is_running()) throw new Error('Main loop was stopped already');
 
-    loop.quit();
-  }
+        loop.quit();
+    }
 
-  // GJS signature is `idle_add(handler, priority)` — handler first — whereas the
-  // introspected GLib.idle_add is `(priority, handler)`; bridge the argument order.
-  function idle_add(handler, priority = DEFAULT_IDLE_PRIORITY) {
-    return GLib.idle_add(priority, handler);
-  }
+    // GJS signature is `idle_add(handler, priority)` — handler first — whereas the
+    // introspected GLib.idle_add is `(priority, handler)`; bridge the argument order.
+    function idle_add(handler, priority = DEFAULT_IDLE_PRIORITY) {
+        return GLib.idle_add(priority, handler);
+    }
 
-  function timeout_add(timeout, handler, priority = GLib.PRIORITY_DEFAULT) {
-    return GLib.timeout_add(priority, timeout, handler);
-  }
+    function timeout_add(timeout, handler, priority = GLib.PRIORITY_DEFAULT) {
+        return GLib.timeout_add(priority, timeout, handler);
+    }
 
-  function timeout_add_seconds(timeout, handler, priority = GLib.PRIORITY_DEFAULT) {
-    return GLib.timeout_add_seconds(priority, timeout, handler);
-  }
+    function timeout_add_seconds(timeout, handler, priority = GLib.PRIORITY_DEFAULT) {
+        return GLib.timeout_add_seconds(priority, timeout, handler);
+    }
 
-  function source_remove(id) {
-    return GLib.source_remove(id);
-  }
+    function source_remove(id) {
+        return GLib.source_remove(id);
+    }
 
-  return { run, quit, idle_add, timeout_add, timeout_add_seconds, source_remove };
+    return { run, quit, idle_add, timeout_add, timeout_add_seconds, source_remove };
 }
 
 export default createMainloop;

package/overrides/package.js

@@ -19,111 +19,111 @@
  * @param {{ requireGi: Function, gettext: any, imports: Record<string, any> }} deps
  */
 export function createPackage({ requireGi, gettext, imports }) {
-  const pkg = {
-    // Public fields GJS source may read. Populated by init().
-    name: undefined,
-    version: undefined,
-    prefix: undefined,
-    libdir: undefined,
-    datadir: undefined,
-    pkgdatadir: undefined,
-    pkglibdir: undefined,
-    moduledir: undefined,
-    localedir: undefined,
+    const pkg = {
+        // Public fields GJS source may read. Populated by init().
+        name: undefined,
+        version: undefined,
+        prefix: undefined,
+        libdir: undefined,
+        datadir: undefined,
+        pkgdatadir: undefined,
+        pkglibdir: undefined,
+        moduledir: undefined,
+        localedir: undefined,
 
-    /**
-     * @param {{ name?: string, version?: string, prefix?: string, libdir?: string, datadir?: string }} params
-     */
-    init(params = {}) {
-      // The accessor GJS apps use right after: `pkg.initGettext()`.
-      globalThis.pkg = pkg;
+        /**
+         * @param {{ name?: string, version?: string, prefix?: string, libdir?: string, datadir?: string }} params
+         */
+        init(params = {}) {
+            // The accessor GJS apps use right after: `pkg.initGettext()`.
+            globalThis.pkg = pkg;
 
-      pkg.name = params.name;
-      pkg.version = params.version;
-      pkg.prefix = params.prefix;
-      pkg.libdir = params.libdir;
-      pkg.datadir = params.datadir ?? (params.prefix ? `${params.prefix}/share` : undefined);
+            pkg.name = params.name;
+            pkg.version = params.version;
+            pkg.prefix = params.prefix;
+            pkg.libdir = params.libdir;
+            pkg.datadir = params.datadir ?? (params.prefix ? `${params.prefix}/share` : undefined);
 
-      // Installed-layout dirs — NOT load-bearing on node-gi (apps carry their own
-      // constants + register their own resources), computed for source-compat only.
-      if (pkg.name) {
-        if (pkg.datadir) {
-          pkg.pkgdatadir = `${pkg.datadir}/${pkg.name}`;
-          pkg.moduledir = pkg.pkgdatadir;
-          pkg.localedir = `${pkg.datadir}/locale`;
-        }
-        if (pkg.libdir) pkg.pkglibdir = `${pkg.libdir}/${pkg.name}`;
-      }
+            // Installed-layout dirs — NOT load-bearing on node-gi (apps carry their own
+            // constants + register their own resources), computed for source-compat only.
+            if (pkg.name) {
+                if (pkg.datadir) {
+                    pkg.pkgdatadir = `${pkg.datadir}/${pkg.name}`;
+                    pkg.moduledir = pkg.pkgdatadir;
+                    pkg.localedir = `${pkg.datadir}/locale`;
+                }
+                if (pkg.libdir) pkg.pkglibdir = `${pkg.libdir}/${pkg.name}`;
+            }
 
-      // Cheap + safe: keeps ARGV[0]/app-id semantics (window-manager grouping etc.).
-      try {
-        const GLib = requireGi('GLib', '2.0');
-        if (pkg.name && typeof GLib.set_prgname === 'function') GLib.set_prgname(pkg.name);
-      } catch {
-        /* GLib not loadable in this context — skip */
-      }
+            // Cheap + safe: keeps ARGV[0]/app-id semantics (window-manager grouping etc.).
+            try {
+                const GLib = requireGi('GLib', '2.0');
+                if (pkg.name && typeof GLib.set_prgname === 'function') GLib.set_prgname(pkg.name);
+            } catch {
+                /* GLib not loadable in this context — skip */
+            }
 
-      // GJS unshifts moduledir onto imports.searchPath (script-import machinery).
-      // node-gi apps use ESM + gi://, so the search path is inert here — but keep
-      // the array present + the unshift safe so source that reads it doesn't throw.
-      if (!Array.isArray(imports.searchPath)) imports.searchPath = [];
-      if (pkg.moduledir) imports.searchPath.unshift(pkg.moduledir);
-    },
+            // GJS unshifts moduledir onto imports.searchPath (script-import machinery).
+            // node-gi apps use ESM + gi://, so the search path is inert here — but keep
+            // the array present + the unshift safe so source that reads it doesn't throw.
+            if (!Array.isArray(imports.searchPath)) imports.searchPath = [];
+            if (pkg.moduledir) imports.searchPath.unshift(pkg.moduledir);
+        },
 
-    initGettext() {
-      if (pkg.name) {
-        try {
-          gettext.bindtextdomain?.(pkg.name, pkg.localedir ?? null);
-          gettext.textdomain?.(pkg.name);
-        } catch {
-          /* passthrough gettext — no catalog, ignore */
-        }
-      }
-      // The globals GJS apps + compiled Blueprint use pervasively.
-      globalThis._ = (msgid) => gettext.gettext(msgid);
-      globalThis.C_ = (context, msgid) => gettext.pgettext(context, msgid);
-      globalThis.N_ = (msgid) => msgid;
-    },
+        initGettext() {
+            if (pkg.name) {
+                try {
+                    gettext.bindtextdomain?.(pkg.name, pkg.localedir ?? null);
+                    gettext.textdomain?.(pkg.name);
+                } catch {
+                    /* passthrough gettext — no catalog, ignore */
+                }
+            }
+            // The globals GJS apps + compiled Blueprint use pervasively.
+            globalThis._ = (msgid) => gettext.gettext(msgid);
+            globalThis.C_ = (context, msgid) => gettext.pgettext(context, msgid);
+            globalThis.N_ = (msgid) => msgid;
+        },
 
-    initFormat() {
-      // GJS sets `String.prototype.format = imports.format.format` (backed by the
-      // native `_format` vprintf). node-gi has no `imports.format`, so supply an
-      // equivalent JS vprintf here (see makeVprintf).
-      const vprintf = makeVprintf();
-      Object.defineProperty(String.prototype, 'format', {
-        configurable: true,
-        writable: true,
-        enumerable: false,
-        value: function format(...args) {
-          return vprintf(this, args);
+        initFormat() {
+            // GJS sets `String.prototype.format = imports.format.format` (backed by the
+            // native `_format` vprintf). node-gi has no `imports.format`, so supply an
+            // equivalent JS vprintf here (see makeVprintf).
+            const vprintf = makeVprintf();
+            Object.defineProperty(String.prototype, 'format', {
+                configurable: true,
+                writable: true,
+                enumerable: false,
+                value: function format(...args) {
+                    return vprintf(this, args);
+                },
+            });
         },
-      });
-    },
 
-    // Script-import machinery is not ported — node-gi apps use ESM + gi://. These
-    // keep the surface present for source that references them (Learn6502 does not).
-    require() {
-      /* no-op: apps import via ESM / gi:// on node-gi */
-    },
-    requireSymbol() {
-      return true;
-    },
-    checkSymbol() {
-      return true;
-    },
-    start(params = {}) {
-      pkg.init(params);
-      if (typeof params.main === 'function') params.main(globalThis.ARGV ? ['', ...globalThis.ARGV] : []);
-    },
-    run() {
-      /* the app drives its own main() on node-gi */
-    },
-    initSubmodule() {
-      /* n/a on node-gi */
-    },
-  };
+        // Script-import machinery is not ported — node-gi apps use ESM + gi://. These
+        // keep the surface present for source that references them (Learn6502 does not).
+        require() {
+            /* no-op: apps import via ESM / gi:// on node-gi */
+        },
+        requireSymbol() {
+            return true;
+        },
+        checkSymbol() {
+            return true;
+        },
+        start(params = {}) {
+            pkg.init(params);
+            if (typeof params.main === 'function') params.main(globalThis.ARGV ? ['', ...globalThis.ARGV] : []);
+        },
+        run() {
+            /* the app drives its own main() on node-gi */
+        },
+        initSubmodule() {
+            /* n/a on node-gi */
+        },
+    };
 
-  return pkg;
+    return pkg;
 }
 
 // A small vprintf covering the GJS `String.prototype.format` spec
@@ -131,37 +131,37 @@ export function createPackage({ requireGi, gettext, imports }) {
 // width, `0`-padding for numerics, and `%%` → literal `%`. Positional `%N$s` is
 // supported (GJS honours it). Learn6502 only uses `%s`; the rest is fidelity.
 function makeVprintf() {
-  return function vprintf(fmt, args) {
-    let auto = 0;
-    return String(fmt).replace(
-      /%(?:(\d+)\$)?(0)?(\d+)?(?:\.(\d+))?([%sdxf])/g,
-      (match, pos, zero, width, prec, spec) => {
-        if (spec === '%') return '%';
-        const arg = pos !== undefined ? args[Number(pos) - 1] : args[auto++];
-        let str;
-        switch (spec) {
-          case 's':
-            str = String(arg);
-            break;
-          case 'd':
-            str = String(Math.trunc(Number(arg)));
-            break;
-          case 'x':
-            str = Math.trunc(Number(arg)).toString(16);
-            break;
-          case 'f':
-            str = prec !== undefined ? Number(arg).toFixed(Number(prec)) : String(Number(arg));
-            break;
-          default:
-            return match;
-        }
-        if (width !== undefined) {
-          const w = Number(width);
-          const pad = zero && spec !== 's' ? '0' : ' ';
-          while (str.length < w) str = pad + str;
-        }
-        return str;
-      },
-    );
-  };
+    return function vprintf(fmt, args) {
+        let auto = 0;
+        return String(fmt).replace(
+            /%(?:(\d+)\$)?(0)?(\d+)?(?:\.(\d+))?([%sdxf])/g,
+            (match, pos, zero, width, prec, spec) => {
+                if (spec === '%') return '%';
+                const arg = pos !== undefined ? args[Number(pos) - 1] : args[auto++];
+                let str;
+                switch (spec) {
+                    case 's':
+                        str = String(arg);
+                        break;
+                    case 'd':
+                        str = String(Math.trunc(Number(arg)));
+                        break;
+                    case 'x':
+                        str = Math.trunc(Number(arg)).toString(16);
+                        break;
+                    case 'f':
+                        str = prec !== undefined ? Number(arg).toFixed(Number(prec)) : String(Number(arg));
+                        break;
+                    default:
+                        return match;
+                }
+                if (width !== undefined) {
+                    const w = Number(width);
+                    const pad = zero && spec !== 's' ? '0' : ' ';
+                    while (str.length < w) str = pad + str;
+                }
+                return str;
+            },
+        );
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/node-gi",
-  "version": "0.26.0",
+  "version": "0.27.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",
@@ -52,9 +52,12 @@
     "gettext.d.ts",
     "cairo.js",
     "cairo.d.ts",
+    "native-paths.js",
     "overrides",
     "src",
     "binding.gyp",
+    "scripts/install.mjs",
+    "scripts/win-gi-gyp-flags.mjs",
     "prebuilds"
   ],
   "gjsify": {
@@ -62,6 +65,7 @@
       "linux-x64",
       "linux-arm64",
       "darwin-arm64",
+      "darwin-x64",
       "win32-x64"
     ],
     "runtimes": {
@@ -73,7 +77,7 @@
     "tier": 2
   },
   "scripts": {
-    "install": "node-gyp rebuild",
+    "install": "node scripts/install.mjs",
     "build": "node-gyp rebuild",
     "build:native": "node-gyp rebuild",
     "build:prebuild": "node-gyp rebuild && node scripts/stage-prebuild.mjs",

package/scripts/install.mjs

@@ -0,0 +1,238 @@
+#!/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.
+//
+// THE FAILURE THIS REPLACES. Until this script existed, `package.json` declared
+// `"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.
+//
+// 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.
+//
+// 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.)
+//
+// 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.
+//
+// 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';
+import { join } from 'node:path';
+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.
+ */
+const buildFromSourceRequested = () =>
+    isEnabled(process.env.NODE_GI_BUILD_FROM_SOURCE) || process.env.npm_config_build_from_source === 'true';
+
+/** The `<os>-<arch>` targets this package PROMISES a prebuild for, from its own manifest. */
+function declaredPlatforms() {
+    try {
+        const manifest = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'));
+        const platforms = manifest?.gjsify?.platforms;
+        return Array.isArray(platforms) ? platforms : [];
+    } catch {
+        // An unreadable own manifest is not worth failing an install over — the
+        // diagnosis below just loses one line of context.
+        return [];
+    }
+}
+
+/**
+ * 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 }}
+ */
+function runNodeGyp() {
+    const win32 = process.platform === 'win32';
+    let command = win32 ? 'node-gyp.cmd' : 'node-gyp';
+    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`.
+        const entry = createRequire(import.meta.url).resolve('node-gyp/bin/node-gyp.js');
+        command = process.execPath;
+        args = [entry, 'rebuild'];
+        shell = false;
+    } catch {
+        // Not resolvable — use the PATH shim.
+    }
+    const res = spawnSync(command, args, { cwd: packageRoot, stdio: 'inherit', shell, windowsHide: true });
+    return { status: res.status === null ? 1 : res.status, error: res.error };
+}
+
+/**
+ * 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.
+ */
+function isRepoCheckout() {
+    return existsSync(join(packageRoot, 'test')) || existsSync(join(packageRoot, 'scripts', 'stage-prebuild.mjs'));
+}
+
+/**
+ * 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
+ * nothing told the consumer).
+ */
+function reportFailure(status, spawnError) {
+    const platforms = declaredPlatforms();
+    const promised = platforms.includes(target);
+    const checkout = isRepoCheckout();
+    const bar = '─'.repeat(78);
+    const lines = [
+        '',
+        bar,
+        `@gjsify/node-gi: could not obtain the native addon for ${target}.`,
+        '',
+        checkout
+            ? '  • This is a source checkout, where `prebuilds/` is gitignored — no staged prebuild\n' +
+              '    for this host was expected, and the source build IS the path here.'
+            : promised
+              ? `  • This package PROMISES a prebuild for ${target} (package.json#gjsify.platforms) but\n` +
+                `    the installed copy carries no prebuilds/${target}/node_gi.node. That is a packaging\n` +
+                '    bug in this release, not a problem with your machine — please report it at\n' +
+                '    https://github.com/gjsify/gjsify/issues.'
+              : `  • No prebuild ships for ${target}.` +
+                (platforms.length > 0 ? ` Prebuilds ship for: ${platforms.join(', ')}.` : ''),
+        spawnError
+            ? `  • The node-gyp source build could not even be STARTED: ${spawnError.message}\n` +
+              '    (node-gyp is normally provided on PATH by npm/yarn/pnpm for install scripts.)'
+            : `  • The node-gyp source build above exited ${status}. Its output is the actual diagnosis.`,
+        '',
+        'Building from source needs a C++ toolchain plus GLib >= 2.80 development headers',
+        'exposing girepository-2.0, and cairo:',
+        '  Fedora        dnf install gcc-c++ make python3 pkgconf-pkg-config glib2-devel \\',
+        '                    gobject-introspection-devel cairo-devel',
+        '  Debian/Ubuntu apt install g++ make python3 pkg-config libglib2.0-dev \\',
+        '                    libgirepository-2.0-dev libcairo2-dev',
+        '  macOS         brew install gobject-introspection cairo pkg-config',
+        '  Windows       gvsbuild GTK4 (MSVC ABI), then PKG_CONFIG_PATH=<prefix>\\lib\\pkgconfig',
+        '',
+        'Escape hatches:',
+        '  NODE_GI_SKIP_NATIVE_BUILD=1     install the JS without an addon (every gi:// import',
+        '                                  then throws until you point NODE_GI_NATIVE at one)',
+        '  NODE_GI_NATIVE=/abs/node_gi.node  load an addon you built or copied yourself',
+        '  NODE_GI_BUILD_FROM_SOURCE=1     build from source even when a prebuild exists',
+        bar,
+        '',
+    ];
+    console.error(lines.join('\n'));
+}
+
+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.
+    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}. ` +
+                'gi:// imports will throw until NODE_GI_NATIVE points at a node_gi.node.',
+        );
+        return 0;
+    }
+
+    const prebuild = prebuildAddonPath();
+    if (!buildFromSourceRequested() && existsSync(prebuild)) {
+        console.log(
+            `@gjsify/node-gi: using the shipped prebuild for ${target} ` +
+                `(prebuilds/${target}/node_gi.node) — no node-gyp, no C++ toolchain needed. ` +
+                'Set NODE_GI_BUILD_FROM_SOURCE=1 to build from source anyway.',
+        );
+        return 0;
+    }
+
+    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.
+    return status === 0 ? 1 : status;
+}
+
+process.exit(main());