@gjsify/cli 0.24.2 → 0.26.0

package/lib/actions/build.d.ts

@@ -60,6 +60,19 @@ export declare class BuildAction {
      * text scan cannot tell from a statement.
      */
     private assertGjsOutputLoadable;
+    /**
+     * Post-bundle gate for `--app node`: throw when the emitted bundle still
+     * references GJS ambient globals (`print`/`imports`/…) although the
+     * pre-build detection decided no `@gjsify/node-gi/globals` shim was needed
+     * — see `utils/node-bundle-guard.ts` for the full rationale.
+     *
+     * Unlike the `--app gjs` gate, the oracle here CANNOT be the module graph:
+     * an ambient global is a free identifier, not an import, so nothing about it
+     * appears in a chunk's `imports` list. It is the same acorn pass the
+     * detector runs, re-applied to what was actually written — a post-condition
+     * on the prediction, not a second opinion.
+     */
+    private assertNodeOutputGlobals;
     /**
      * 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

@@ -11,6 +11,7 @@ import { normalizeBundlerOptions, mergeBundlerOptions } from '../utils/normalize
 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';
+import { assertNodeBundleGlobalsShimmed } from '../utils/node-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
@@ -291,6 +292,31 @@ export class BuildAction {
         const chunks = (result.output ?? []).filter((item) => item.type === 'chunk');
         assertGjsBundleLoadable(chunks, outfile ?? outdir ?? 'the GJS bundle');
     }
+    /**
+     * Post-bundle gate for `--app node`: throw when the emitted bundle still
+     * references GJS ambient globals (`print`/`imports`/…) although the
+     * pre-build detection decided no `@gjsify/node-gi/globals` shim was needed
+     * — see `utils/node-bundle-guard.ts` for the full rationale.
+     *
+     * Unlike the `--app gjs` gate, the oracle here CANNOT be the module graph:
+     * an ambient global is a free identifier, not an import, so nothing about it
+     * appears in a chunk's `imports` list. It is the same acorn pass the
+     * detector runs, re-applied to what was actually written — a post-condition
+     * on the prediction, not a second opinion.
+     */
+    assertNodeOutputGlobals(result, outfile, outdir) {
+        const label = outfile ?? outdir ?? 'the node bundle';
+        for (const item of result.output ?? []) {
+            if (item.type !== 'chunk')
+                continue;
+            // `code` is present on a written chunk for both engines; skip
+            // defensively rather than fail a build over a missing field.
+            const code = item.code;
+            if (typeof code !== 'string' || code.length === 0)
+                continue;
+            assertNodeBundleGlobalsShimmed(code, item.fileName ? `${label} (${item.fileName})` : label);
+        }
+    }
     /**
      * Post-bundle step for a `--app browser` HTML entry: write the processed
      * `index.html` beside the JS bundle, with the entry `<script>`'s `src`
@@ -530,6 +556,30 @@ export class BuildAction {
             // detection must run BEFORE the final build so the entry can be
             // wrapped; nothing is injected when no globals are referenced (the
             // eager-native-load regression guard).
+            //
+            // Explicit extras on a node build (`--globals auto,dom,…`) are the
+            // reverse bridge's DOM-surface request: inject the SAME register
+            // modules the gjs target would for those identifiers, so a genuine
+            // GJS source (an Excalibur/WebGLBridge app) gets document /
+            // HTMLCanvasElement / matchMedia / … on Node via node-gi. The
+            // orchestrator lifts the `@gjsify/empty` register routing only when
+            // this inject stub is present (see app/node.ts) — plain `auto`
+            // node builds are byte-unchanged.
+            //
+            // The stub is resolved BEFORE the detection pass, and that ordering
+            // is load-bearing: it is one of the two signals `isGjsSourceBuild`
+            // reads, so it decides whether `/register` subpaths resolve for real
+            // or route to `@gjsify/empty` and whether `@girs/*` bodies survive.
+            // Resolving it afterwards made the analysis bundle a DIFFERENT
+            // module graph from the one actually emitted — every GJS ambient
+            // global reachable only THROUGH a register module was invisible, so
+            // the shim was not injected and the emitted bundle threw
+            // `ReferenceError: imports is not defined` at runtime (the
+            // excalibur-jelly-jumper showcase on node/bun, via
+            // `@gjsify/canvas2d-core`'s `_toDataURL` and `@gjsify/utils`).
+            if (extras) {
+                pluginOpts.autoGlobalsInject = await this.resolveGlobalsInject(app, extras, verbose);
+            }
             const gjsifyPluginFactory = async (opts) => {
                 const cfg = await gjsifyPlugin({
                     input: userBundler.input,
@@ -550,17 +600,6 @@ export class BuildAction {
             }, pluginOpts, gjsifyPluginFactory, bundleToChunks);
             if (needsGiGlobals)
                 pluginOpts.nodeGiGlobalsInject = true;
-            // Explicit extras on a node build (`--globals auto,dom,…`) are the
-            // reverse bridge's DOM-surface request: inject the SAME register
-            // modules the gjs target would for those identifiers, so a genuine
-            // GJS source (an Excalibur/WebGLBridge app) gets document /
-            // HTMLCanvasElement / matchMedia / … on Node via node-gi. The
-            // orchestrator lifts the `@gjsify/empty` register routing only when
-            // this inject stub is present (see app/node.ts) — plain `auto`
-            // node builds are byte-unchanged.
-            if (extras) {
-                pluginOpts.autoGlobalsInject = await this.resolveGlobalsInject(app, extras, verbose);
-            }
         }
         else if (extras) {
             pluginOpts.autoGlobalsInject = await this.resolveGlobalsInject(app, extras, verbose);
@@ -596,6 +635,13 @@ export class BuildAction {
         if (app === 'gjs') {
             this.assertGjsOutputLoadable(writeResult, outfile, outdir);
         }
+        // Refuse to hand back a `--app node` bundle that reaches for GJS ambient
+        // globals nothing seeds. Only meaningful when the shim was NOT injected:
+        // with it, the globals are installed and the references are correct.
+        // `--globals none` opts out of the mechanism, so it opts out of the gate.
+        if (app === 'node' && autoMode && !pluginOpts.nodeGiGlobalsInject) {
+            this.assertNodeOutputGlobals(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

package/lib/cli-app.js

@@ -10,7 +10,7 @@
 // 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.
+// into one. See status/open-todos.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
@@ -28,15 +28,12 @@ import { ensureGjsifyShimOnPath } from './utils/gjsify-shim.js';
 // GJS's @gjsify/process shim — fake `process.versions.node` for npm
 // compatibility, so a plain Node probe is a false positive on either.
 function runtimeLabel() {
-    try {
-        const sysVersion = gjsSystemVersion();
-        if (sysVersion !== undefined) {
-            const v = Number(sysVersion);
-            return `GJS ${Math.floor(v / 10000)}.${Math.floor((v % 10000) / 100)}.${v % 100} (SpiderMonkey)`;
-        }
-    }
-    catch {
-        /* not GJS */
+    // Off GJS `gjsSystemVersion()` RETURNS undefined (an optional-chained
+    // `globalThis.imports` read, same probe as `isGjs()`) — it never throws.
+    const sysVersion = gjsSystemVersion();
+    if (sysVersion !== undefined) {
+        const v = Number(sysVersion);
+        return `GJS ${Math.floor(v / 10000)}.${Math.floor((v % 10000) / 100)}.${v % 100} (SpiderMonkey)`;
     }
     if (isBun()) {
         const version = globalThis.Bun?.version ?? process.versions.bun;

package/lib/commands/affected.js

@@ -343,7 +343,16 @@ function runGitDiff(cwd, base, head) {
         // Surface a clear error — caller (CI) will fall back to full run
         // via `continue-on-error: true` on the classify step.
         process.stderr.write(`gjsify affected: git diff failed (${r.status}): ${r.stderr.trim()}\n`);
+        // Under GJS `process.exit()` is DEFERRED (no atexit — the call
+        // returns), so in this synchronous, value-returning helper a bare
+        // exit fell through to the `return` below and handed the caller a
+        // diff parsed from a failed git run. `return process.exit(…)` cannot
+        // help here either — it would hand the caller the pending exit
+        // promise as a `string[]`. The throw is what actually stops the
+        // caller; on Node the exit(2) halts first and the throw is dead.
+        // oxlint-disable-next-line gjsify/deferred-process-exit -- the throw below IS the halt for the GJS path; see the comment above.
         process.exit(2);
+        throw new Error(`gjsify affected: git diff failed (${r.status})`);
     }
     return r.stdout.split('\n').filter(Boolean);
 }
@@ -409,8 +418,11 @@ function assertShellSafeWorkspaceName(name) {
         `  \`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`);
+    // NOT unreachable under GJS: `process.exit()` is DEFERRED there (no atexit
+    // — the call returns), so the throw below is what actually stops an unsafe
+    // name from reaching the emit site; the exit code rides the scheduled
+    // teardown. On Node the exit(2) halts first and the throw is dead code.
+    // oxlint-disable-next-line gjsify/deferred-process-exit -- the throw below IS the halt for the GJS path; see the comment above.
     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

@@ -112,7 +112,10 @@ export const checkCommand = {
                     console.log(`[check] cwd=${cwd}  → npm run check`);
                 }
                 const r = spawnSync('npm', ['run', 'check'], { cwd, stdio: 'inherit' });
-                process.exit(r.status ?? 1);
+                // `return` — a bare `process.exit()` is deferred under GJS (no
+                // atexit), so execution fell through into workspace mode and
+                // re-checked the whole monorepo after the single-package run.
+                return process.exit(r.status ?? 1);
             }
             // Fall through to workspace mode when the local package has no
             // check script (cd'd into a non-package dir under the root).
