@gjsify/cli 0.28.0 → 0.30.0

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

@@ -22,9 +22,9 @@
 // reported. So the DECLARATIONS are locked and the VERDICT is recomputed per
 // host at install time (see applyPlatformFilter).
 //
-// TWO INVARIANTS MAKE THAT CLAIM TRUE, and both are structural rather than
-// documented, because the first draft of this feature broke both while reading
-// as if it did not:
+// THREE INVARIANTS MAKE THAT CLAIM TRUE, and each is structural rather than
+// documented, because the first draft of this feature broke the first two while
+// reading as if it did not — and shipped without the third:
 //
 //   1. THE RESOLVE IS TARGET-BLIND. `resolveDeps` is not given the platform
 //      target at all — it cannot be, so it cannot record a target-dependent
@@ -47,6 +47,31 @@
 //      fixpoint for the same reason (refs/npm-cli/workspaces/arborist/lib/
 //      calc-dep-flags.js: "If a node is changed, we add to the queue and
 //      continue until no more changes").
+//   3. OPTIONALITY BELONGS TO THE EDGE, NOT TO THE BLOCK THE NAME WAS READ FROM.
+//      A name listed in BOTH `dependencies` and `optionalDependencies` is
+//      OPTIONAL: "entries in optionalDependencies will override entries of the
+//      same name in dependencies" (npm's package.json docs), which is why every
+//      walk over a node's dep edges here goes through {@link requiredDepEntries}
+//      instead of `Object.keys(node.dependencies)`. `@parcel/rust@2.16.4` is why
+//      it is written down: it declares all eight of its per-platform napi
+//      packages in both blocks, so a `dependencies`-only walk made
+//      `@parcel/rust-darwin-x64` REQUIRED and every Linux install of any tree
+//      containing parcel died with EBADPLATFORM — while `npm install` on the same
+//      manifest exits 0, installs
+//      `@parcel/rust-linux-x64-gnu`, and records the other seven as
+//      `"optional": true` in its own lockfile. The rule was already applied to
+//      swallowed resolve failures (`assertRequiredEdgesResolved`: "optionality
+//      lives on the edge, not on its endpoints") and missing from the two walks
+//      that decide fatal-vs-inert, which is the worst place to have half of it.
+//      It costs a lockfile field (`optionalDependencies` per entry, v4): without
+//      it the fresh-resolve path and the lockfile path would disagree about the
+//      same tree, which is the split invariant 2 exists to close.
+//      WHY THE DEFECT LOOKED LIKE IT DID NOT EXIST: the same napi shape is
+//      overwhelmingly published in ONE block — measured on the latest of `oxlint`,
+//      `esbuild` and `rollup`, all three list their per-platform bindings in
+//      `optionalDependencies` only (zero overlap), so they installed correctly
+//      throughout and every mock corpus reaches for that shape too. The block a
+//      publisher chooses is not a property this installer may assume.
 //
 // Out of scope (still deferred): peerDependencies validation,
 // lifecycle scripts, git/file specs.
@@ -74,9 +99,12 @@ const LOCKFILE_NAME = 'gjsify-lock.json';
 /**
  * v3 adds the per-entry platform declaration (`os`/`cpu`/`libc`) plus
  * `optional`, which together let a foreign-platform package be recorded without
- * being installed. v2 lockfiles are still READ (see {@link readLockfile}).
+ * being installed. v4 adds the per-entry `optionalDependencies` map, without
+ * which the optionality fixpoint cannot see WHICH of an entry's edges are
+ * optional and a name declared in both blocks comes out required (header note,
+ * invariant 3). Older lockfiles are still READ (see {@link readLockfile}).
  */
