@gjsify/cli 0.23.0 → 0.24.2

package/lib/actions/build.d.ts

@@ -48,6 +48,18 @@ export declare class BuildAction {
      * there is no in-bundle plugin, so this hook is the sole injection point.
      */
     private applyShebang;
+    /**
+     * Post-bundle gate for `--app gjs`: throw when the emitted bundle still
+     * STATICALLY imports Node builtins, which stock GJS cannot resolve (see
+     * `utils/gjs-bundle-guard.ts` for the full rationale).
+     *
+     * The oracle is the bundler's own module graph — each chunk's `imports`
+     * list — not the emitted text. Both engines report it (npm `rolldown`
+     * natively, `@gjsify/rolldown-native` via `synthRolldownOutput`), and it
+     * cannot be fooled by a `node:` specifier quoted inside a string, which a
+     * text scan cannot tell from a statement.
+     */
+    private assertGjsOutputLoadable;
     /**
      * 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

@@ -10,6 +10,7 @@ import { chmod, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { normalizeBundlerOptions, mergeBundlerOptions } from '../utils/normalize-bundler-options.js';
 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';
 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
@@ -275,6 +276,21 @@ export class BuildAction {
         if (verbose)
             console.debug(`[gjsify] --shebang: wrote ${line} + chmod 0o755 to ${outfile}`);
     }
+    /**
+     * Post-bundle gate for `--app gjs`: throw when the emitted bundle still
+     * STATICALLY imports Node builtins, which stock GJS cannot resolve (see
+     * `utils/gjs-bundle-guard.ts` for the full rationale).
+     *
+     * The oracle is the bundler's own module graph — each chunk's `imports`
+     * list — not the emitted text. Both engines report it (npm `rolldown`
+     * natively, `@gjsify/rolldown-native` via `synthRolldownOutput`), and it
+     * cannot be fooled by a `node:` specifier quoted inside a string, which a
+     * text scan cannot tell from a statement.
+     */
+    assertGjsOutputLoadable(result, outfile, outdir) {
+        const chunks = (result.output ?? []).filter((item) => item.type === 'chunk');
+        assertGjsBundleLoadable(chunks, outfile ?? outdir ?? 'the GJS bundle');
+    }
     /**
      * Post-bundle step for a `--app browser` HTML entry: write the processed
      * `index.html` beside the JS bundle, with the entry `<script>`'s `src`
@@ -576,6 +592,10 @@ export class BuildAction {
         if ((app === 'gjs' || app === 'node') && this.configData.shebang) {
             await this.applyShebang(app, outfile, verbose);
         }
+        // Refuse to hand back a `--app gjs` bundle stock GJS cannot even load.
+        if (app === 'gjs') {
+            this.assertGjsOutputLoadable(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
@@ -626,6 +646,12 @@ export class BuildAction {
                         if ((app === 'gjs' || app === 'node') && this.configData.shebang) {
                             await this.applyShebang(app, outfile, verbose);
                         }
+                        // No `--app gjs` loadability gate here: the watcher's
+                        // BUNDLE_END carries the bundle, not the generated
+                        // output, and re-running `generate()` just to read the
+                        // chunk graph would double every rebuild. The one-shot
+                        // build is the gate that CI and the pre-commit hook go
+                        // through; `--watch` is a dev loop.
                     }
                     finally {
                         await event.result.close();

package/lib/bundler-pick.js

@@ -50,16 +50,7 @@ async function loadNpmRolldown() {
     if (isGjs()) {
         throw new Error('gjsify build: no usable bundler engine under GJS — `@gjsify/rolldown-native` is not loadable, ' +
             'and the npm `rolldown` engine is a Rust napi crate that cannot run under GJS.\n' +
-            'Most likely cause: the CLI bundle was invoked DIRECTLY (`gjs -m …/cli.gjs.mjs` or by executing ' +
-            'dist/cli.gjs.mjs), which bypasses the `gjsify` launcher that exports GI_TYPELIB_PATH / ' +
-            'LD_LIBRARY_PATH for the prebuilds. The typelib lookup happens inside the GJS runtime, so those ' +
-            'must be set BEFORE the process starts — the CLI cannot repair it from the inside. ' +
-            'Run through the `gjsify` bin instead (`node_modules/.bin/gjsify …`, or the globally installed shim), ' +
-            'or export the env yourself:\n' +
-            '  P=<repo>/packages/infra/rolldown-native/prebuilds/linux-x86_64\n' +
-            '  GI_TYPELIB_PATH=$P LD_LIBRARY_PATH=$P gjs -m …/cli.gjs.mjs build …\n' +
-            'Other causes: the JS facade `lib/` is not built (`gjsify workspace @gjsify/rolldown-native build` ' +
-            'under Node), or no prebuild exists for this architecture. Running the build under Node also works.');
+            diagnoseNativeEngine());
     }
     // Indirect specifier so Rolldown's static-analysis doesn't try to
     // bundle the npm crate into a GJS target build.
@@ -68,6 +59,58 @@ async function loadNpmRolldown() {
     const mod = (await import(/* @vite-ignore */ target));
     return mod.rolldown;
 }
