@gjsify/cli 0.24.1 → 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/dlx.d.ts

@@ -16,6 +16,21 @@ export interface EnsureOpts {
     registry?: string;
     cacheMaxAge: number;
     frozen: boolean;
+    /**
+     * Extra specs to install into the SAME cache tree as the requested package.
+     *
+     * A dlx tree is the package plus its own `dependencies`, which is right for
+     * the GJS path — the showcase's `--app gjs` bundle needs nothing else. The
+     * `--app node` bundle does: its `gi://` imports resolve through
+     * `@gjsify/node-gi`, which is a build-time concern for the showcase (a
+     * devDependency) but a RUNTIME one for whoever launches it off GJS. Nobody
+     * can act on the resulting "add @gjsify/node-gi as a dependency" error —
+     * the tree belongs to the cache, not to the user — so the launcher that
+     * knows the runtime supplies it.
+     *
+     * Part of the cache key, so the gjs and node trees never share an entry.
+     */
+    extraSpecs?: readonly string[];
 }
 /**
  * Resolve (installing + caching when remote) the on-disk directory of a package

package/lib/commands/dlx.js

@@ -106,7 +106,8 @@ export async function ensurePkgDir(parsed, opts) {
     if (parsed.kind === 'local') {
         return { pkgDir: parsed.path, cachedPkgName: null };
     }
-    const cacheKey = createCacheKey({ packages: [parsed.spec] });
+    const specs = [parsed.spec, ...(opts.extraSpecs ?? [])];
+    const cacheKey = createCacheKey({ packages: specs });
     const cacheDir = cacheDirFor(cacheKey);
     const cached = opts.cacheMaxAge > 0 ? getValidCachedPkg(cacheDir, opts.cacheMaxAge) : undefined;
     if (cached) {
@@ -124,7 +125,7 @@ export async function ensurePkgDir(parsed, opts) {
     const progress = makeProgressReporter({ enabled: !opts.verbose });
     await installPackages({
         prefix: prepareDir,
-        specs: [parsed.spec],
+        specs,
         verbose: opts.verbose,
         registry: opts.registry,
         // Cache-prepare dirs are scoped per cache key, so writing a lockfile

package/lib/commands/install.d.ts

@@ -14,7 +14,7 @@ interface InstallOptions {
     timeout: number;
 }
 export declare const installCommand: Command<unknown, InstallOptions>;
-export declare function buildBinShim(wsLocation: string, nodeTarget?: string, gjsTarget?: string, nativePrebuildDirs?: string[], platform?: string): string;
+export declare function buildBinShim(wsLocation: string, nodeTarget?: string, gjsTarget?: string, nativePrebuildDirs?: string[], platform?: string, scanRoot?: string): string;
 /**
  * `.cmd` / `.ps1` companions for {@link buildBinShim}.
  *

package/lib/commands/install.js

@@ -34,8 +34,8 @@ import { spawnSync } from 'node:child_process';
 import { gjsExit } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { discoverWorkspaces } from '@gjsify/workspace';
 import { buildInstallCommand, detectPackageManager, runMinimalChecks } from '../utils/check-system-deps.js';
-import { detectNativePackages, libraryPathVar } from '../utils/detect-native-packages.js';
-import { buildLauncherShims } from '../utils/bin-shim.js';
+import { detectNativePackages } from '../utils/detect-native-packages.js';
+import { buildLauncherShims, buildNativeEnvPreamble } from '../utils/bin-shim.js';
 import { installPackages, makeProgressReporter } from '../utils/install-backend.js';
 import { atomicWriteStrict } from '../utils/install-cache-fs.js';
 import { acquireInstallLock } from '../utils/install-lock.js';
@@ -957,9 +957,7 @@ function writeWorkspaceBinShims(cwd, workspaces) {
                     /* fine */
                 }
             }
-            writeFileSync(linkPath, buildBinShim(ws.location, nodeTarget, gjsTarget, nativePrebuildDirs), {
-                mode: 0o755,
-            });
+            writeFileSync(linkPath, buildBinShim(ws.location, nodeTarget, gjsTarget, nativePrebuildDirs, process.platform, cwd), { mode: 0o755 });
             chmodSync(linkPath, 0o755);
             // Windows executes neither an extension-less file nor a `#!` line —
             // the sh shim above is only reachable from git-bash/MSYS/WSL. Write
