@gjsify/cli 0.37.0 → 0.38.1

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/commands/showcase.js

@@ -7,18 +7,19 @@ import { ensurePkgDir } from './dlx.js';
 import { fetchPackument } from '@gjsify/npm-registry';
 import { loadNpmrc } from '../utils/load-npmrc.js';
 import { parseSpec } from '../utils/parse-spec.js';
+import { cliVersion } from '../utils/publish-headers.js';
 import { resolveNodeEntry } from '../utils/resolve-gjs-entry.js';
 import { runRuntimeBundle } from '../utils/run-node.js';
 import { EXAMPLE_RUNTIMES, isExampleRuntime, readDeclaredRuntimes, checkRuntimeSupported, defaultExampleRuntime, requiresGjsSystemDeps, } from '../utils/runtimes.js';
+/**
+ * This CLI's own version, or `undefined` when it genuinely cannot be told.
+ *
+ * The shared resolver, never a local fixed-depth manifest read — that misses from
+ * `dist/`, unpinning `dlxSpec`. Incident: `docs/code-anti-patterns.md`.
+ */
 function readCliVersion() {
-    try {
-        const pkgUrl = new URL('../../package.json', import.meta.url);
-        const pkg = JSON.parse(readFileSync(pkgUrl, 'utf8'));
-        return typeof pkg.version === 'string' ? pkg.version : undefined;
-    }
-    catch {
-        return undefined;
-    }
+    const version = cliVersion();
+    return version === 'unknown' ? undefined : version;
 }
 /**
  * `[gjsify <version>] ` for the banner — the CLI naming ITSELF.

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

@@ -20,9 +20,70 @@
 
 import GLib from 'gi://GLib';
 import Gio from 'gi://Gio';
-import Soup from 'gi://Soup?version=3.0';
 import system, { exit } from 'system';
 
+/**
+ * Soup, loaded late and — on a macOS that cannot find it — through one re-exec.
+ *
+ * WHY THIS IS NOT A PLAIN IMPORT. GI resolves a typelib's shared library with a
+ * bare-leaf `dlopen("libsoup-3.0.0.dylib")`. Homebrew installs that dylib in
+ * `/usr/local/lib` (Intel) or `/opt/homebrew/lib` (arm64), and `gjs` carries an
+ * rpath only for glib's own directory, so on a stock Homebrew macOS dyld never
+ * looks where the library actually is. Measured 2026-08-13 on macOS 15.7.9:
+ *
+ *     $ curl -fsSL .../install.mjs -o /tmp/g.mjs && gjs -m /tmp/g.mjs
+ *     Failed to load shared library 'libsoup-3.0.0.dylib' referenced by the typelib
+ *     JS ERROR: Error: Unsupported type void, deriving from fundamental void
+ *
+ * That is the DOCUMENTED install path for a platform this project advertises,
+ * and it fails before the first byte is downloaded — the bootstrap's own fetcher
+ * is Soup. `DYLD_FALLBACK_LIBRARY_PATH=/usr/local/lib` fixes it, but nothing can
+ * export that on the user's behalf from inside this process: the variable is
+ * read by dyld at image load, long before any JS runs. Hence a re-exec.
+ *
+ * Repaired ONLY when the load actually fails, so a healthy host (arm64 Homebrew,
+ * a distro-packaged gjs, anything with a working rpath) re-execs never.
+ *
+ * Note the probe touches `Session` rather than just importing the namespace:
+ * `imports.gi.Soup` SUCCEEDS on a broken host — the library is resolved lazily,
+ * when a type is first needed. A namespace-only check reports a healthy
+ * environment and is the reason this looked like a network bug for so long.
+ */
+const DYLD_REEXEC_MARKER = 'GJSIFY_INSTALL_DYLD_REEXEC';
+
+/** dyld's documented default fallback list, plus both Homebrew prefixes. */
+function dyldFallbackDirs() {
+    const home = GLib.get_home_dir();
+    return [`${home}/lib`, '/usr/local/lib', '/opt/homebrew/lib', '/lib', '/usr/lib'].join(':');
+}
+
+async function loadSoup() {
+    const mod = await import('gi://Soup?version=3.0');
+    void mod.default.Session; // forces the dlopen; see above
+    return mod.default;
+}
+
+let Soup;
+try {
+    Soup = await loadSoup();
+} catch (error) {
+    const onMacos = GLib.file_test('/usr/lib/dyld', GLib.FileTest.EXISTS);
+    if (!onMacos || GLib.getenv(DYLD_REEXEC_MARKER)) throw error;
+
+    const self = GLib.filename_from_uri(import.meta.url)[0];
+    const gjs = GLib.find_program_in_path('gjs');
+    if (!gjs) throw error;
+
+    // SIP strips an INHERITED DYLD_* when a protected binary is exec'd, but a
+    // value this process sets itself survives into Homebrew's unprotected `gjs`.
+    const launcher = new Gio.SubprocessLauncher({ flags: Gio.SubprocessFlags.NONE });
+    launcher.setenv('DYLD_FALLBACK_LIBRARY_PATH', dyldFallbackDirs(), true);
+    launcher.setenv(DYLD_REEXEC_MARKER, '1', true);
+    const child = launcher.spawnv([gjs, '-m', self, ...(system?.programArgs ?? [])]);
+    child.wait(null);
+    exit(child.get_exit_status() === 0 ? 0 : 1);
+}
+
 Gio._promisify(Soup.Session.prototype, 'send_and_read_async');
 Gio._promisify(Gio.Subprocess.prototype, 'wait_check_async');
 
@@ -134,6 +195,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 +258,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 +325,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 +382,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;
 }