+/**
+ * Say WHY the native engine could not be loaded, read off disk rather than
+ * guessed.
+ *
+ * The three causes need three different fixes, and this message used to assert
+ * the rarest of them ("the CLI bundle was invoked DIRECTLY … bypasses the
+ * `gjsify` launcher") as the "most likely cause". On the by-far most common
+ * one — a freshly cloned + freshly installed tree, where the engine's JS facade
+ * has simply never been built — that reading is not merely unhelpful, it points
+ * at a launcher that was in fact used correctly, so the reader goes looking for
+ * an env-var problem that does not exist. `scripts/verify-committed-bundles.mjs`
+ * hit exactly that and it blocked releases.
+ *
+ * The probe is `existsSync`-only (no import, no resolution) so it cannot itself
+ * throw or recurse into the failure being explained.
+ */
+function diagnoseNativeEngine() {
+    let pkgDir = null;
+    try {
+        const bundleDir = path.dirname(new URL(import.meta.url).pathname);
+        pkgDir = findRolldownNativeDir(process.cwd(), bundleDir);
+    }
+    catch {
+        pkgDir = null;
+    }
+    if (pkgDir === null) {
+        return ('`@gjsify/rolldown-native` is NOT INSTALLED — no node_modules/@gjsify/rolldown-native was found ' +
+            `walking up from ${process.cwd()} or from the CLI bundle's own directory.\n` +
+            'Install it: `gjsify install @gjsify/rolldown-native` (in the gjsify repo: `gjsify install`). ' +
+            'Running the build under Node also works — there the npm `rolldown` crate is used instead.');
+    }
+    const facade = path.join(pkgDir, 'lib', 'esm', 'index.js');
+    if (!existsSync(facade)) {
+        return (`The engine's JS facade is NOT BUILT: ${facade} does not exist.\n` +
+            'It is a BUILD OUTPUT, not something `gjsify install` produces — so a freshly cloned or freshly ' +
+            'installed tree never has it, and every `gjsify build` under GJS fails here until it is built once. ' +
+            'Building it needs a bundler, which is why it cannot bootstrap itself under GJS; the Node CLI entry ' +
+            'does it instead. From the gjsify repo root:\n' +
+            '  gjsify run build:infra                          # the full cold-tree chain (recommended)\n' +
+            '  node scripts/bootstrap-native-facades.mjs       # just the facades, if the rest is already built\n' +
+            'Both are idempotent and skip already-built facades in seconds.');
+    }
+    return ('The JS facade is built, so this is the typelib/prebuild lookup failing. Most likely the CLI bundle was ' +
+        'invoked DIRECTLY (`gjs -m …/cli.gjs.mjs`, or by executing dist/cli.gjs.mjs), which bypasses the `gjsify` ' +
+        'launcher that exports GI_TYPELIB_PATH / LD_LIBRARY_PATH for the prebuilds. The typelib lookup happens ' +
+        'inside the GJS runtime, so those must be set BEFORE the process starts — the CLI cannot repair it from ' +
+        'the inside. Run through the `gjsify` bin instead (`node_modules/.bin/gjsify …`, or the globally installed ' +
+        'shim), or export the env yourself:\n' +
+        `  P=${path.join(pkgDir, 'prebuilds', `${process.platform ?? 'linux'}-${process.arch ?? 'x64'}`)}\n` +
+        '  GI_TYPELIB_PATH=$P LD_LIBRARY_PATH=$P gjs -m …/cli.gjs.mjs build …\n' +
+        'Otherwise: no prebuild exists for this architecture. Running the build under Node also works.');
+}
 /**
  * Convert a bare npm specifier into something dynamic `import(...)` can
  * load regardless of host runtime:
@@ -295,9 +338,7 @@ async function tryLoadNative() {
                             return null;
                         }
                     })();
-                const resolved = resolvedFromNpm ??
-                    resolvedFromFs ??
-                    createRequire(import.meta.url).resolve(specifier);
+                const resolved = resolvedFromNpm ?? resolvedFromFs ?? createRequire(import.meta.url).resolve(specifier);
                 target = pathToFileURL(resolved).href;
             }
             const mod = (await import(/* @vite-ignore */ target));

