@gjsify/cli 0.4.44 → 0.5.0

package/lib/actions/build.js

@@ -259,7 +259,15 @@ export class BuildAction {
                 external: userBundler.external,
                 transform: userBundler.transform,
                 format,
-            }, pluginOpts, gjsifyPluginFactory, verbose, { extraGlobalsList: extras, excludeGlobals }, bundleToChunks);
+            }, pluginOpts, gjsifyPluginFactory, verbose, 
+            // Pass the project working dir so the resolvability gate in
+            // detectAutoGlobals can check whether each detected global's
+            // polyfill package is installed before writing a register
+            // import. Without `cwd` the gate is bypassed and an
+            // unresolvable import would hard-crash the analysis pass.
+            // Mirrors the explicit-globals path (resolveGlobalsInject)
+            // and resolveUserPlugins above, which already anchor on cwd.
+            { extraGlobalsList: extras, excludeGlobals, cwd: process.cwd() }, bundleToChunks);
             pluginOpts.autoGlobalsInject = injectPath;
         }
         else if (extras) {

package/lib/bundler-pick.d.ts

@@ -78,6 +78,62 @@ export declare function runWatch(finalOpts: BundlerOptions): Promise<RolldownWat
  */
 export declare function runBundle(finalOpts: BundlerOptions): Promise<RolldownOutput>;
 export declare function shouldUseNative(): Promise<boolean>;
+/**
+ * Sanitize fields the JSON encoder can't ship to the Rust deserializer.
+ *
+ * Functions vanish under `JSON.stringify` (the key disappears from the
+ * JSON), silently changing build behavior vs npm rolldown — so dropping
+ * one now WARNS (once per key). `external` gets a dedicated message: the
+ * orchestrators express externals as exact-name arrays + an
+ * `externalsPlugin` resolveId hook precisely because a function predicate
+ * cannot cross this boundary; a function here means a regression (or a
+ * user config) reintroduced the dropped-predicate class.
+ *
+ * `external` array elements must be plain strings — the Rust
+ * `deserialize_external` only accepts `Vec<String>` and a RegExp
+ * serializes to `{}`, producing an opaque serde column error. Reject
+ * RegExp/non-string elements with a NAMED error instead.
+ *
+ * `sourcemap` is TRANSLATED, not dropped: the JS API accepts
+ * `boolean | 'inline' | 'hidden'` while the Rust `SourceMapType` enum
+ * (plain serde derive, no rename_all) only accepts `'File' | 'Inline' |
+ * 'Hidden'`. `true` → `'File'`, `'inline'` → `'Inline'`, `'hidden'` →
+ * `'Hidden'`; `false` is omitted (same effect).
+ *
+ * Exported for the unit tests in `bundler-pick.spec.ts`.
+ */
+export declare function stripUnserializable<T extends Record<string, unknown>>(opts: T): T;
+/**
+ * Map the JS-API `sourcemap` spellings onto the Rust `SourceMapType` enum
+ * variants. Returns `undefined` for `false`/unknown shapes (omit the key).
+ * Exported for the unit tests in `bundler-pick.spec.ts`.
+ */
+export declare function translateSourcemapOption(v: unknown): 'File' | 'Inline' | 'Hidden' | undefined;
+/**
+ * Convert npm rolldown's `transform.inject` map shorthand into the array
+ * of descriptors the native Rust deserializer expects. The Rust
+ * `InjectImport` enum (`tag = "type"`, `rename_all = "camelCase"`) has
+ * exactly TWO variants:
+ *
+ *   - `{ type: 'named', imported, alias?, from }`
+ *   - `{ type: 'namespace', alias, from }`
+ *
+ * npm rolldown's map spellings translate as:
+ *
+ *   - `{ alias: 'module' }`        → default import →
+ *     `{ type: 'named', imported: 'default', alias, from: 'module' }`
+ *     (the Rust `InjectImport::default()` constructor encodes default
+ *     imports as a named import of `default` — there is NO `'default'`
+ *     variant; emitting `{ type: 'default' }` crashes the deserializer
+ *     with `unknown variant \`default\``).
+ *   - `{ alias: ['module', '*'] }` → namespace import →
+ *     `{ type: 'namespace', alias, from: 'module' }`.
+ *   - `{ alias: ['module', 'name'] }` → named import →
+ *     `{ type: 'named', from: 'module', imported: 'name', alias }`.
+ *
+ * Exported for the unit tests in `bundler-pick.spec.ts`.
+ */
+export declare function mapToInjectArray(map: Record<string, string | [string, string]>): Array<Record<string, string>>;
 export type PluginRecord = {
     name?: string;
     [k: string]: unknown;

package/lib/bundler-pick.js

@@ -39,6 +39,20 @@ import { resolveNpmPackage } from './utils/resolve-npm-package.js';
 // Dynamic import keeps it off the GJS code path entirely; the native
 // branch (`@gjsify/rolldown-native`) handles bundling there.
 async function loadNpmRolldown() {
+    // Under GJS the npm crate can NEVER run (its JS wrapper requires a
+    // napi binary). Reaching this loader under GJS means the native
+    // engine probe failed — historically that surfaced as an opaque
+    // `ImportError: Unsupported URI scheme for importing: node` from deep
+    // inside the crate's wrapper (e.g. on a truly-cold workspace where
+    // `@gjsify/rolldown-native`'s lib/ is not built yet, issue #497).
+    // Fail with the actionable diagnosis instead.
+    const isGjs = typeof globalThis.imports?.gi !== 'undefined';
+    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.');
+    }
     // Indirect specifier so Rolldown's static-analysis doesn't try to
     // bundle the npm crate into a GJS target build.
     const specifier = 'rolldown';
@@ -102,6 +116,7 @@ export async function bundleToChunks(input) {
         }));
         delete opts.plugins;
         const result = await native.bundleWithPlugins(opts, nativePlugins);
