@gjsify/cli 0.24.2 → 0.25.1

package/lib/actions/build.d.ts

@@ -60,6 +60,19 @@ export declare class BuildAction {
      * text scan cannot tell from a statement.
      */
     private assertGjsOutputLoadable;
+    /**
+     * Post-bundle gate for `--app node`: throw when the emitted bundle still
+     * references GJS ambient globals (`print`/`imports`/…) although the
+     * pre-build detection decided no `@gjsify/node-gi/globals` shim was needed
+     * — see `utils/node-bundle-guard.ts` for the full rationale.
+     *
+     * Unlike the `--app gjs` gate, the oracle here CANNOT be the module graph:
+     * an ambient global is a free identifier, not an import, so nothing about it
+     * appears in a chunk's `imports` list. It is the same acorn pass the
+     * detector runs, re-applied to what was actually written — a post-condition
+     * on the prediction, not a second opinion.
+     */
+    private assertNodeOutputGlobals;
     /**
      * Post-bundle step for a `--app browser` HTML entry: write the processed
      * `index.html` beside the JS bundle, with the entry `<script>`'s `src`

package/lib/actions/build.js

@@ -11,6 +11,7 @@ import { normalizeBundlerOptions, mergeBundlerOptions } from '../utils/normalize
 import { inputSourceDirs, isOutdirInsideSource, libraryOutputLeakError } from '../utils/library-output.js';
 import { detectHtmlEntry, parseHtmlEntry, emitBrowserHtml, htmlOutPathFor } from '../utils/html-entry.js';
 import { assertGjsBundleLoadable } from '../utils/gjs-bundle-guard.js';
+import { assertNodeBundleGlobalsShimmed } from '../utils/node-bundle-guard.js';
 const DEFAULT_GJS_SHEBANG = '#!/usr/bin/env -S gjs -m';
 /**
  * `true` when `path` points at a location that's unsafe to use as a build
@@ -291,6 +292,31 @@ export class BuildAction {
         const chunks = (result.output ?? []).filter((item) => item.type === 'chunk');
         assertGjsBundleLoadable(chunks, outfile ?? outdir ?? 'the GJS bundle');
     }
+    /**
+     * Post-bundle gate for `--app node`: throw when the emitted bundle still
+     * references GJS ambient globals (`print`/`imports`/…) although the
+     * pre-build detection decided no `@gjsify/node-gi/globals` shim was needed
+     * — see `utils/node-bundle-guard.ts` for the full rationale.
+     *
+     * Unlike the `--app gjs` gate, the oracle here CANNOT be the module graph:
+     * an ambient global is a free identifier, not an import, so nothing about it
+     * appears in a chunk's `imports` list. It is the same acorn pass the
+     * detector runs, re-applied to what was actually written — a post-condition
+     * on the prediction, not a second opinion.
+     */
+    assertNodeOutputGlobals(result, outfile, outdir) {
+        const label = outfile ?? outdir ?? 'the node bundle';
+        for (const item of result.output ?? []) {
+            if (item.type !== 'chunk')
+                continue;
+            // `code` is present on a written chunk for both engines; skip
+            // defensively rather than fail a build over a missing field.
+            const code = item.code;
+            if (typeof code !== 'string' || code.length === 0)
+                continue;
+            assertNodeBundleGlobalsShimmed(code, item.fileName ? `${label} (${item.fileName})` : label);
+        }
+    }
     /**
      * Post-bundle step for a `--app browser` HTML entry: write the processed
      * `index.html` beside the JS bundle, with the entry `<script>`'s `src`
@@ -530,6 +556,30 @@ export class BuildAction {
             // detection must run BEFORE the final build so the entry can be
             // wrapped; nothing is injected when no globals are referenced (the
             // eager-native-load regression guard).
+            //
+            // Explicit extras on a node build (`--globals auto,dom,…`) are the
+            // reverse bridge's DOM-surface request: inject the SAME register
+            // modules the gjs target would for those identifiers, so a genuine
+            // GJS source (an Excalibur/WebGLBridge app) gets document /
+            // HTMLCanvasElement / matchMedia / … on Node via node-gi. The
+            // orchestrator lifts the `@gjsify/empty` register routing only when
+            // this inject stub is present (see app/node.ts) — plain `auto`
+            // node builds are byte-unchanged.
+            //
+            // The stub is resolved BEFORE the detection pass, and that ordering
+            // is load-bearing: it is one of the two signals `isGjsSourceBuild`
+            // reads, so it decides whether `/register` subpaths resolve for real
+            // or route to `@gjsify/empty` and whether `@girs/*` bodies survive.
+            // Resolving it afterwards made the analysis bundle a DIFFERENT
+            // module graph from the one actually emitted — every GJS ambient
+            // global reachable only THROUGH a register module was invisible, so
+            // the shim was not injected and the emitted bundle threw
+            // `ReferenceError: imports is not defined` at runtime (the
+            // excalibur-jelly-jumper showcase on node/bun, via
+            // `@gjsify/canvas2d-core`'s `_toDataURL` and `@gjsify/utils`).
+            if (extras) {
+                pluginOpts.autoGlobalsInject = await this.resolveGlobalsInject(app, extras, verbose);
+            }
             const gjsifyPluginFactory = async (opts) => {
                 const cfg = await gjsifyPlugin({
                     input: userBundler.input,
@@ -550,17 +600,6 @@ export class BuildAction {
             }, pluginOpts, gjsifyPluginFactory, bundleToChunks);
             if (needsGiGlobals)
                 pluginOpts.nodeGiGlobalsInject = true;
-            // Explicit extras on a node build (`--globals auto,dom,…`) are the
-            // reverse bridge's DOM-surface request: inject the SAME register
-            // modules the gjs target would for those identifiers, so a genuine
-            // GJS source (an Excalibur/WebGLBridge app) gets document /
-            // HTMLCanvasElement / matchMedia / … on Node via node-gi. The
-            // orchestrator lifts the `@gjsify/empty` register routing only when
-            // this inject stub is present (see app/node.ts) — plain `auto`
-            // node builds are byte-unchanged.
-            if (extras) {
-                pluginOpts.autoGlobalsInject = await this.resolveGlobalsInject(app, extras, verbose);
-            }
         }
         else if (extras) {
             pluginOpts.autoGlobalsInject = await this.resolveGlobalsInject(app, extras, verbose);
@@ -596,6 +635,13 @@ export class BuildAction {
         if (app === 'gjs') {
             this.assertGjsOutputLoadable(writeResult, outfile, outdir);
         }
+        // Refuse to hand back a `--app node` bundle that reaches for GJS ambient
+        // globals nothing seeds. Only meaningful when the shim was NOT injected:
+        // with it, the globals are installed and the references are correct.
+        // `--globals none` opts out of the mechanism, so it opts out of the gate.
+        if (app === 'node' && autoMode && !pluginOpts.nodeGiGlobalsInject) {
+            this.assertNodeOutputGlobals(writeResult, outfile, outdir);
+        }
         // Browser HTML entry: emit the processed `index.html` beside the bundle
         // (engine-portable post-step — the native rolldown engine has no
         // `emitFile`, so this can't live in a plugin). `outfile` is guaranteed

package/lib/commands/showcase.js

@@ -266,6 +266,17 @@ async function runShowcaseOnRuntime(showcase, runtime, cliVersion) {
         return process.exit(1);
     }
     console.log(`Running showcase: ${showcase.name} ${runningAs(cliVersion)}on ${runtime} (${entry})\n`);
-    // Terminal call — exit on success.
-    await runRuntimeBundle(runtime, entry, [], { exitOnSuccess: true });
+    // Terminal call — exit on success. Failures are reported here rather than
+    // thrown: an exception escaping the handler makes yargs dump the command's
+    // full `--help` above the message, which buries it.
+    try {
+        await runRuntimeBundle(runtime, entry, [], { exitOnSuccess: true });
+    }
+    catch (err) {
+        console.error(`${err.message}\n\n` +
+            `  The showcase and the \`@gjsify/node-gi\` bridge it needs are both installed by THIS CLI\n` +
+            `  (gjsify ${cliVersion ?? '(unknown)'}) into its own cache, so a missing bridge points at the CLI\n` +
+            `  rather than at anything in your project.\n\n  ${PIN_HINT}`);
+        return process.exit(1);
+    }
 }

package/lib/utils/node-bundle-guard.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The GJS ambient globals referenced as BARE identifiers in `code`, sorted.
+ *
+ * Empty for a bundle that only uses the `globalThis.imports` isomorphic-guard
+ * shape — that form is a runtime probe, not a dependency, and the detector
+ * ignores it for exactly that reason.
+ */
+export declare function findUnshimmedGjsGlobals(code: string): string[];
+/**
+ * Throw when a `--app node` bundle references GJS ambient globals but was built
+ * without the `@gjsify/node-gi/globals` shim.
+ *
+ * @param code     the emitted bundle source
+ * @param outfile  path of the bundle, for the error message
+ */
+export declare function assertNodeBundleGlobalsShimmed(code: string, outfile: string): void;

package/lib/utils/node-bundle-guard.js

@@ -0,0 +1,69 @@
+// Build-time guard: a `--app node` bundle that USES the GJS ambient globals
+// must also have been given `@gjsify/node-gi/globals`.
+//
+// `print`/`printerr`/`log`/`logError`/`ARGV`/`imports` exist implicitly under
+// gjs and nowhere else. On the node target they are seeded by the side-effect
+// shim `@gjsify/node-gi/globals`, which the CLI injects when — and only when —
+// `detectNodeGiGlobals` finds one of them in an analysis bundle. Injecting it
+// unconditionally is not an option: it eagerly loads the native node-gi addon,
+// so a cross-platform package's node bundle would stop loading on plain Node.
+//
+// That makes the decision a PREDICTION about an artifact that does not exist
+// yet, and a prediction can be wrong. It was: the analysis pass used to run
+// before the explicit-`--globals` register stub was resolved, and that stub is
+// one of the two signals `isGjsSourceBuild()` reads — so the analysis bundle
+// routed `/register` subpaths to `@gjsify/empty` and emptied `@girs/*` while the
+// REAL build resolved them for real. Every ambient global reachable only through
+// a register module was therefore invisible to the detector. The build exited 0
+// and the emitted bundle died at its first canvas op with
+//
+//   ReferenceError: imports is not defined
+//       at CanvasRenderingContext2D._toDataURL
+//
+// on node AND bun (the excalibur-jelly-jumper showcase), while gjs — where the
+// globals are ambient — ran fine. Nothing between `gjsify build --app node` and
+// a user running the bundle ever looked at the artifact.
+//
+// So this is a POST-condition on what was actually emitted: whatever the
+// detector predicted, check it against the bundle. It is deliberately NOT a
+// second detector — it runs the SAME `detectGjsAmbientGlobals` over the SAME
+// kind of input (bundled, tree-shaken output, parsed by acorn, bare identifiers
+// only). Two passes over one oracle that must agree; when they don't, the graph
+// they saw differed, which is a bug in the build pipeline, not in user code.
+//
+// Scope: only when the CLI decided NOT to inject (`--globals auto`, no shim).
+// `--globals none` opts out of the whole mechanism explicitly and is skipped.
+import { detectGjsAmbientGlobals } from '@gjsify/rolldown-plugin-gjsify/globals';
+/**
+ * The GJS ambient globals referenced as BARE identifiers in `code`, sorted.
+ *
+ * Empty for a bundle that only uses the `globalThis.imports` isomorphic-guard
+ * shape — that form is a runtime probe, not a dependency, and the detector
+ * ignores it for exactly that reason.
+ */
+export function findUnshimmedGjsGlobals(code) {
+    return [...detectGjsAmbientGlobals(code)].sort();
+}
+/**
+ * Throw when a `--app node` bundle references GJS ambient globals but was built
+ * without the `@gjsify/node-gi/globals` shim.
+ *
+ * @param code     the emitted bundle source
+ * @param outfile  path of the bundle, for the error message
+ */
+export function assertNodeBundleGlobalsShimmed(code, outfile) {
+    const offenders = findUnshimmedGjsGlobals(code);
+    if (offenders.length === 0)
+        return;
+    throw new Error(`gjsify build --app node: ${outfile} references ${offenders.length} GJS ambient global(s) that ` +
+        'nothing installs on node/bun/deno, so the bundle throws `ReferenceError: <name> is not defined` ' +
+        'the first time that code runs:\n' +
+        offenders.map((s) => `  - ${s}`).join('\n') +
+        '\n\nThe `@gjsify/node-gi/globals` shim seeds them, but it is injected only when the pre-build ' +
+        'detection pass finds them — and that pass did not. The two passes therefore disagreed about the ' +
+        'module graph. Either the detection ran against a different graph than the one emitted (check that ' +
+        'anything feeding `isGjsSourceBuild()` — the `--globals` register stub, `nodeGiGlobalsInject` — is ' +
+        'settled BEFORE `detectNodeGiGlobals`), or the offending package should stop reaching for the ' +
+        'legacy `imports` object: `gi://<Ns>` and the bare `system`/`gettext`/`cairo` built-ins resolve on ' +
+        'both runtimes, `imports` does not.');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/cli",
-    "version": "0.24.2",
+    "version": "0.25.1",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -130,19 +130,19 @@
         "cli"
     ],
     "dependencies": {
-        "@gjsify/buffer": "^0.24.2",
-        "@gjsify/create-app": "^0.24.2",
-        "@gjsify/node-globals": "^0.24.2",
-        "@gjsify/node-polyfills": "^0.24.2",
-        "@gjsify/npm-registry": "^0.24.2",
-        "@gjsify/resolve-npm": "^0.24.2",
-        "@gjsify/rolldown-plugin-gjsify": "^0.24.2",
-        "@gjsify/rolldown-plugin-pnp": "^0.24.2",
-        "@gjsify/semver": "^0.24.2",
-        "@gjsify/tar": "^0.24.2",
-        "@gjsify/tsc": "^0.24.2",
-        "@gjsify/web-polyfills": "^0.24.2",
-        "@gjsify/workspace": "^0.24.2",
+        "@gjsify/buffer": "^0.25.1",
+        "@gjsify/create-app": "^0.25.1",
+        "@gjsify/node-globals": "^0.25.1",
+        "@gjsify/node-polyfills": "^0.25.1",
+        "@gjsify/npm-registry": "^0.25.1",
+        "@gjsify/resolve-npm": "^0.25.1",
+        "@gjsify/rolldown-plugin-gjsify": "^0.25.1",
+        "@gjsify/rolldown-plugin-pnp": "^0.25.1",
+        "@gjsify/semver": "^0.25.1",
+        "@gjsify/tar": "^0.25.1",
+        "@gjsify/tsc": "^0.25.1",
+        "@gjsify/web-polyfills": "^0.25.1",
+        "@gjsify/workspace": "^0.25.1",
         "cosmiconfig": "^9.0.2",
         "get-tsconfig": "^4.14.0",
         "pkg-types": "^2.3.1",
@@ -150,13 +150,13 @@
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@gjsify/unit": "^0.24.2",
+        "@gjsify/unit": "^0.25.1",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/oxfmt-native": "^0.24.2",
-        "@gjsify/rolldown-native": "^0.24.2"
+        "@gjsify/oxfmt-native": "^0.25.1",
+        "@gjsify/rolldown-native": "^0.25.1"
     },
     "peerDependenciesMeta": {
         "@gjsify/oxfmt-native": {