@gjsify/cli 0.22.0 → 0.24.1

package/lib/actions/build.d.ts

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

package/lib/actions/build.js

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

package/lib/bundler-pick.js

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

package/lib/commands/affected.js

@@ -45,11 +45,55 @@
 //   --format=globs                        one `@gjsify/<name>` per line
 //   --format=github-actions                $GITHUB_OUTPUT key=value lines
 //
+// `include-args` CONTRACT (github-actions format) — read this before changing
+// its shape. The value is a SPACE-SEPARATED list of ALREADY-SHELL-SAFE tokens:
+//
+//     include-args=--include @gjsify/fs --include @gjsify/stream
+//
+// and its only supported consumption is an UNQUOTED `$INCLUDE_ARGS` expansion
+// in a POSIX shell, where word splitting is exactly the intent. It carries NO
+// quoting of its own, deliberately:
+//
+//   * `main.yml` splices it into a `su testuser -c "… sh -c '…'"` nesting, and
+//     the result of a parameter expansion is NEVER re-scanned for quotes. When
+//     this emitted `--include '@gjsify/fs'`, the apostrophes became part of the
+//     glob, every pattern matched zero workspaces, and `foreach` exited 0 —
+//     CI "built" nothing on every selective PR run in 0.65 s (repo task #75).
+//     Pre-quoting a value for an unknown number of nesting levels cannot work;
+//     emitting tokens that need no quoting at any level can.
+//   * There are FIVE consumers of this one output — the build / browser-bundle
+//     / check / test steps splice it into a command line, and thirteen
+//     `contains(needs.changes.outputs.include-args, '@gjsify/…')` GitHub
+//     expressions substring-match it. A format that requires per-consumer
+//     unquoting would have to be repeated five times in the very nesting that
+//     produced the bug; `contains()` is unaffected either way (it matched the
+//     quoted spelling too, which is why the gates kept working while the build
+//     silently did nothing).
+//
+// Shell-safety is ENFORCED, not assumed: `assertShellSafeWorkspaceName` rejects
+// any workspace name outside `[A-Za-z0-9@._/-]` before it is emitted. npm names
+// cannot contain those characters, so this never fires in practice — and if it
+// somehow does, the command exits non-zero, the classify step's
+// `continue-on-error` leaves the outputs unset, and CI falls back to a FULL
+// run. Failing towards "run everything" is the safe direction.
+//
 // `--changed-from-stdin` skips `git diff` entirely and reads a newline-
 // separated list of paths from stdin. Useful for local debugging and