@@ -120,7 +123,9 @@ export const checkCommand = {
         // ---- Workspace mode ----
         if (!workspaceRoot) {
             console.error('gjsify check: no workspace root found from cwd. Run inside a workspace (or a package within one) with `npm run check` defined.');
-            process.exit(1);
+            // `return` — the deferred GJS exit otherwise ran discoverWorkspaces
+            // on a null root.
+            return process.exit(1);
         }
         const allWorkspaces = discoverWorkspaces(workspaceRoot);
         // Always exclude @girs/* (type-only packages, no own tsc check).
@@ -137,7 +142,7 @@ export const checkCommand = {
         });
         if (targets.length === 0) {
             console.error('gjsify check: no workspaces with a `check` script found.');
-            process.exit(1);
+            return process.exit(1);
         }
         if (args.verbose) {
             console.log(`[check] root=${workspaceRoot}  workspaces=${targets.length}  parallel=${args.parallel ? 'yes' : 'no'}`);
@@ -145,16 +150,26 @@ export const checkCommand = {
         // ---- Sequential mode ----
         if (!args.parallel) {
             let firstFail = 0;
+            let failCount = 0;
             for (const ws of targets) {
                 if (args.verbose)
                     console.log(`[check] → ${ws.name}`);
                 const code = await runCheck(ws, null);
-                if (code !== 0 && firstFail === 0)
-                    firstFail = code;
+                if (code !== 0) {
+                    failCount++;
+                    if (firstFail === 0)
+                        firstFail = code;
+                }
             }
+            // Count failures from the loop above — the previous
+            // `targets.filter(async …)` spelling RE-SPAWNED every workspace's
+            // check (fire-and-forget) just to print a count, and its async
+            // predicate is always truthy, so it counted ALL targets.
             if (firstFail !== 0)
-                console.error(`gjsify check: failures in ${targets.filter(async (ws) => (await runCheck(ws, null)) !== 0).length}+ workspaces`);
-            process.exit(firstFail);
+                console.error(`gjsify check: failures in ${failCount} workspace(s)`);
+            // `return` — a bare exit is deferred under GJS and fell through
+            // into parallel mode, re-running every check.
+            return process.exit(firstFail);
         }
         // ---- Parallel mode (default) ----
         const concurrency = args.jobs ?? Math.max(1, cpus().length);
@@ -179,7 +194,9 @@ export const checkCommand = {
             console.error(`\ngjsify check: ${failures.length} of ${targets.length} workspace(s) failed:`);
             for (const f of failures)
                 console.error(`  ✗ ${f.name} (exit ${f.code})`);
-            process.exit(1);
+            // `return` — the deferred GJS exit otherwise fell through to the
+            // success `process.exit(0)` below, clobbering the failure code.
+            return process.exit(1);
         }
         if (args.verbose)
             console.log(`\ngjsify check: ${targets.length} workspace(s) green.`);

package/lib/commands/create.js

@@ -37,7 +37,9 @@ export const createCommand = {
             if (!process.stdin.isTTY) {
                 const list = templates.map((t) => t.name).join(', ');
                 console.error(`Error: --template is required in non-interactive mode. Available templates: ${list || '(none)'}`);
-                process.exit(1);
+                // `return` — the deferred GJS exit otherwise fell through into
+                // the interactive template prompt on a non-TTY.
+                return process.exit(1);
             }
             const picked = await promptTemplate(templates);
             template = picked.name;

package/lib/commands/debug.js

@@ -122,7 +122,9 @@ export const debugCommand = {
                     : undefined);
         if (!busNameBase) {
             console.error('gjsify debug: no bus name — set package.json#gjsify.devtools.busNameBase or pass --bus-name <org.example.App>');
-            process.exit(1);
+            // `return` — a bare `process.exit()` is deferred under GJS and the
+            // handler would continue without a bus name.
+            return process.exit(1);
         }
         const globals = args.globals ?? config.globals ?? 'auto';
         const name = pkg.name ? `${pkg.name}-devtools` : 'gjsify-devtools';

package/lib/commands/flatpak/check.js

@@ -73,8 +73,7 @@ export const flatpakCheckCommand = {
         if (args.builderLint !== false) {
             if (!existsSync(manifestPath)) {
                 console.error(`[gjsify flatpak check] manifest not found: ${manifestPath}`);
-                process.exit(1);
-                return;
+                return process.exit(1);
             }
             const ok = await runLinter('flatpak-builder-lint', ['manifest', manifestPath], args.verbose ?? false);
             if (!ok)
@@ -88,7 +87,9 @@ export const flatpakCheckCommand = {
         }
         if (failures > 0) {
             console.error(`\n[gjsify flatpak check] ${failures} check(s) failed.`);
-            process.exit(1);
+            // `return` — the deferred GJS exit otherwise fell through and ALSO
+            // printed "all checks passed" after reporting failures.
+            return process.exit(1);
         }
         console.log('[gjsify flatpak check] all checks passed.');
     },

package/lib/commands/flatpak/diff.js

@@ -87,7 +87,9 @@ export const flatpakDiffCommand = {
         }
         if (!remoteTag) {
             console.warn('[gjsify flatpak diff] flathub manifest has no `tag` field on the inspected source.');
-            process.exit(1);
+            // `return` — the deferred GJS exit otherwise compared an undefined
+            // tag below and could report "in sync" on a broken manifest.
+            return process.exit(1);
         }
         if (remoteTag === localVersion) {
             console.log(`✅ in sync (${localVersion})`);

package/lib/commands/flatpak/sources.js

@@ -31,13 +31,10 @@ function parseSri(integrity) {
         return null;
     const algorithm = integrity.slice(0, dash);
     const b64 = integrity.slice(dash + 1).replace(/=+$/, '');
-    let hex;
-    try {
-        hex = Buffer.from(b64, 'base64').toString('hex');
-    }
-    catch {
-        return null;
-    }
+    // Base64 decoding is lenient on every runtime (Node skips invalid chars,
+    // @gjsify/buffer's table decode maps them to 0): malformed input yields
+    // short/garbage output — caught by the length check below — never a throw.
+    const hex = Buffer.from(b64, 'base64').toString('hex');
     if (hex.length < 4)
         return null;
     return { algorithm, hex };

package/lib/commands/foreach.js

@@ -141,7 +141,9 @@ function signalTree(child, descendants, signal) {
         child.kill(signal);
     }
     catch {
-        // already gone — fine
+        // NOT the already-dead case — `ChildProcess.kill()` swallows ESRCH
+        // itself and returns false. This guards Node's residual throw paths
+        // (EPERM surfacing via an unhandled 'error' emit, unknown signal).
     }
 }
 function killActiveChildren() {
@@ -292,7 +294,9 @@ export const foreachCommand = {
             }
             if (!cmd) {
                 console.error('gjsify foreach --exec: missing command. Pass it after `--`, e.g. `gjsify foreach --exec -- npm publish --tag latest`.');
-                process.exit(1);
+                // `return` — a bare `process.exit()` is deferred under GJS and
+                // the handler would keep running without a command.
+                return process.exit(1);
             }
         }
         assertEveryIncludeMatches(allWorkspaces, args.include);
@@ -309,7 +313,8 @@ export const foreachCommand = {
         if (!exec) {
             if (!cmd) {
                 console.error('gjsify foreach: missing <script> positional. Pass --exec to run an arbitrary command instead.');
-                process.exit(1);
+                // `return` — see the deferred-exit note on the --exec guard.
+                return process.exit(1);
             }
             const scriptName = cmd;
             selected = selected.filter((ws) => {
@@ -330,13 +335,16 @@ export const foreachCommand = {
             const m = /^\s*(\d+)\s*\/\s*(\d+)\s*$/.exec(args.shard);
             if (!m) {
                 console.error(`gjsify foreach: invalid --shard "${args.shard}" — expected "<index>/<total>" (1-based), e.g. 2/4.`);
-                process.exit(1);
+                // `return` — the deferred GJS exit otherwise ran the whole
+                // unsharded set.
+                return process.exit(1);
             }
             const index = Number(m[1]);
             const total = Number(m[2]);
             if (total < 1 || index < 1 || index > total) {
                 console.error(`gjsify foreach: invalid --shard "${args.shard}" — need 1 <= index <= total and total >= 1.`);
-                process.exit(1);
+                // `return` — see the deferred-exit note on the shard guard above.
+                return process.exit(1);
             }
             if (total > 1) {
                 const byName = [...selected].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
@@ -376,7 +384,8 @@ export const foreachCommand = {
             // default covers whole script chains (CI sets it once for the
             // build job) where an --exec invocation is simply not cacheable.
             console.error('gjsify foreach: --cached only applies to script mode, not --exec.');
-            process.exit(1);
+            // `return` — the deferred GJS exit otherwise ran the --exec anyway.
+            return process.exit(1);
         }
         const cache = cached && !exec
             ? new BuildCacheRunner({
@@ -409,7 +418,9 @@ export const foreachCommand = {
             // leave orphans holding the CI step's stdio open.
             killActiveChildren();
             console.error(err.message);
-            process.exit(1);
+            // `return` — the deferred GJS exit otherwise fell through to the
+            // success `process.exit(0)` below, clobbering the failure code.
+            return process.exit(1);
         }
         // ensureMainLoop() (called inside spawn) keeps GJS alive after every
         // child exits — without an explicit process.exit() the success path
@@ -472,7 +483,14 @@ function assertEveryIncludeMatches(allWorkspaces, include) {
     }
     lines.push(`  ${allWorkspaces.length} workspace(s) discovered. Refusing to run: a filter that selects nothing would`, `  otherwise exit 0 and look exactly like a successful run over the whole set.`);
     console.error(lines.join('\n'));
+    // Under GJS `process.exit()` is DEFERRED (no atexit — the call returns), so
+    // a bare exit here RETURNED to the handler, which kept going and could
+    // spawn children for the patterns that DID match before the scheduled exit
+    // fired. The throw is what actually stops the run on GJS; on Node the
+    // exit(1) halts first and the throw is dead code.
+    // oxlint-disable-next-line gjsify/deferred-process-exit -- the throw below IS the halt for the GJS path; see the comment above.
     process.exit(1);
+    throw new Error('gjsify foreach: --include matched no workspace');
 }
 /** Drop ONE matching pair of surrounding `'` or `"` — the quoting-bug probe. */
 function stripSurroundingQuotes(s) {

package/lib/commands/generate-installer.js

@@ -60,8 +60,7 @@ export const generateInstallerCommand = {
         const outputPath = resolve(process.cwd(), args.output);
         if (existsSync(outputPath) && !args.force) {
             console.error(`${args.output} already exists. Re-run with --force to overwrite.`);
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         const pkgJsonPath = resolve(process.cwd(), 'package.json');
         let pkgJson = null;
@@ -76,8 +75,7 @@ export const generateInstallerCommand = {
         const target = args.target ?? pkgJson?.name;
         if (!target) {
             console.error('No target package: pass `gjsify generate-installer <pkg>` or run inside a directory with a package.json.');
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         const binName = args['bin-name'] ?? pickDefaultBinName(pkgJson, target);
         const bootstrapUrl = args['bootstrap-url'] ?? DEFAULT_BOOTSTRAP_URL;

package/lib/commands/install.js

@@ -17,7 +17,7 @@
 // `node_modules/` and symlinks `workspace:*` / `workspace:^` / `workspace:~`
 // refs to their target source. Conflicting version ranges of the same
 // external dep from different workspaces still share ONE hoisted root copy
-// (a real per-workspace dedup pass is Phase D.8, see STATUS.md), but since
+// (a real per-workspace dedup pass is Phase D.8, see status/open-todos.md), but since
 // ADR 0001 step 3 the resolver surfaces every such conflict loudly —
 // `[gjsify] warning: version conflict for <pkg> …` names both ranges, the
 // workspaces that requested them, and the version that actually won.
@@ -133,22 +133,27 @@ export const installCommand = {
             if (args.packages && args.packages.length > 0) {
                 console.error('gjsify install --immutable does not accept package arguments. ' +
                     'Remove the package names or drop --immutable.');
-                process.exit(1);
+                // `return` — a bare `process.exit()` is deferred under GJS and
+                // the install would proceed past a refused flag combination.
+                return process.exit(1);
             }
             if (args.global) {
                 console.error('gjsify install --immutable is incompatible with --global.');
-                process.exit(1);
+                // `return` — see the deferred-exit note above.
+                return process.exit(1);
             }
             if (args['refresh-lockfile']) {
                 console.error('gjsify install --immutable is incompatible with --refresh-lockfile ' +
                     '(--immutable forbids rewriting the lockfile). Drop one.');
-                process.exit(1);
+                // `return` — see the deferred-exit note above.
+                return process.exit(1);
             }
         }
         if (args.global) {
             if (!args.packages || args.packages.length === 0) {
                 console.error('gjsify install --global requires at least one <pkg> argument.');
-                process.exit(1);
+                // `return` — see the deferred-exit note above.
+                return process.exit(1);
             }
             for (const flag of ['save-dev', 'save-peer', 'save-optional']) {
                 if (args[flag]) {
@@ -241,7 +246,10 @@ export const installCommand = {
                 const secs = Math.round(overallTimeoutMs / 100) / 10;
                 console.error(`gjsify install: timed out after ${secs}s — likely a registry slowdown or a wedged extract.\n` +
                     `Re-run, or override with --timeout <ms> (set --timeout 0 to disable the overall budget).`);
-                process.exit(1);
+                // `return` — the deferred GJS exit otherwise fell through into
+                // the rethrow below and reported the timeout twice. The
+                // `finally` still runs on the way out and clears the timers.
+                return process.exit(1);
             }
             throw err;
         }
@@ -536,7 +544,7 @@ function syncLockfileRequested(cwd, specs) {
  *
  * Hoisting strategy is intentionally minimal — per-workspace dedup +
  * nested `node_modules/` for cross-workspace version conflicts are the
- * Phase D.8 follow-up tracked in STATUS.md.
+ * Phase D.8 follow-up tracked in status/open-todos.md.
  */
 async function workspaceInstall(cwd, args, signal) {
     // Hold the root-prefix lock for the WHOLE workspace flow: bin shims,

package/lib/commands/login.js

@@ -63,7 +63,9 @@ export const loginCommand = {
         catch (err) {
             if (err instanceof LoginError) {
                 console.error(err.message);
-                process.exit(1);
+                // `return` — the deferred GJS exit otherwise fell through into
+                // the rethrow below and reported the login error twice.
+                return process.exit(1);
             }
             throw err;
         }

package/lib/commands/onboard.js

@@ -116,8 +116,7 @@ export const onboardCommand = {
                 process.stdout.write(`${JSON.stringify({ ok: false, error: 'auth', message: msg })}\n`);
             else
                 console.error(msg);
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         // Login may have written a fresh token — reload so the probes/ops use it.
         npmrc = await loadNpmrc(cwd);
@@ -136,8 +135,7 @@ export const onboardCommand = {
                 process.stdout.write(`${JSON.stringify({ ok: false, error: 'repository', message: msg })}\n`);
             else
                 console.error(msg);
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         const workflow = normalizeWorkflowFile(args.workflow);
         const environment = args.environment;
@@ -155,8 +153,7 @@ export const onboardCommand = {
                 process.stdout.write(`${JSON.stringify({ ok: false, error: 'no-packages', message: msg })}\n`);
             else
                 console.error(msg);
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         log(`gjsify onboard: ${selected.length} package(s) | repo=${repository} workflow=${workflow}`);
         if (dryRun)

package/lib/commands/publish.js

@@ -125,7 +125,9 @@ export const publishCommand = {
             const rawPkg = JSON.parse(readFileSync(rawPkgPath, 'utf-8'));
             if (typeof rawPkg.name !== 'string') {
                 process.stderr.write(`gjsify publish --check-trusted: ${rawPkgPath} has no \`name\` field\n`);
-                process.exit(2);
+                // `return` — a bare `process.exit()` is deferred under GJS and
+                // the check would continue on a nameless manifest.
+                return process.exit(2);
             }
             if (rawPkg.private === true) {
                 const out = { ok: true, action: 'check-trusted', name: rawPkg.name, skipped: 'private' };
@@ -432,13 +434,11 @@ function reportPublishOutcome(outcome, asJson) {
         }
         case 'otp-required': {
             console.error(`gjsify publish: npm requires a 2FA one-time code — re-run with \`--otp <code>\``);
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         case 'oidc-failed': {
             handleOidcFailure(outcome.error, outcome.name, asJson);
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         case 'oidc-no-token': {
             const msg = outcome.error instanceof Error ? outcome.error.message : String(outcome.error);
@@ -446,8 +446,7 @@ function reportPublishOutcome(outcome, asJson) {
             if (asJson) {
                 process.stdout.write(`${JSON.stringify({ ok: false, name: outcome.name, version: outcome.version, error: 'oidc-failed-no-token' }, null, 2)}\n`);
             }
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         case 'diagnostic': {
             if (asJson) {
@@ -463,14 +462,12 @@ function reportPublishOutcome(outcome, asJson) {
             else {
                 process.stderr.write(`${outcome.diag.message}\n`);
             }
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         case 'error': {
             console.error(`gjsify publish: ${outcome.name}@${outcome.version} — ${outcome.status} ${outcome.statusText}`);
             console.error(outcome.text);
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
     }
 }

package/lib/commands/self-update.js

@@ -65,15 +65,13 @@ export const selfUpdateCommand = {
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             console.error(`Failed to fetch packument: ${msg}`);
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         const target = resolveTag(packument, args.tag);
         if (!target) {
             console.error(`Unknown dist-tag '${args.tag}' on ${PACKAGE_NAME}. ` +
                 `Known tags: ${Object.keys(packument['dist-tags'] ?? {}).join(', ') || '(none)'}`);
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         console.log(`Latest matching --tag ${args.tag}: v${target}`);
         // A version match is NOT sufficient to declare "up to date": a global
@@ -103,8 +101,7 @@ export const selfUpdateCommand = {
         }
         if (args.check) {
             console.log(currentVersion ? `Update available: v${currentVersion} → v${target}` : `Install required: → v${target}`);
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         // `@gjsify/cli` ships two runtimes from one package: the Node `bin`
         // (`lib/index.js`, which imports its deps from `node_modules`) and the
@@ -141,8 +138,7 @@ export const selfUpdateCommand = {
             const msg = err instanceof Error ? err.message : String(err);
             console.error(`self-update: install failed — ${msg}`);
             console.error(`Re-run \`gjsify self-update\` to retry.`);
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         // Lay down (or repair) the GJS-native engine bridges in lockstep with
         // the bundle — same set + best-effort handling as the global installer.