@gjsify/node-gi 0.35.0 → 0.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/node-gi",
-  "version": "0.35.0",
+  "version": "0.37.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/class.cc

@@ -617,6 +617,21 @@ static void NodeGiClassInit(gpointer g_class, gpointer class_data) {
       // init_template. Independent of the child binding above — Children /
       // InternalChildren behaviour is unchanged.
       NodeGiInstallTemplateScopeOnClass(cd, g_class);
+    } else if (widgetType == 0) {
+      // GtkWidget is not registered in the type registry THIS addon calls into. The
+      // class in hand descends from one (registerClass resolved its parent), so the
+      // honest reading is not "your class is wrong" but "there are two GObject copies
+      // in this process" — the addon bound one libgobject and GTK registered its types
+      // in another. Reported separately because the subclass wording below sent #1120
+      // hunting a JS bug for a dyld one: an unrelocated darwin prebuild kept the build
+      // host's absolute Homebrew paths and bound Homebrew's libgobject while the
+      // batteries-included bundle's libgtk used its own.
+      g_warning(
+          "node-gi: GtkWidget is not registered in this process's GObject type registry, "
+          "so the Template on %s cannot be installed. This means TWO GLib/GObject copies "
+          "are loaded — check that the addon and GTK resolve to the same libgobject "
+          "(otool -L on the addon; DYLD_PRINT_LIBRARIES=1 to list what loaded)",
+          g_type_name(G_TYPE_FROM_CLASS(g_class)));
     } else if (!isWidget) {
       g_warning(
           "node-gi: a Template was set on %s, which is not a Gtk.Widget subclass — "