-const LOCKFILE_VERSION = 3;
+const LOCKFILE_VERSION = 4;
 /**
  * Lockfile versions this CLI can read. A v2 lockfile is a valid pin set that
  * simply predates the platform fields; rejecting it (the old
@@ -84,8 +112,19 @@ const LOCKFILE_VERSION = 3;
  * the following fresh resolve bump every `^`-range to the newest in-range
  * version — the exact silent churn lockfile preservation exists to prevent, on
  * every user's first install after upgrading the CLI.
+ *
+ * READING an older file is not the same as TRUSTING it for everything: only the
+ * current version short-circuits the resolve (see the branch below), so a v2/v3
+ * file seeds version preservation and is then rewritten. `--immutable` is the one
+ * path that must consume what it was handed verbatim, so there — and only there —
+ * a pre-v4 file keeps its pre-v4 edge fidelity: a both-blocks optional dep is
+ * judged required, exactly as before this fix. That is a strictly unchanged
+ * outcome rather than a new failure, and one plain `gjsify install` upgrades the
+ * file. Failing `--immutable` on an old-but-readable lockfile instead would break
+ * every CI whose committed file predates this CLI, including this repo's own
+ * (still v2).
  */
-const READABLE_LOCKFILE_VERSIONS = new Set([2, LOCKFILE_VERSION]);
+const READABLE_LOCKFILE_VERSIONS = new Set([2, 3, LOCKFILE_VERSION]);
 export async function installPackagesNative(opts) {
     // Fail clearly on an unsupported Node major BEFORE touching the ABI-locked
     // native deps — otherwise they SIGSEGV mid-extract with no actionable message.
@@ -161,11 +200,18 @@ async function installPackagesNativeLocked(opts, npmrc, log) {
     else {
         // A resolve has to run (new/changed/removed dep, or no lockfile yet).
         //
-        // A pre-v3 lockfile lands here too, even when it matches the request:
-        // its entries carry no platform declarations, so consuming it verbatim
-        // would keep installing the foreign-platform tree forever with nothing
-        // on disk to recompute the verdict from. One resolve — version-
-        // preserving, per the seeding below, so nothing bumps — upgrades it.
+        // A pre-v4 lockfile lands here too, even when it matches the request,
+        // because each bump added something the verdict is recomputed FROM and a
+        // file that lacks it cannot be consumed verbatim: pre-v3 entries carry no
+        // platform declaration (so the foreign-platform tree would keep installing
+        // forever), pre-v4 entries carry no `optionalDependencies` map (so a name
+        // declared in both blocks looks required and its incompatible siblings
+        // fail the install — the `@parcel/rust` shape, header note invariant 3).
+        // One resolve — version-preserving, per the seeding below, so nothing
+        // bumps — upgrades the file. That matters beyond tidiness here: the
+        // lockfile is written BEFORE the platform filter runs, so the failing
+        // install left a v3 file behind that would otherwise reproduce its own
+        // EBADPLATFORM on every later run without ever resolving again.
         //
         // Unless --refresh-lockfile was passed, seed it with the versions
         // already pinned in the existing lockfile so unchanged deps keep their
@@ -641,7 +687,13 @@ optionalSpecs) {
                     name: `${edge.name}@${version}`,
                 });
                 if (!skipDeps) {
-                    for (const [depName, depRange] of Object.entries(node.dependencies)) {
+                    // REQUIRED edges only — a name this package also lists in
+                    // `optionalDependencies` is queued by the loop below instead,
+                    // once, as optional (header note, invariant 3). Queuing it here
+                    // as well would place it with a `required: true` forward guess,
+                    // making a resolve failure fatal and (via the fixpoint) its
+                    // incompatible platform siblings fatal too.
+                    for (const [depName, depRange] of requiredDepEntries(node)) {
                         queue.push({
                             from: installPath,
                             name: depName,
@@ -764,6 +816,38 @@ function requiredTopLevelNames(specs, optionalSpecs) {
     }
     return names;
 }
+/**
+ * A node's REQUIRED dependency edges: its `dependencies`, minus every name its
+ * `optionalDependencies` also lists. The one place that decides what kind an edge
+ * is — both the resolve walk and the optionality fixpoint read it, so the two
+ * cannot drift.
+ *
+ * THE SUBTRACTION IS npm's RULE, not a policy of ours: "entries in
+ * optionalDependencies will override entries of the same name in dependencies, so
+ * it's usually best to only put in one place" (npm's package.json docs). Measured
+ * on `@parcel/rust@2.16.4`, which lists all eight per-platform napi packages in
+ * both blocks: `npm install` exits 0, installs `@parcel/rust-linux-x64-gnu` only,
+ * and writes `"optional": true` for all eight in its `package-lock.json`.
+ *
+ * WHY IT IS NOT MERELY A DEDUP: the kind decides what an incompatible
+ * `os`/`cpu`/`libc` MEANS (`applyPlatformFilter` — fatal vs. inert) and whether a
+ * failed resolve is tolerated. Reading `dependencies` alone therefore does not
+ * just visit a name twice, it promotes a foreign-platform binary to a required
+ * dependency and fails installs npm completes.
+ *
+ * The inverse direction is deliberately NOT symmetric: a name in
+ * `optionalDependencies` alone is optional (no `dependencies` entry to override),
+ * which is what {@link resolveDeps}'s second queue loop covers.
+ */
+export function requiredDepEntries(node) {
+    const entries = [];
+    for (const [name, range] of Object.entries(node.dependencies)) {
+        if (name in node.optionalDependencies)
+            continue;
+        entries.push([name, range]);
+    }
+    return entries;
+}
 /**
  * Recompute every node's `optional` flag as a FIXPOINT over the placed graph.
  * The only writer of the final flag; whatever the nodes arrive carrying is an
@@ -771,9 +855,10 @@ function requiredTopLevelNames(specs, optionalSpecs) {
  * back out of a file on the lockfile path) and is overwritten unconditionally.
  *
  * DEFINITION: a node is REQUIRED iff it is reachable from `requiredNames`
- * through `dependencies` edges alone; every other node is optional. Optionality
- * is therefore INHERITED — a plain dependency OF an optional package is still
- * optional — which is what npm's `optionalSet` computes.
+ * through REQUIRED edges alone ({@link requiredDepEntries} — `dependencies` minus
+ * the names `optionalDependencies` overrides); every other node is optional.
+ * Optionality is therefore INHERITED — a plain dependency OF an optional package
+ * is still optional — which is what npm's `optionalSet` computes.
  *
  * WHY A FIXPOINT AND NOT A ONE-SHOT PROMOTION AT THE REUSE SITE (the reviewed
  * defect): the walk queues a node's own dep edges at the moment it is placed,
@@ -788,23 +873,29 @@ function requiredTopLevelNames(specs, optionalSpecs) {
  * refs/npm-cli/workspaces/arborist/lib/calc-dep-flags.js: "If a node is changed,
  * we add to the queue and continue until no more changes."
  *
- * PATH-INDEPENDENCE IS THE OTHER REQUIREMENT, and it is why the walk reads
- * `dependencies` ONLY. A lockfile entry records `dependencies` and nothing else
- * (an `optionalDependencies` map is not persisted), so consulting
- * `node.optionalDependencies` here would make the fresh-resolve path and the
- * lockfile path compute different flags for the same tree — precisely the split
- * this pass exists to close. The cost is one npm quirk we do not reproduce: a
- * publisher listing the same name in BOTH blocks means "optional" to npm, and
- * comes out required here. That shape is vanishingly rare in practice (the
- * platform-binary packages this feature is about — rollup, lightningcss,
- * esbuild, fsevents — all list their optional deps in one block only), and
- * erring toward REQUIRED errs toward the loud failure, not the silent one.
+ * PATH-INDEPENDENCE IS THE OTHER REQUIREMENT, and it is why the lockfile carries
+ * an `optionalDependencies` map per entry (v4). The walk USED to read
+ * `dependencies` only, for exactly that reason — a lockfile entry recorded nothing
+ * else, so consulting `node.optionalDependencies` would have made the two paths
+ * compute different flags for the same tree. The premise was fixable and the
+ * consequence was not: a publisher listing the same name in BOTH blocks means
+ * "optional" to npm, came out REQUIRED here, and the shape is not rare — it is
+ * `@parcel/rust@2.16.4` (all eight per-platform napi packages in both blocks), so
+ * every Linux install of any tree containing parcel failed with EBADPLATFORM on
+ * `@parcel/rust-darwin-x64` while `npm install` thinned the same tree and exited
+ * 0. "Erring toward REQUIRED errs toward the loud failure" is true and was the
+ * wrong trade: the loud failure was not a real one, and no `--force` lifts it
+ * (nor should it). So the declaration is persisted and both paths subtract it.
+ * Reading a pre-v4 lockfile leaves the map empty, which reproduces the old
+ * behaviour for that file alone — see READABLE_LOCKFILE_VERSIONS.
  *
  * Runs before `writeLockfile` so the persisted flag is the final one, and before
  * `applyPlatformFilter` so the fatal-vs-inert decision reads it rather than the
- * guess.
+ * guess. Exported so the unit spec can drive it with INJECTED graphs: the whole
+ * fatal-vs-inert question is decided by these two functions in composition, and
+ * that is worth pinning without a registry.
  */
-function computeOptionalFlags(nodes, requiredNames, log) {
+export function computeOptionalFlags(nodes, requiredNames, log) {
     const byPath = new Map();
     for (const node of nodes)
         byPath.set(node.installPath, node);
@@ -833,7 +924,7 @@ function computeOptionalFlags(nodes, requiredNames, log) {
         const node = byPath.get(installPath);
         if (!node)
             continue;
-        for (const depName of Object.keys(node.dependencies)) {
+        for (const [depName] of requiredDepEntries(node)) {
             // Resolve the edge the way the REQUESTER will at runtime — through
             // the ancestor `node_modules` chain — so a nested copy is credited
             // to the requester that nested it and the hoisted one is not
@@ -904,8 +995,14 @@ function assertRequiredEdgesResolved(nodes, skippedEdges) {
             continue;
         // A REQUIRED package's own optionalDependency stays optional whatever
         // the package's flag says: optionality lives on the edge, not on its
-        // endpoints. This branch is what keeps a darwin-only `fsevents` under a
-        // required `chokidar` from failing every Linux install.
+        // endpoints (header note, invariant 3 — the same rule
+        // {@link requiredDepEntries} applies to the two graph walks). This branch
+        // is what keeps a darwin-only `fsevents` under a required `chokidar` from
+        // failing every Linux install.
+        //
+        // Membership, not `requiredDepEntries`: the failed edge may name something
+        // no longer in `dependencies` at all, and what is being asked here is
+        // whether the requester declared THIS name optional.
         //
         // Safe on both paths because `skippedEdges` is only ever non-empty on
         // the fresh-resolve path, where `optionalDependencies` is populated; the
@@ -1137,6 +1234,11 @@ function writeLockfile(lockfilePath, specs, nodes) {
             resolved: node.tarballUrl,
             integrity: node.integrity,
             dependencies: Object.keys(node.dependencies).length > 0 ? node.dependencies : undefined,
+            // The EDGE KINDS, for the same reason the platform declaration is
+            // here: `computeOptionalFlags` runs on the lockfile path too and
+            // cannot recompute what the file does not carry (v4, header note
+            // invariant 3). Omitted when empty, which is most packages.
+            optionalDependencies: Object.keys(node.optionalDependencies).length > 0 ? node.optionalDependencies : undefined,
             bin: node.bin,
             // The DECLARATION, never the verdict: `inert` is per-host and
             // deliberately absent from the file (a lockfile that recorded which
@@ -1208,7 +1310,12 @@ function lockfileToNodes(lockfile) {
             integrity: entry.integrity,
             installPath,
             dependencies: entry.dependencies ?? {},
-            optionalDependencies: {},
+            // Empty for a pre-v4 entry, which is why such a file never
+            // short-circuits the resolve: with no edge kinds recorded, a name the
+            // publisher put in both blocks reads as required here (the pre-fix
+            // behaviour). `--immutable` is the one path that consumes it anyway —
+            // see READABLE_LOCKFILE_VERSIONS.
+            optionalDependencies: entry.optionalDependencies ?? {},
             bin: entry.bin,
             // Rebuilt from the recorded declaration so `applyPlatformFilter`
             // reaches the SAME verdict on this path as on the fresh-resolve
@@ -1659,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) {
@@ -1668,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);
         }
@@ -1686,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);
@@ -1765,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)

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

@@ -0,0 +1,71 @@
+/** Injectable host facts — the darwin branch is testable from Linux. */
+export interface SystemGiOptions {
+    /** `process.platform` value; defaults to the running process. */
+    platform?: string;
+    /** Environment to read `GI_TYPELIB_PATH` / `PKG_CONFIG_PATH` from; defaults to `process.env`. */
+    env?: Record<string, string | undefined>;
+    /** Directory-existence predicate; defaults to a `statSync` probe. */
+    existsDir?: (dir: string) => boolean;
+    /** `pkg-config`'s `.pc` search directories; defaults to {@link pkgConfigSearchDirs}. */
+    searchDirs?: (env: Record<string, string | undefined>) => string[];
+}
+/**
+ * Split an OS search-path variable, dropping empty segments.
+ */
+export declare function splitSearchPath(value: string | undefined, separator?: string): string[];
+/**
+ * `pkg-config`'s OWN configured `.pc` search path plus `$PKG_CONFIG_PATH`. Every
+ * entry is a `<libdir>/pkgconfig` (or `<datadir>/pkgconfig`) directory, so its
+ * parent is a candidate libdir — which is how a prefix nobody hardcoded is
+ * found. Measured on the reported host: `pc_path` =
+ * `/usr/local/lib/pkgconfig:/usr/local/share/pkgconfig:/usr/lib/pkgconfig:…`,
+ * whose first parent is exactly the `/usr/local/lib` that resolves every leaf.
+ *
+ * `spawnSync` reports a missing executable as `result.error`, not by throwing —
+ * an absent `pkg-config` is expected on a runtime-only GTK install, so it is a
+ * checked return value here and not an exception path. (`@gjsify/child_process`
+ * matches Node here deliberately; see its `spawnSync` note.)
+ */
+export declare function pkgConfigSearchDirs(env: Record<string, string | undefined>): string[];
+/**
+ * Directories holding the host's system GObject-Introspection shared libraries —
+ * most specific first, deduplicated, each verified on disk.
+ *
+ * Three sources, in precedence order:
+ *   1. `GI_TYPELIB_PATH` — the host stating outright where typelibs live; the
+ *      libraries are the sibling `dirname()`. Accepted on directory existence
+ *      alone: an explicit statement is not second-guessed.
+ *   2. `pkg-config`'s `.pc` search path → each `<dir>/pkgconfig`'s parent. The
+ *      general mechanism (any prefix, including a custom one).
+ *   3. {@link PROBED_GI_LIBDIRS} — the standard macOS prefixes, for the common
+ *      case where GTK is installed and pkg-config is not.
+ * Sources 2 and 3 are GUESSES at a prefix, so each must show the
+ * `girepository-1.0/` marker before it is believed.
+ *
+ * Empty off darwin, and that is a statement about LOADERS, not about GI. Linux
+ * resolves these leaves through `ld.so`'s system-wide configured cache
+ * (`/etc/ld.so.conf.d`), which a package install populates — nothing per-process
+ * is needed. dyld is the one loader that neither consults a system-wide config
+ * NOR re-reads its search path after launch, which is why darwin needs the
+ * variable set at launch and nobody else does.
+ *
+ * win32 is deliberately absent rather than proven unnecessary: `PATH` is the DLL
+ * search path, a Windows GTK distribution puts its `bin` there itself, and
+ * Windows re-reads that path at every `LoadLibrary` — so if a system GTK ever
+ * turns out not to be on it, the repair is a `PATH` prepend (which
+ * {@link buildNativeEnv} already does for the prebuilds), never a second
+ * variable. Untested there.
+ *
+ * @returns absolute directories, or `[]` when this platform's loader needs none
+ */
+export declare function systemGiLibraryDirs({ platform, env, existsDir, searchDirs, }?: SystemGiOptions): string[];
+/**
+ * Whether `current` (a split `DYLD_FALLBACK_LIBRARY_PATH`) already covers every
+ * directory in `wanted` — the "nothing to do" test.
+ *
+ * Kept in the port even though this CLI's consumer does not branch on it: the
+ * mirror's value is that the two files are the SAME file, and a surface that
+ * drifts by one export is a mirror nobody can check. `system-gi.spec.ts` pins
+ * both.
+ */
+export declare function pathCovers(wanted: readonly string[], current: readonly string[]): boolean;