@gjsify/cli 0.29.0 → 0.30.0

package/lib/config.js

@@ -223,7 +223,7 @@ export class Config {
         const pkg = (await this.readPackageJSON(configFilePath));
         const tsConfig = (await this.readTSConfig(configFilePath));
         tsConfig.reflection ||= cliArgs.reflection;
-        // TODO replace with `cliArgs.logLevel`
+        // TODO(open-todos: 10 small API gaps): replace with `cliArgs.logLevel`
         configData.verbose = cliArgs.verbose || false;
         configData.exclude = cliArgs.exclude || [];
         if (cliArgs.consoleShim !== undefined)

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

@@ -61,6 +61,17 @@ export declare function buildLauncherShims(opts: {
      * path the prebuilds have to be reachable through.
      */
     prependEnv?: Readonly<Record<string, string>>;
+    /**
+     * Second interpreter + script to run when the primary interpreter is not on
+     * `PATH`. The batch/PowerShell counterpart of {@link buildShLauncher}'s
+     * `nodeFallbackAbs` — a Windows host with no `gjs` is the majority case, and
+     * the `.cmd`/`.ps1` members are the ones cmd.exe and pwsh actually reach.
+     */
+    fallback?: {
+        interpreter: string;
+        interpreterArgs?: readonly string[];
+        target: string;
+    };
 }): {
     cmd: string;
     ps1: string;
@@ -182,6 +193,26 @@ export declare function normalizeBinMap(pkgName: string, bin: string | Record<st
  *
  * `isGjsBin` lets the caller keep plain-Node packages on the plain symlink path
  * — this must not change how `lodash`'s bin is linked.
+ *
+ * WHY THE npm MAP COMES BACK TOO
+ *
+ * The reasoning above is sound and INCOMPLETE: it was written from the Node-less
+ * GJS host and is blind to the mirror case. `@gjsify/cli` declares BOTH fields,
+ * so a host with no `gjs` — macOS and Windows, the two active port targets —
+ * got `exec gjs -m <bundle>`, which is exit 127, while a working Node entry sat
+ * beside it in the same package. `cli-cross-platform.yml` recorded that on both
+ * OSes for three consecutive releases (v0.27.1, v0.28.0, v0.29.0); it is
+ * advisory, so it stayed red. The install even KNEW: its own post-install check
+ * printed `Missing required system dependencies: ✗ GJS` and then wrote a
+ * gjs-only launcher anyway.
+ *
+ * So `nodeFallback` carries the npm map alongside, and the LAUNCHER decides per
+ * invocation. Deliberately not an install-time host probe: an install-time
+ * decision is a SNAPSHOT, and this repo has already paid for that exact mistake
+ * once — `buildNativeEnvPreamble` used to bake the install-time prebuild scan,
+ * so a package installed later was invisible and v0.24.1 shipped a launcher with
+ * no preamble at all. A host probe here fails the same way in reverse: install
+ * without gjs, install gjs afterwards, shim still points at Node forever.
  */
 export declare function pickBinMap(pkgName: string, pkgJson: {
     bin?: string | Record<string, string>;
@@ -191,6 +222,7 @@ export declare function pickBinMap(pkgName: string, pkgJson: {
 }): {
     map: Map<string, string>;
     isGjsBin: boolean;
+    nodeFallback: Map<string, string> | null;
 } | null;
 /**
  * The POSIX `sh` launcher gjsify writes for a bin it owns.
@@ -205,10 +237,17 @@ export declare function pickBinMap(pkgName: string, pkgJson: {
  * because not every published bundle carries a `#!/usr/bin/env -S gjs -m` line,
  * and direct-exec'ing a shebang-less `.mjs` falls through to `/bin/sh`, which
  * then parses JavaScript as shell.
+ *
+ * `nodeFallbackAbs` makes the runtime choice per INVOCATION rather than per
+ * install — see {@link pickBinMap} for why a host probe at install time is the
+ * wrong shape. `gjs` stays first: that is today's behaviour on a host carrying
+ * both, and which runtime wins is a separate decision from making the shim
+ * runnable at all.
  */
 export declare function buildShLauncher(targetAbs: string, opts: {
     envPreamble?: string;
     isGjsBundle: boolean;
+    nodeFallbackAbs?: string;
 }): string;
 /** True when a bin target is a GJS-runnable bundle rather than a Node script. */
 export declare function isGjsBundlePath(target: string): boolean;

package/lib/utils/bin-shim.js

@@ -223,26 +223,63 @@ export function buildCmdShim(relTargetPosix, shebang) {
  * fails the same way on every OS.
  */
 export function buildLauncherShims(opts) {
-    const { interpreter, interpreterArgs = [], target, prependEnv = {} } = opts;
+    const { interpreter, interpreterArgs = [], target, prependEnv = {}, fallback } = opts;
     const winTarget = target.split('/').join('\\');
     const argv = interpreterArgs.length > 0 ? `${interpreterArgs.join(' ')} ` : '';
     const entries = Object.entries(prependEnv);
+    const fbTarget = fallback === undefined ? '' : fallback.target.split('/').join('\\');
+    const fbArgv = fallback?.interpreterArgs !== undefined && fallback.interpreterArgs.length > 0
+        ? `${fallback.interpreterArgs.join(' ')} `
+        : '';
     let cmd = CMD_HEAD;
     for (const [key, value] of entries)
         cmd += `@SET "${key}=${value};%${key}%"\r\n`;
-    cmd += `${interpreter} ${argv}"${winTarget}" %*\r\n`;
+    if (fallback === undefined) {
+        cmd += `${interpreter} ${argv}"${winTarget}" %*\r\n`;
+    }
+    else {
+        // `where` is the batch equivalent of `command -v`; it writes to stdout,
+        // so both streams are silenced. ERRORLEVEL is read via IF/ELSE rather
+        // than `&&`/`||` chaining, which would swallow the child's own exit code.
+        cmd +=
+            `@where ${interpreter} >NUL 2>NUL\r\n` +
+                `@IF %ERRORLEVEL% EQU 0 (\r\n` +
+                `  ${interpreter} ${argv}"${winTarget}" %*\r\n` +
+                `) ELSE (\r\n` +
+                `  ${fallback.interpreter} ${fbArgv}"${fbTarget}" %*\r\n` +
+                `)\r\n`;
+    }
     let ps1 = '#!/usr/bin/env pwsh\n';
     for (const [key, value] of entries)
         ps1 += `$env:${key} = "${value};" + $env:${key}\n`;
     const ps1Args = interpreterArgs.map((a) => `"${a}" `).join('');
-    ps1 +=
-        '# Support pipeline input\n' +
-            'if ($MyInvocation.ExpectingInput) {\n' +
-            `  $input | & "${interpreter}" ${ps1Args}"${winTarget}" $args\n` +
-            '} else {\n' +
-            `  & "${interpreter}" ${ps1Args}"${winTarget}" $args\n` +
-            '}\n' +
-            'exit $LASTEXITCODE\n';
+    if (fallback === undefined) {
+        ps1 +=
+            '# Support pipeline input\n' +
+                'if ($MyInvocation.ExpectingInput) {\n' +
+                `  $input | & "${interpreter}" ${ps1Args}"${winTarget}" $args\n` +
+                '} else {\n' +
+                `  & "${interpreter}" ${ps1Args}"${winTarget}" $args\n` +
+                '}\n';
+    }
+    else {
+        // Bind the three parts once, then call once — the alternative (a full
+        // if/else around two near-identical invocation blocks, each of which
+        // already branches on pipeline input) is four copies of the same call.
+        const psList = (a) => a.length === 0 ? '@()' : `@(${a.map((x) => `"${x}"`).join(', ')})`;
+        ps1 +=
+            `$exe = "${interpreter}"; $exeArgs = ${psList(interpreterArgs)}; $script = "${winTarget}"\n` +
+                `if (-not (Get-Command "${interpreter}" -ErrorAction SilentlyContinue)) {\n` +
+                `  $exe = "${fallback.interpreter}"; $exeArgs = ${psList(fallback.interpreterArgs ?? [])}; $script = "${fbTarget}"\n` +
+                '}\n' +
+                '# Support pipeline input\n' +
+                'if ($MyInvocation.ExpectingInput) {\n' +
+                '  $input | & $exe @exeArgs $script $args\n' +
+                '} else {\n' +
+                '  & $exe @exeArgs $script $args\n' +
+                '}\n';
+    }
+    ps1 += 'exit $LASTEXITCODE\n';
     return { cmd, ps1 };
 }
 /** POSIX `sh` single-quoting — the one place the escape lives. */
@@ -437,14 +474,39 @@ export function normalizeBinMap(pkgName, bin) {
  *
  * `isGjsBin` lets the caller keep plain-Node packages on the plain symlink path
  * — this must not change how `lodash`'s bin is linked.
+ *
+ * WHY THE npm MAP COMES BACK TOO
+ *
+ * The reasoning above is sound and INCOMPLETE: it was written from the Node-less
+ * GJS host and is blind to the mirror case. `@gjsify/cli` declares BOTH fields,
+ * so a host with no `gjs` — macOS and Windows, the two active port targets —
+ * got `exec gjs -m <bundle>`, which is exit 127, while a working Node entry sat
+ * beside it in the same package. `cli-cross-platform.yml` recorded that on both
+ * OSes for three consecutive releases (v0.27.1, v0.28.0, v0.29.0); it is
+ * advisory, so it stayed red. The install even KNEW: its own post-install check
+ * printed `Missing required system dependencies: ✗ GJS` and then wrote a
+ * gjs-only launcher anyway.
+ *
+ * So `nodeFallback` carries the npm map alongside, and the LAUNCHER decides per
+ * invocation. Deliberately not an install-time host probe: an install-time
+ * decision is a SNAPSHOT, and this repo has already paid for that exact mistake
+ * once — `buildNativeEnvPreamble` used to bake the install-time prebuild scan,
+ * so a package installed later was invisible and v0.24.1 shipped a launcher with
+ * no preamble at all. A host probe here fails the same way in reverse: install
+ * without gjs, install gjs afterwards, shim still points at Node forever.
  */
 export function pickBinMap(pkgName, pkgJson) {
     const gjsifyBin = pkgJson.gjsify?.bin;
-    if (gjsifyBin !== undefined)
-        return { map: normalizeBinMap(pkgName, gjsifyBin), isGjsBin: true };
     const npmBin = pkgJson.bin;
+    if (gjsifyBin !== undefined) {
+        return {
+            map: normalizeBinMap(pkgName, gjsifyBin),
+            isGjsBin: true,
+            nodeFallback: npmBin === undefined ? null : normalizeBinMap(pkgName, npmBin),
+        };
+    }
     if (npmBin !== undefined)
-        return { map: normalizeBinMap(pkgName, npmBin), isGjsBin: false };
+        return { map: normalizeBinMap(pkgName, npmBin), isGjsBin: false, nodeFallback: null };
     return null;
 }
 /**
@@ -460,9 +522,23 @@ export function pickBinMap(pkgName, pkgJson) {
  * because not every published bundle carries a `#!/usr/bin/env -S gjs -m` line,
  * and direct-exec'ing a shebang-less `.mjs` falls through to `/bin/sh`, which
  * then parses JavaScript as shell.
+ *
+ * `nodeFallbackAbs` makes the runtime choice per INVOCATION rather than per
+ * install — see {@link pickBinMap} for why a host probe at install time is the
+ * wrong shape. `gjs` stays first: that is today's behaviour on a host carrying
+ * both, and which runtime wins is a separate decision from making the shim
+ * runnable at all.
  */
 export function buildShLauncher(targetAbs, opts) {
     const preamble = opts.isGjsBundle ? (opts.envPreamble ?? '') : '';
+    if (opts.isGjsBundle && opts.nodeFallbackAbs !== undefined) {
+        // The preamble only ever configures the GI search path, so it stays
+        // inside the gjs branch — exporting it around a Node exec would be
+        // inert at best and misleading to anyone reading the shim.
+        return (`#!/bin/sh\nif command -v gjs >/dev/null 2>&1; then\n${preamble}` +
+            `exec gjs -m ${shQuote(targetAbs)} "$@"\nfi\n` +
+            `exec node ${shQuote(opts.nodeFallbackAbs)} "$@"\n`);
+    }
     const exec = opts.isGjsBundle ? `exec gjs -m ${shQuote(targetAbs)} "$@"` : `exec ${shQuote(targetAbs)} "$@"`;
     return `#!/bin/sh\n${preamble}${exec}\n`;
 }

package/lib/utils/check-system-deps.d.ts

@@ -28,6 +28,27 @@ export type PackageManager = 'apt' | 'dnf' | 'pacman' | 'zypper' | 'apk' | 'brew
  * MacPorts or Nix host, and it is why this must never fall back to "probably brew".
  */
 export declare function detectPackageManager(): PackageManager;
+interface OptionalDep {
+    /** DepCheck id */
+    id: string;
+    /** Display name */
+    name: string;
+    /** pkg-config library name */
+    pkgName: string;
+}
+/** Optional system deps keyed by their DepCheck id. Exported for the spec's declaration invariant. */
+export declare const OPTIONAL_DEPS: Record<string, OptionalDep>;
+/**
+ * Map of @gjsify/* package name → ids of OPTIONAL_DEPS this package needs.
+ * Generated by walking each package's `gi://` imports (excluding the always-
+ * available trio GLib/GObject/Gio).
+ *
+ * Used to compute the set of optional deps to check for a given project.
+ *
+ * Exported for the spec's declaration invariant: every id named here must exist in
+ * OPTIONAL_DEPS, or the dep is silently never checked.
+ */
+export declare const PACKAGE_DEPS: Record<string, string[]>;
 /**
  * Run all dependency checks. Used by `gjsify check` to show full system status.
  *
@@ -86,3 +107,4 @@ export interface TypeSkewReaders {
  * ignore the output.
  */
 export declare function checkTypeSkew(cwd: string, readers?: TypeSkewReaders): TypeSkew[];
+export {};

package/lib/utils/check-system-deps.js

@@ -87,8 +87,8 @@ export function detectPackageManager() {
     }
     return 'unknown';
 }
-/** Optional system deps keyed by their DepCheck id. */
-const OPTIONAL_DEPS = {
+/** Optional system deps keyed by their DepCheck id. Exported for the spec's declaration invariant. */
+export const OPTIONAL_DEPS = {
     manette: { id: 'manette', name: 'libmanette', pkgName: 'manette-0.2' },
     gstreamer: { id: 'gstreamer', name: 'GStreamer', pkgName: 'gstreamer-1.0' },
     'gst-app': { id: 'gst-app', name: 'GStreamer App', pkgName: 'gstreamer-app-1.0' },
@@ -105,6 +105,21 @@ const OPTIONAL_DEPS = {
     // `Run-time dependency X found: NO` error mid-build.
     gnutls: { id: 'gnutls', name: 'GnuTLS', pkgName: 'gnutls' },
     nghttp2: { id: 'nghttp2', name: 'libnghttp2', pkgName: 'libnghttp2' },
+    // RUNTIME deps of the shipped prebuilds, not build-time ones — the distinction
+    // the two entries above make does not hold for these. Measured on fedora:43
+    // provisioned like a CONSUMER (gjs + libsoup3 only), `ldd` over every committed
+    // linux-x64 prebuild: three sonames do not resolve, and each makes its typelib
+    // UNLOADABLE, which surfaces as `Unsupported type void, deriving from
+    // fundamental void` at first construction — a message that names nothing.
+    //   @gjsify/rolldown-native  libjson-glib-1.0.so.0
+    //   @gjsify/webgl            libepoxy.so.0            (gdk-pixbuf already listed)
+    //   @gjsify/webrtc-native    libgstwebrtc-1.0.so.0    (gstreamer already listed)
+    // json-glib is the severe one: rolldown-native IS the GJS bundler engine, so a
+    // host without it cannot `gjsify build` at all, while `gjsify install` printed
+    // "System dependencies OK." — a check passing for the wrong reason.
+    'json-glib': { id: 'json-glib', name: 'JSON-GLib', pkgName: 'json-glib-1.0' },
+    epoxy: { id: 'epoxy', name: 'libepoxy', pkgName: 'epoxy' },
+    'gst-webrtc': { id: 'gst-webrtc', name: 'GStreamer WebRTC', pkgName: 'gstreamer-webrtc-1.0' },
 };
 /**
  * Map of @gjsify/* package name → ids of OPTIONAL_DEPS this package needs.
@@ -112,8 +127,11 @@ const OPTIONAL_DEPS = {
  * available trio GLib/GObject/Gio).
  *
  * Used to compute the set of optional deps to check for a given project.
+ *
+ * Exported for the spec's declaration invariant: every id named here must exist in
+ * OPTIONAL_DEPS, or the dep is silently never checked.
  */
-const PACKAGE_DEPS = {
+export const PACKAGE_DEPS = {
     '@gjsify/gamepad': ['manette'],
     '@gjsify/webaudio': ['gstreamer', 'gst-app'],
     '@gjsify/iframe': ['webkitgtk'],
@@ -124,13 +142,17 @@ const PACKAGE_DEPS = {
     // as a special-case checkNpmPackage rather than checkPkgConfig in
     // runOptionalChecks. Mapping it here so its presence in the project's
     // dep tree triggers the check.
-    '@gjsify/webgl': ['gwebgl'],
+    '@gjsify/webgl': ['gwebgl', 'gdk-pixbuf', 'epoxy'],
     // Native Vala bridges with `dependency('gnutls')` / `dependency('libnghttp2')`
     // in their meson.build. Optional because the shipped prebuild covers the
     // common-arch user path; only contributors rebuilding from source hit the
     // build-time dep.
     '@gjsify/tls-native': ['gnutls'],
     '@gjsify/http2-native': ['nghttp2'],
+    // Unlike the two above, these are LOAD-time: the prebuild is dynamically linked
+    // and GIRepository cannot open its backing library without them.
+    '@gjsify/rolldown-native': ['json-glib'],
+    '@gjsify/webrtc-native': ['gstreamer', 'gst-webrtc'],
     // @gjsify/event-bridge only needs gtk4/gdk which are already in the
     // required set, so it doesn't need an optional entry.
 };
@@ -367,6 +389,8 @@ const PM_PACKAGES = {
         cairo: 'libcairo2-dev',
         gnutls: 'libgnutls28-dev',
         nghttp2: 'libnghttp2-dev',
+        'json-glib': 'libjson-glib-dev',
+        epoxy: 'libepoxy-dev',
     },
     dnf: {
         gjs: 'gjs',
@@ -390,6 +414,8 @@ const PM_PACKAGES = {
         cairo: 'cairo-devel',
         gnutls: 'gnutls-devel',
         nghttp2: 'libnghttp2-devel',
+        'json-glib': 'json-glib-devel',
+        epoxy: 'libepoxy-devel',
     },
     pacman: {
         gjs: 'gjs',
@@ -413,6 +439,8 @@ const PM_PACKAGES = {
         cairo: 'cairo',
         gnutls: 'gnutls',
         nghttp2: 'libnghttp2',
+        'json-glib': 'json-glib',
+        epoxy: 'libepoxy',
     },
     zypper: {
         gjs: 'gjs',
@@ -436,6 +464,8 @@ const PM_PACKAGES = {
         cairo: 'cairo-devel',
         gnutls: 'libgnutls-devel',
         nghttp2: 'libnghttp2-devel',
+        'json-glib': 'json-glib-devel',
+        epoxy: 'libepoxy-devel',
     },
     apk: {
         gjs: 'gjs',
@@ -459,6 +489,8 @@ const PM_PACKAGES = {
         cairo: 'cairo-dev',
         gnutls: 'gnutls-dev',
         nghttp2: 'nghttp2-dev',
+        'json-glib': 'json-glib-dev',
+        epoxy: 'libepoxy-dev',
     },
     // macOS. Names verified against homebrew/core rather than inferred from the
     // Linux rows — the mapping is NOT mechanical: Homebrew ships no `-dev`/`-devel`
@@ -502,6 +534,8 @@ const PM_PACKAGES = {
         cairo: 'cairo',
         gnutls: 'gnutls',
         nghttp2: 'nghttp2',
+        'json-glib': 'json-glib',
+        epoxy: 'libepoxy',
     },
     unknown: {},
 };

package/lib/utils/dlx-cache.js

@@ -158,7 +158,7 @@ export function symlinkSwap(cacheDir, prepareDir, opts = {}) {
 }
 /** Clean up `<cacheDir>/<oldPrepareDir>` siblings older than `maxAgeMinutes`. */
 export function cleanupStalePrepareDirs(cacheDir, _maxAgeMinutes = DEFAULT_TTL_MIN) {
-    // Out of scope for Phase 1 — pnpm has the same TODO. Leaving a stub so
+    // TODO(open-todos: 10 small API gaps): out of scope for Phase 1 — pnpm has the same stub. Kept so
     // call sites already exist when we do implement it.
     void cacheDir;
 }

package/lib/utils/install-backend-native.d.ts

@@ -250,6 +250,14 @@ export declare function writeBinEntry(opts: {
         envPreamble: string;
         prebuildDirs: readonly string[];
     };
+    /**
+     * The package's npm `bin` target, when it declares one ALONGSIDE
+     * `gjsify.bin`. The launcher then picks a runtime per invocation instead of
+     * hard-coding `gjs` — see {@link pickBinMap}. Absent for a package that
+     * declares only one of the two, which is every package but `@gjsify/cli`
+     * today.
+     */
+    nodeFallbackAbs?: string;
 }): void;
 type Logger = (fmt: string, ...args: unknown[]) => void;
 export {};

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

@@ -1766,7 +1766,7 @@ function readShebang(file) {
  * the same set from the same templates. See `./bin-shim.ts`.
  */
 export function writeBinEntry(opts) {
-    const { binDir, binName, targetAbs, gjs } = opts;
+    const { binDir, binName, targetAbs, gjs, nodeFallbackAbs } = opts;
     const platform = opts.platform ?? process.platform;
     const linkPath = path.join(binDir, binName);
     if (gjs) {
@@ -1775,7 +1775,7 @@ export function writeBinEntry(opts) {
         // plain symlink (or npm's three-file shim) under this very name.
         for (const stale of [linkPath, `${linkPath}.cmd`, `${linkPath}.ps1`])
             rmWithRetry(stale);
-        fs.writeFileSync(linkPath, buildShLauncher(targetAbs, { envPreamble: gjs.envPreamble, isGjsBundle: isBundle }));
+        fs.writeFileSync(linkPath, buildShLauncher(targetAbs, { envPreamble: gjs.envPreamble, isGjsBundle: isBundle, nodeFallbackAbs }));
         try {
             fs.chmodSync(linkPath, 0o755);
         }
@@ -1793,6 +1793,7 @@ export function writeBinEntry(opts) {
                 interpreterArgs: ['-m'],
                 target: targetAbs,
                 prependEnv,
+                fallback: nodeFallbackAbs === undefined ? undefined : { interpreter: 'node', target: nodeFallbackAbs },
             });
             fs.writeFileSync(`${linkPath}.cmd`, shims.cmd);
             fs.writeFileSync(`${linkPath}.ps1`, shims.ps1);
@@ -1872,11 +1873,16 @@ async function linkBins(nodes, prefix, log) {
             catch {
                 /* best effort */
             }
+            // Only a fallback that EXISTS is worth writing: a launcher naming a
+            // missing Node entry would trade exit 127 for a different exit 127.
+            const fallbackRel = picked.nodeFallback?.get(binName);
+            const fallbackAbs = fallbackRel === undefined ? undefined : path.join(pkgDir, fallbackRel);
             writeBinEntry({
                 binDir,
                 binName,
                 targetAbs,
                 gjs: picked.isGjsBin ? gjsEnvForPrefix() : undefined,
+                nodeFallbackAbs: fallbackAbs !== undefined && fs.existsSync(fallbackAbs) ? fallbackAbs : undefined,
             });
             created++;
         }

package/lib/utils/install-global.js

@@ -198,10 +198,19 @@ export function linkGlobalBins(packageNames, layout) {
             // then tries to parse JavaScript as shell. Plain Node scripts
             // with shebangs (lib/index.js) keep the direct-exec path.
             const isGjsBundle = isGjsBundlePath(targetAbs);
+            // A global install extracts the WHOLE package, so when it declares
+            // an npm `bin` beside its `gjsify.bin` that entry is on disk here
+            // too and the launcher can fall back to it on a host without `gjs`
+            // — the same fix as the project-local backend. Guarded on existence
+            // rather than assumed: naming a missing Node entry would only trade
+            // one exit 127 for another. See `pickBinMap`.
+            const fallbackRel = picked.nodeFallback?.get(binName);
+            const fallbackCandidate = fallbackRel === undefined ? undefined : path.join(pkgDir, fallbackRel);
+            const nodeFallbackAbs = fallbackCandidate !== undefined && fs.existsSync(fallbackCandidate) ? fallbackCandidate : undefined;
             // Only GJS bundles need the GI typelib search path. Plain Node
             // scripts ignore GI_TYPELIB_PATH, so skipping the preamble there
             // keeps the launcher minimal.
-            fs.writeFileSync(linkPath, buildShLauncher(targetAbs, { envPreamble, isGjsBundle }));
+            fs.writeFileSync(linkPath, buildShLauncher(targetAbs, { envPreamble, isGjsBundle, nodeFallbackAbs }));
             fs.chmodSync(linkPath, 0o755);
             // Windows runs neither an extension-less file nor a `#!` line, so
             // the `sh` launcher above is only reachable from git-bash/MSYS/WSL.
@@ -224,6 +233,9 @@ export function linkGlobalBins(packageNames, layout) {
                         interpreterArgs: ['-m'],
                         target: targetAbs,
                         prependEnv,
+                        fallback: nodeFallbackAbs === undefined
+                            ? undefined
+                            : { interpreter: 'node', target: nodeFallbackAbs },
                     })
                     : buildLauncherShims({
                         interpreter: shebang?.prog || 'node',

package/lib/utils/run-lifecycle-script.js

@@ -7,8 +7,28 @@
 // behaves like `yarn run` / `npm run`. That's wrong for the embedded use
 // case where pack/publish needs the lifecycle script to finish, then keep
 // running its own logic. This helper resolves to a Promise that settles
-// when the child exits — no process.exit, no GLib-mainloop intermingling
-// from `ensureMainLoop`.
+// when the child exits.
+//
+// ## Not calling `process.exit()` is what ARMED the hang, not what avoided it
+//
+// This header used to end "no process.exit, no GLib-mainloop intermingling
+// from `ensureMainLoop`". The second half was exactly backwards, and it is why
+// nobody looked here for #1010.
+//
+// `@gjsify/child_process`'s async `spawn()` calls `ensureMainLoop()`
+// unconditionally — the caller has no say. That arms a GJS main-loop hook whose
+// blocking `g_main_loop_run()` only `process.exit()` tears down. So a helper
+// that spawns asynchronously and deliberately does NOT exit leaves the loop
+// armed forever: `gjsify pack` on a package with a `prepack` wrote its tarball,
+// printed its complete JSON, and then parked at 0% CPU until killed at 5m30s.
+// A package with no lifecycle script exited in under a second, and the same
+// pack under Node exited in 0.68s.
+//
+// `utils/spawn.ts` already owns that contract and makes every call site DECLARE
+// which side of it they are on. This helper was the one spawn in the CLI that
+// bypassed it — the seventh of the "six near-identical wrappers" that file was
+// written to consolidate. It now goes through it with `completion: 'return'`,
+// which is what "settle, then keep running our own logic" means.
 //
 // Matches yarn / npm script semantics:
 //   - `shell: true` so `&&` / `|` / env-var refs work
@@ -16,8 +36,8 @@
 //   - `npm_lifecycle_event` / `npm_package_name` / `npm_package_version`
 //     env vars set
 //   - FORCE_COLOR=1 default unless caller overrides
-import { spawn } from 'node:child_process';
 import { delimiter, join } from 'node:path';
+import { describeExit, spawnToCompletion } from './spawn.js';
 import { findWorkspaceRoot } from './workspace-root.js';
 /**
  * Run a lifecycle script defined in `pkg.scripts[name]` from `wsDir`.
@@ -52,28 +72,24 @@ export async function runLifecycleScript(wsDir, pkg, name, opts = {}) {
         npm_package_version: pkg.version ?? '',
         ...opts.env,
     };
-    // `'inherit-stderr'` is our extension on top of node's stdio modes —
-    // child stdin inherits, child stdout → parent's stderr (fd 2), child
-    // stderr → parent's stderr. Used by `gjsify pack --json` so the
-    // prepack's log lines don't get interleaved with the JSON we emit on
-    // parent stdout. `spawn`'s `stdio` accepts numeric fds in array form
-    // and routes the child's matching stream to that fd.
-    const stdioConfig = opts.stdio === 'inherit-stderr' ? ['inherit', 2, 2] : (opts.stdio ?? 'inherit');
-    await new Promise((resolveOk, reject) => {
-        const child = spawn(literal, [], {
-            cwd: wsDir,
-            env: env,
-            stdio: stdioConfig,
-            shell: true,
-        });
-        child.on('close', (code) => {
-            if (code === 0)
-                resolveOk();
-            else {
-                reject(new Error(`gjsify lifecycle-script: "${name}" in ${wsDir} exited with code ${code}`));
-            }
-        });
-        child.on('error', reject);
+    // `'ignore'` has no `spawnToCompletion` equivalent and no call site in the
+    // tree; folding it onto `'inherit'` would silently start printing where a
+    // caller asked for silence, so it is rejected rather than approximated.
+    if (opts.stdio === 'ignore') {
+        throw new Error('gjsify lifecycle-script: stdio "ignore" is not supported — see utils/spawn.ts');
+    }
+    const result = await spawnToCompletion(literal, [], {
+        // The whole point of this helper: pack/publish waits for the script and
+        // then keeps running. Under GJS that is the blocking path, which is what
+        // keeps the armed main loop from outliving us — see the header.
+        completion: 'return',
+        cwd: wsDir,
+        env: env,
+        shell: true,
+        stdio: opts.stdio === 'inherit-stderr' ? 'inherit-stderr' : opts.stdio === 'pipe' ? 'pipe' : 'inherit',
     });
+    if (result.code !== 0) {
+        throw new Error(`gjsify lifecycle-script: "${name}" in ${wsDir} exited with ${describeExit(result)}`);
+    }
     return true;
 }

package/lib/utils/spawn.d.ts

@@ -33,8 +33,24 @@ export interface SpawnToCompletionOptions {
      * `'inherit'` (default) forwards the parent's stdio. `'pipe'` gives the
      * caller `child.stdout` / `child.stderr` via {@link onSpawn} — only
      * meaningful together with `completion: 'exit'` (see {@link onSpawn}).
+     *
+     * `'inherit-stderr'` inherits, but routes the child's **stdout to the
+     * parent's stderr**. For a parent whose own stdout is a machine-readable
+     * stream: `gjsify pack --json` emits JSON there, and a lifecycle script's
+     * log lines interleaved into it make the result unparseable for every
+     * caller that pipes it into `JSON.parse`.
+     */
+    stdio?: 'inherit' | 'pipe' | 'inherit-stderr';
+    /**
+     * Run `cmd` through the platform shell, so `&&`, `|` and env-var
+     * references work. `cmd` is then a whole command LINE and `args` must be
+     * empty — that is npm/yarn script semantics.
+     *
+     * Skips the win32 command rewrite by design, per this file's own rule:
+     * Node routes a `shell: true` spawn through `%COMSPEC%`, which finds
+     * `.cmd` shims on its own, so rewriting the string would corrupt it.
      */
-    stdio?: 'inherit' | 'pipe';
+    shell?: boolean;
     /**
      * Invoked synchronously with the live `ChildProcess` right after a
      * successful async spawn — the seam for kill-tracking registries and for

package/lib/utils/spawn.js

@@ -133,34 +133,51 @@ function mustBlock(opts) {
  */
 export function spawnToCompletion(cmd, args, opts) {
     const env = resolveEnv(opts);
+    // A shell invocation is a command LINE, not an argv, so the win32 rewrite
+    // must not touch it — see `SpawnToCompletionOptions.shell`.
+    const invocation = opts.shell
+        ? { cmd, args: [...args], windowsVerbatimArguments: false }
+        : forWin32(cmd, args, env);
     if (mustBlock(opts)) {
         // `'inherit'` is NOT forwarded through `@gjsify/child_process`'s GJS
         // spawnSync path (it drives a private main context via
         // `communicateWithTimeout`), so the child's diagnostics would be
         // silently dropped. Capture them and re-emit after the child exits.
         // stdin stays inherited so an interactive child still reads the tty.
-        const win = forWin32(cmd, args, env);
-        const r = spawnSync(win.cmd, win.args, {
+        const r = spawnSync(invocation.cmd, invocation.args, {
             stdio: ['inherit', 'pipe', 'pipe'],
             cwd: opts.cwd,
             env,
+            shell: opts.shell,
             maxBuffer: opts.maxBuffer ?? DEFAULT_MAX_BUFFER,
-            windowsVerbatimArguments: win.windowsVerbatimArguments,
+            windowsVerbatimArguments: invocation.windowsVerbatimArguments,
         });
         if (r.error)
             return Promise.reject(mapSpawnError(r.error, opts));
+        // The captured stdout goes to the parent's STDERR under
+        // `'inherit-stderr'` — same destination the streaming path routes it to,
+        // so the two agree on where a lifecycle script's chatter lands.
+        const out = opts.stdio === 'inherit-stderr' ? process.stderr : process.stdout;
         if (r.stdout && r.stdout.length > 0)
-            process.stdout.write(r.stdout);
+            out.write(r.stdout);
         if (r.stderr && r.stderr.length > 0)
             process.stderr.write(r.stderr);
         return Promise.resolve({ code: r.status, signal: r.signal ?? null });
     }
     return new Promise((resolvePromise, reject) => {
-        const win = forWin32(cmd, args, env);
+        const win = invocation;
         const spawnOpts = {
             cwd: opts.cwd,
-            stdio: opts.stdio === 'pipe' ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+            // Numeric fds route the child's matching stream to that fd, so
+            // `['inherit', 2, 2]` is stdin inherited, stdout AND stderr → fd 2.
+            stdio: opts.stdio === 'pipe'
+                ? ['ignore', 'pipe', 'pipe']
+                : opts.stdio === 'inherit-stderr'
+                    ? ['inherit', 2, 2]
+                    : 'inherit',
         };
+        if (opts.shell)
+            spawnOpts.shell = true;
         if (env)
             spawnOpts.env = env;
         if (win.windowsVerbatimArguments)