+        reportNativeWarnings(result, input.rolldownInput);
         const codes = [];
         for (const item of result.output) {
             if (item.type === 'chunk')
@@ -261,6 +276,7 @@ async function runNativeBundle(finalOpts) {
         console.error('[gjsify-bundler-pick] native opts JSON:', JSON.stringify(bundlerOpts));
     }
     const result = await native.bundleWithPlugins(bundlerOpts, nativePlugins);
+    reportNativeWarnings(result, finalOpts);
     // The native facade returns the BundleOutput shape but doesn't
     // write files — replicate `.write()` here so callers see the same
     // on-disk layout whether they used npm rolldown or native.
@@ -282,6 +298,14 @@ async function runNativeBundle(finalOpts) {
         await fs.mkdir(path.dirname(target), { recursive: true });
         if (item.type === 'chunk') {
             await fs.writeFile(target, item.code, 'utf8');
+            // `.write()` parity: npm rolldown emits `<fileName>.map` next to
+            // each chunk when `sourcemap: 'File'|'Hidden'` is set. The native
+            // facade carries the map JSON on the chunk (`map` is undefined for
+            // inline/disabled sourcemaps) — write it or sourcemaps would be
+            // silently unavailable under the GJS-default engine.
+            if (typeof item.map === 'string') {
+                await fs.writeFile(`${target}.map`, item.map, 'utf8');
+            }
         }
         else if (item.sourceText !== undefined) {
             await fs.writeFile(target, item.sourceText, 'utf8');
@@ -291,28 +315,111 @@ async function runNativeBundle(finalOpts) {
     return synthRolldownOutput(result);
 }
 /**
- * Drop fields the JSON encoder can't ship to the Rust deserializer.
- * `external` may be a function predicate (npm rolldown supports this);
- * functions vanish under `JSON.stringify` and surface as parse errors on
- * the Rust side. Strip top-level function values so the option object
- * is JSON-clean. (The actual external behavior under native rolldown
- * comes from arrays/regex strings, set elsewhere by the orchestrator.)
+ * Surface native-engine bundle warnings through the same channel npm
+ * rolldown uses (its default `onLog` prints warnings at logLevel 'info').
+ * The Rust side collects rolldown warnings + plugin `this.warn()` calls
+ * into `BundleResult.warnings`; never reading them is what let the
+ * dropped-options hazard class ship unnoticed — UNRESOLVED_IMPORT (the
+ * only runtime signal that an import is riding the unresolved-fallback
+ * accident) and every plugin warning were invisible on the GJS-default
+ * engine. De-duplicated per call; respects `logLevel: 'silent'` (the
+ * `--globals auto` analysis passes set it, so analysis stays quiet).
+ */
+function reportNativeWarnings(result, opts) {
+    if (opts['logLevel'] === 'silent')
+        return;
+    if (!Array.isArray(result.warnings) || result.warnings.length === 0)
+        return;
+    const seen = new Set();
+    for (const warning of result.warnings) {
+        if (seen.has(warning))
+            continue;
+        seen.add(warning);
+        console.warn(`[gjsify-bundler] ${warning}`);
+    }
+}
+// Warn-once registry for `stripUnserializable` — one warning per option
+// key per process, so a 3-pass `--globals auto` build doesn't repeat the
+// same message. The silent drop of function-valued options is the
+// recurring footgun behind three shipped/near-shipped bugs (app/node.ts,
+// library/lib.ts, app/gjs.ts external predicates) — never drop silently.
+const warnedDroppedKeys = new Set();
+/**
+ * Sanitize fields the JSON encoder can't ship to the Rust deserializer.
  *
- * Also drops `sourcemap: false` — the JS API accepts a boolean while
- * the Rust deserializer expects an enum (`'File' | 'Inline' | 'Hidden'`).
- * Omitting the field has the same effect as `false`.
+ * Functions vanish under `JSON.stringify` (the key disappears from the
+ * JSON), silently changing build behavior vs npm rolldown — so dropping
+ * one now WARNS (once per key). `external` gets a dedicated message: the
+ * orchestrators express externals as exact-name arrays + an
+ * `externalsPlugin` resolveId hook precisely because a function predicate
+ * cannot cross this boundary; a function here means a regression (or a
+ * user config) reintroduced the dropped-predicate class.
+ *
+ * `external` array elements must be plain strings — the Rust
+ * `deserialize_external` only accepts `Vec<String>` and a RegExp
+ * serializes to `{}`, producing an opaque serde column error. Reject
+ * RegExp/non-string elements with a NAMED error instead.
+ *
+ * `sourcemap` is TRANSLATED, not dropped: the JS API accepts
+ * `boolean | 'inline' | 'hidden'` while the Rust `SourceMapType` enum
+ * (plain serde derive, no rename_all) only accepts `'File' | 'Inline' |
+ * 'Hidden'`. `true` → `'File'`, `'inline'` → `'Inline'`, `'hidden'` →
+ * `'Hidden'`; `false` is omitted (same effect).
+ *
+ * Exported for the unit tests in `bundler-pick.spec.ts`.
  */
-function stripUnserializable(opts) {
+export function stripUnserializable(opts) {
     const out = {};
     for (const [k, v] of Object.entries(opts)) {
-        if (typeof v === 'function')
+        if (typeof v === 'function') {
+            if (!warnedDroppedKeys.has(k)) {
+                warnedDroppedKeys.add(k);
+                const hint = k === 'external'
+                    ? ' Function `external` predicates are NOT supported by the native engine — ' +
+                        'pass exact names as a string array and/or enforce shape rules via a ' +
+                        'resolveId plugin returning `{ external: true }` (see externalsPlugin in ' +
+                        '@gjsify/rolldown-plugin-gjsify).'
+                    : ' Function-valued options do not survive the JSON boundary to the Rust core.';
+                console.warn(`[gjsify-bundler] dropping non-serializable option "${k}" for the native rolldown engine —` +
+                    ` behavior may diverge from npm rolldown.${hint}`);
+            }
             continue;
-        if (k === 'sourcemap' && typeof v === 'boolean')
+        }
+        if (k === 'external' && Array.isArray(v)) {
+            const bad = v.find((el) => typeof el !== 'string');
+            if (bad !== undefined) {
+                throw new Error('gjsify build: `external` entries must be exact string names under the native ' +
+                    `rolldown engine (got ${bad instanceof RegExp ? bad.toString() : typeof bad}). ` +
+                    'RegExp/function externals are only supported by npm rolldown — use exact names ' +
+                    'or a resolveId plugin returning `{ external: true }`.');
+            }
+            out[k] = v;
             continue;
+        }
+        if (k === 'sourcemap') {
+            const mapped = translateSourcemapOption(v);
+            if (mapped !== undefined)
+                out[k] = mapped;
+            continue;
+        }
         out[k] = v;
     }
     return out;
 }
+/**
+ * Map the JS-API `sourcemap` spellings onto the Rust `SourceMapType` enum
+ * variants. Returns `undefined` for `false`/unknown shapes (omit the key).
+ * Exported for the unit tests in `bundler-pick.spec.ts`.
+ */
+export function translateSourcemapOption(v) {
+    if (v === true || v === 'file' || v === 'File')
+        return 'File';
+    if (v === 'inline' || v === 'Inline')
+        return 'Inline';
+    if (v === 'hidden' || v === 'Hidden')
+        return 'Hidden';
+    return undefined;
+}
 /**
  * The Rust deserializer in the native facade treats `define` and `inject`
  * as top-level fields on `BundlerOptions`, while npm rolldown's JS API
@@ -345,17 +452,47 @@ function liftTransformExtras(opts) {
         ...lift,
     };
 }
-function mapToInjectArray(map) {
+/**
+ * Convert npm rolldown's `transform.inject` map shorthand into the array
+ * of descriptors the native Rust deserializer expects. The Rust
+ * `InjectImport` enum (`tag = "type"`, `rename_all = "camelCase"`) has
+ * exactly TWO variants:
+ *
+ *   - `{ type: 'named', imported, alias?, from }`
+ *   - `{ type: 'namespace', alias, from }`
+ *
+ * npm rolldown's map spellings translate as:
+ *
+ *   - `{ alias: 'module' }`        → default import →
+ *     `{ type: 'named', imported: 'default', alias, from: 'module' }`
+ *     (the Rust `InjectImport::default()` constructor encodes default
+ *     imports as a named import of `default` — there is NO `'default'`
+ *     variant; emitting `{ type: 'default' }` crashes the deserializer
+ *     with `unknown variant \`default\``).
+ *   - `{ alias: ['module', '*'] }` → namespace import →
+ *     `{ type: 'namespace', alias, from: 'module' }`.
+ *   - `{ alias: ['module', 'name'] }` → named import →
+ *     `{ type: 'named', from: 'module', imported: 'name', alias }`.
+ *
+ * Exported for the unit tests in `bundler-pick.spec.ts`.
+ */
+export function mapToInjectArray(map) {
     const out = [];
     for (const [alias, value] of Object.entries(map)) {
         if (typeof value === 'string') {
             // Default-import binding: `import alias from 'module'`
-            out.push({ type: 'default', from: value, alias });
+            out.push({ type: 'named', imported: 'default', from: value, alias });
         }
         else {
-            // Named-import binding: `import { imported as alias } from 'from'`
             const [from, imported] = value;
-            out.push({ type: 'named', from, imported, alias });
+            if (imported === '*') {
+                // Namespace-import binding: `import * as alias from 'from'`
+                out.push({ type: 'namespace', from, alias });
+            }
+            else {
+                // Named-import binding: `import { imported as alias } from 'from'`
+                out.push({ type: 'named', from, imported, alias });
+            }
         }
     }
     return out;

package/lib/cli-app.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Build + run the gjsify yargs command surface for the given argv (already
+ * stripped of the `node`/`gjs` + script prefix — i.e. what `hideBin` returns).
+ *
+ * `parseAsync()` (not `.argv`) so the caller's `await` keeps the process alive
+ * until command handlers finish — under GJS the script ends as soon as the
+ * top-level synchronous flow does, and fire-and-forget handlers would silently
+ * exit before any async work runs.
+ */
+export declare function runCli(argv: readonly string[]): Promise<void>;

package/lib/cli-app.js

@@ -0,0 +1,112 @@
+// The gjsify CLI command surface, factored out of `index.ts` so it can be
+// invoked two ways:
+//   1. As the process entry point (`index.ts` → `runCli(hideBin(process.argv))`).
+//   2. IN-PROCESS by `gjsify run` (`commands/run.ts`) to dispatch a script
+//      that is a single `gjsify <subcommand>` WITHOUT spawning a fresh gjs.
+//
+// Why (2) matters: under the GJS-first default every nested `gjsify …`
+// invocation is a heavyweight gjs process (startup + bundle loads). A package
+// build chains ~5 of them (`foreach → npm → gjsify run build:gjsify → gjsify
+// build`, and `gjsify run build:types → gjsify tsc → gjs tsc.gjs.mjs`), so on
+// CI's few cores the multiplier oversubscribes and the build thrashes. Letting
+// `gjsify run` dispatch the inner `gjsify <cmd>` in-process collapses two gjs
+// into one. See STATUS.md.
+//
+// This module MUST NOT execute anything at load time (no top-level
+// `parseAsync`) — `run.ts` imports it, and a top-level run would re-dispatch
+// the original argv on import.
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import yargs from 'yargs';
+import { buildCommand as build, testCommand as test, runCommand as run, infoCommand as info, systemCheckCommand as systemCheck, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, gsettingsCommand as gsettings, flatpakCommand as flatpak, dlxCommand as dlx, installCommand as install, foreachCommand as foreach, workspaceCommand as workspace, packCommand as pack, publishCommand as publish, whoamiCommand as whoami, loginCommand as login, logoutCommand as logout, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, uninstallCommand as uninstall, formatCommand as format, lintCommand as lint, fixCommand as fix, upgradeCommand as upgrade, barrelsCommand as barrels, tscCommand as tsc, affectedCommand as affected, } from './commands/index.js';
+import { APP_NAME } from './constants.js';
+// Detect which runtime is executing the CLI (GJS or Node.js).
+// GJS MUST be checked first because @gjsify/process sets
+// `process.versions.node = '20.0.0'` for compatibility — a plain
+// `process.versions.node` check would be a false Node positive under GJS.
+function runtimeLabel() {
+    try {
+        const sys = globalThis.imports?.system;
+        if (sys?.version !== undefined) {
+            const v = Number(sys.version);
+            return `GJS ${Math.floor(v / 10000)}.${Math.floor((v % 10000) / 100)}.${v % 100} (SpiderMonkey)`;
+        }
+    }
+    catch {
+        /* not GJS */
+    }
+    if (typeof process !== 'undefined' && typeof process.versions?.node === 'string') {
+        return `Node.js ${process.version}`;
+    }
+    return 'unknown runtime';
+}
+// Read the version from package.json adjacent to the bundle. yargs's
+// auto-version-discovery (its `pkg-up`-driven default) doesn't reach
+// through the bundled `dist/cli.gjs.mjs` path on GJS — falls back to
+// "unknown". Both layouts are covered:
+//   - dev (tsx, `yarn workspace`):  src/index.ts → ../package.json
+//   - bundled (install -g):         dist/cli.gjs.mjs → ../package.json
+function readBundleVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
+        return typeof pkg.version === 'string' ? pkg.version : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * Build + run the gjsify yargs command surface for the given argv (already
+ * stripped of the `node`/`gjs` + script prefix — i.e. what `hideBin` returns).
+ *
+ * `parseAsync()` (not `.argv`) so the caller's `await` keeps the process alive
+ * until command handlers finish — under GJS the script ends as soon as the
+ * top-level synchronous flow does, and fire-and-forget handlers would silently
+ * exit before any async work runs.
+ */
+export async function runCli(argv) {
+    const cli = yargs(argv);
+    await cli
+        .scriptName(APP_NAME)
+        .version(readBundleVersion())
+        .strict()
+        // Use the full terminal width for help (yargs caps at 80 by default).
+        .wrap(cli.terminalWidth())
+        .command(create.command, create.description, create.builder, create.handler)
+        .command(install.command, install.description, install.builder, install.handler)
+        .command(build.command, build.description, build.builder, build.handler)
+        .command(test.command, test.description, test.builder, test.handler)
+        .command(run.command, run.description, run.builder, run.handler)
+        .command(dlx.command, dlx.description, dlx.builder, dlx.handler)
+        .command(info.command, info.description, info.builder, info.handler)
+        .command(systemCheck.command, systemCheck.description, systemCheck.builder, systemCheck.handler)
+        .command(check.command, check.description, check.builder, check.handler)
+        .command(showcase.command, showcase.description, showcase.builder, showcase.handler)
+        .command(gresource.command, gresource.description, gresource.builder, gresource.handler)
+        .command(gettext.command, gettext.description, gettext.builder, gettext.handler)
+        .command(gsettings.command, gsettings.description, gsettings.builder, gsettings.handler)
+        .command(flatpak.command, flatpak.description, flatpak.builder, flatpak.handler)
+        .command(foreach.command, foreach.description, foreach.builder, foreach.handler)
+        .command(workspace.command, workspace.description, workspace.builder, workspace.handler)
+        .command(pack.command, pack.description, pack.builder, pack.handler)
+        .command(publish.command, publish.description, publish.builder, publish.handler)
+        .command(whoami.command, whoami.description, whoami.builder, whoami.handler)
+        .command(login.command, login.description, login.builder, login.handler)
+        .command(logout.command, logout.description, logout.builder, logout.handler)
+        .command(selfUpdate.command, selfUpdate.description, selfUpdate.builder, selfUpdate.handler)
+        .command(generateInstaller.command, generateInstaller.description, generateInstaller.builder, generateInstaller.handler)
+        .command(uninstall.command, uninstall.description, uninstall.builder, uninstall.handler)
+        .command(upgrade.command, upgrade.description, upgrade.builder, upgrade.handler)
+        .command(format.command, format.description, format.builder, format.handler)
+        .command(lint.command, lint.description, lint.builder, lint.handler)
+        .command(fix.command, fix.description, fix.builder, fix.handler)
+        .command(barrels.command, barrels.description, barrels.builder, barrels.handler)
+        .command(tsc.command, tsc.description, tsc.builder, tsc.handler)
+        .command(affected.command, affected.description, affected.builder, affected.handler)
+        .demandCommand(1)
+        .epilogue(`Running on ${runtimeLabel()}`)
+        .help()
+        .parseAsync();
+}

package/lib/commands/affected.js

@@ -114,6 +114,10 @@ const IGNORE = [
     /^docs\//,
     /^\.github\/workflows\/(deploy-docs|commitlint|release|audit-runtimes|prebuilds)\.yml$/,
     /^\.githooks\//,
+    // 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.
+    /^flatpak\//,
     /^LICENSE/,
     /^\.gitignore$/,
     /^\.gjsify-[^/]*\.md$/,

package/lib/commands/build.js

@@ -107,7 +107,7 @@ export const buildCommand = {
             normalize: true,
         })
             .option('external', {
-            description: 'Module names that should NOT be bundled. Repeat the flag or pass a comma-separated list (e.g. --external typedoc,prettier). Globs are forwarded to esbuild as-is. See https://esbuild.github.io/api/#external',
+            description: 'Module names that should NOT be bundled — EXACT package names only, matched literally on both bundler engines (no globs). Repeat the flag or pass a comma-separated list (e.g. --external typedoc,prettier). Appended to the per-app built-in externals; register subpaths (`<pkg>/register[/…]`) are always force-inlined for --app gjs regardless of this flag.',
             array: true,
             type: 'string',
             default: [],
@@ -146,6 +146,10 @@ export const buildCommand = {
         });
     },
     handler: async (args) => {
+        // NOTE: `gjsify build` runs under BOTH Node (npm `rolldown`) and GJS
+        // (native `@gjsify/rolldown-native`, PR #483). The Node-free release
+        // pipeline dogfoods the GJS path — `gjsify run build` under the
+        // GJS-bundled CLI rebuilds the bundle. Do NOT gate this on the runtime.
         const config = new Config();
         const configData = await config.forBuild(args);
         const action = new BuildAction(configData);

package/lib/commands/check.js

@@ -15,6 +15,7 @@
 // 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 { prefixLines } from '../utils/prefixed-output.js';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { cpus } from 'node:os';
@@ -42,22 +43,29 @@ function runCheck(ws, prefix) {
             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}] `;
-            const forward = (stream, dest) => {
-                stream.on('data', (chunk) => {
-                    const text = chunk.toString('utf-8');
-                    for (const line of text.split('\n')) {
-                        if (line.length > 0)
-                            dest.write(`${tag}${line}\n`);
-                    }
-                });
-            };
-            forward(child.stdout, process.stdout);
-            forward(child.stderr, process.stderr);
+            flushers.push(prefixLines(child.stdout, process.stdout, tag, buffered));
+            flushers.push(prefixLines(child.stderr, process.stderr, tag, buffered));
         }
-        child.on('close', (code) => resolve(code ?? 1));
-        child.on('error', () => resolve(1));
+        child.on('close', (code) => {
+            for (const flush of flushers)
+                flush();
+            resolve(code ?? 1);
+        });
+        child.on('error', () => {
+            for (const flush of flushers)
+                flush();
+            resolve(1);
+        });
     });
 }
 export const checkCommand = {

package/lib/commands/dlx.js

@@ -91,7 +91,9 @@ export const dlxCommand = {
         if (entry.fromFallback) {
             console.warn(`[gjsify dlx] package "${cachedPkgName ?? parsed.kind}" has no \`gjsify\` field — falling back to package.json#main. Add \`gjsify.main\` to silence.`);
         }
-        await runGjsBundle(entry.bundlePath, extraArgs);
+        // Terminal call — exit on success, or the GJS main loop parks this
+        // process forever (see RunGjsBundleOptions.exitOnSuccess).
+        await runGjsBundle(entry.bundlePath, extraArgs, { exitOnSuccess: true });
     },
 };
 async function ensurePkgDir(parsed, opts) {

package/lib/commands/fix.js

@@ -7,7 +7,7 @@
 // Naming: deliberately distinct from `gjsify check` (workspace TS check) and
 // `gjsify system-check` (system-dependency verifier).
 import { resolve } from 'node:path';
-import { OxcNotFoundError, findOxfmtConfig, findOxlintConfig, printOxcNotFound, runOxfmt, runOxlint, } from '../utils/oxc-resolve.js';
+import { OxcNotFoundError, findOxfmtConfig, findOxlintConfig, printOxcNotFound, runOxfmt, runOxlint, setOxcExitCode, } from '../utils/oxc-resolve.js';
 export const fixCommand = {
     command: 'fix [paths..]',
     description: 'Run oxfmt --write then oxlint --fix — format + safe lint fixes in one pass.',
@@ -56,12 +56,12 @@ export const fixCommand = {
                 lintArgs.push('--config', resolve(lintConfig));
             lintArgs.push(...paths);
             const lintCode = await runOxlint(lintArgs, { cwd, verbose });
-            process.exitCode = fmtCode || lintCode;
+            setOxcExitCode(fmtCode || lintCode);
         }
         catch (err) {
             if (err instanceof OxcNotFoundError) {
                 printOxcNotFound(err);
-                process.exitCode = 1;
+                setOxcExitCode(1);
                 return;
             }
             throw err;