@gjsify/cli 0.41.0 → 0.42.0

package/lib/utils/dev-plan.js

@@ -0,0 +1,117 @@
+// What `gjsify dev` builds, launches and watches — resolved from the project's
+// OWN declarations rather than from a second set of flags.
+//
+// Re-declaring `--globals auto,dom,PointerEvent,…` here, beside the `build:gjs`
+// script that already says it, would be exactly the drifting second copy this
+// repo keeps paying for: the day the build script gains a flag, the dev loop
+// builds a different bundle than `gjsify run build` does, and the difference
+// surfaces as a runtime error in the app rather than as a diff. So the plan is
+// DERIVED from the script, with the CLI flags as overrides on top.
+//
+// Pure by design — no filesystem, no process — so precedence is unit-tested
+// instead of inferred from a running watch loop.
+import { dirname } from 'node:path';
+import { gjsifyCommandArgv } from './simple-command.js';
+/** The value of `--name value` / `--name=value` in `argv`, if present. */
+export function readFlag(argv, name) {
+    const long = `--${name}`;
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === long)
+            return argv[i + 1];
+        if (token.startsWith(`${long}=`))
+            return token.slice(long.length + 1);
+    }
+    return undefined;
+}
+/** `argv` with `--name value` set — replacing any existing occurrence, else appended. */
+export function withFlag(argv, name, value) {
+    const long = `--${name}`;
+    const out = [...argv];
+    for (let i = 0; i < out.length; i++) {
+        const token = out[i];
+        if (token === long) {
+            out[i + 1] = value;
+            return out;
+        }
+        if (token.startsWith(`${long}=`)) {
+            out[i] = `${long}=${value}`;
+            return out;
+        }
+    }
+    out.push(long, value);
+    return out;
+}
+/**
+ * The entry point a `gjsify build` argv names positionally. Only the token
+ * DIRECTLY after `build` counts: further positionals are indistinguishable from
+ * the value of a preceding flag without knowing every flag's arity, and a wrong
+ * guess here would silently build the wrong file.
+ */
+export function buildEntryPoint(argv) {
+    const candidate = argv[1];
+    if (candidate === undefined || candidate.startsWith('-'))
+        return undefined;
+    return candidate;
+}
+/** Message shown when neither a usable build script nor an explicit entry exists. */
+function noEntryError(scriptName, hasScript) {
+    const why = hasScript
+        ? `\`${scriptName}\` is not a plain \`gjsify build <entry> …\` command, so its entry point cannot be read`
+        : `this package declares no \`${scriptName}\` script`;
+    return new Error(`gjsify dev: nothing to build — ${why}.\n` +
+        `  Name the entry point directly:   gjsify dev src/index.ts\n` +
+        `  or point at another script:      gjsify dev --script <name>`);
+}
+/**
+ * Resolve the build argv, the bundle to launch and the directory to watch.
+ * Throws with both fixes named when the project declares neither.
+ */
+export function planDev(req) {
+    const literal = req.scripts[req.scriptName];
+    const scriptArgv = typeof literal === 'string' ? gjsifyCommandArgv(literal) : null;
+    const derived = scriptArgv && scriptArgv[0] === 'build' ? scriptArgv : null;
+    const entry = req.entry ?? (derived ? buildEntryPoint(derived) : undefined);
+    if (entry === undefined)
+        throw noEntryError(req.scriptName, typeof literal === 'string');
+    // Start from the script's own argv so every flag it declares survives, then
+    // put the overrides on top. `--app` is SET rather than inherited: `--script`
+    // and `--runtime` can name different targets, and the runtime that will
+    // launch the bundle is the one that must decide what is built.
+    let argv;
+    if (derived) {
+        argv = [...derived];
+        // Replace the entry the script names, or splice one in when it names
+        // none (the script may take its entry from `gjsify.bundler.input`).
+        if (buildEntryPoint(derived) !== undefined)
+            argv[1] = entry;
+        else
+            argv.splice(1, 0, entry);
+    }
+    else {
+        argv = ['build', entry];
+    }
+    argv = withFlag(argv, 'app', req.app);
+    if (req.globals !== undefined)
+        argv = withFlag(argv, 'globals', req.globals);
+    if (req.outfile !== undefined)
+        argv = withFlag(argv, 'outfile', req.outfile);
+    return {
+        buildArgv: argv,
+        bundle: readFlag(argv, 'outfile') ?? req.declaredBundle,
+        watchDir: req.watchDir ?? dirname(entry),
+    };
+}
+/**
+ * Message for a launch that has no bundle to launch. Separate from `planDev`
+ * because only the LAUNCHING caller needs one: a build writing an `--outdir`
+ * legitimately has no single output file, and refusing inside the planner would
+ * fail `--build-only` for a reason that does not apply to it.
+ */
+export function noBundleError(scriptName, app) {
+    const declaration = app === 'gjs' ? '`gjsify.main`' : '`gjsify.example.node`';
+    return new Error(`gjsify dev: nothing to launch — neither \`${scriptName}\` nor --outfile names an output file, ` +
+        `and this package declares no ${declaration}.\n` +
+        `  Pass one:   gjsify dev --outfile dist/index.${app}.mjs\n` +
+        `  or rebuild without launching:   gjsify dev --build-only`);
+}