package/lib/commands/affected.js

@@ -45,6 +45,38 @@
 //   --format=globs                        one `@gjsify/<name>` per line
 //   --format=github-actions                $GITHUB_OUTPUT key=value lines
 //
+// `include-args` CONTRACT (github-actions format) — read this before changing
+// its shape. The value is a SPACE-SEPARATED list of ALREADY-SHELL-SAFE tokens:
+//
+//     include-args=--include @gjsify/fs --include @gjsify/stream
+//
+// and its only supported consumption is an UNQUOTED `$INCLUDE_ARGS` expansion
+// in a POSIX shell, where word splitting is exactly the intent. It carries NO
+// quoting of its own, deliberately:
+//
+//   * `main.yml` splices it into a `su testuser -c "… sh -c '…'"` nesting, and
+//     the result of a parameter expansion is NEVER re-scanned for quotes. When
+//     this emitted `--include '@gjsify/fs'`, the apostrophes became part of the
+//     glob, every pattern matched zero workspaces, and `foreach` exited 0 —
+//     CI "built" nothing on every selective PR run in 0.65 s (repo task #75).
+//     Pre-quoting a value for an unknown number of nesting levels cannot work;
+//     emitting tokens that need no quoting at any level can.
+//   * There are FIVE consumers of this one output — the build / browser-bundle
+//     / check / test steps splice it into a command line, and thirteen
+//     `contains(needs.changes.outputs.include-args, '@gjsify/…')` GitHub
+//     expressions substring-match it. A format that requires per-consumer
+//     unquoting would have to be repeated five times in the very nesting that
+//     produced the bug; `contains()` is unaffected either way (it matched the
+//     quoted spelling too, which is why the gates kept working while the build
+//     silently did nothing).
+//
+// Shell-safety is ENFORCED, not assumed: `assertShellSafeWorkspaceName` rejects
+// any workspace name outside `[A-Za-z0-9@._/-]` before it is emitted. npm names
+// cannot contain those characters, so this never fires in practice — and if it
+// somehow does, the command exits non-zero, the classify step's
+// `continue-on-error` leaves the outputs unset, and CI falls back to a FULL
+// run. Failing towards "run everything" is the safe direction.
+//
 // `--changed-from-stdin` skips `git diff` entirely and reads a newline-
 // separated list of paths from stdin. Useful for local debugging and
 // for the spec suite. Stdin is slurped via `utils/stdin.ts`, NOT