-// for the spec suite.
+// for the spec suite. Stdin is slurped via `utils/stdin.ts`, NOT
+// `readFileSync(0)` — `@gjsify/fs` has no numeric-fd path, so the Node
+// idiom opens the relative file `./0` and the committed GJS classifier
+// bundle died with `ENOENT … read '0'` on every `--changed-from-stdin` run.
 import { spawnSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
+// STATIC import, never a lazy `require('node:fs')`. This package is ESM
+// (`"type": "module"`), so a bare `require` is a ReferenceError the moment the
+// line executes — and the only line that executes it sits behind
+// `if (process.env.GITHUB_OUTPUT)`, i.e. exclusively inside a GitHub Actions
+// step. That is why it survived from the command's first commit: every local
+// run and every spec took the stdout branch. There is no reason for laziness
+// here — the command already statically imports `node:child_process`, and the
+// classifier bundle resolves `node:fs` through `@gjsify/fs` like any other.
+import { appendFileSync } from 'node:fs';
+import { readStdinLines } from '../utils/stdin.js';
 import { discoverWorkspaces, buildDependencyGraph, buildReverseDependencyGraph, affectedClosure, workspacesForChangedFiles, } from '@gjsify/workspace';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
 export const affectedCommand = {
@@ -85,7 +129,7 @@ export const affectedCommand = {
         const changedFiles = args['changed-from-stdin']
             ? readStdinLines()
             : runGitDiff(rootDir, args.base ?? 'origin/main', args.head ?? 'HEAD');
-        const result = classifyAndExpand(workspaces, rootDir, changedFiles);
+        const result = classifyAndExpand(workspaces, changedFiles);
         emit(args.format, result);
     },
 };
@@ -103,6 +147,11 @@ const GLOBAL_TRIGGERS = [
     // can break assertions anywhere. Treat it as a global trigger so a
     // `@gjsify/unit` change re-runs the full suite.
     /^packages\/gjs\/unit\//,
+    // The composite action every CI job runs to set itself up. A change here
+    // alters the environment of the whole matrix, so it must force a full run
+    // EXPLICITLY — it already did, but only by falling through to the
+    // conservative "unmatched files" path, which is luck rather than intent.
+    /^\.github\/actions\//,
     // Cross-cutting dep + lockfile + root config.
     /^gjsify-lock\.json$/,
     /^package\.json$/,
@@ -119,7 +168,7 @@ const IGNORE = [
     /^refs\//,
     /^website\//,
     /^docs\//,
-    /^\.github\/workflows\/(deploy-docs|commitlint|release|audit-runtimes|prebuilds|node-gi)\.yml$/,
+    /^\.github\/workflows\/(deploy-docs|commitlint|release|audit-runtimes|prebuilds|node-gi|napi|cli-cross-platform|build-ci-image)\.yml$/,
     /^\.githooks\//,
     // @gjsify/node-gi (the Node-native GObject-Introspection engine, Axis 5) is
     // NOT a gjsify workspace member — the GJS-first install/foreach tooling can't
@@ -128,6 +177,14 @@ const IGNORE = [
     // tested on Node). Without this carve-out its files map to no workspace and
     // land in `unmatched`, forcing a conservative full run on every node-gi PR.
     /^packages\/node-gi\//,
+    // @gjsify/napi (the N-API host over GJS's SpiderMonkey, the forward mirror of
+    // node-gi) is likewise NOT a gjsify workspace member — the GJS-first
+    // install/foreach tooling can't build its Vala+C++/meson shim or its node-gyp
+    // test addons, so the main workflow neither builds nor tests it. Its own
+    // `.github/workflows/napi.yml` is the source of truth. Without this carve-out
+    // its files map to no workspace and force a conservative full run on every
+    // napi PR.
+    /^packages\/napi\//,
     // Flatpak build/distribution tooling (SDK-extension manifest + metainfo).
     // Like `.githooks/`, it has no package-test consumers; its own
     // `tests/e2e/flatpak-sdk-extension` runs on `tests/e2e/**` / global triggers.
@@ -143,7 +200,7 @@ const IGNORE = [
 ];
 /** Patterns that suggest a test-only change. */
 const TEST_PATHS = [/\.spec\.[mc]?[tj]sx?$/, /^tests\/(e2e|integration)\//];
-function classifyAndExpand(workspaces, rootDir, changedFiles) {
+function classifyAndExpand(workspaces, changedFiles) {
     const files = changedFiles.map((f) => f.replace(/\\/g, '/')).filter((f) => f.length > 0);
     if (files.length === 0) {
         return {
@@ -192,7 +249,7 @@ function classifyAndExpand(workspaces, rootDir, changedFiles) {
         }
     }
     // Map files → workspaces. Files outside any workspace stay in `unmatched`.
-    const { matched, unmatched } = workspacesForChangedFiles(workspaces, rootDir, remaining);
+    const { matched, unmatched } = workspacesForChangedFiles(workspaces, remaining);
     // Unmatched-but-not-ignored files are suspicious enough to fall back to
     // the conservative "full run" path. Examples: a new top-level dotfile,
     // a script in `scripts/` we haven't carved out, a refs/-adjacent file.
@@ -290,10 +347,6 @@ function runGitDiff(cwd, base, head) {
     }
     return r.stdout.split('\n').filter(Boolean);
 }
-function readStdinLines() {
-    const data = readFileSync(0, 'utf8');
-    return data.split('\n').map((s) => s.trim()).filter(Boolean);
-}
 // ─── Output ────────────────────────────────────────────────────────────────
 function emit(format, r) {
     if (format === 'json') {
@@ -306,9 +359,11 @@ function emit(format, r) {
         return;
     }
     if (format === 'github-actions') {
+        // Unquoted, space-separated tokens — see the `include-args` CONTRACT
+        // block at the top of this file. Do NOT re-add quoting here.
         const includeArgs = r.global
             ? ''
-            : r.workspaces.map((n) => `--include '${escSingleQuote(n)}'`).join(' ');
+            : r.workspaces.map((n) => `--include ${assertShellSafeWorkspaceName(n)}`).join(' ');
         const out = process.env.GITHUB_OUTPUT;
         const lines = [
             `skip-all=${r.skipAll}`,
@@ -320,7 +375,6 @@ function emit(format, r) {
         ];
         if (out) {
             // GitHub Actions: append to $GITHUB_OUTPUT.
-            const { appendFileSync } = require('node:fs');
             for (const l of lines)
                 appendFileSync(out, `${l}\n`);
         }
@@ -341,6 +395,22 @@ function emit(format, r) {
     for (const name of r.workspaces)
         process.stdout.write(`    - ${name}\n`);
 }
-function escSingleQuote(s) {
-    return s.replace(/'/g, `'\\''`);
+// A workspace name that survives an UNQUOTED shell expansion unchanged: no
+// whitespace, no quote/escape characters, no glob metacharacters, no `$`, and
+// nothing the shell would treat as an operator. npm package names are a strict
+// subset of this, so the guard is a machine-checked restatement of the
+// `include-args` contract rather than a real runtime branch. Returns the name
+// so it can be used inline at the emit site.
+const SHELL_SAFE_WORKSPACE_NAME = /^[A-Za-z0-9@][A-Za-z0-9@._/-]*$/;
+function assertShellSafeWorkspaceName(name) {
+    if (SHELL_SAFE_WORKSPACE_NAME.test(name))
+        return name;
+    process.stderr.write(`gjsify affected: workspace name ${JSON.stringify(name)} is not shell-safe, so it cannot be emitted as an\n` +
+        `  \`include-args\` token (the value is consumed by an UNQUOTED $INCLUDE_ARGS expansion — see the\n` +
+        `  contract at the top of commands/affected.ts). Rename the workspace, or teach this command a\n` +
+        `  transport the consumers can unquote. Refusing to emit a filter that would silently mis-match.\n`);
+    process.exit(2);
+    // Unreachable — `process.exit` terminates. Present so this function has no
+    // fall-through path that could ever return an unsafe name.
+    throw new Error(`gjsify affected: unsafe workspace name ${name}`);
 }

package/lib/commands/check.js

@@ -14,8 +14,9 @@
 // — if both `system-check`-style flags (`--json`) and `check`-style scripts
 // are reachable here, the `--json` flag routes through this command first
 // (since the typescript-check binding is positional `[paths..]`).
-import { spawn, spawnSync } from 'node:child_process';
+import { spawnSync } from 'node:child_process';
 import { prefixLines } from '../utils/prefixed-output.js';
+import { spawnToCompletion } from '../utils/spawn.js';
 import { readPackageJson } from '../utils/pkg-json.js';
 import { join } from 'node:path';
 import { cpus } from 'node:os';
@@ -26,36 +27,44 @@ import { findWorkspaceRoot } from '../utils/workspace-root.js';
  * indicates failure. Output is forwarded to the parent's stdout/stderr,
  * line-prefixed with the workspace name when `prefix` is set.
  */
-function runCheck(ws, prefix) {
-    return new Promise((resolve) => {
-        const child = spawn('npm', ['run', 'check', '--if-present'], {
+async function runCheck(ws, prefix) {
+    // `completion: 'exit'` — every path out of this command's handler ends in
+    // `process.exit(…)`, which quits the GLib main loop `spawn()` arms under
+    // GJS, so the STREAMING async path is safe here (and required: the
+    // blocking one would serialize the parallel workers). See utils/spawn.ts.
+    const flushers = [];
+    try {
+        const { code } = await spawnToCompletion('npm', ['run', 'check', '--if-present'], {
+            completion: 'exit',
             cwd: ws.location,
-            stdio: prefix === null ? 'inherit' : ['ignore', 'pipe', 'pipe'],
-        });
-        // Shared with `foreach`: live line-prefixing on a tty, buffered
-        // flush-on-close on a non-tty sink. The previous inline forwarder
-        // wrote every line live — under GJS `process.stdout.write` is a
-        // blocking `Gio.write_all`, so a parallel check into a
-        // backpressuring CI pipe could stall the GLib loop the same way
-        // the foreach examples build did. See utils/prefixed-output.ts.
-        const buffered = !process.stdout.isTTY;
-        const flushers = [];
-        if (prefix !== null && child.stdout && child.stderr) {
-            const tag = `[${prefix}] `;
-            flushers.push(prefixLines(child.stdout, process.stdout, tag, buffered));
-            flushers.push(prefixLines(child.stderr, process.stderr, tag, buffered));
-        }
-        child.on('close', (code) => {
-            for (const flush of flushers)
-                flush();
-            resolve(code ?? 1);
-        });
-        child.on('error', () => {
-            for (const flush of flushers)
-                flush();
-            resolve(1);
+            stdio: prefix === null ? 'inherit' : 'pipe',
+            onSpawn: (child) => {
+                // Shared with `foreach`: live line-prefixing on a tty, buffered
+                // flush-on-close on a non-tty sink. The previous inline
+                // forwarder wrote every line live — under GJS
+                // `process.stdout.write` is a blocking `Gio.write_all`, so a
+                // parallel check into a backpressuring CI pipe could stall the
+                // GLib loop the same way the foreach examples build did. See
+                // utils/prefixed-output.ts.
+                const buffered = !process.stdout.isTTY;
+                if (prefix !== null && child.stdout && child.stderr) {
+                    const tag = `[${prefix}] `;
+                    flushers.push(prefixLines(child.stdout, process.stdout, tag, buffered));
+                    flushers.push(prefixLines(child.stderr, process.stderr, tag, buffered));
+                }
+            },
         });
-    });
+        for (const flush of flushers)
+            flush();
+        return code ?? 1;
+    }
+    catch {
+        // Spawn failure (npm not on PATH, …) reports as a failed check —
+        // `gjsify check` aggregates codes rather than throwing per workspace.
+        for (const flush of flushers)
+            flush();
+        return 1;
+    }
 }
 export const checkCommand = {
     command: 'check',

package/lib/commands/flatpak/build.js

@@ -3,9 +3,9 @@
 // Replaces the project-local `build-flatpak.sh`-style scripts: same flag
 // shape (manifest, build-dir, install, repo, bundle), plus a `--tarball`
 // helper for Flathub submissions.
-import { spawn } from 'node:child_process';
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
+import { spawnToCompletion } from '../../utils/spawn.js';
 export const flatpakBuildCommand = {
     command: 'build [manifest]',
     description: 'Build the Flatpak via `flatpak-builder`. Wraps a typical install + export + bundle + tarball pipeline.',
@@ -115,6 +115,12 @@ export const flatpakBuildCommand = {
             await runTar(['-czf', tarballPath, '-C', buildDir, '.'], { verbose: args.verbose });
         }
         console.log(`[gjsify flatpak build] done (${buildDir})`);
+        // Terminal command: exit explicitly. Under GJS the async `spawn` used
+        // above arms a GLib main loop (`ensureMainLoop`) that only
+        // `process.exit()` quits — returning here would park the CLI at 0% CPU
+        // after flatpak-builder had already finished. Same reason `foreach` /
+        // `workspace` / `check` end this way; see utils/spawn.ts.
+        return process.exit(0);
     },
 };
 /** Pick the first JSON file in cwd that looks like a Flatpak manifest. */
@@ -167,25 +173,20 @@ async function runFlatpak(args, opts) {
 async function runTar(args, opts) {
     return runProc('tar', args, opts, { notFoundHint: 'tar not found.' });
 }
-function runProc(cmd, args, opts, extra) {
+async function runProc(cmd, args, opts, extra) {
     if (opts.verbose) {
         console.log(`[gjsify flatpak] ${cmd} ${args.join(' ')}`);
     }
-    return new Promise((res, rej) => {
-        const child = spawn(cmd, args, { stdio: 'inherit' });
-        child.on('error', (err) => {
-            if (err.code === 'ENOENT') {
-                rej(new Error(`gjsify flatpak: ${extra.notFoundHint}`));
-            }
-            else {
-                rej(err);
-            }
-        });
-        child.on('exit', (code) => {
-            if (code === 0)
-                res();
-            else
-                rej(new Error(`gjsify flatpak: ${cmd} exited with status ${code}`));
-        });
+    // `completion: 'exit'` — the handler ends in `process.exit(0)` (added for
+    // exactly this reason), so the GLib main loop `spawn()` arms under GJS is
+    // quit on the way out and the STREAMING path stays available. That matters
+    // here more than anywhere: `flatpak-builder` runs for minutes and its live
+    // progress is the whole point of `stdio: 'inherit'`. See utils/spawn.ts.
+    const { code } = await spawnToCompletion(cmd, args, {
+        completion: 'exit',
+        notFound: () => new Error(`gjsify flatpak: ${extra.notFoundHint}`),
     });
+    if (code !== 0) {
+        throw new Error(`gjsify flatpak: ${cmd} exited with status ${code}`);
+    }
 }