package/lib/utils/gi-runtime-paths.d.ts

@@ -0,0 +1,27 @@
+import type { GiSystemProbe } from '@gjsify/rolldown-plugin-gjsify';
+/**
+ * The system libdir candidates a `--app gjs` bundle carries — every platform the
+ * table names, not the building host's.
+ *
+ * A build-time platform gate would be exactly the snapshot the note above exists to
+ * avoid: `--app gjs` emits platform-neutral JavaScript, so the bundle a Linux runner
+ * produces is the bundle a Mac runs. What travels instead is the RUNTIME gate, and it
+ * is two markers, not one, because the `girepository-1.0` marker alone answers the
+ * wrong question. It says "a GI stack is installed under this prefix" — true on a
+ * Linux box built with `meson setup --prefix=/usr/local` or jhbuild, a normal shape
+ * for this project's own audience — while the rule this mirrors is about LOADERS:
+ * `systemGiLibraryDirs()` is empty off darwin because `ld.so`'s system-wide cache
+ * already resolves these leaves. Without the host marker every such Linux host would
+ * get `/usr/local/lib` prepended ahead of the distro's typelibs AND libraries, which
+ * is the two-stacks precedence ADR 0023 § 4 / #910 paid for — measured against a
+ * stand-in host in `gi-runtime-paths-banner.spec.ts`.
+ *
+ * A platform in the table with no {@link HOST_MARKERS} entry THROWS rather than
+ * shipping an ungated candidate: an unknown-host default of "prepend" is the bug
+ * above, on every platform at once.
+ *
+ * SORTED and deduplicated: the result is emitted into a bundle two machines must be
+ * able to build byte-for-byte identically, and `Object.entries()` order is the
+ * table's, which is a source-edit away from changing.
+ */
+export declare function giSystemProbes(): GiSystemProbe[];