@@ -52,6 +84,15 @@
 // idiom opens the relative file `./0` and the committed GJS classifier
 // bundle died with `ENOENT … read '0'` on every `--changed-from-stdin` run.
 import { spawnSync } from 'node:child_process';
+// STATIC import, never a lazy `require('node:fs')`. This package is ESM
+// (`"type": "module"`), so a bare `require` is a ReferenceError the moment the
+// line executes — and the only line that executes it sits behind
+// `if (process.env.GITHUB_OUTPUT)`, i.e. exclusively inside a GitHub Actions
+// step. That is why it survived from the command's first commit: every local
+// run and every spec took the stdout branch. There is no reason for laziness
+// here — the command already statically imports `node:child_process`, and the
+// classifier bundle resolves `node:fs` through `@gjsify/fs` like any other.
+import { appendFileSync } from 'node:fs';
 import { readStdinLines } from '../utils/stdin.js';
 import { discoverWorkspaces, buildDependencyGraph, buildReverseDependencyGraph, affectedClosure, workspacesForChangedFiles, } from '@gjsify/workspace';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
@@ -318,9 +359,11 @@ function emit(format, r) {
         return;
     }
     if (format === 'github-actions') {
+        // Unquoted, space-separated tokens — see the `include-args` CONTRACT
+        // block at the top of this file. Do NOT re-add quoting here.
         const includeArgs = r.global
             ? ''
-            : r.workspaces.map((n) => `--include '${escSingleQuote(n)}'`).join(' ');
+            : r.workspaces.map((n) => `--include ${assertShellSafeWorkspaceName(n)}`).join(' ');
         const out = process.env.GITHUB_OUTPUT;
         const lines = [
             `skip-all=${r.skipAll}`,
@@ -332,7 +375,6 @@ function emit(format, r) {
         ];
         if (out) {
             // GitHub Actions: append to $GITHUB_OUTPUT.
-            const { appendFileSync } = require('node:fs');
             for (const l of lines)
                 appendFileSync(out, `${l}\n`);
         }
@@ -353,6 +395,22 @@ function emit(format, r) {
     for (const name of r.workspaces)
         process.stdout.write(`    - ${name}\n`);
 }
-function escSingleQuote(s) {
-    return s.replace(/'/g, `'\\''`);
+// A workspace name that survives an UNQUOTED shell expansion unchanged: no
+// whitespace, no quote/escape characters, no glob metacharacters, no `$`, and
+// nothing the shell would treat as an operator. npm package names are a strict
+// subset of this, so the guard is a machine-checked restatement of the
+// `include-args` contract rather than a real runtime branch. Returns the name
+// so it can be used inline at the emit site.
+const SHELL_SAFE_WORKSPACE_NAME = /^[A-Za-z0-9@][A-Za-z0-9@._/-]*$/;
+function assertShellSafeWorkspaceName(name) {
+    if (SHELL_SAFE_WORKSPACE_NAME.test(name))
+        return name;
+    process.stderr.write(`gjsify affected: workspace name ${JSON.stringify(name)} is not shell-safe, so it cannot be emitted as an\n` +
+        `  \`include-args\` token (the value is consumed by an UNQUOTED $INCLUDE_ARGS expansion — see the\n` +
+        `  contract at the top of commands/affected.ts). Rename the workspace, or teach this command a\n` +
+        `  transport the consumers can unquote. Refusing to emit a filter that would silently mis-match.\n`);
+    process.exit(2);
+    // Unreachable — `process.exit` terminates. Present so this function has no
+    // fall-through path that could ever return an unsafe name.
+    throw new Error(`gjsify affected: unsafe workspace name ${name}`);
 }

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/foreach.js

@@ -208,7 +208,7 @@ export const foreachCommand = {
         default: false,
     })
         .option('include', {
-        description: 'Glob pattern to include workspaces by name (repeatable).',
+        description: 'Glob pattern to include workspaces by name (repeatable). A pattern that matches NO discovered workspace is a hard error — a filter selecting nothing is a typo or a caller-side quoting bug, never an intent.',
         type: 'string',
         array: true,
     })
@@ -295,6 +295,7 @@ export const foreachCommand = {
                 process.exit(1);
             }
         }
