@gjsify/cli 0.30.0 → 0.31.0

package/lib/actions/build.d.ts

@@ -48,6 +48,20 @@ export declare class BuildAction {
      * there is no in-bundle plugin, so this hook is the sole injection point.
      */
     private applyShebang;
+    /**
+     * Post-bundle rewrite for `--app gjs`: replace raw U+0000 bytes with `\x00`.
+     *
+     * GJS hands module source to SpiderMonkey as a NUL-terminated C string, so one raw NUL
+     * truncates the file and the loader reports whatever construct was open — typically
+     * "`` literal not terminated before end of script", which names neither the NUL nor its
+     * location. The minifier produces them by inlining a `'\u0000'` constant into a template
+     * literal, so a bundle can build and run unminified and fail under the default `--minify`.
+     *
+     * Rewrites the files on disk rather than the in-memory chunks: rolldown has already
+     * written them by this point, and the same treatment has to reach every chunk of an
+     * `--outdir` build, not just a single `--outfile`.
+     */
+    private escapeRawNul;
     /**
      * Post-bundle gate for `--app gjs`: throw when the emitted bundle still
      * STATICALLY imports Node builtins, which stock GJS cannot resolve (see

package/lib/actions/build.js

@@ -6,11 +6,12 @@ import { resolveGlobalsList, writeRegisterInjectFile, detectAutoGlobals, detectN
 import { pnpPlugin } from '@gjsify/rolldown-plugin-pnp';
 import { dirname, extname, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { chmod, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { chmod, mkdir, readdir, 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';
+import { escapeRawNulForGjs } from '../utils/gjs-source-escape.js';
 import { assertNodeBundleGlobalsShimmed } from '../utils/node-bundle-guard.js';
 const DEFAULT_GJS_SHEBANG = '#!/usr/bin/env -S gjs -m';
 /**
@@ -277,6 +278,68 @@ export class BuildAction {
         if (verbose)
             console.debug(`[gjsify] --shebang: wrote ${line} + chmod 0o755 to ${outfile}`);
     }
+    /**
+     * Post-bundle rewrite for `--app gjs`: replace raw U+0000 bytes with `\x00`.
+     *
+     * GJS hands module source to SpiderMonkey as a NUL-terminated C string, so one raw NUL
+     * truncates the file and the loader reports whatever construct was open — typically
+     * "`` literal not terminated before end of script", which names neither the NUL nor its
+     * location. The minifier produces them by inlining a `'\u0000'` constant into a template
+     * literal, so a bundle can build and run unminified and fail under the default `--minify`.
+     *
+     * Rewrites the files on disk rather than the in-memory chunks: rolldown has already
+     * written them by this point, and the same treatment has to reach every chunk of an
+     * `--outdir` build, not just a single `--outfile`.
+     */
+    async escapeRawNul(outfile, outdir, verbose) {
+        // Deliberately NOT driven by the chunk graph: `--watch`'s BUNDLE_END carries the bundle
+        // rather than the generated output, and re-running generate() just to list chunks would
+        // double every rebuild. Reading the directory needs neither, so the same hook serves the
+        // one-shot build and the watch loop — and a watch rebuild that quietly reintroduced the
+        // raw NUL would fail exactly like the bug this exists to prevent, only intermittently.
+        const targets = [];
+        if (outfile) {
+            targets.push(outfile);
+        }
+        else if (outdir) {
+            try {
+                for (const name of await readdir(outdir)) {
+                    if (name.endsWith('.mjs') || name.endsWith('.js'))
+                        targets.push(resolve(outdir, name));
+                }
+            }
+            catch (err) {
+                // ENOENT alone is benign — a watch pass that failed before writing anything has
+                // no outdir yet, and there is nothing to escape. Anything ELSE (a permissions
+                // error, an I/O error, a wrong outdir) would silently skip the escape and let
+                // the build report success while emitting a bundle GJS cannot load, which is
+                // precisely the failure this hook exists to prevent.
+                if (err?.code === 'ENOENT')
+                    return;
+                throw err;
+            }
+        }
+        for (const target of targets) {
+            let original;
+            try {
+                original = await readFile(target, 'utf-8');
+            }
+            catch (err) {
+                // Same split: a listed-but-unwritten chunk is not this hook's problem; a real
+                // read failure must not pass for "nothing to do".
+                if (err?.code === 'ENOENT')
+                    continue;
+                throw err;
+            }
+            const { code, replaced } = escapeRawNulForGjs(original);
+            if (replaced === 0)
+                continue; // the overwhelmingly common case — touch nothing
+            await writeFile(target, code);
+            if (verbose) {
+                console.debug(`[gjsify] escaped ${replaced} raw NUL byte(s) in ${target} so GJS can load it`);
+            }
+        }
+    }
     /**
      * Post-bundle gate for `--app gjs`: throw when the emitted bundle still
      * STATICALLY imports Node builtins, which stock GJS cannot resolve (see
@@ -624,10 +687,16 @@ export class BuildAction {
             plugins: [...pnpPlugins, ...userPlugins, ...cfg.plugins],
         };
         if (opts.watch) {
-            await this.runWatchLoop(finalOpts, app, outfile, verbose);
+            await this.runWatchLoop(finalOpts, app, outfile, outdir, verbose);
             return [];
         }
         const writeResult = await runBundle(finalOpts);
+        // GJS truncates module source at a raw U+0000 (it is handed to SpiderMonkey as a
+        // NUL-terminated C string), so escape any the minifier emitted before anything else
+        // touches the file. See utils/gjs-source-escape.ts.
+        if (app === 'gjs') {
+            await this.escapeRawNul(outfile, outdir, verbose);
+        }
         if ((app === 'gjs' || app === 'node') && this.configData.shebang) {
             await this.applyShebang(app, outfile, verbose);
         }
@@ -657,7 +726,7 @@ export class BuildAction {
      * without exiting, clean up on SIGINT/SIGTERM. Resolves only when the
      * watcher closes — keeps the CLI process alive across rebuilds.
      */
-    async runWatchLoop(finalOpts, app, outfile, verbose) {
+    async runWatchLoop(finalOpts, app, outfile, outdir, verbose) {
         const watcher = await runWatch(finalOpts);
         const closed = new Promise((resolve) => {
             watcher.on('close', () => resolve());
@@ -689,6 +758,12 @@ export class BuildAction {
                 case 'BUNDLE_END':
                     console.log(`[gjsify build --watch] built in ${event.duration}ms`);
                     try {
+                        // Before the shebang, which re-reads the file: a rebuild that dropped a
+                        // raw NUL back in would produce a bundle GJS cannot load, and on the
+                        // watch loop that reads as "it broke when I saved", not as a build bug.
+                        if (app === 'gjs') {
+                            await this.escapeRawNul(outfile, outdir, verbose);
+                        }
                         if ((app === 'gjs' || app === 'node') && this.configData.shebang) {
                             await this.applyShebang(app, outfile, verbose);
                         }

package/lib/actions/index.d.ts

@@ -0,0 +1,2 @@
+export * from './build.js';
+export * from './barrels-generate.js';

package/lib/actions/index.js

@@ -0,0 +1,2 @@
+export * from './build.js';
+export * from './barrels-generate.js';

package/lib/affected-entry.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/affected-entry.js

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: MIT
+// Standalone entry for the affected classifier — bundled to
+// `dist/affected.gjs.mjs` and run by CI's `changes` job (`gjs -m …`) on a plain
+// ubuntu-latest host that only `apt install`s gjs.
+//
+// CRITICAL — ZERO gi:// TYPELIB DEPENDENCIES (beyond GLib/Gio, which ship with
+// gjs): this entry imports ONLY the `affected` command (→ `@gjsify/workspace`
+// + `@gjsify/fs`/`@gjsify/child_process` for the git diff). It MUST NOT import
+// the full CLI, whose network commands (login/publish/trust/whoami/self-update/
+// upgrade) pull `@gjsify/npm-registry` → `@gjsify/fetch` → `gi://Soup?version=3.0`.
+// The classifier host has no Soup typelib, so a bundle that eagerly requires
+// Soup throws at module load → the classifier crashes → main.yml fails open to
+// a full run on every PR (the regression this entry fixes). Keep the import
+// graph below Soup-free; `tests/e2e/affected-classifier-bundle` guards it.
+import { affectedCommand } from './commands/affected.js';
+function parseArgs(argv) {
+    const args = { head: 'HEAD', format: 'text', 'changed-from-stdin': false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--changed-from-stdin')
+            args['changed-from-stdin'] = true;
+        else if (a === '--base')
+            args.base = argv[++i];
+        else if (a === '--head')
+            args.head = argv[++i] ?? 'HEAD';
+        else if (a === '--cwd')
+            args.cwd = argv[++i];
+        else if (a.startsWith('--base='))
+            args.base = a.slice('--base='.length);
+        else if (a.startsWith('--head='))
+            args.head = a.slice('--head='.length);
+        else if (a.startsWith('--cwd='))
+            args.cwd = a.slice('--cwd='.length);
+        else if (a.startsWith('--format='))
+            args.format = a.slice('--format='.length);
+        else if (a === '--format')
+            args.format = argv[++i] ?? 'text';
+    }
+    return args;
+}
+const argv = process.argv.slice(2);
+// Tolerate an optional leading `affected` token so the bundle can be invoked
+// either as `gjs -m affected.gjs.mjs --base …` or `… affected --base …`.
+const rest = argv[0] === 'affected' ? argv.slice(1) : argv;
+// The cast is only about the ARGUMENT shape: `parseArgs` returns the flags this
+// entry accepts, while the handler wants yargs' `ArgumentsCamelCase` wrapper
+// around them. It is no longer also papering over a possibly-undefined handler —
+// `affectedCommand` is a `LeafCommand`, so its handler is required by type.
+await affectedCommand.handler(parseArgs(rest));

package/lib/bundler-pick.js

@@ -32,6 +32,12 @@ import * as path from 'node:path';
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
 import { resolveNpmPackage } from './utils/resolve-npm-package.js';
+// Static, not dynamic: `diagnoseNativeEngine()` is synchronous and is called
+// inside a `throw` expression. Safe — check-system-deps imports only `node:`
+// builtins, so there is no cycle, and every one of them is already in the GJS
+// bundle via `commands/install.ts`.
+import { buildInstallCommand, detectPackageManager, missingSystemDepsFor } from './utils/check-system-deps.js';
+import { activateNativePrebuilds } from './utils/gi-search-path.js';
 import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
 // npm `rolldown` is a Rust crate with platform-specific prebuilds; loading
 // it eagerly at module init pulls musl-detection code that does
@@ -63,17 +69,24 @@ async function loadNpmRolldown() {
  * 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 causes need 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. ADR 0021 then removed the bypassed
+ * launcher as a CAUSE outright, so it is no longer among the candidates at all.
  *
- * The probe is `existsSync`-only (no import, no resolution) so it cannot itself
- * throw or recurse into the failure being explained.
+ * NOTHING here may throw or recurse into the failure being explained. Branches 1
+ * and 2 are `existsSync`-only (no import, no resolution). Branch 3 additionally
+ * asks `missingSystemDepsFor()` and reads the memoized `activateNativePrebuilds()`
+ * result — both safe by construction rather than by a catch: the former routes
+ * every probe through `tryExecFile`, which returns null on any failure, and the
+ * latter is an array the failing load attempt already computed. Keep that
+ * property when editing: a probe that dies here replaces the diagnosis with its
+ * own stack.
  */
 function diagnoseNativeEngine() {
     let pkgDir = null;
@@ -109,15 +122,60 @@ function diagnoseNativeEngine() {
             'that is closed, seed `lib/` from the published package — which ships it — or from a host that has ' +
             'Node. Tracked in `status/open-todos.md` ("A Node-less host cannot bootstrap a fresh CLONE").');
     }
-    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.');
+    // Branch 3: installed AND built, so the typelib/prebuild LOOKUP failed.
+    //
+    // This branch used to assert "Most likely the CLI bundle was invoked
+    // DIRECTLY … bypasses the launcher" — repeating, one branch later, the exact
+    // mistake this function's docblock records fixing in branch 2: naming the
+    // rarest cause as the most likely one. After #994 measured `ldd` over every
+    // committed linux-x64 prebuild on a consumer-baseline host, a missing
+    // `libjson-glib-1.0.so.0` is at least as common, and it is what ts-for-gir#437
+    // actually hit — with this message on screen.
+    //
+    // So both candidates are now MEASURED, cheaply and without any call that can
+    // throw while explaining a failure, and the measured one is printed first.
+    //
+    // ADR 0021 RETIRED THE THIRD CANDIDATE. "The launcher was bypassed, export
+    // these two variables yourself" is no longer a cause of failure at all:
+    // `tryLoadNative()` calls `activateNativePrebuilds()` before the engine is
+    // loaded, which puts every detected prebuild dir on girepository's typelib
+    // AND library search paths in-process. Do not reintroduce it — besides now
+    // being false, the path it printed (`<facade>/prebuilds/<target>`) had been
+    // wrong since ADR 0017 moved every artifact into a per-target SIBLING
+    // package, so it told readers to export a directory that does not exist.
+    const parts = ['The JS facade is built, so this is the typelib/prebuild lookup failing.'];
+    // (1) A declared system library that is not on this host. `missingSystemDepsFor`
+    // reads the same tables `gjsify system-check` does, so the answer cannot drift
+    // from the declaration.
+    const missing = missingSystemDepsFor('@gjsify/rolldown-native');
+    if (missing.length > 0) {
+        const names = missing.map((d) => d.name).join(', ');
+        parts.push(`\nMEASURED CAUSE — a system library the engine's prebuild loads is MISSING: ${names}.\n` +
+            'The prebuild is present but its typelib cannot open its backing library, which GJS reports as ' +
+            '`Unsupported type void, deriving from fundamental void` — a message that names nothing. ' +
+            'This is a system package, not an npm one.');
+        const cmd = buildInstallCommand(detectPackageManager(), missing);
+        if (cmd)
+            parts.push(`Install it:\n  ${cmd}`);
+        else
+            parts.push(`Install ${names} with your system package manager (this host's manager was not recognised, so no command is suggested rather than a wrong one).`);
+    }
+    // (2) The remaining cause, last because it is the least actionable: no
+    // prebuild for this architecture. Read off the set `activateNativePrebuilds()`
+    // ACTUALLY put on the search paths — memoized, so this is a cached-array read
+    // that cannot throw, and unlike the old hand-composed path it names the
+    // per-target sibling package that really holds the artifact.
+    if (missing.length === 0) {
+        const engine = activateNativePrebuilds().find((p) => p.name.startsWith('@gjsify/rolldown-native'));
+        parts.push(engine
+            ? `\nEvery declared system library resolves and ${engine.name}'s prebuild (${engine.prebuildsDir}) IS on ` +
+                "girepository's search paths, so it is present but did not load."
+            : `\nEvery declared system library resolves, so most likely no prebuild exists for ` +
+                `${process.platform}/${process.arch} — no @gjsify/rolldown-native prebuild directory was found ` +
+                `walking up from ${process.cwd()}.`);
+    }
+    parts.push('\nRunning the build under Node also works — there the npm `rolldown` crate is used instead.');
+    return parts.join('\n');
 }
 /**
  * Convert a bare npm specifier into something dynamic `import(...)` can
@@ -296,6 +354,13 @@ async function tryLoadNative() {
         if (!isGjs())
             return null;
         try {
+            // Make the engine's prebuild resolvable to THIS process before the
+            // import that needs it. Without this the engine loads only when the
+            // `gjsify` launcher exported GI_TYPELIB_PATH + the library-path var
+            // before exec, so a direct `gjs -m …/dist/cli.gjs.mjs build …` — what
+            // several e2e suites do — died with "no usable bundler engine under
+            // GJS" on a tree where the engine was installed and loadable. ADR 0021.
+            activateNativePrebuilds();
             // Under GJS the ESM loader has no node_modules resolver — a bare
             // `import('@gjsify/rolldown-native')` would throw `Module not
             // found`. Resolve via createRequire (PnP+node_modules-aware) to

package/lib/cli-app.js

@@ -19,6 +19,7 @@ import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import yargs from 'yargs';
+import { classifyCliFailure } from './cli-fail.js';
 import { buildCommand as build, clearCommand as clear, copyCommand as copy, 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, trustCommand as trust, onboardCommand as onboard, 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, storybookCommand as storybook, debugCommand as debug, browseCommand as browse, } from './commands/index.js';
 import { APP_NAME } from './constants.js';
 import { isBun, isDeno, isNode, gjsSystemVersion } from '@gjsify/rolldown-plugin-gjsify/runtime';
@@ -84,6 +85,25 @@ export async function runCli(argv) {
         .scriptName(APP_NAME)
         .version(readBundleVersion())
         .strict()
+        // Sits beside `.strict()` because that is what produces most of what it
+        // classifies. See `cli-fail.ts` for the four yargs measurements this
+        // depends on; the short version: `msg` is the discriminator (a handler
+        // rejection is the ONE call site that passes null), registering a handler
+        // removes yargs' own showHelp+exit, and the incoming error must never be
+        // re-thrown as-is because yargs routes `YError` back into `fail()`.
+        .fail((msg, err) => {
+        const failure = classifyCliFailure(msg, err);
+        if (failure.kind === 'usage') {
+            cli.showHelp('error');
+            // Plain Error, not `err`: re-throwing a YError re-enters fail()
+            // and prints the help twice. `index.ts` prints this message.
+            throw new Error(failure.message, { cause: err });
+        }
+        // A handler threw. Return WITHOUT printing or exiting — that is the
+        // entire fix. The rejection propagates out of `parseAsync()` and
+        // `index.ts`'s catch is the one printer (message, optional
+        // GJSIFY_DEBUG stack, `process.exitCode = 1`, `gjsExit(1)`).
+    })
         // 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)

package/lib/cli-fail.d.ts

@@ -0,0 +1,22 @@
+/** What kind of failure yargs is reporting, and the message when it has one. */
+export type CliFailure = 
+/** A usage/validation/parse error: the caller's argv was wrong, so help helps. */
+{
+    kind: 'usage';
+    message: string;
+}
+/** A command handler threw or rejected: help is noise, `index.ts` prints it. */
+ | {
+    kind: 'runtime';
+};
+/**
+ * Classify a yargs `fail(msg, err)` callback into the two cases that need
+ * different output.
+ *
+ * Pure on purpose — the whole point is that the rule is testable without
+ * driving a process to its death. `cli-fail.spec.ts` additionally pins the
+ * yargs-side half (which call site passes `null`) against a real instance, so a
+ * yargs upgrade that changes the routing fails a test instead of silently
+ * turning every runtime error back into a help dump.
+ */
+export declare function classifyCliFailure(msg: string | null | undefined, _err: unknown): CliFailure;

package/lib/cli-fail.js

@@ -0,0 +1,67 @@
+// How the CLI ends when something goes wrong — the one place that decides
+// whether a failure is a USAGE error (help is the right output) or a RUNTIME
+// error (help is noise that buries the answer).
+//
+// The defect this exists for, measured from outside the repo: `gjsify build`
+// under GJS without `@gjsify/rolldown-native` prints a CORRECT and actionable
+// diagnosis — `diagnoseNativeEngine()` names the package and the exact install
+// command — and then yargs prints ~60 lines of `gjsify build` help on top of it
+// and exits 1. In a CI log the actionable line scrolls out of view and the
+// visible artifact is a help dump, which reads as "bad arguments". That is what
+// ts-for-gir's `test-e2e` leg looked like (#1005). A missing engine is not a
+// usage error and must not leave through the usage path.
+//
+// Four things about yargs make this module's shape non-obvious. All four were
+// measured against the pinned `yargs@18.0.0` (note `@types/yargs` is still 17,
+// one major behind, so the types lie in one place — see below):
+//
+//  1. `.fail()` IS reached for an async handler rejection. `command.js:253-260`
+//     does `if (isPromise(innerArgv) && !hasParseCallback()) innerArgv.catch(e =>
+//     usage.fail(null, e))`, and `hasParseCallback()` is false because
+//     `cli-app.ts` calls `parseAsync()` with no function argument. So no
+//     try/catch around `parseAsync` is needed to see handler errors here.
+//
+//  2. THE DISCRIMINATOR IS `msg`, NOT `err`. Every usage/validation/parse
+//     failure passes a STRING: all ten `validation.js` sites call
+//     `usage.fail(msg)`, `command.js:370` calls `fail(parsed.error.message,
+//     parsed.error)`, and `yargs-factory.js:188/192/1473` call `fail(msg, err)`.
+//     Only `command.js:257` — the handler rejection — passes `null`. Branching on
+//     `err` instead would suppress help for genuine parser errors, which is
+//     exactly backwards.
+//
+//  3. REGISTERING A HANDLER REMOVES YARGS' OWN EXIT. With no `.fail()` yargs does
+//     `showHelp('error')` + `logger.error(msg || err)` + `exit(1)` itself
+//     (`usage.js:27-70`). With one, it does none of that — so the usage branch has
+//     to terminate on its own. `showHelp()` happens to set `hasOutput`
+//     (`yargs-factory.js:834`), which blocks the handler while the chain is still
+//     synchronous, but that is a side effect, not a guarantee: `throw` is what
+//     survives a future async builder or middleware.
+//
+//  4. NEVER RE-THROW THE INCOMING `YError`. `yargs-factory.js:1471-1475` routes
+//     that class back into `usage.fail()`, so re-throwing it prints the help a
+//     second time. The usage branch throws a plain `Error` with the original
+//     attached as `cause`.
+//
+// The runtime branch deliberately prints NOTHING and exits NOTHING: the rejection
+// propagates out of `parseAsync()` on its own, and `index.ts` is the single
+// printer (it also handles `GJSIFY_DEBUG` stacks and the GJS-side `gjsExit(1)`,
+// which a second printer here would duplicate). Suppressing yargs'
+// help-and-exit IS this branch's whole job — it only looks like a no-op.
+/**
+ * Classify a yargs `fail(msg, err)` callback into the two cases that need
+ * different output.
+ *
+ * Pure on purpose — the whole point is that the rule is testable without
+ * driving a process to its death. `cli-fail.spec.ts` additionally pins the
+ * yargs-side half (which call site passes `null`) against a real instance, so a
+ * yargs upgrade that changes the routing fails a test instead of silently
+ * turning every runtime error back into a help dump.
+ */
+export function classifyCliFailure(msg, _err) {
+    // A non-empty string means yargs itself diagnosed the argv. An empty string
+    // is treated as "no message" rather than as an empty usage error: it carries
+    // nothing to print, and printing help with no reason is the worst of both.
+    if (typeof msg === 'string' && msg.length > 0)
+        return { kind: 'usage', message: msg };
+    return { kind: 'runtime' };
+}

package/lib/commands/affected.d.ts

@@ -1,4 +1,4 @@
-import type { Command } from '../types/index.js';
+import type { LeafCommand } from '../types/index.js';
 interface AffectedOptions {
     base?: string;
     head?: string;
@@ -6,5 +6,5 @@ interface AffectedOptions {
     'changed-from-stdin': boolean;
     cwd?: string;
 }
-export declare const affectedCommand: Command<unknown, AffectedOptions>;
+export declare const affectedCommand: LeafCommand<unknown, AffectedOptions>;
 export {};

package/lib/commands/affected.js

@@ -223,6 +223,22 @@ const OTHER_WORKFLOW_INPUTS = [
     // other. Only the `scripts/`-side repo-scoped half is ignored, and that
     // half is precisely the half `main.yml` does not load.
     /^scripts\/manifest-conformance\//,
+    // The authored status data (ADR 0016) and the generator that renders it.
+    // Same two halves as the entry above, and both hold: `main.yml` reads
+    // NEITHER — it never runs `npm run status:generate` and never opens
+    // `status/`, which the grep for it confirms (the only hits are comments
+    // citing `open-todos.md` as a ledger) — while `audit-runtimes.yml` runs the
+    // `status-data` rule over exactly this data on EVERY pull_request with no
+    // `paths:` filter.
+    //
+    // WHAT IT COSTS TODAY: `status/*.md` already fell into `IGNORE` through the
+    // generic `/\.md$/i`, so the drift was invisible for the prose files and
+    // showed up only on `status/status.json` — which matched nothing, landed in
+    // `unmatched`, and forced a FULL CI run for a file `main.yml` cannot read.
+    // Editing one package's status prose paid for the whole matrix. Naming the
+    // directory makes the `.md` case intentional rather than incidental.
+    /^status\//,
+    /^scripts\/generate-status\.mjs$/,
 ];
 /** Patterns that contribute no seed and don't force a full run. */
 const IGNORE = [

package/lib/commands/install.d.ts

@@ -61,4 +61,59 @@ export declare function buildWorkspaceBinShimsForWindows(wsLocation: string, nod
     cmd: string;
     ps1: string;
 };
+/**
+ * Lay the GJS bundler engine down after a PROJECT install, when the host will
+ * need it and does not have it. Closes #1005.
+ *
+ * The engine is an OPTIONAL PEER of `@gjsify/cli`, deliberately: a plain
+ * `npm install @gjsify/cli` on Node/macOS/Windows must not fetch Linux
+ * prebuilds. But nobody resolves it for a project — npm 7+ skips optional peers,
+ * and the native backend does not resolve peerDependencies at all
+ * (`install-backend-native.ts:76`). Under GJS there is no npm `rolldown`
+ * fallback, so `gjsify build` simply cannot work. Every consumer in the
+ * workspace independently discovered this and hand-declared the engine.
+ *
+ * Four conditions, and the second is the one worth reading:
+ *
+ *   (a) `@gjsify/cli` is in this tree — otherwise the engine has no caller.
+ *   (b) THE HOST CAN RUN GJS, which is NOT the same question as `isGjs()`.
+ *       `isGjs()` asks which runtime is executing the installer; the launcher
+ *       (`bin-shim.ts:616`) prefers the GJS bundle whenever `command -v gjs`
+ *       succeeds, so a tree installed BY NODE is routinely built BY GJS. Gating
+ *       on the interpreter would reproduce #1005 for every contributor who
+ *       installs on Node and builds through the shim. `runMinimalChecks()` above
+ *       already probed for gjs, so this costs no extra spawn — and it goes
+ *       nowhere near `which`.
+ *   (c) No engine is already reachable — asked with the same walk the BUILD uses.
+ *   (d) Not `--immutable`. A frozen install cannot acquire something its
+ *       lockfile does not name without breaking the contract `--immutable`
+ *       exists to hold, so that case warns and installs nothing.
+ *
+ * Deliberately NOT gated on `gjsify.app` or on "declares a build script":
+ * neither of the failing consumers declares the former, and the latter would
+ * mean pattern-matching script bodies — the hand-maintained judgement that
+ * drifts, which ADR 0017 rejects by name.
+ *
+ * NOT recorded in the lockfile. `installPackages` writes one only under
+ * `if (resolved && opts.lockfile)` and the default is falsy, so a consumer's
+ * `gjsify-lock.json` is never rewritten by this. An e2e row pins that.
+ *
+ * Ordering is not a constraint here, unlike the global path (which must precede
+ * `linkGlobalBins`): `buildNativeEnvPreamble` scans the prefix at LAUNCH time
+ * (`bin-shim.ts:432-444`), so a shim written before the engine arrives still
+ * exports its dir. `tests/e2e/global-install-engine/run.mjs:361-374` asserts
+ * exactly that case.
+ */
+export interface EnsureProjectGjsEngineDeps {
+    /** Project root. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** Injected so the decision is testable without a registry — the shape
+     *  `installGjsEnginePackages` already uses for the same reason. */
+    installFn?: (prefix: string, version: string, opts: {
+        verbose?: boolean;
+    }) => Promise<void>;
+    /** Injected so a host that HAS an engine can still exercise the missing branch. */
+    hasEngineFn?: (dir: string) => boolean;
+}
+export declare function ensureProjectGjsEngine(args: InstallOptions, gjsFound: boolean, deps?: EnsureProjectGjsEngineDeps): Promise<void>;
 export {};