@@ -1045,26 +1043,19 @@ function scopedOverrideFor(ws, depName, extracted) {
     }
     return undefined;
 }
-export function buildBinShim(wsLocation, nodeTarget, gjsTarget, nativePrebuildDirs = [], platform = process.platform) {
+export function buildBinShim(wsLocation, nodeTarget, gjsTarget, nativePrebuildDirs = [], platform = process.platform, scanRoot = wsLocation) {
     const nodeAbs = nodeTarget ? join(wsLocation, nodeTarget) : null;
     const gjsAbs = gjsTarget ? join(wsLocation, gjsTarget) : null;
     // GJS-only env preamble — Node ignores GI_TYPELIB_PATH so we scope the
     // export to the gjs branch, keeping the shim minimal when no native pkgs
     // exist or only the Node bin is in play.
     //
-    // The library-path variable is host-dependent: `dyld` on macOS never reads
-    // LD_LIBRARY_PATH, so exporting it there silently produced a launcher that
-    // could not load a single `darwin-arm64` prebuild. `libraryPathVar()` is the
-    // one place that mapping lives.
-    const { name: libVar } = libraryPathVar(platform);
-    const gjsPreamble = nativePrebuildDirs.length === 0
-        ? ''
-        : (() => {
-            const joined = `'${nativePrebuildDirs.join(':').replace(/'/g, `'\\''`)}'`;
-            return (`GI_TYPELIB_PATH=${joined}\${GI_TYPELIB_PATH:+":$GI_TYPELIB_PATH"}\n` +
-                `${libVar}=${joined}\${${libVar}:+":$${libVar}"}\n` +
-                `export GI_TYPELIB_PATH ${libVar}\n`);
-        })();
+    // `scanRoot` is the INSTALL prefix (the tree holding `node_modules/.bin`),
+    // not the workspace package dir: the preamble globs its `node_modules` at
+    // launch time instead of embedding what was installed the day the shim was
+    // written, so `gjsify install <some>-native` afterwards is picked up without
+    // a re-link. See `buildNativeEnvPreamble`.
+    const gjsPreamble = buildNativeEnvPreamble(scanRoot, nativePrebuildDirs, { platform });
     if (nodeAbs && gjsAbs) {
         // GJS-FIRST: prefer the committed Node-free GJS bundle when `gjs` is on
         // PATH AND the bundle exists; fall back to the Node entry otherwise (a

package/lib/commands/showcase.js

@@ -18,6 +18,27 @@ function readCliVersion() {
         return undefined;
     }
 }
+/**
+ * `[gjsify <version>] ` for the banner — the CLI naming ITSELF.
+ *
+ * `showcase` pins the showcase package to the CLI's own version, so a stale CLI
+ * silently runs a stale showcase, and the only version in the output was the
+ * showcase's. That is not a hypothetical: every runner that caches an unpinned
+ * bin reuses whatever it resolved once (`npx @gjsify/cli` → a 0.4.x `_npx`
+ * entry; `deno run npm:@gjsify/cli` → whatever sits in `DENO_DIR`), so the same
+ * command produced 0.24.1 under bunx, 0.4.25 under npx and 0.23.0 under deno on
+ * ONE machine on ONE day — and the two old ones failed in ways that read as
+ * gjsify bugs. gjsify cannot flush somebody else's cache, but it can stop the
+ * output from hiding which gjsify is talking.
+ */
+function runningAs(cliVersion) {
+    return cliVersion ? `[gjsify ${cliVersion}] ` : '';
+}
+/** Pinned invocations for the three runners that cache an unpinned bin. */
+const PIN_HINT = 'A package runner reuses a CACHED copy of an unpinned bin. Force the current one:\n' +
+    '    npx @gjsify/cli@latest showcase <name>\n' +
+    '    bunx @gjsify/cli@latest showcase <name>\n' +
+    '    deno run -A --reload npm:@gjsify/cli@latest showcase <name>';
 export const showcaseCommand = {
     command: 'showcase [name]',
     description: 'List or run curated gjsify showcase applications.',
@@ -146,7 +167,7 @@ export const showcaseCommand = {
         // newer CLI assumes (the `@gjsify/http-soup-bridge` regression
         // reported against `@gjsify/cli@0.3.17`).
         const dlxSpec = cliVersion ? `${showcase.packageName}@${cliVersion}` : showcase.packageName;
-        console.log(`Running showcase: ${showcase.name} (via gjsify dlx ${dlxSpec})\n`);
+        console.log(`Running showcase: ${showcase.name} ${runningAs(cliVersion)}(via gjsify dlx ${dlxSpec})\n`);
         // Dispatch `dlx` IN-PROCESS (not `spawn(process.execPath, [cliBin, …])`):
         // under the committed GJS bundle `process.execPath` is `gjs` and
         // `../index.js` is the Node entry, so the spawn ran `gjs cli.gjs.mjs
@@ -169,7 +190,7 @@ export const showcaseCommand = {
  * in-tree build), falling back to `gjsify dlx`'s install-into-cache for a
  * published showcase. Returns the directory containing the package.json.
  */
-async function resolveShowcaseDir(showcase, cliVersion) {
+async function resolveShowcaseDir(showcase, cliVersion, extraSpecs = []) {
     // Local-first: a workspace showcase resolves via its own package name.
     try {
         const req = createRequire(import.meta.url);
@@ -185,6 +206,7 @@ async function resolveShowcaseDir(showcase, cliVersion) {
         verbose: false,
         cacheMaxAge: 60 * 24 * 7,
         frozen: false,
+        extraSpecs,
     });
     return pkgDir;
 }
@@ -197,7 +219,16 @@ async function resolveShowcaseDir(showcase, cliVersion) {
 async function runShowcaseOnRuntime(showcase, runtime, cliVersion) {
     let pkgDir;
     try {
-        pkgDir = await resolveShowcaseDir(showcase, cliVersion);
+        // `@gjsify/node-gi` is the `gi://` bridge the `--app node` bundle
+        // resolves at RUNTIME. Showcases carry it as a devDependency (it is a
+        // build input for them), so a dlx tree — the package plus its own
+        // `dependencies` — does not contain it and the launch died with "add
+        // @gjsify/node-gi as a dependency": advice the user cannot act on,
+        // since the tree is the CLI's cache. The launcher knows the runtime, so
+        // it supplies the bridge. Pinned to the CLI's version like the showcase
+        // itself, so the bridge and the bundle move together.
+        const nodeGiSpec = cliVersion ? `@gjsify/node-gi@${cliVersion}` : '@gjsify/node-gi';
+        pkgDir = await resolveShowcaseDir(showcase, cliVersion, [nodeGiSpec]);
     }
     catch (err) {
         console.error(`Could not resolve showcase "${showcase.name}": ${err.message}`);
@@ -222,10 +253,30 @@ async function runShowcaseOnRuntime(showcase, runtime, cliVersion) {
         entry = resolveNodeEntry(pkgDir);
     }
     catch (err) {
-        console.error(`Cannot run showcase "${showcase.name}" on ${runtime}: ${err.message}`);
+        // The showcase promised this runtime and did not ship the bundle. Two
+        // causes, and the user can only act on one of them, so name both: the
+        // package version is genuinely broken (fixed by a newer one), or THIS
+        // CLI is a cached old copy that pinned a genuinely broken old showcase.
+        const version = typeof pkg.name === 'string' ? `${pkg.name}@${cliVersion ?? '?'}` : showcase.packageName;
+        console.error(`Cannot run showcase "${showcase.name}" on ${runtime}: ${err.message}\n\n` +
+            `  ${version} declares --runtime ${runtime} but ships no \`--app node\` bundle, so that\n` +
+            `  version of the showcase cannot run there. You are running gjsify ${cliVersion ?? '(unknown)'},\n` +
+            `  and \`showcase\` pins the showcase to the CLI's own version.\n\n  ${PIN_HINT}\n\n` +
+            `  Or run it on GJS, which every showcase ships: gjsify showcase ${showcase.name} --runtime gjs`);
+        return process.exit(1);
+    }
+    console.log(`Running showcase: ${showcase.name} ${runningAs(cliVersion)}on ${runtime} (${entry})\n`);
+    // 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);
     }
-    console.log(`Running showcase: ${showcase.name} on ${runtime} (${entry})\n`);
-    // Terminal call — exit on success.
-    await runRuntimeBundle(runtime, entry, [], { exitOnSuccess: true });
 }

package/lib/utils/bin-shim.d.ts

@@ -64,3 +64,52 @@ export declare function buildLauncherShims(opts: {
     cmd: string;
     ps1: string;
 };
+/**
+ * The `sh` preamble a GJS launcher needs so `imports.gi.X` resolves against the
+ * `@gjsify/*` native prebuilds installed next to it.
+ *
+ * WHY IT SCANS AT RUN TIME INSTEAD OF BAKING A LIST
+ *
+ * The typelib/library lookup happens inside the GJS runtime, before a single
+ * line of the CLI bundle runs, so the env MUST be set by the launcher — the CLI
+ * cannot repair it from the inside. The launcher used to bake the directories
+ * `detectNativePackages()` found at INSTALL time, which makes the env a SNAPSHOT
+ * of one moment:
+ *
+ *   - a native package installed into the same prefix LATER (`gjsify install -g
+ *     @gjsify/<x>-native`, a project `gjsify install` that adds one) is invisible
+ *     until something happens to rewrite the launcher;
+ *   - and if the scan comes back empty for any reason, the launcher is written
+ *     with NO preamble at all and nothing says so. The failure then surfaces
+ *     much later and somewhere else entirely — `gjsify build` dying with "no
+ *     usable bundler engine under GJS" in an unrelated project, which reads as a
+ *     broken install rather than a stale launcher. That is what shipped in
+ *     v0.24.1: a `~/.local/bin/gjsify` with a bare `exec gjs -m …` line while
+ *     `@gjsify/rolldown-native` sat correctly installed in the prefix.
+ *
+ * Deriving the env from disk on every launch removes both: the launcher states
+ * WHERE to look rather than WHAT was there, so it cannot go stale, and an empty
+ * result is a fact about the current prefix instead of a silently frozen one.
+ * The cost is a handful of shell globs per launch (they are builtins, and a
+ * pattern that matches nothing stays literal and is rejected by `[ -d ]`).
+ *
+ * `bakedDirs` covers what a run-time scan of `scanRoot` structurally cannot see:
+ * `detectNativePackages()` walks UP the directory chain, so in a hoisted layout
+ * a prebuild may live in an ancestor's `node_modules`. Those are still embedded
+ * verbatim; only the primary root is dynamic. Duplicates are harmless (both
+ * variables are search paths).
+ *
+ * Windows is deliberately excluded: there the `sh` file is only reachable from
+ * git-bash/MSYS, the real launchers are the `.cmd`/`.ps1` companions built by
+ * {@link buildLauncherShims} from the same baked list, and `PATH` doubles as the
+ * DLL search path with `;` separators. It keeps the snapshot behaviour.
+ *
+ * @param scanRoot Directory whose `node_modules` is globbed at launch time.
+ * @param bakedDirs Prebuild dirs found at write time; entries outside `scanRoot`
+ *   are embedded (entries inside it are dropped — the scan finds them).
+ * @returns the preamble, or `''` when there is nothing to export.
+ */
+export declare function buildNativeEnvPreamble(scanRoot: string, bakedDirs?: readonly string[], target?: {
+    platform?: string;
+    arch?: string;
+}): string;

package/lib/utils/bin-shim.js

@@ -24,6 +24,7 @@
 // All three re-derive the interpreter from the target's shebang, so a bin
 // declaring `#!/usr/bin/env node` and one declaring `#!/usr/bin/env -S gjs -m`
 // both work without the caller knowing which it is.
+import { libraryPathVar, prebuildDirCandidates } from './detect-native-packages.js';
 // Matches `#!<prog> <args>` and `#!/usr/bin/env [-S] [K=V ...] <prog> <args>`.
 // Verbatim from cmd-shim's `shebangExpr`.
 const SHEBANG_RE = /^#!\s*(?:\/usr\/bin\/env\s+(?:-S\s+)?((?:[^ \t=]+=[^ \t=]+\s+)*))?([^ \t]+)(.*)$/;
@@ -244,3 +245,107 @@ export function buildLauncherShims(opts) {
             'exit $LASTEXITCODE\n';
     return { cmd, ps1 };
 }
+/** POSIX `sh` single-quoting — the one place the escape lives. */
+function shQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * The `sh` preamble a GJS launcher needs so `imports.gi.X` resolves against the
+ * `@gjsify/*` native prebuilds installed next to it.
+ *
+ * WHY IT SCANS AT RUN TIME INSTEAD OF BAKING A LIST
+ *
+ * The typelib/library lookup happens inside the GJS runtime, before a single
+ * line of the CLI bundle runs, so the env MUST be set by the launcher — the CLI
+ * cannot repair it from the inside. The launcher used to bake the directories
+ * `detectNativePackages()` found at INSTALL time, which makes the env a SNAPSHOT
+ * of one moment:
+ *
+ *   - a native package installed into the same prefix LATER (`gjsify install -g
+ *     @gjsify/<x>-native`, a project `gjsify install` that adds one) is invisible
+ *     until something happens to rewrite the launcher;
+ *   - and if the scan comes back empty for any reason, the launcher is written
+ *     with NO preamble at all and nothing says so. The failure then surfaces
+ *     much later and somewhere else entirely — `gjsify build` dying with "no
+ *     usable bundler engine under GJS" in an unrelated project, which reads as a
+ *     broken install rather than a stale launcher. That is what shipped in
+ *     v0.24.1: a `~/.local/bin/gjsify` with a bare `exec gjs -m …` line while
+ *     `@gjsify/rolldown-native` sat correctly installed in the prefix.
+ *
+ * Deriving the env from disk on every launch removes both: the launcher states
+ * WHERE to look rather than WHAT was there, so it cannot go stale, and an empty
+ * result is a fact about the current prefix instead of a silently frozen one.
+ * The cost is a handful of shell globs per launch (they are builtins, and a
+ * pattern that matches nothing stays literal and is rejected by `[ -d ]`).
+ *
+ * `bakedDirs` covers what a run-time scan of `scanRoot` structurally cannot see:
+ * `detectNativePackages()` walks UP the directory chain, so in a hoisted layout
+ * a prebuild may live in an ancestor's `node_modules`. Those are still embedded
+ * verbatim; only the primary root is dynamic. Duplicates are harmless (both
+ * variables are search paths).
+ *
+ * Windows is deliberately excluded: there the `sh` file is only reachable from
+ * git-bash/MSYS, the real launchers are the `.cmd`/`.ps1` companions built by
+ * {@link buildLauncherShims} from the same baked list, and `PATH` doubles as the
+ * DLL search path with `;` separators. It keeps the snapshot behaviour.
+ *
+ * @param scanRoot Directory whose `node_modules` is globbed at launch time.
+ * @param bakedDirs Prebuild dirs found at write time; entries outside `scanRoot`
+ *   are embedded (entries inside it are dropped — the scan finds them).
+ * @returns the preamble, or `''` when there is nothing to export.
+ */
+export function buildNativeEnvPreamble(scanRoot, bakedDirs = [], target = {}) {
+    const platform = target.platform ?? process.platform;
+    const arch = target.arch ?? process.arch;
+    const { name: libVar, separator } = libraryPathVar(platform);
+    if (platform === 'win32') {
+        if (bakedDirs.length === 0)
+            return '';
+        const joined = shQuote(bakedDirs.join(separator));
+        return (`GI_TYPELIB_PATH=${joined}\${GI_TYPELIB_PATH:+"${separator}$GI_TYPELIB_PATH"}\n` +
+            `${libVar}=${joined}\${${libVar}:+"${separator}$${libVar}"}\n` +
+            `export GI_TYPELIB_PATH ${libVar}\n`);
+    }
+    // Only the ancestors' hits need embedding — anything under `scanRoot` is
+    // what the loop below finds, and re-embedding it would reintroduce the
+    // snapshot for exactly the packages the scan exists to keep current.
+    const nmRoot = `${scanRoot.replace(/\/+$/, '')}/node_modules/`;
+    const external = bakedDirs.filter((d) => !d.startsWith(nmRoot));
+    // The same `<os>-<arch>` spellings `resolvePrebuildDirName()` probes, in the
+    // same order: the canonical `${platform}-${arch}` plus the legacy uname one
+    // a tarball published before the rename still ships. Passing no declared
+    // platforms is correct here — the shell cannot read a package.json, and a
+    // package declaring ONLY a non-canonical spelling of this host has not
+    // existed since the audit made that state impossible.
+    const candidates = prebuildDirCandidates(platform, arch);
+    const patterns = [];
+    for (const candidate of candidates) {
+        // Scoped (`@gjsify/x`) and unscoped packages, matching `scanNodeModules`.
+        patterns.push(`${shQuote(scanRoot)}/node_modules/@*/*/prebuilds/${candidate}`);
+        patterns.push(`${shQuote(scanRoot)}/node_modules/*/prebuilds/${candidate}`);
+    }
+    const seed = external.length > 0 ? shQuote(external.join(separator)) : `''`;
+    // A directory match is not enough: `prebuilds/<os>-<arch>/` is ALSO the
+    // prebuildify convention, so a plain glob sweeps in `bare-fs`, `bare-os`
+    // and friends — packages with no typelib at all, which `detectNativePackages`
+    // never returned because it keyed on `gjsify.prebuilds`. Onto
+    // GI_TYPELIB_PATH that is merely noise; onto the LOADER path it is a
+    // directory of foreign shared objects ahead of the system ones. The
+    // `.typelib` probe restores the old precision from the filesystem alone —
+    // and it is exactly what the artifact invariant already guarantees every
+    // gjsify GI bridge ships (a library AND the typelib without which
+    // GI_TYPELIB_PATH resolves nothing).
+    return (`gjsify_np=${seed}\n` +
+        `for gjsify_d in ${patterns.join(' ')}; do\n` +
+        `  [ -d "$gjsify_d" ] || continue\n` +
+        `  for gjsify_t in "$gjsify_d"/*.typelib; do\n` +
+        `    if [ -f "$gjsify_t" ]; then gjsify_np="\${gjsify_np:+$gjsify_np${separator}}$gjsify_d"; break; fi\n` +
+        `  done\n` +
+        `done\n` +
+        `if [ -n "$gjsify_np" ]; then\n` +
+        `  GI_TYPELIB_PATH="$gjsify_np\${GI_TYPELIB_PATH:+${separator}$GI_TYPELIB_PATH}"\n` +
+        `  ${libVar}="$gjsify_np\${${libVar}:+${separator}$${libVar}}"\n` +
+        `  export GI_TYPELIB_PATH ${libVar}\n` +
+        `fi\n` +
+        `unset gjsify_np gjsify_d gjsify_t\n`);
+}

package/lib/utils/install-backend-native.js

@@ -571,7 +571,6 @@ function findVisible(requesterPath, name, byPath) {
         candidates.push(`${requesterPath}/node_modules/${name}`);
         // Walk up: strip the last `/node_modules/<pkg>` segment and try again.
         let p = requesterPath;
-        // eslint-disable-next-line no-constant-condition
         while (true) {
             // Find the deepest `/node_modules/<pkg>` in `p`, strip it.
             const idx = p.lastIndexOf('/node_modules/');

package/lib/utils/install-global.d.ts

@@ -86,22 +86,6 @@ export interface LinkedBin {
  *   simplicity and so we don't need to discriminate by runtime here.
  */
 export declare function linkGlobalBins(packageNames: string[], layout: GlobalLayout): LinkedBin[];
-/**
- * Build the POSIX-sh `export` lines that prepend the given prebuild
- * directories to GI_TYPELIB_PATH and the host's shared-library search path.
- * Any pre-existing value inherited from the user's environment is preserved as
- * a suffix so user-installed typelibs/libraries still resolve.
- *
- * The library variable is host-dependent — `LD_LIBRARY_PATH` on Linux,
- * `DYLD_LIBRARY_PATH` on macOS (dyld never reads the ELF one), so a launcher
- * written on a Mac used to export a variable nothing consults, leaving every
- * `darwin-arm64` prebuild unloadable. `platform` is a parameter so both
- * branches are unit-testable from either host.
- *
- * Returns the empty string when no prebuilds were found — avoids emitting an
- * inert assignment in the launcher.
- */
-export declare function buildLauncherEnvPreamble(prebuildsDirs: string[], platform?: string): string;
 /** Returns `true` if `binDir` is on the user's PATH. */
 export declare function binDirOnPath(binDir: string): boolean;
 /**

package/lib/utils/install-global.js

@@ -23,8 +23,8 @@
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import { detectNativePackages, libraryPathVar } from './detect-native-packages.js';
-import { buildLauncherShims, parseShebang } from './bin-shim.js';
+import { detectNativePackages } from './detect-native-packages.js';
+import { buildLauncherShims, buildNativeEnvPreamble, parseShebang } from './bin-shim.js';
 /**
  * Compute the canonical global install layout for the current user. Honours
  * `XDG_DATA_HOME` (per the XDG Base Directory Spec) plus
@@ -143,18 +143,25 @@ export async function installGjsEnginePackages(prefix, version, opts = {}) {
 export function linkGlobalBins(packageNames, layout) {
     fs.mkdirSync(layout.binDir, { recursive: true });
     const created = [];
-    // Discover @gjsify/* packages with native prebuilds (Vala/GObject typelibs
-    // + shared libs) under the global prefix. The launcher bakes their
-    // directories into GI_TYPELIB_PATH / LD_LIBRARY_PATH so `imports.gi.X`
-    // resolves at CLI startup — required for e.g. @gjsify/terminal-native,
-    // without which process.stdout.isTTY / columns / colors all fall back to
-    // the conservative env-only defaults (no colors, 80-col wrap).
+    // The launcher exports GI_TYPELIB_PATH / <loader path> for the @gjsify/*
+    // native prebuilds (Vala/GObject typelibs + shared libs) installed in this
+    // prefix, so `imports.gi.X` resolves at CLI startup — required for the
+    // bundler engine `@gjsify/rolldown-native` (without which `gjsify build`
+    // hard-fails under GJS) and for e.g. `@gjsify/terminal-native`, without
+    // which isTTY / columns / colors fall back to conservative defaults.
     //
-    // `runGjsBundle()` does the same dance for `gjsify run <bundle>` at
-    // runtime; here we do it at install time because the global launcher
-    // invokes the CLI bundle directly, with no opportunity to set env first.
+    // `runGjsBundle()` does the same dance for `gjsify run <bundle>` at runtime;
+    // here it has to be the launcher, because the typelib lookup happens inside
+    // the GJS runtime before the bundle's first line runs.
+    //
+    // The preamble SCANS the prefix at launch time rather than embedding what
+    // was there at install time — see `buildNativeEnvPreamble` for why a
+    // snapshot is the wrong shape. `nativePrebuildDirs` is still computed: the
+    // Windows `.cmd`/`.ps1` shims take the baked list, and a hit in an
+    // ANCESTOR's node_modules (which the walk finds and a single-root scan
+    // cannot) is embedded verbatim.
     const nativePrebuildDirs = detectNativePackages(layout.prefix).map((p) => p.prebuildsDir);
-    const envPreamble = buildLauncherEnvPreamble(nativePrebuildDirs);
+    const envPreamble = buildNativeEnvPreamble(layout.prefix, nativePrebuildDirs);
     for (const pkgName of packageNames) {
         const pkgDir = path.join(layout.prefix, 'node_modules', pkgName);
         const pkgJsonPath = path.join(pkgDir, 'package.json');
@@ -237,30 +244,6 @@ export function linkGlobalBins(packageNames, layout) {
 function shQuote(s) {
     return `'${s.replace(/'/g, `'\\''`)}'`;
 }
-/**
- * Build the POSIX-sh `export` lines that prepend the given prebuild
- * directories to GI_TYPELIB_PATH and the host's shared-library search path.
- * Any pre-existing value inherited from the user's environment is preserved as
- * a suffix so user-installed typelibs/libraries still resolve.
- *
- * The library variable is host-dependent — `LD_LIBRARY_PATH` on Linux,
- * `DYLD_LIBRARY_PATH` on macOS (dyld never reads the ELF one), so a launcher
- * written on a Mac used to export a variable nothing consults, leaving every
- * `darwin-arm64` prebuild unloadable. `platform` is a parameter so both
- * branches are unit-testable from either host.
- *
- * Returns the empty string when no prebuilds were found — avoids emitting an
- * inert assignment in the launcher.
- */
-export function buildLauncherEnvPreamble(prebuildsDirs, platform = process.platform) {
-    if (prebuildsDirs.length === 0)
-        return '';
-    const { name: libVar } = libraryPathVar(platform);
-    const joined = shQuote(prebuildsDirs.join(':'));
-    return (`GI_TYPELIB_PATH=${joined}\${GI_TYPELIB_PATH:+":$GI_TYPELIB_PATH"}\n` +
-        `${libVar}=${joined}\${${libVar}:+":$${libVar}"}\n` +
-        `export GI_TYPELIB_PATH ${libVar}\n`);
-}
 /** Parse a bin file's `#!` line; `null` when unreadable or not a shebang. */
 function readShebangOf(file) {
     try {

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;