+        assertEveryIncludeMatches(allWorkspaces, args.include);
         let selected = filterWorkspaces(allWorkspaces, {
             include: args.include,
             exclude: args.exclude,
@@ -344,6 +345,12 @@ export const foreachCommand = {
             }
         }
         if (selected.length === 0) {
+            // Reaching here means every --include pattern DID match something
+            // (assertEveryIncludeMatches above is fatal otherwise) and the set
+            // was then narrowed to nothing by --exclude, --no-private, the
+            // script-presence filter, or --shard. All four are legitimate, so
+            // this stays a clean exit-0 no-op — see the assert's doc comment
+            // for why the two cases are not the same condition.
             console.log(`gjsify foreach: no workspaces match (${exec ? 'exec' : 'script'}="${cmd}", include=${JSON.stringify(args.include ?? [])}, exclude=${JSON.stringify(args.exclude ?? [])})`);
             return;
         }
@@ -410,6 +417,69 @@ export const foreachCommand = {
         process.exit(0);
     },
 };
+/**
+ * A `--include` pattern that matches ZERO of the discovered workspaces is a
+ * hard error. This is the load-bearing half of the fix for repo task #75: the
+ * CI classifier emitted its filter pre-quoted (`--include '@gjsify/fs'`), the
+ * workflow expanded it unquoted inside a `su … -c "… sh -c '…'"` nesting, the
+ * apostrophes became part of every glob, and this command matched nothing,
+ * printed one line, and exited 0. A build that did nothing was indistinguishable
+ * from a build that succeeded, so the bug lived through every selective PR run
+ * — the Build step took 0.65 s and every later step inspected whatever the
+ * cache had restored. The quoting was the defect; the SILENCE is why nobody saw
+ * it.
+ *
+ * Scope is deliberately "an include PATTERN matched no workspace", NOT "the
+ * final selection is empty". The final selection is legitimately empty in
+ * several supported situations and must stay exit-0:
+ *   * `--shard 3/4` over a 2-workspace closure — most shards run nothing;
+ *   * `--exclude '@gjsify/integration-*'` removing everything the include kept;
+ *   * script mode dropping workspaces that don't declare `<script>` (yarn does
+ *     this too, and it is why `foreach check` over a closure of script-less
+ *     packages is a no-op rather than a failure).
+ * All three describe a real, existing set being narrowed to nothing. A pattern
+ * that names something the workspace tree does not contain is different in
+ * kind: it is a typo, a stale package name, or a caller-side quoting bug, and
+ * it can never be what the caller meant. There is no opt-out flag — an escape
+ * hatch here would be re-arming exactly the silence this exists to remove.
+ */
+function assertEveryIncludeMatches(allWorkspaces, include) {
+    if (!include || include.length === 0)
+        return;
+    const unmatched = include.filter((pattern) => filterWorkspaces(allWorkspaces, { include: [pattern] }).length === 0);
+    if (unmatched.length === 0)
+        return;
+    const lines = [
+        `gjsify foreach: --include matched no workspace (${unmatched.length} of ${include.length} pattern(s)):`,
+    ];
+    for (const pattern of unmatched) {
+        lines.push(`  ${JSON.stringify(pattern)}`);
+        // The task-#75 signature: the pattern only fails because the caller's
+        // shell quotes ended up INSIDE the value. Name it outright — that
+        // failure reads as "package not found" and sends people hunting in the
+        // wrong place.
+        const unquoted = stripSurroundingQuotes(pattern);
+        if (unquoted !== pattern && filterWorkspaces(allWorkspaces, { include: [unquoted] }).length > 0) {
+            lines.push(`    → matches as ${JSON.stringify(unquoted)}: the QUOTES are part of the value. A shell expansion`, `      is not re-scanned for quoting, so a pre-quoted filter spliced through \`sh -c\` arrives with`, `      the quotes attached. Pass the bare name and let word splitting do the work.`);
+            continue;
+        }
+        const near = allWorkspaces
+            .map((w) => w.name)
+            .filter((name) => name.toLowerCase().includes(unquoted.replace(/\*/g, '').toLowerCase()))
+            .slice(0, 3);
+        if (near.length > 0)
+            lines.push(`    → did you mean: ${near.join(', ')}?`);
+    }
+    lines.push(`  ${allWorkspaces.length} workspace(s) discovered. Refusing to run: a filter that selects nothing would`, `  otherwise exit 0 and look exactly like a successful run over the whole set.`);
+    console.error(lines.join('\n'));
+    process.exit(1);
+}
+/** Drop ONE matching pair of surrounding `'` or `"` — the quoting-bug probe. */
+function stripSurroundingQuotes(s) {
+    if (s.length >= 2 && (s[0] === "'" || s[0] === '"') && s[s.length - 1] === s[0])
+        return s.slice(1, -1);
+    return s;
+}
 async function runSequential(workspaces, script, args, verbose, exec, cache) {
     for (const ws of workspaces) {
         await runOne(ws, script, args, /* prefixOutput */ false, verbose, exec, cache);

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';
@@ -205,10 +205,26 @@ export const installCommand = {
         const hardExitTimerId = overallTimeoutMs > 0
             ? setTimeout(() => {
                 const secs = Math.round(overallTimeoutMs / 100) / 10;
-                console.error(`gjsify install: still stuck ${Math.round(HARD_EXIT_GRACE_MS / 1000)}s after the ${secs}s ` +
-                    `budget elapsed and the in-flight aborts — forcing exit. A dependency's extract or ` +
-                    `link step wedged (typically a dropped Gio stream event under GJS). Re-run; if it ` +
-                    `persists, raise --timeout or file an issue.`);
+                // Do NOT assert a cause here — this timer cannot tell the
+                // two shapes apart, and claiming the rarer one sends the
+                // next reader after a bug that isn't there. Measured on a
+                // cold tree of this workspace: 1597 packages / ~4.8 GB
+                // extracted, of which ~3.4 GB are foreign-platform
+                // optional deps (`os`/`cpu` excludes the host) that npm
+                // would never place. That install was still making steady
+                // progress when the 30-min budget elapsed, and a re-run
+                // finished the remainder in ~2 min. Extraction also has
+                // multi-second SYNCHRONOUS stretches (tar parse + file
+                // writes) and 16 run concurrently, so the clean abort path
+                // can easily miss the grace window with nothing wedged.
+                console.error(`gjsify install: the ${secs}s budget elapsed and the abort did not unwind within ` +
+                    `${Math.round(HARD_EXIT_GRACE_MS / 1000)}s — forcing exit. That means one of two ` +
+                    `things, and this timer cannot distinguish them: the install was still WORKING ` +
+                    `(a cold tree here extracts several GB, and extraction blocks the loop in ` +
+                    `multi-second synchronous stretches), or a step genuinely wedged. Re-running tells ` +
+                    `you which, and is safe: extraction is idempotent, every package already on disk ` +
+                    `is skipped, so a second run finishes the remainder in a fraction of the time. A ` +
+                    `re-run that makes NO further progress is a real wedge — file an issue.`);
                 forceExit(1);
             }, overallTimeoutMs + HARD_EXIT_GRACE_MS)
             : null;
@@ -941,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
@@ -1029,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