@gjsify/cli 0.37.0 → 0.38.0

package/lib/actions/build.d.ts

@@ -159,6 +159,13 @@ export declare class BuildAction {
          * wrapper does not apply here.
          */
         preserveDefaultExport?: boolean;
+        /**
+         * The globals policy for this bundle, when the caller has one
+         * (`Config.forNodeScript`). Unset keeps `--globals auto`, which is what
+         * the plugin and config loaders want.
+         */
+        globals?: string;
+        excludeGlobals?: string[];
     }): Promise<string>;
     /** Application mode */
     buildApp(app?: App, opts?: {

package/lib/actions/build.js

@@ -4,7 +4,7 @@ import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { resolveUserPlugins } from '../utils/resolve-plugin-by-name.js';
 import { resolveGlobalsList, writeRegisterInjectFile, detectAutoGlobals, detectNodeGiGlobals, } from '@gjsify/rolldown-plugin-gjsify/globals';
 import { pnpPlugin } from '@gjsify/rolldown-plugin-pnp';
-import { dirname, extname, join, resolve } from 'node:path';
+import { basename, dirname, extname, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { chmod, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { normalizeBundlerOptions, mergeBundlerOptions } from '../utils/normalize-bundler-options.js';
@@ -467,7 +467,20 @@ export class BuildAction {
         const cwd = process.cwd();
         const cacheDir = join(cwd, 'node_modules', '.cache', 'gjsify', opts.cacheSubdir);
         const safeName = opts.label.replace(/[^a-zA-Z0-9._-]/g, '_');
-        const outfile = join(cacheDir, `${safeName}-${shortHash(inputPath)}.mjs`);
+        // The policy belongs in the cache KEY, not only in the build: one file under two
+        // policies is two artifacts, and the freshness check below (entry mtime + lockfile)
+        // cannot see the `package.json` edit that changed one. Callers without a policy keep
+        // their existing cache filenames.
+        const cacheKey = opts.globals === undefined && opts.excludeGlobals === undefined
+            ? inputPath
+            : `${inputPath} ${JSON.stringify([opts.globals ?? null, opts.excludeGlobals ?? null])}`;
+        // THE HASH GOES IN THE DIRECTORY, THE FILE KEEPS THE SOURCE'S NAME. As
+        // `<name>-<hash>.mjs` it broke every script guarding its body with the standard
+        // is-entry test: `audit-runtimes.mjs` asks whether `process.argv[1]` ENDS WITH its
+        // own name, so `--node-script` ran it, printed NOTHING and exited 0. Same cause the
+        // `import.meta.url` define exists for — the bundle does not live where the source
+        // does — and a name is cheaper to keep right than an argv to rewrite.
+        const outfile = join(cacheDir, `${safeName}-${shortHash(cacheKey)}`, `${basename(inputPath).replace(/\.[cm]?[jt]sx?$/i, '')}.mjs`);
         const cacheDisabled = opts.cache === false || (opts.noCacheEnv ? isTruthyEnv(process.env[opts.noCacheEnv]) : false);
         if (!cacheDisabled && (await isBundleFresh(outfile, inputPath, cwd))) {
             if (opts.verbose)
@@ -476,9 +489,11 @@ export class BuildAction {
         }
         if (opts.verbose)
             console.debug(`[gjsify] bundling ${inputPath} for GJS → ${outfile}`);
-        await mkdir(cacheDir, { recursive: true });
+        await mkdir(dirname(outfile), { recursive: true });
         await new BuildAction({
             verbose: opts.verbose,
+            ...(opts.globals !== undefined ? { globals: opts.globals } : {}),
+            ...(opts.excludeGlobals !== undefined ? { excludeGlobals: opts.excludeGlobals } : {}),
             bundler: {
                 input: inputPath,
                 output: { file: outfile },

package/lib/config.d.ts

@@ -10,5 +10,19 @@ export declare class Config {
     private readPackageJSON;
     /** Loads tsconfig.json of the current project */
     private readTSConfig;
+    /**
+     * The globals policy for a `gjsify run --node-script` bundle, resolved from the
+     * package that OWNS THE SCRIPT — not the cwd, which during a monorepo build is the
+     * repo root. `gjsify.nodeScript` overrides either key (see `ConfigData.nodeScript`).
+     *
+     * CONFIG AND NOT A FLAG because on a host with no `node` the caller is a
+     * `package.json` spelling `node scripts/x.mjs`, re-entering the CLI through the shim
+     * `writeNodeShim()` writes: no call site to hang a flag on, on exactly the hosts this
+     * exists for.
+     */
+    forNodeScript(scriptPath: string): Promise<{
+        globals?: string;
+        excludeGlobals?: string[];
+    }>;
     forBuild(cliArgs: ArgumentsCamelCase<CliBuildOptions>): Promise<ConfigData>;
 }

package/lib/config.js

@@ -1,6 +1,6 @@
 import { APP_NAME } from './constants.js';
 import { cosmiconfig } from 'cosmiconfig';
-import { basename } from 'node:path';
+import { basename, dirname } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { isGjs, hostRuntime } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { buildAppForRuntime } from './utils/runtimes.js';
@@ -216,6 +216,23 @@ export class Config {
         const tsconfig = getTsconfig(dirPath)?.config || {};
         return tsconfig;
     }
+    /**
+     * The globals policy for a `gjsify run --node-script` bundle, resolved from the
+     * package that OWNS THE SCRIPT — not the cwd, which during a monorepo build is the
+     * repo root. `gjsify.nodeScript` overrides either key (see `ConfigData.nodeScript`).
+     *
+     * CONFIG AND NOT A FLAG because on a host with no `node` the caller is a
+     * `package.json` spelling `node scripts/x.mjs`, re-entering the CLI through the shim
+     * `writeNodeShim()` writes: no call site to hang a flag on, on exactly the hosts this
+     * exists for.
+     */
+    async forNodeScript(scriptPath) {
+        const { config } = await this.load(dirname(scriptPath));
+        return {
+            globals: config.nodeScript?.globals ?? config.globals,
+            excludeGlobals: config.nodeScript?.excludeGlobals ?? config.excludeGlobals,
+        };
+    }
     async forBuild(cliArgs) {
         const configFile = await this.load(process.cwd());
         const configData = { ...configFile.config };

package/lib/templates/install.mjs.tmpl

@@ -134,6 +134,62 @@ function checkGjsVersion() {
     }
 }
 
+/** Total attempts per URL, and the wait before each retry. Override for tests / slow links. */
+const FETCH_ATTEMPTS = Number(GLib.getenv('GJSIFY_INSTALL_FETCH_ATTEMPTS') || '5');
+const RETRY_BACKOFF_MS = [1000, 2000, 4000, 8000];
+
+function sleepMs(ms) {
+    return new Promise((resolve) => {
+        GLib.timeout_add(GLib.PRIORITY_DEFAULT, ms, () => {
+            resolve();
+            return GLib.SOURCE_REMOVE;
+        });
+    });
+}
+
+async function fetchOnce(session, url, { forceHttp1 = false } = {}) {
+    const message = Soup.Message.new('GET', url);
+    message.request_headers.append('User-Agent', USER_AGENT);
+    // The failure this retries against announces its own protocol — libsoup reports it
+    // verbatim as `HTTP/2 Error: NO_ERROR`, a stream closed mid-response. Retrying over
+    // HTTP/1.1 sidesteps the multiplexing that produces it, so the first attempt keeps the
+    // faster protocol and every retry drops to the one that cannot fail that way. Guarded:
+    // `set_force_http1` is libsoup 3.4+, and this script must still run on older hosts.
+    if (forceHttp1 && typeof message.set_force_http1 === 'function') message.set_force_http1(true);
+    const bytes = await session.send_and_read_async(message, GLib.PRIORITY_DEFAULT, null);
+    const status = message.get_status();
+    if (status !== Soup.Status.OK) {
+        const err = new Error(`HTTP ${status} from ${url}`);
+        err.httpStatus = status;
+        throw err;
+    }
+    return bytes.get_data();
+}
+
+/**
+ * A dropped connection is a HICCUP; an HTTP answer is an ANSWER.
+ *
+ * THE INCIDENT. `https://github.com/gjsify/gjsify/releases/latest/download/…` dropped
+ * HTTP/2 connections for a stretch on 2026-08-12 and took four CI jobs across two PRs
+ * with it, each dying in `gjsify-setup` before a line of the change under test ran.
+ * Measured from a workstation during the same window: one in three `curl` attempts
+ * returned `Connection died, tried 5 times before giving up`. A single-shot fetch turns
+ * that into "Refusing to install an UNVERIFIED bootstrap bundle", which reads like the
+ * digest is missing or hostile — the one message that must never be a false alarm, since
+ * the correct response to it is to disable verification.
+ *
+ * So retries are scoped to what CANNOT be an answer: a transport failure (no status at
+ * all), plus 429 and 5xx. A 404 is the registry saying the asset does not exist and a 403
+ * is it saying no; retrying either would only delay the same result while making a real
+ * outage look like a hang.
+ *
+ * FIVE attempts, not three, and the numbers come from a run rather than a preference:
+ * with three the CI log showed `retry 2/3` and `retry 3/3` and still failed, because each
+ * attempt takes ~20 s to give up — so the 500ms/1500ms backoff was noise beside it and the
+ * whole sequence covered barely 40 s of a longer wobble. 1/2/4/8 s over five attempts
+ * covers about two minutes. Beyond that it is an outage, not a hiccup, and waiting longer
+ * only turns a clear failure into a hang.
+ */
 async function fetchBytes(session, url) {
     if (url.startsWith('file://')) {
         const path = url.slice('file://'.length);
@@ -141,14 +197,22 @@ async function fetchBytes(session, url) {
         const [, bytes] = file.load_contents(null);
         return bytes;
     }
-    const message = Soup.Message.new('GET', url);
-    message.request_headers.append('User-Agent', USER_AGENT);
-    const bytes = await session.send_and_read_async(message, GLib.PRIORITY_DEFAULT, null);
-    const status = message.get_status();
-    if (status !== Soup.Status.OK) {
-        throw new Error(`HTTP ${status} from ${url}`);
+    const attempts = Number.isFinite(FETCH_ATTEMPTS) && FETCH_ATTEMPTS >= 1 ? FETCH_ATTEMPTS : 1;
+    let lastErr = null;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        try {
+            return await fetchOnce(session, url, { forceHttp1: attempt > 1 });
+        } catch (err) {
+            lastErr = err;
+            const status = err.httpStatus;
+            const retriable = status === undefined || status === 429 || status >= 500;
+            if (!retriable || attempt === attempts) break;
+            const wait = RETRY_BACKOFF_MS[Math.min(attempt - 1, RETRY_BACKOFF_MS.length - 1)];
+            info(`Fetch of ${url} failed (${err.message}) — retry ${attempt + 1}/${attempts} in ${wait}ms`);
+            await sleepMs(wait);
+        }
     }
-    return bytes.get_data();
+    throw lastErr;
 }
 
 function sha256Hex(bytes) {
@@ -200,6 +264,41 @@ function pruneCache(dir, keepBasename) {
     }
 }
 
+/**
+ * The newest cached bootstrap whose CONTENTS hash to the digest in its own name, or
+ * null. Re-hashing is the whole point: the filename is a claim, and a truncated entry
+ * keeps its name — the same reason the warm-cache path below re-hashes rather than
+ * trusting it.
+ */
+function newestCachedBootstrap(dir) {
+    let best = null;
+    let children;
+    try {
+        children = Gio.File.new_for_path(dir).enumerate_children(
+            'standard::name,time::modified',
+            Gio.FileQueryInfoFlags.NONE,
+            null,
+        );
+    } catch {
+        // No cache directory yet — `enumerate_children` is `throws="1"`.
+        return null;
+    }
+    for (;;) {
+        const entry = children.next_file(null);
+        if (entry === null) break;
+        const name = entry.get_name();
+        if (!name.startsWith(CACHE_PREFIX) || !name.endsWith(CACHE_SUFFIX)) continue;
+        const claimed = name.slice(CACHE_PREFIX.length, name.length - CACHE_SUFFIX.length).toLowerCase();
+        if (!/^[0-9a-f]{64}$/.test(claimed)) continue;
+        const path = GLib.build_filenamev([dir, name]);
+        const bytes = readBytesOrNull(path);
+        if (!bytes || sha256Hex(bytes).toLowerCase() !== claimed) continue;
+        const mtime = entry.get_modification_date_time()?.to_unix() ?? 0;
+        if (!best || mtime > best.mtime) best = { path, basename: name, mtime };
+    }
+    return best;
+}
+
 /**
  * Resolve a VERIFIED bootstrap bundle and return its path.
  *
@@ -222,6 +321,26 @@ async function resolveBootstrap(session, bootstrapUrl, sha256Url) {
         try {
             sumBytes = await fetchBytes(session, sha256Url);
         } catch (err) {
+            // Before refusing: a bundle already in the cache carries its own digest in
+            // its NAME, and re-hashing the bytes proves the name. Those bytes were
+            // verified against a digest that WAS fetched, on an earlier run — so reusing
+            // them installs nothing unverified. That is a different thing from the defect
+            // this function's header records, where a failed digest fetch waved a FRESH
+            // download through with no digest at all.
+            //
+            // What it does concede is FRESHNESS: someone who can block the network can
+            // hold you on the release you already have. So it is loud, it names the
+            // digest, and it only ever runs after the retries above are exhausted — which
+            // on 2026-08-12 was a GitHub release CDN dropping every connection from the
+            // CI runners for over an hour, with a warm cache sitting right there, unusable
+            // because the digest fetch comes first.
+            const cached = newestCachedBootstrap(cacheDir());
+            if (cached) {
+                error(`Could not fetch ${sha256Url}: ${err.message}`);
+                info(`Falling back to the cached bootstrap verified earlier: ${cached.basename}`);
+                info('It may be OLDER than `latest` — re-run once the network recovers.');
+                return cached.path;
+            }
             error(`Could not fetch ${sha256Url}: ${err.message}`);
             error('Refusing to install an UNVERIFIED bootstrap bundle.');
             error("To bootstrap without verification, set GJSIFY_INSTALL_BOOTSTRAP_SHA256_URL='' explicitly.");

package/lib/types/config-data.d.ts

@@ -105,6 +105,18 @@ export interface ConfigData {
      * excludes the HTTP polyfill stack.
      */
     excludeGlobals?: string[];
+    /**
+     * Overrides for the ad-hoc bundle `gjsify run --node-script <file>` builds under
+     * GJS. Unset keys fall through to the package-level `globals` / `excludeGlobals`
+     * above, so most packages need only those. `@gjsify/adwaita-web` forced the split:
+     * its browser bundle wants the DOM registers, while the script that COMPILES its
+     * stylesheet must not have them — injecting them made that bundle demand `gi://Gdk`
+     * and believe it was running on Node (#1053).
+     */
+    nodeScript?: {
+        globals?: string;
+        excludeGlobals?: string[];
+    };
     /**
      * Compile-time defines from `package.json` fields: JS identifier → dotted
      * package.json path. Values are JSON-stringified before merging into

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

@@ -130,31 +130,16 @@ export declare function buildLauncherShims(opts: {
  * script chain: the self-relative `@loader_path` rpath that
  * `check-prebuild-loader-path.mjs` enforces is what actually has to carry it.
  *
- * NOT EXTENDED WITH THE HOST'S GI LIBDIRS — a decision, not an oversight.
- * `buildNativeEnv()` now puts `systemGiLibraryDirs()` on the gjs CHILD's
- * `DYLD_FALLBACK_LIBRARY_PATH`, which repairs every command that goes through this
- * CLI. A launcher that `exec`s a GJS bundle DIRECTLY — `gjsify install -g` on a
- * package whose `gjsify.bin` is a GTK app — has no CLI in the loop and still
- * carries the gap.
- *
- * The MECHANISM would work, and that was measured on the macOS 15.7.8 VM rather
- * than assumed. It is a finer point than the caveat above: what SIP strips is an
- * INHERITED `DYLD_*` at the `/bin/sh` exec, so a value this preamble exports
- * ITSELF survives the following `exec gjs` (an unprotected Homebrew binary) and
- * `Gtk.init()` then succeeds. What is missing is a shape worth having:
- *
- *   - BAKING `systemGiLibraryDirs()` in at write time reintroduces precisely the
- *     snapshot this function exists to remove — a launcher is routinely written
- *     BEFORE `brew install gtk4`, and would bake nothing while saying nothing.
- *   - RE-DERIVING it in shell means a THIRD copy of a rule that already has two,
- *     pinned in agreement by `system-gi.spec.ts` — and shell can express only one
- *     of its three sources (the probed prefixes; `pkg-config` would be a spawn on
- *     every launch), so that copy would be knowingly partial, in the one language
- *     nothing here type-checks.
- *
- * So the gap is recorded in `status/open-todos.md` with the measurement attached
- * instead of being closed by a mechanism that drifts. Closing it properly means
- * teaching such a launcher to defer to the CLI, not to re-derive.
+ * IT DOES export dyld's own default fallback list on darwin — see
+ * {@link dyldFallbackPreamble}. That is a CONSTANT, so it carries none of the
+ * staleness that rules out the alternatives: BAKING `systemGiLibraryDirs()` in
+ * at write time reintroduces the snapshot this function exists to remove (a
+ * launcher is routinely written BEFORE `brew install gtk4`), and RE-DERIVING it
+ * in shell would be a knowingly partial THIRD copy of a two-copy rule, in the
+ * one language nothing here type-checks. The REMAINING gap — a host GI stack
+ * under a prefix dyld never defaulted to, `/opt/homebrew/lib` on Apple silicon —
+ * stays in `status/open-todos.md`, to be closed by teaching such a launcher to
+ * defer to the CLI rather than to re-derive.
  *
  * @param scanRoot Directory whose `node_modules` is globbed at launch time.
  * @param bakedDirs Prebuild dirs found at write time; entries outside `scanRoot`
@@ -166,6 +151,36 @@ export declare function buildNativeEnvPreamble(scanRoot: string, bakedDirs?: rea
     arch?: string;
     libc?: HostLibc | null;
 }): string;
+/**
+ * The darwin half of {@link buildNativeEnvPreamble}: put dyld's OWN default
+ * fallback list back, from inside the launcher.
+ *
+ * MEASURED on the macOS 15.7.9 x86_64 VM against the published 0.37.0: every
+ * `gjsify` command died in `dlopen(libsoup-3.0.0.dylib)` — before downloading
+ * anything, the CLI's own npm fetcher going through Soup — with a dyld search
+ * list that ended at `/usr/lib` and never held `/usr/local/lib`, where Homebrew
+ * puts every GTK library on Intel macOS. Exporting these four directories here
+ * makes the same command resolve, download and render (`OpenGL 4.1`).
+ *
+ * WHY HERE, and not the caller's job: SIP strips every `DYLD_*` variable when a
+ * PROTECTED binary is exec'd, and `/bin/sh` — this script — is protected. A
+ * value the USER exports is already gone by the time the preamble runs
+ * (measured: exporting the identical value around `gjsify showcase` changes
+ * nothing), while one the preamble exports ITSELF survives the following
+ * `exec gjs`, Homebrew's gjs being unprotected. This is the last hop that can.
+ *
+ * A CONSTANT is safe here only because it is dyld's DOCUMENTED DEFAULT: it
+ * cannot go stale the way baking `systemGiLibraryDirs()` in would (a launcher is
+ * routinely written before `brew install gtk4`), and it re-derives nothing —
+ * four literals from `dyld(1)`, shared with {@link dyldDefaultFallbackDirs}.
+ * An inherited value stays AHEAD of it; the export only ADDS BACK what dyld
+ * would have searched on its own.
+ *
+ * NOT the host's GI libdirs: `/opt/homebrew/lib` was never in dyld's default
+ * either, so an ARM Mac has that gap with or without gjsify —
+ * `status/open-todos.md`.
+ */
+export declare function dyldFallbackPreamble(platform: string): string;
 /** POSIX `sh` single-quoting for a launcher's target path. */
 export declare function shQuoteArg(s: string): string;
 /**

package/lib/utils/bin-shim.js

@@ -25,6 +25,7 @@
 // declaring `#!/usr/bin/env node` and one declaring `#!/usr/bin/env -S gjs -m`
 // both work without the caller knowing which it is.
 import { detectHostLibc, libraryPathVar, prebuildDirCandidates } from './detect-native-packages.js';
+import { dyldDefaultFallbackDirs } from './system-gi.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]+)(.*)$/;
@@ -340,31 +341,16 @@ function shQuote(s) {
  * script chain: the self-relative `@loader_path` rpath that
  * `check-prebuild-loader-path.mjs` enforces is what actually has to carry it.
  *
- * NOT EXTENDED WITH THE HOST'S GI LIBDIRS — a decision, not an oversight.
- * `buildNativeEnv()` now puts `systemGiLibraryDirs()` on the gjs CHILD's
- * `DYLD_FALLBACK_LIBRARY_PATH`, which repairs every command that goes through this
- * CLI. A launcher that `exec`s a GJS bundle DIRECTLY — `gjsify install -g` on a
- * package whose `gjsify.bin` is a GTK app — has no CLI in the loop and still
- * carries the gap.
- *
- * The MECHANISM would work, and that was measured on the macOS 15.7.8 VM rather
- * than assumed. It is a finer point than the caveat above: what SIP strips is an
- * INHERITED `DYLD_*` at the `/bin/sh` exec, so a value this preamble exports
- * ITSELF survives the following `exec gjs` (an unprotected Homebrew binary) and
- * `Gtk.init()` then succeeds. What is missing is a shape worth having:
- *
- *   - BAKING `systemGiLibraryDirs()` in at write time reintroduces precisely the
- *     snapshot this function exists to remove — a launcher is routinely written
- *     BEFORE `brew install gtk4`, and would bake nothing while saying nothing.
- *   - RE-DERIVING it in shell means a THIRD copy of a rule that already has two,
- *     pinned in agreement by `system-gi.spec.ts` — and shell can express only one
- *     of its three sources (the probed prefixes; `pkg-config` would be a spawn on
- *     every launch), so that copy would be knowingly partial, in the one language
- *     nothing here type-checks.
- *
- * So the gap is recorded in `status/open-todos.md` with the measurement attached
- * instead of being closed by a mechanism that drifts. Closing it properly means
- * teaching such a launcher to defer to the CLI, not to re-derive.
+ * IT DOES export dyld's own default fallback list on darwin — see
+ * {@link dyldFallbackPreamble}. That is a CONSTANT, so it carries none of the
+ * staleness that rules out the alternatives: BAKING `systemGiLibraryDirs()` in
+ * at write time reintroduces the snapshot this function exists to remove (a
+ * launcher is routinely written BEFORE `brew install gtk4`), and RE-DERIVING it
+ * in shell would be a knowingly partial THIRD copy of a two-copy rule, in the
+ * one language nothing here type-checks. The REMAINING gap — a host GI stack
+ * under a prefix dyld never defaulted to, `/opt/homebrew/lib` on Apple silicon —
+ * stays in `status/open-todos.md`, to be closed by teaching such a launcher to
+ * defer to the CLI rather than to re-derive.
  *
  * @param scanRoot Directory whose `node_modules` is globbed at launch time.
  * @param bakedDirs Prebuild dirs found at write time; entries outside `scanRoot`
@@ -433,7 +419,46 @@ export function buildNativeEnvPreamble(scanRoot, bakedDirs = [], target = {}) {
         `  ${libVar}="$gjsify_np\${${libVar}:+${separator}$${libVar}}"\n` +
         `  export GI_TYPELIB_PATH ${libVar}\n` +
         `fi\n` +
-        `unset gjsify_np gjsify_d gjsify_t\n`);
+        `unset gjsify_np gjsify_d gjsify_t\n` +
+        dyldFallbackPreamble(platform));
+}
+/**
+ * The darwin half of {@link buildNativeEnvPreamble}: put dyld's OWN default
+ * fallback list back, from inside the launcher.
+ *
+ * MEASURED on the macOS 15.7.9 x86_64 VM against the published 0.37.0: every
+ * `gjsify` command died in `dlopen(libsoup-3.0.0.dylib)` — before downloading
+ * anything, the CLI's own npm fetcher going through Soup — with a dyld search
+ * list that ended at `/usr/lib` and never held `/usr/local/lib`, where Homebrew
+ * puts every GTK library on Intel macOS. Exporting these four directories here
+ * makes the same command resolve, download and render (`OpenGL 4.1`).
+ *
+ * WHY HERE, and not the caller's job: SIP strips every `DYLD_*` variable when a
+ * PROTECTED binary is exec'd, and `/bin/sh` — this script — is protected. A
+ * value the USER exports is already gone by the time the preamble runs
+ * (measured: exporting the identical value around `gjsify showcase` changes
+ * nothing), while one the preamble exports ITSELF survives the following
+ * `exec gjs`, Homebrew's gjs being unprotected. This is the last hop that can.
+ *
+ * A CONSTANT is safe here only because it is dyld's DOCUMENTED DEFAULT: it
+ * cannot go stale the way baking `systemGiLibraryDirs()` in would (a launcher is
+ * routinely written before `brew install gtk4`), and it re-derives nothing —
+ * four literals from `dyld(1)`, shared with {@link dyldDefaultFallbackDirs}.
+ * An inherited value stays AHEAD of it; the export only ADDS BACK what dyld
+ * would have searched on its own.
+ *
+ * NOT the host's GI libdirs: `/opt/homebrew/lib` was never in dyld's default
+ * either, so an ARM Mac has that gap with or without gjsify —
+ * `status/open-todos.md`.
+ */
+export function dyldFallbackPreamble(platform) {
+    if (platform !== 'darwin')
+        return '';
+    // `HOME: '$HOME'` on purpose — the shim must expand it at LAUNCH, not bake
+    // the writing machine's home directory into every launcher.
+    const dirs = dyldDefaultFallbackDirs({ HOME: '$HOME' }).join(':');
+    return (`DYLD_FALLBACK_LIBRARY_PATH="\${DYLD_FALLBACK_LIBRARY_PATH:+$DYLD_FALLBACK_LIBRARY_PATH:}${dirs}"\n` +
+        `export DYLD_FALLBACK_LIBRARY_PATH\n`);
 }
 /** POSIX `sh` single-quoting for a launcher's target path. */
 export function shQuoteArg(s) {

package/lib/utils/detect-native-packages.d.ts

@@ -285,12 +285,12 @@ export declare function libraryPathVar(platform: string): {
  *      exactly the "nothing else found it" case. Consequence, and it is the
  *      intended precedence: gjsify's own prebuilds keep priority through the
  *      override variable, the system stack fills in behind it.
- *   2. **Our dirs go FIRST, an inherited fallback is kept BEHIND them, and
- *      `/usr/lib` is appended when there is none.** Setting the variable
- *      REPLACES dyld's own default fallback list, so writing only our dirs would
- *      silently remove `/usr/lib` from the search — a host that exported the
- *      variable itself already carries whatever tail it wants. Same composition
- *      as node-gi's re-exec.
+ *   2. **Our dirs go FIRST, an inherited fallback behind them, and dyld's own
+ *      default list behind that** — `composeDyldFallback()`, the same
+ *      composition node-gi's re-exec uses. Setting the variable REPLACES that
+ *      default list rather than extending it, so any composition that does not
+ *      carry it hands the child a SMALLER search path than it would have had
+ *      with the variable unset.
  *
  * Emitted even when `packages` is empty: the gap is in the host's loader, not in
  * a gjsify prebuild, so a plain `gjsify run script.gjs.js` that touches GTK needs

package/lib/utils/detect-native-packages.js

@@ -24,7 +24,7 @@
 import { readdirSync, existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { readPackageJson } from './pkg-json.js';
-import { splitSearchPath, systemGiLibraryDirs } from './system-gi.js';
+import { composeDyldFallback, systemGiLibraryDirs } from './system-gi.js';
 /**
  * Node `process.arch` → the uname-style spelling the Vala/meson bridges used to stage
  * into (`prebuilds/linux-x86_64/`).
@@ -567,12 +567,12 @@ const DYLD_FALLBACK_VAR = 'DYLD_FALLBACK_LIBRARY_PATH';
  *      exactly the "nothing else found it" case. Consequence, and it is the
  *      intended precedence: gjsify's own prebuilds keep priority through the
  *      override variable, the system stack fills in behind it.
- *   2. **Our dirs go FIRST, an inherited fallback is kept BEHIND them, and
- *      `/usr/lib` is appended when there is none.** Setting the variable
- *      REPLACES dyld's own default fallback list, so writing only our dirs would
- *      silently remove `/usr/lib` from the search — a host that exported the
- *      variable itself already carries whatever tail it wants. Same composition
- *      as node-gi's re-exec.
+ *   2. **Our dirs go FIRST, an inherited fallback behind them, and dyld's own
+ *      default list behind that** — `composeDyldFallback()`, the same
+ *      composition node-gi's re-exec uses. Setting the variable REPLACES that
+ *      default list rather than extending it, so any composition that does not
+ *      carry it hands the child a SMALLER search path than it would have had
+ *      with the variable unset.
  *
  * Emitted even when `packages` is empty: the gap is in the host's loader, not in
  * a gjsify prebuild, so a plain `gjsify run script.gjs.js` that touches GTK needs
@@ -603,19 +603,7 @@ export function buildNativeEnv(packages, opts = {}) {
     // it, so a Mac with no GI stack installed is left byte-unchanged.
     const systemDirs = (opts.systemGiDirs ?? systemGiLibraryDirs)({ platform, env });
     if (systemDirs.length > 0) {
-        const inherited = splitSearchPath(env[DYLD_FALLBACK_VAR]);
-        // Deduplicated, and not for tidiness: `systemGiLibraryDirs()` accepts a
-        // libdir stated outright through `GI_TYPELIB_PATH` on directory
-        // existence alone, so a host that names `/usr/lib/girepository-1.0`
-        // there puts `/usr/lib` in `systemDirs` — and the `/usr/lib` tail below
-        // then repeated it. A search path that lists the same directory twice
-        // asks the loader to stat it twice for every miss, and it makes the
-        // value the `$ …` echo prints read as though the CLI had composed
-        // something it did not. First occurrence wins in every loader, so
-        // dropping later repeats is behaviour-preserving.
-        out[DYLD_FALLBACK_VAR] = [
-            ...new Set([...systemDirs, ...(inherited.length > 0 ? inherited : ['/usr/lib'])]),
-        ].join(':');
+        out[DYLD_FALLBACK_VAR] = composeDyldFallback(systemDirs, env);
     }
     return out;
 }

package/lib/utils/node-script.js

@@ -17,6 +17,10 @@
 //                            injects the globals the script reads, and resolves bare
 //                            specifiers), then run the bundle.
 //
+// "the globals the script reads" is auto-detection: a syntactic answer to a runtime question,
+// blind to a dead branch. The script's own package overrides it through `gjsify.nodeScript` /
+// `gjsify.globals` (`Config.forNodeScript`) — the shim path has no command line for a flag.
+//
 // `import.meta.url` is the whole trick: the bundle does not live where the source lives, and
 // a script's own location is how it finds what it operates on — all four scripts this was
 // built for derive their package root from `dirname(fileURLToPath(import.meta.url))`. Left
@@ -29,6 +33,7 @@ import { existsSync, statSync } from 'node:fs';
 import { basename, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { hostRuntime } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { Config } from '../config.js';
 import { runGjsBundle } from './run-gjs.js';
 import { runRuntimeBundle } from './run-node.js';
 /**
@@ -73,6 +78,7 @@ export async function runNodeScript(file, extraArgs = [], options = {}) {
     // Dynamic import keeps the bundler machinery out of the eager module graph
     // of every `gjsify run`, matching how config.ts pulls it.
     const { BuildAction } = await import('../actions/build.js');
+    const { globals, excludeGlobals } = await new Config().forNodeScript(scriptPath);
     let bundlePath;
     try {
         bundlePath = await BuildAction.bundleFileForGjsCached(scriptPath, {
@@ -82,6 +88,8 @@ export async function runNodeScript(file, extraArgs = [], options = {}) {
             // A script is executed, never imported — no default export to preserve.
             preserveDefaultExport: false,
             define: { 'import.meta.url': JSON.stringify(pathToFileURL(scriptPath).href) },
+            globals,
+            excludeGlobals,
         });
     }
     catch (err) {
@@ -90,6 +98,6 @@ export async function runNodeScript(file, extraArgs = [], options = {}) {
             `workspace packages, pure-JS npm deps). (${err.message})`);
     }
     // Quiet for the same reason as the node path above; the bundle's location is
-    // deterministic (`node_modules/.cache/gjsify/node-scripts/<name>-<hash>.mjs`).
+    // deterministic (`node_modules/.cache/gjsify/node-scripts/<name>-<hash>/<name>.mjs`).
     await runGjsBundle(bundlePath, extraArgs, { exitOnSuccess: options.exitOnSuccess, quiet: true });
 }

package/lib/utils/system-gi.d.ts

@@ -60,3 +60,21 @@ export declare function systemGiLibraryDirs({ platform, env, existsDir, searchDi
  * pins both.
  */
 export declare function pathCovers(wanted: readonly string[], current: readonly string[]): boolean;
+/**
+ * dyld's OWN default fallback list, verbatim from `dyld(1)`. Setting
+ * `DYLD_FALLBACK_LIBRARY_PATH` REPLACES it, so anything composed for that
+ * variable must carry it as a tail. The incident that bought this rule is in the
+ * ORIGINAL (`packages/node-gi/node-gi/system-gi.js`); the mirror does not
+ * restate it.
+ */
+export declare function dyldDefaultFallbackDirs(env?: Record<string, string | undefined>): string[];
+/**
+ * Compose a `DYLD_FALLBACK_LIBRARY_PATH` value: `wanted`, then the launching
+ * environment's own value, then {@link dyldDefaultFallbackDirs} —
+ * unconditionally, so a child launched through gjsify never searches LESS than
+ * one launched without it. Deduplicated: `systemGiLibraryDirs()` can legitimately
+ * yield a directory the tail also names, and a repeated entry costs the loader a
+ * second stat on every miss. First occurrence wins everywhere, so dropping later
+ * repeats is behaviour-preserving.
+ */
+export declare function composeDyldFallback(wanted: readonly string[], env?: Record<string, string | undefined>): string;

package/lib/utils/system-gi.js

@@ -174,3 +174,28 @@ export function systemGiLibraryDirs({ platform = process.platform, env = process
 export function pathCovers(wanted, current) {
     return wanted.every((dir) => current.includes(dir));
 }
+/**
+ * dyld's OWN default fallback list, verbatim from `dyld(1)`. Setting
+ * `DYLD_FALLBACK_LIBRARY_PATH` REPLACES it, so anything composed for that
+ * variable must carry it as a tail. The incident that bought this rule is in the
+ * ORIGINAL (`packages/node-gi/node-gi/system-gi.js`); the mirror does not
+ * restate it.
+ */
+export function dyldDefaultFallbackDirs(env = process.env) {
+    const home = env['HOME'];
+    return [...(home ? [`${home}/lib`] : []), '/usr/local/lib', '/lib', '/usr/lib'];
+}
+/**
+ * Compose a `DYLD_FALLBACK_LIBRARY_PATH` value: `wanted`, then the launching
+ * environment's own value, then {@link dyldDefaultFallbackDirs} —
+ * unconditionally, so a child launched through gjsify never searches LESS than
+ * one launched without it. Deduplicated: `systemGiLibraryDirs()` can legitimately
+ * yield a directory the tail also names, and a repeated entry costs the loader a
+ * second stat on every miss. First occurrence wins everywhere, so dropping later
+ * repeats is behaviour-preserving.
+ */
+export function composeDyldFallback(wanted, env = process.env) {
+    return [
+        ...new Set([...wanted, ...splitSearchPath(env['DYLD_FALLBACK_LIBRARY_PATH']), ...dyldDefaultFallbackDirs(env)]),
+    ].join(':');
+}