package/lib/utils/gi-runtime-paths.js

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: MIT
+// WHAT a `--app gjs` bundle's byte-1 GI prologue is told. The prologue itself is
+// `rolldown-plugin-gjsify`'s `giRuntimePathsStub`; this is the only production caller
+// that fills it, and until it did, every bundle carried the empty string that stub
+// returns for nothing-to-say.
+//
+// WHY A BUNDLE NEEDS IT. On macOS a typelib names its library by bare leaf
+// (`libgtk-4.1.dylib`), and SIP strips an inherited `DYLD_*` at the `/bin/sh` exec a
+// launcher goes through, so the only repair that survives is one the process makes to
+// girepository's own search paths from the inside. Measurements, and what this reaches
+// (loads AFTER module evaluation starts, not a static `gi://` import):
+// `status/open-todos.md` § "A globally installed GJS launcher still cannot load a
+// system GTK on macOS".
+//
+// A SHIPPED BUNDLE RUNS ON A MACHINE THE BUILD NEVER SAW, which rules out both
+// tempting sources. `systemGiLibraryDirs()` MEASURES the build host and answers `[]`
+// on the Linux runner that builds most releases — so what travels is the CANDIDATE
+// table it probes, with the probe moved into the bundle. `detectNativePackages()`
+// answers with the build tree's `node_modules/@gjsify/<pkg>-<target>/prebuilds/
+// <target>`: the build host's target twice over (ADR 0017), at the build tree's depth,
+// so it names nothing on an installed macOS host — and baking it would make
+// `dist/affected.gjs.mjs`, a `--app gjs` bundle `scripts/verify-committed-bundles.mjs`
+// compares byte for byte, encode which platform siblings the committing machine had.
+// `activateNativePrebuilds()` already covers those from inside the running process.
+//
+// DELIBERATELY NOT INCLUDED: a `@gjsify/gtk-runtime-<target>` bundle's `gtk/lib`. That
+// is node-gi's mechanism, for a host process that brings no GTK of its own; a `--app
+// gjs` bundle runs under a `gjs` already linked against a system GLib, so a second GTK
+// stack in that process is the two-registries failure #910 paid for (ADR 0023 § 4).
+import { PROBED_GI_LIBDIRS, TYPELIB_SUBDIR } from './system-gi.js';
+/**
+ * A path that proves the RUNNING host is the platform whose candidates it keys, for
+ * every platform `PROBED_GI_LIBDIRS` names.
+ *
+ * The bundle cannot read `process.platform` — it is platform-neutral JavaScript, built
+ * on a machine that is not the host — so the darwin scope `systemGiLibraryDirs()`
+ * enforces with `PROBED_GI_LIBDIRS[platform]` has to travel as a marker path.
+ * Same probe, same spelling as `@gjsify/child_process`'s `detectPlatform()` and
+ * `@gjsify/v8`'s `detectHeapPlatform()`: macOS has no procfs, and this plist is
+ * present on every install.
+ */
+const HOST_MARKERS = {
+    darwin: '/System/Library/CoreServices/SystemVersion.plist',
+};
+/**
+ * The system libdir candidates a `--app gjs` bundle carries — every platform the
+ * table names, not the building host's.
+ *
+ * A build-time platform gate would be exactly the snapshot the note above exists to
+ * avoid: `--app gjs` emits platform-neutral JavaScript, so the bundle a Linux runner
+ * produces is the bundle a Mac runs. What travels instead is the RUNTIME gate, and it
+ * is two markers, not one, because the `girepository-1.0` marker alone answers the
+ * wrong question. It says "a GI stack is installed under this prefix" — true on a
+ * Linux box built with `meson setup --prefix=/usr/local` or jhbuild, a normal shape
+ * for this project's own audience — while the rule this mirrors is about LOADERS:
+ * `systemGiLibraryDirs()` is empty off darwin because `ld.so`'s system-wide cache
+ * already resolves these leaves. Without the host marker every such Linux host would
+ * get `/usr/local/lib` prepended ahead of the distro's typelibs AND libraries, which
+ * is the two-stacks precedence ADR 0023 § 4 / #910 paid for — measured against a
+ * stand-in host in `gi-runtime-paths-banner.spec.ts`.
+ *
+ * A platform in the table with no {@link HOST_MARKERS} entry THROWS rather than
+ * shipping an ungated candidate: an unknown-host default of "prepend" is the bug
+ * above, on every platform at once.
+ *
+ * SORTED and deduplicated: the result is emitted into a bundle two machines must be
+ * able to build byte-for-byte identically, and `Object.entries()` order is the
+ * table's, which is a source-edit away from changing.
+ */
+export function giSystemProbes() {
+    const probes = new Map();
+    for (const [platform, dirs] of Object.entries(PROBED_GI_LIBDIRS)) {
+        const hostMarker = HOST_MARKERS[platform];
+        if (!hostMarker) {
+            throw new Error(`[gjsify] PROBED_GI_LIBDIRS names '${platform}' but HOST_MARKERS does not: ` +
+                'a bundle cannot ask process.platform, so an ungated candidate would be ' +
+                'prepended on every host that happens to have the directory.');
+        }
+        for (const dir of dirs) {
+            probes.set(`${dir}\u0000${hostMarker}`, [dir, `${dir}/${TYPELIB_SUBDIR}`, hostMarker]);
+        }
+    }
+    return [...probes.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([, probe]) => probe);
+}

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

@@ -0,0 +1,49 @@
+/** Injectable host facts — every platform branch is testable from any host. */
+export interface GiTypelibOptions {
+    /** `process.platform` value; defaults to the running process. */
+    platform?: string;
+    /** Environment to read `GI_TYPELIB_PATH` / `PATH` from; defaults to `process.env`. */
+    env?: Record<string, string | undefined>;
+    /** Directory-existence predicate; defaults to a `statSync` probe. */
+    existsDir?: (dir: string) => boolean;
+    /** File-existence predicate; defaults to `existsSync`. */
+    existsFile?: (file: string) => boolean;
+    /** Immediate subdirectory names of `dir`, or `[]`; defaults to a `readdirSync` probe. */
+    listDirs?: (dir: string) => string[];
+    /** `pkg-config`'s `.pc` search directories; defaults to {@link pkgConfigSearchDirs}. */
+    searchDirs?: (env: Record<string, string | undefined>) => string[];
+}
+/**
+ * Directories girepository looks for typelibs in, most specific first,
+ * deduplicated, each verified on disk.
+ *
+ * Sources, in precedence order:
+ *   1. `GI_TYPELIB_PATH` — the host stating outright where typelibs live.
+ *      Believed on existence alone; an explicit statement is not second-guessed.
+ *   2. `pkg-config`'s `.pc` search path → `<libdir>/girepository-1.0`. The
+ *      general mechanism: it finds a jhbuild or otherwise bespoke prefix that no
+ *      list here could name. Present only when pkg-config is, which on a
+ *      runtime-only host it is not — hence 3.
+ *   3. Platform defaults, each believed only on the marker directory existing.
+ *
+ * Source 3 is where the platforms differ, and each branch is a statement about
+ * that platform's install layout:
+ *   * **linux** — {@link LINUX_LIBDIRS} plus the discovered multiarch triplets.
+ *   * **darwin** — {@link systemGiLibraryDirs}, which already probes Homebrew,
+ *     MacPorts and pkg-config prefixes for exactly this marker. Reused rather
+ *     than re-derived: the two must not be able to disagree about where the GI
+ *     stack is.
+ *   * **win32** — a GTK distribution ships `<prefix>/bin` on `PATH` and its
+ *     typelibs in the sibling `<prefix>/lib/girepository-1.0`, so PATH is the
+ *     prefix oracle. (Untested against a real Windows GTK; it costs a `stat` per
+ *     `bin` entry and cannot make any host worse than the empty list it replaces.)
+ */
+export declare function systemGiTypelibDirs({ platform, env, existsDir, listDirs, searchDirs, }?: GiTypelibOptions): string[];
+/**
+ * The installed `<namespace>-<version>.typelib`, or `null`.
+ *
+ * `version` is GI's API version as it appears in a `gi://` specifier (`4.0` for
+ * `gi://Gtk?version=4.0`, `1` for Adwaita) — the same string the filename
+ * carries, so the caller states it exactly once.
+ */
+export declare function findSystemTypelib(namespace: string, version: string, { existsFile, ...options }?: GiTypelibOptions): string | null;

package/lib/utils/gi-typelib.js

@@ -0,0 +1,160 @@
+// SPDX-License-Identifier: MIT
+// Is a GObject-Introspection namespace INSTALLED on this host — the question
+// `gi_repository_require()` answers, asked without loading anything.
+//
+// WHY THIS EXISTS. `gjsify system-check` used to answer it with `pkg-config
+// --modversion libadwaita-1`, which is a question about the DEVELOPMENT package.
+// Measured on postmarketOS v26.06 / aarch64 (OnePlus 6T, gjs 1.88.1, no node):
+// libadwaita 1.9.2 installed, `Adw-1.typelib` present, every Adwaita app on the
+// device running — and `system-check` printing `✗ libadwaita` under **Required**
+// and exiting 1, because `libadwaita-dev` (which ships the `.pc` file and
+// nothing a running app loads) was not installed. A check that fails on a host
+// where the thing it checks demonstrably works is worse than no check: it sends
+// people to install packages they do not need, and it teaches them to ignore the
+// output — the same failure mode `checkTypeSkew`'s comment in
+// `check-system-deps.ts` describes from the other direction.
+//
+// THE ORACLE is the typelib FILE on girepository's search path:
+//   * it is what GI itself resolves, so it cannot disagree with what an app does;
+//   * it is identical under GJS and Node, so the CLI's two entry points give the
+//     same answer (`pkg-config` at least had that property; `imports.gi` would
+//     not);
+//   * it needs no `dlopen`, and a presence probe must not have the side effect of
+//     loading GTK into the process asking the question.
+//
+// It answers PRESENCE only. The version still comes from `pkg-config` where that
+// is installed — see `checkGiLibrary` in `check-system-deps.ts`, which reports a
+// version when it can and a bare `✓` when it cannot. Presence without a version
+// is the honest answer on a runtime-only host; `✗` was not.
+//
+// PURE FUNCTION of injected host facts (platform / env / fs / pkg-config), like
+// `systemGiLibraryDirs()` and `resolvePrebuildDirName()` beside it, so the
+// darwin and win32 branches are unit-tested from Linux.
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { posix, win32 } from 'node:path';
+import { pkgConfigSearchDirs, splitSearchPath, systemGiLibraryDirs, TYPELIB_SUBDIR } from './system-gi.js';
+/**
+ * Library prefixes a Linux GI stack is installed under, before multiarch.
+ * `/usr/lib64` is Fedora/openSUSE, `/usr/lib` everything else, `/usr/local/lib`
+ * a source install. Each is accepted only when it actually holds the marker
+ * directory, so naming one that does not exist costs a `stat` and nothing else.
+ */
+const LINUX_LIBDIRS = ['/usr/lib', '/usr/lib64', '/usr/local/lib'];
+/**
+ * Where a Debian/Ubuntu multiarch layout hides the typelibs
+ * (`/usr/lib/x86_64-linux-gnu/girepository-1.0`). The triplet is DISCOVERED by
+ * listing the parent rather than derived from `process.arch`: the mapping from
+ * Node's arch names to Debian triplets is a table that would need a row per
+ * port, and one `readdir` of `/usr/lib` answers it for every architecture
+ * including the ones nobody has written down.
+ */
+const MULTIARCH_PARENTS = ['/usr/lib'];
+function isDirectory(dir) {
+    try {
+        return statSync(dir).isDirectory();
+    }
+    catch {
+        // ENOENT on an uninstalled prefix, EACCES on a path this process may not
+        // read: not a usable typelib directory either way.
+        return false;
+    }
+}
+function subdirectories(dir) {
+    try {
+        return readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Directories girepository looks for typelibs in, most specific first,
+ * deduplicated, each verified on disk.
+ *
+ * Sources, in precedence order:
+ *   1. `GI_TYPELIB_PATH` — the host stating outright where typelibs live.
+ *      Believed on existence alone; an explicit statement is not second-guessed.
+ *   2. `pkg-config`'s `.pc` search path → `<libdir>/girepository-1.0`. The
+ *      general mechanism: it finds a jhbuild or otherwise bespoke prefix that no
+ *      list here could name. Present only when pkg-config is, which on a
+ *      runtime-only host it is not — hence 3.
+ *   3. Platform defaults, each believed only on the marker directory existing.
+ *
+ * Source 3 is where the platforms differ, and each branch is a statement about
+ * that platform's install layout:
+ *   * **linux** — {@link LINUX_LIBDIRS} plus the discovered multiarch triplets.
+ *   * **darwin** — {@link systemGiLibraryDirs}, which already probes Homebrew,
+ *     MacPorts and pkg-config prefixes for exactly this marker. Reused rather
+ *     than re-derived: the two must not be able to disagree about where the GI
+ *     stack is.
+ *   * **win32** — a GTK distribution ships `<prefix>/bin` on `PATH` and its
+ *     typelibs in the sibling `<prefix>/lib/girepository-1.0`, so PATH is the
+ *     prefix oracle. (Untested against a real Windows GTK; it costs a `stat` per
+ *     `bin` entry and cannot make any host worse than the empty list it replaces.)
+ */
+export function systemGiTypelibDirs({ platform = process.platform, env = process.env, existsDir = isDirectory, listDirs = subdirectories, searchDirs = pkgConfigSearchDirs, } = {}) {
+    // POSIX semantics unless the TARGET is win32 — `platform` is a parameter, so
+    // this answers a question about a foreign filesystem from any host. The same
+    // trap `system-gi.ts` documents: a host-following `join` turns
+    // `/usr/lib/girepository-1.0` into a backslash path on Windows and matches
+    // nothing the caller holds.
+    const { join, dirname, basename } = platform === 'win32' ? win32 : posix;
+    const separator = platform === 'win32' ? ';' : ':';
+    const out = [];
+    const add = (dir) => {
+        if (dir && !out.includes(dir))
+            out.push(dir);
+    };
+    // 1. Explicit.
+    for (const dir of splitSearchPath(env['GI_TYPELIB_PATH'], separator)) {
+        if (existsDir(dir))
+            add(dir);
+    }
+    // 2 + 3. Candidate libdirs, believed only on the marker.
+    const libDirs = [];
+    for (const pcDir of searchDirs(env)) {
+        if (basename(pcDir) === 'pkgconfig')
+            libDirs.push(dirname(pcDir));
+    }
+    if (platform === 'linux') {
+        libDirs.push(...LINUX_LIBDIRS);
+        for (const parent of MULTIARCH_PARENTS) {
+            for (const entry of listDirs(parent))
+                libDirs.push(join(parent, entry));
+        }
+    }
+    else if (platform === 'darwin') {
+        libDirs.push(...systemGiLibraryDirs({ platform, env, existsDir, searchDirs }));
+    }
+    else if (platform === 'win32') {
+        for (const pathEntry of splitSearchPath(env['PATH'], separator)) {
+            if (basename(pathEntry).toLowerCase() === 'bin')
+                libDirs.push(join(dirname(pathEntry), 'lib'));
+        }
+    }
+    for (const libDir of libDirs) {
+        const typelibDir = join(libDir, TYPELIB_SUBDIR);
+        if (existsDir(typelibDir))
+            add(typelibDir);
+    }
+    return out;
+}
+/**
+ * The installed `<namespace>-<version>.typelib`, or `null`.
+ *
+ * `version` is GI's API version as it appears in a `gi://` specifier (`4.0` for
+ * `gi://Gtk?version=4.0`, `1` for Adwaita) — the same string the filename
+ * carries, so the caller states it exactly once.
+ */
+export function findSystemTypelib(namespace, version, { existsFile = existsSync, ...options } = {}) {
+    const { join } = options.platform === 'win32' ? win32 : posix;
+    const leaf = `${namespace}-${version}.typelib`;
+    for (const dir of systemGiTypelibDirs(options)) {
+        const candidate = join(dir, leaf);
+        if (existsFile(candidate))
+            return candidate;
+    }
+    return null;
+}

package/lib/utils/node-script.d.ts

@@ -1,4 +1,7 @@
+import type { SpawnCompletionContract } from './spawn.js';
 export interface RunNodeScriptOptions {
+    /** The caller's teardown contract, forwarded verbatim — see `RunGjsBundleOptions.completion`. */
+    completion: SpawnCompletionContract;
     /** Exit the process when the script succeeds. See `RunGjsBundleOptions.exitOnSuccess`. */
     exitOnSuccess?: boolean;
 }
@@ -9,4 +12,4 @@ export interface RunNodeScriptOptions {
  * Terminal callers pass `exitOnSuccess` (a GJS main loop armed by the spawn
  * parks the process otherwise); see {@link runGjsBundle}.
  */
-export declare function runNodeScript(file: string, extraArgs?: string[], options?: RunNodeScriptOptions): Promise<void>;
+export declare function runNodeScript(file: string, extraArgs: string[] | undefined, options: RunNodeScriptOptions): Promise<void>;

package/lib/utils/node-script.js

@@ -59,7 +59,7 @@ function scriptCacheEnabled() {
  * Terminal callers pass `exitOnSuccess` (a GJS main loop armed by the spawn
  * parks the process otherwise); see {@link runGjsBundle}.
  */
-export async function runNodeScript(file, extraArgs = [], options = {}) {
+export async function runNodeScript(file, extraArgs = [], options) {
     const scriptPath = resolve(file);
     if (!existsSync(scriptPath) || !statSync(scriptPath).isFile()) {
         console.error(`gjsify run --node-script: no such file: ${scriptPath}`);
@@ -72,7 +72,11 @@ export async function runNodeScript(file, extraArgs = [], options = {}) {
         // differ from what the runtime would have done itself. `quiet` because the echo
         // would print `node <file>` — what the package.json script already reads — behind
         // ~2 kB of native-library env, a dozen times per build chain.
-        await runRuntimeBundle(host, scriptPath, extraArgs, { exitOnSuccess: options.exitOnSuccess, quiet: true });
+        await runRuntimeBundle(host, scriptPath, extraArgs, {
+            completion: options.completion,
+            exitOnSuccess: options.exitOnSuccess,
+            quiet: true,
+        });
         return;
     }
     // Dynamic import keeps the bundler machinery out of the eager module graph
@@ -90,6 +94,22 @@ export async function runNodeScript(file, extraArgs = [], options = {}) {
             define: { 'import.meta.url': JSON.stringify(pathToFileURL(scriptPath).href) },
             globals,
             excludeGlobals,
+            // OPT-IN, and the widest of the three call sites — say what it does and
+            // does not mean. This function is reached through the `node` shim `gjsify
+            // run` puts on the PATH, so it also bundles a consumer's
+            // `"start": "node ./src/main.mjs"`, not only a repo build script. The
+            // discriminator is therefore "the CLI is bundling this on the project's
+            // behalf", NOT "this is toolchain".
+            //
+            // Narrowing it to the CLI's own tree was considered and does not work: in
+            // the ADR 0002 bootstrap the CLI is a GLOBAL install (`install.mjs` →
+            // `gjsify install -g`) and the script is in the user's clone, so no
+            // containment test relates them. What contains the hazard instead is
+            // PROJECT FIRST (a resolvable dependency is never shadowed) plus the
+            // `this.warn` the guard emits on every rescue, which names the package and
+            // the anchor — so a mixed artifact is visible in the build log rather than
+            // byte-identical to a healthy one.
+            resolveFromToolchain: true,
         });
     }
     catch (err) {
@@ -99,5 +119,9 @@ export async function runNodeScript(file, extraArgs = [], options = {}) {
     }
     // Quiet for the same reason as the node path above; the bundle's location is
     // deterministic (`node_modules/.cache/gjsify/node-scripts/<name>-<hash>/<name>.mjs`).
-    await runGjsBundle(bundlePath, extraArgs, { exitOnSuccess: options.exitOnSuccess, quiet: true });
+    await runGjsBundle(bundlePath, extraArgs, {
+        completion: options.completion,
+        exitOnSuccess: options.exitOnSuccess,
+        quiet: true,
+    });
 }

package/lib/utils/npm-oidc.js

@@ -80,11 +80,14 @@ export async function fetchGithubOidcToken(audience, log) {
         throw new OidcUnavailableError('GitHub Actions OIDC env vars (ACTIONS_ID_TOKEN_REQUEST_{URL,TOKEN}) not set. ' +
             'The calling workflow needs `permissions: id-token: write`.', 'no-env');
     }
-    // Append the audience by STRING CONCATENATION, as @actions/core's getIDToken does. Do NOT
-    // use `URL.searchParams.set` + `.href`: under GJS that serialization dropped the `audience`
-    // param, so GitHub issued an id-token with the DEFAULT audience (the repo API URL) and npm
-    // rejected an otherwise-valid token with 401 — repository/workflow_ref/sub all matched the
-    // Trusted Publisher, only `aud` was wrong.
+    // Append the audience by STRING CONCATENATION, as @actions/core's getIDToken does.
+    //
+    // fixed upstream in gjsify: `URL.searchParams.set` + `.href` used to DROP the parameter under
+    // GJS — the mutation never reached the serialisation — so GitHub issued an id-token with the
+    // DEFAULT audience (the repo API URL) and npm rejected an otherwise-valid token with 401:
+    // repository/workflow_ref/sub all matched the Trusted Publisher, only `aud` was wrong. The
+    // URL live view now works, so the ban is lifted; the concatenation stays because it is what
+    // the reference implementation does, not because the alternative is broken.
     const sep = url.includes('?') ? '&' : '?';
     const requestUrl = `${url}${sep}audience=${encodeURIComponent(audience)}`;
     log?.(`gjsify oidc: GET ${requestUrl.replace(bearer, '<bearer>')}`);

package/lib/utils/run-gjs.d.ts

@@ -1,4 +1,5 @@
 import { type NativeEnv } from './detect-native-packages.js';
+import { type SpawnCompletionContract } from './spawn.js';
 /**
  * Pure env computation: the typelib + shared-library search paths {@link runGjsBundle} would
  * inject into the spawned `gjs`, plus the formatted prefix for the `$ …` echo. Which library
@@ -15,6 +16,16 @@ export declare function computeNativeEnvForBundle(bundlePath: string, cwd?: stri
  * bundle's own node_modules tree.
  */
 export interface RunGjsBundleOptions {
+    /**
+     * The teardown contract of the command that will end this process — the same field,
+     * and the same reason, `spawnToCompletion` demands. Required rather than defaulted:
+     * absent, a caller silently inherited the side that ARMS the GJS main loop.
+     *
+     * Distinct from {@link exitOnSuccess}, which asks WHO performs the exit. `gjsify test`
+     * is `'exit'` — its handler exits at the end of `commands/test.ts` — while leaving
+     * `exitOnSuccess` off, because an exit HERE would truncate its multi-runtime loop.
+     */
+    completion: SpawnCompletionContract;
     /**
      * Exit this process with code 0 once the child succeeds. Under GJS, `ensureMainLoop()`
      * (armed by spawn) keeps the parent's GLib loop alive after the child exits, so a TERMINAL
@@ -31,4 +42,4 @@ export interface RunGjsBundleOptions {
      */
     quiet?: boolean;
 }
-export declare function runGjsBundle(bundlePath: string, extraArgs?: string[], options?: RunGjsBundleOptions): Promise<void>;
+export declare function runGjsBundle(bundlePath: string, extraArgs: string[] | undefined, options: RunGjsBundleOptions): Promise<void>;

package/lib/utils/run-gjs.js

@@ -9,9 +9,9 @@
 //
 // Env composition is split out as the pure `computeNativeEnvForBundle()` so the e2e tests can
 // assert the env without spawning gjs.
-import { spawn } from 'node:child_process';
 import { dirname, resolve } from 'node:path';
 import { detectNativePackages, buildNativeEnv } from './detect-native-packages.js';
+import { describeExit, spawnToCompletion } from './spawn.js';
 /**
  * Pure env computation: the typelib + shared-library search paths {@link runGjsBundle} would
  * inject into the spawned `gjs`, plus the formatted prefix for the `$ …` echo. Which library
@@ -40,7 +40,7 @@ export function computeNativeEnvForBundle(bundlePath, cwd = process.cwd(), inher
         .join(' ');
     return { env, envPrefix };
 }
-export async function runGjsBundle(bundlePath, extraArgs = [], options = {}) {
+export async function runGjsBundle(bundlePath, extraArgs = [], options) {
     const { env: nativeEnv, envPrefix } = computeNativeEnvForBundle(bundlePath);
     const env = {
         ...process.env,
@@ -52,36 +52,29 @@ export async function runGjsBundle(bundlePath, extraArgs = [], options = {}) {
     const gjsCommand = ['gjs', ...gjsArgs.map((a) => (a.includes(' ') ? `"${a}"` : a))].join(' ');
     if (!options.quiet)
         console.error(`$ ${envPrefix ? `${envPrefix} ` : ''}${gjsCommand}`);
-    const child = spawn('gjs', gjsArgs, { env, stdio: 'inherit' });
-    let failed = false;
-    // The CHILD's own exit code, re-raised verbatim; a spawn error (no `gjs` on PATH) has none
-    // of its own and falls back to 1. Collapsing every failure to 1 lost information callers
-    // act on — a chain reading `$?` to tell "tool failed" from "tool says no" saw 1 for both.
-    let childCode = 1;
-    await new Promise((resolvePromise, reject) => {
-        child.on('close', (code) => {
-            if (code !== 0) {
-                childCode = code ?? 1;
-                reject(new Error(`gjs exited with code ${code}`));
-            }
-            else {
-                resolvePromise();
-            }
-        });
-        child.on('error', reject);
-    }).catch((err) => {
+    // The CHILD's own exit code is re-raised verbatim; a spawn error (no `gjs` on PATH) has
+    // none of its own and falls back to 1. Collapsing every failure to 1 lost information
+    // callers act on — a chain reading `$?` to tell "tool failed" from "tool says no" saw 1
+    // for both.
+    const failed = (code) => {
+        // `process.exitCode` is set BEFORE exiting because `gjsify run <script>` dispatches a
+        // nested `gjsify run <bundle>` IN PROCESS: the outer command reads `process.exitCode`
+        // to propagate. Without it a failing `test:gjs` returned 0 through the `test` chain,
+        // and through `gjsify foreach test` in CI. The `return` guards a fall-through exit.
+        process.exitCode = code;
+        return process.exit(code);
+    };
+    let result;
+    try {
+        result = await spawnToCompletion('gjs', gjsArgs, { completion: options.completion, env });
+    }
+    catch (err) {
         console.error(err.message);
-        failed = true;
-    });
-    if (failed) {
-        // Set `process.exitCode` synchronously BEFORE exiting: under GJS `process.exit()` is
-        // deferred (the GLib main loop is armed), so under run.ts's in-process script dispatch
-        // execution returns to the caller, which propagates by reading `process.exitCode`.
-        // Without it, `gjsify run <script>` wrapping `gjsify run <bundle>` swallowed a non-zero
-        // gjs exit and returned 0 — masking a failing `test:gjs` in the `test` chain, and via
-        // `gjsify foreach test` in CI. The `return` guards a fall-through second `exit`.
-        process.exitCode = childCode;
-        return process.exit(childCode);
+        return failed(1);
+    }
+    if (result.code !== 0) {
+        console.error(`gjs exited with ${describeExit(result)}`);
+        return failed(result.code ?? 1);
     }
     // See RunGjsBundleOptions.exitOnSuccess — terminal callers opt in,
     // mid-flow callers (test.ts's runtime loop) keep the process alive.