@gjsify/cli 0.23.0 → 0.24.1

package/lib/actions/build.d.ts

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

package/lib/actions/build.js

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

package/lib/bundler-pick.js

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

package/lib/commands/affected.js

@@ -45,6 +45,38 @@
 //   --format=globs                        one `@gjsify/<name>` per line
 //   --format=github-actions                $GITHUB_OUTPUT key=value lines
 //
+// `include-args` CONTRACT (github-actions format) — read this before changing
+// its shape. The value is a SPACE-SEPARATED list of ALREADY-SHELL-SAFE tokens:
+//
+//     include-args=--include @gjsify/fs --include @gjsify/stream
+//
+// and its only supported consumption is an UNQUOTED `$INCLUDE_ARGS` expansion
+// in a POSIX shell, where word splitting is exactly the intent. It carries NO
+// quoting of its own, deliberately:
+//
+//   * `main.yml` splices it into a `su testuser -c "… sh -c '…'"` nesting, and
+//     the result of a parameter expansion is NEVER re-scanned for quotes. When
+//     this emitted `--include '@gjsify/fs'`, the apostrophes became part of the
+//     glob, every pattern matched zero workspaces, and `foreach` exited 0 —
+//     CI "built" nothing on every selective PR run in 0.65 s (repo task #75).
+//     Pre-quoting a value for an unknown number of nesting levels cannot work;
+//     emitting tokens that need no quoting at any level can.
+//   * There are FIVE consumers of this one output — the build / browser-bundle
+//     / check / test steps splice it into a command line, and thirteen
+//     `contains(needs.changes.outputs.include-args, '@gjsify/…')` GitHub
+//     expressions substring-match it. A format that requires per-consumer
+//     unquoting would have to be repeated five times in the very nesting that
+//     produced the bug; `contains()` is unaffected either way (it matched the
+//     quoted spelling too, which is why the gates kept working while the build
+//     silently did nothing).
+//
+// Shell-safety is ENFORCED, not assumed: `assertShellSafeWorkspaceName` rejects
+// any workspace name outside `[A-Za-z0-9@._/-]` before it is emitted. npm names
+// cannot contain those characters, so this never fires in practice — and if it
+// somehow does, the command exits non-zero, the classify step's
+// `continue-on-error` leaves the outputs unset, and CI falls back to a FULL
+// run. Failing towards "run everything" is the safe direction.
+//
 // `--changed-from-stdin` skips `git diff` entirely and reads a newline-
 // separated list of paths from stdin. Useful for local debugging and
 // for the spec suite. Stdin is slurped via `utils/stdin.ts`, NOT
@@ -52,6 +84,15 @@
 // idiom opens the relative file `./0` and the committed GJS classifier
 // bundle died with `ENOENT … read '0'` on every `--changed-from-stdin` run.
 import { spawnSync } from 'node:child_process';
+// STATIC import, never a lazy `require('node:fs')`. This package is ESM
+// (`"type": "module"`), so a bare `require` is a ReferenceError the moment the
+// line executes — and the only line that executes it sits behind
+// `if (process.env.GITHUB_OUTPUT)`, i.e. exclusively inside a GitHub Actions
+// step. That is why it survived from the command's first commit: every local
+// run and every spec took the stdout branch. There is no reason for laziness
+// here — the command already statically imports `node:child_process`, and the
+// classifier bundle resolves `node:fs` through `@gjsify/fs` like any other.
+import { appendFileSync } from 'node:fs';
 import { readStdinLines } from '../utils/stdin.js';
 import { discoverWorkspaces, buildDependencyGraph, buildReverseDependencyGraph, affectedClosure, workspacesForChangedFiles, } from '@gjsify/workspace';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
@@ -318,9 +359,11 @@ function emit(format, r) {
         return;
     }
     if (format === 'github-actions') {
+        // Unquoted, space-separated tokens — see the `include-args` CONTRACT
+        // block at the top of this file. Do NOT re-add quoting here.
         const includeArgs = r.global
             ? ''
-            : r.workspaces.map((n) => `--include '${escSingleQuote(n)}'`).join(' ');
+            : r.workspaces.map((n) => `--include ${assertShellSafeWorkspaceName(n)}`).join(' ');
         const out = process.env.GITHUB_OUTPUT;
         const lines = [
             `skip-all=${r.skipAll}`,
@@ -332,7 +375,6 @@ function emit(format, r) {
         ];
         if (out) {
             // GitHub Actions: append to $GITHUB_OUTPUT.
-            const { appendFileSync } = require('node:fs');
             for (const l of lines)
                 appendFileSync(out, `${l}\n`);
         }
@@ -353,6 +395,22 @@ function emit(format, r) {
     for (const name of r.workspaces)
         process.stdout.write(`    - ${name}\n`);
 }
-function escSingleQuote(s) {
-    return s.replace(/'/g, `'\\''`);
+// A workspace name that survives an UNQUOTED shell expansion unchanged: no
+// whitespace, no quote/escape characters, no glob metacharacters, no `$`, and
+// nothing the shell would treat as an operator. npm package names are a strict
+// subset of this, so the guard is a machine-checked restatement of the
+// `include-args` contract rather than a real runtime branch. Returns the name
+// so it can be used inline at the emit site.
+const SHELL_SAFE_WORKSPACE_NAME = /^[A-Za-z0-9@][A-Za-z0-9@._/-]*$/;
+function assertShellSafeWorkspaceName(name) {
+    if (SHELL_SAFE_WORKSPACE_NAME.test(name))
+        return name;
+    process.stderr.write(`gjsify affected: workspace name ${JSON.stringify(name)} is not shell-safe, so it cannot be emitted as an\n` +
+        `  \`include-args\` token (the value is consumed by an UNQUOTED $INCLUDE_ARGS expansion — see the\n` +
+        `  contract at the top of commands/affected.ts). Rename the workspace, or teach this command a\n` +
+        `  transport the consumers can unquote. Refusing to emit a filter that would silently mis-match.\n`);
+    process.exit(2);
+    // Unreachable — `process.exit` terminates. Present so this function has no
+    // fall-through path that could ever return an unsafe name.
+    throw new Error(`gjsify affected: unsafe workspace name ${name}`);
 }

package/lib/commands/foreach.js

@@ -208,7 +208,7 @@ export const foreachCommand = {
         default: false,
     })
         .option('include', {
-        description: 'Glob pattern to include workspaces by name (repeatable).',
+        description: 'Glob pattern to include workspaces by name (repeatable). A pattern that matches NO discovered workspace is a hard error — a filter selecting nothing is a typo or a caller-side quoting bug, never an intent.',
         type: 'string',
         array: true,
     })
@@ -295,6 +295,7 @@ export const foreachCommand = {
                 process.exit(1);
             }
         }
+        assertEveryIncludeMatches(allWorkspaces, args.include);
         let selected = filterWorkspaces(allWorkspaces, {
             include: args.include,
             exclude: args.exclude,
@@ -344,6 +345,12 @@ export const foreachCommand = {
             }
         }
         if (selected.length === 0) {
+            // Reaching here means every --include pattern DID match something
+            // (assertEveryIncludeMatches above is fatal otherwise) and the set
+            // was then narrowed to nothing by --exclude, --no-private, the
+            // script-presence filter, or --shard. All four are legitimate, so
+            // this stays a clean exit-0 no-op — see the assert's doc comment
+            // for why the two cases are not the same condition.
             console.log(`gjsify foreach: no workspaces match (${exec ? 'exec' : 'script'}="${cmd}", include=${JSON.stringify(args.include ?? [])}, exclude=${JSON.stringify(args.exclude ?? [])})`);
             return;
         }
@@ -410,6 +417,69 @@ export const foreachCommand = {
         process.exit(0);
     },
 };
+/**
+ * A `--include` pattern that matches ZERO of the discovered workspaces is a
+ * hard error. This is the load-bearing half of the fix for repo task #75: the
+ * CI classifier emitted its filter pre-quoted (`--include '@gjsify/fs'`), the
+ * workflow expanded it unquoted inside a `su … -c "… sh -c '…'"` nesting, the
+ * apostrophes became part of every glob, and this command matched nothing,
+ * printed one line, and exited 0. A build that did nothing was indistinguishable
+ * from a build that succeeded, so the bug lived through every selective PR run
+ * — the Build step took 0.65 s and every later step inspected whatever the
+ * cache had restored. The quoting was the defect; the SILENCE is why nobody saw
+ * it.
+ *
+ * Scope is deliberately "an include PATTERN matched no workspace", NOT "the
+ * final selection is empty". The final selection is legitimately empty in
+ * several supported situations and must stay exit-0:
+ *   * `--shard 3/4` over a 2-workspace closure — most shards run nothing;
+ *   * `--exclude '@gjsify/integration-*'` removing everything the include kept;
+ *   * script mode dropping workspaces that don't declare `<script>` (yarn does
+ *     this too, and it is why `foreach check` over a closure of script-less
+ *     packages is a no-op rather than a failure).
+ * All three describe a real, existing set being narrowed to nothing. A pattern
+ * that names something the workspace tree does not contain is different in
+ * kind: it is a typo, a stale package name, or a caller-side quoting bug, and
+ * it can never be what the caller meant. There is no opt-out flag — an escape
+ * hatch here would be re-arming exactly the silence this exists to remove.
+ */
+function assertEveryIncludeMatches(allWorkspaces, include) {
+    if (!include || include.length === 0)
+        return;
+    const unmatched = include.filter((pattern) => filterWorkspaces(allWorkspaces, { include: [pattern] }).length === 0);
+    if (unmatched.length === 0)
+        return;
+    const lines = [
+        `gjsify foreach: --include matched no workspace (${unmatched.length} of ${include.length} pattern(s)):`,
+    ];
+    for (const pattern of unmatched) {
+        lines.push(`  ${JSON.stringify(pattern)}`);
+        // The task-#75 signature: the pattern only fails because the caller's
+        // shell quotes ended up INSIDE the value. Name it outright — that
+        // failure reads as "package not found" and sends people hunting in the
+        // wrong place.
+        const unquoted = stripSurroundingQuotes(pattern);
+        if (unquoted !== pattern && filterWorkspaces(allWorkspaces, { include: [unquoted] }).length > 0) {
+            lines.push(`    → matches as ${JSON.stringify(unquoted)}: the QUOTES are part of the value. A shell expansion`, `      is not re-scanned for quoting, so a pre-quoted filter spliced through \`sh -c\` arrives with`, `      the quotes attached. Pass the bare name and let word splitting do the work.`);
+            continue;
+        }
+        const near = allWorkspaces
+            .map((w) => w.name)
+            .filter((name) => name.toLowerCase().includes(unquoted.replace(/\*/g, '').toLowerCase()))
+            .slice(0, 3);
+        if (near.length > 0)
+            lines.push(`    → did you mean: ${near.join(', ')}?`);
+    }
+    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'));
+    process.exit(1);
+}
+/** Drop ONE matching pair of surrounding `'` or `"` — the quoting-bug probe. */
+function stripSurroundingQuotes(s) {
+    if (s.length >= 2 && (s[0] === "'" || s[0] === '"') && s[s.length - 1] === s[0])
+        return s.slice(1, -1);
+    return s;
+}
 async function runSequential(workspaces, script, args, verbose, exec, cache) {
     for (const ws of workspaces) {
         await runOne(ws, script, args, /* prefixOutput */ false, verbose, exec, cache);

package/lib/commands/install.js

@@ -205,10 +205,26 @@ export const installCommand = {
         const hardExitTimerId = overallTimeoutMs > 0
             ? setTimeout(() => {
                 const secs = Math.round(overallTimeoutMs / 100) / 10;
-                console.error(`gjsify install: still stuck ${Math.round(HARD_EXIT_GRACE_MS / 1000)}s after the ${secs}s ` +
-                    `budget elapsed and the in-flight aborts — forcing exit. A dependency's extract or ` +
-                    `link step wedged (typically a dropped Gio stream event under GJS). Re-run; if it ` +
-                    `persists, raise --timeout or file an issue.`);
+                // Do NOT assert a cause here — this timer cannot tell the
+                // two shapes apart, and claiming the rarer one sends the
+                // next reader after a bug that isn't there. Measured on a
+                // cold tree of this workspace: 1597 packages / ~4.8 GB
+                // extracted, of which ~3.4 GB are foreign-platform
+                // optional deps (`os`/`cpu` excludes the host) that npm
+                // would never place. That install was still making steady
+                // progress when the 30-min budget elapsed, and a re-run
+                // finished the remainder in ~2 min. Extraction also has
+                // multi-second SYNCHRONOUS stretches (tar parse + file
+                // writes) and 16 run concurrently, so the clean abort path
+                // can easily miss the grace window with nothing wedged.
+                console.error(`gjsify install: the ${secs}s budget elapsed and the abort did not unwind within ` +
+                    `${Math.round(HARD_EXIT_GRACE_MS / 1000)}s — forcing exit. That means one of two ` +
+                    `things, and this timer cannot distinguish them: the install was still WORKING ` +
+                    `(a cold tree here extracts several GB, and extraction blocks the loop in ` +
+                    `multi-second synchronous stretches), or a step genuinely wedged. Re-running tells ` +
+                    `you which, and is safe: extraction is idempotent, every package already on disk ` +
+                    `is skipped, so a second run finishes the remainder in a fraction of the time. A ` +
+                    `re-run that makes NO further progress is a real wedge — file an issue.`);
                 forceExit(1);
             }, overallTimeoutMs + HARD_EXIT_GRACE_MS)
             : null;

package/lib/commands/showcase.js

@@ -7,8 +7,7 @@ import { ensurePkgDir } from './dlx.js';
 import { parseSpec } from '../utils/parse-spec.js';
 import { resolveNodeEntry } from '../utils/resolve-gjs-entry.js';
 import { runRuntimeBundle } from '../utils/run-node.js';
-import { hostRuntime } from '@gjsify/rolldown-plugin-gjsify/runtime';
-import { EXAMPLE_RUNTIMES, isExampleRuntime, readDeclaredRuntimes, checkRuntimeSupported, } from '../utils/runtimes.js';
+import { EXAMPLE_RUNTIMES, isExampleRuntime, readDeclaredRuntimes, checkRuntimeSupported, defaultExampleRuntime, } from '../utils/runtimes.js';
 function readCliVersion() {
     try {
         const pkgUrl = new URL('../../package.json', import.meta.url);
@@ -38,18 +37,23 @@ export const showcaseCommand = {
         default: false,
     })
         .option('runtime', {
-        // Runtime selector, mirroring `gjsify storybook --runtime`. The
-        // default FOLLOWS the host runtime the CLI executes in (gjs under
-        // gjs, node under node/bun/deno). gjs runs the showcase's GJS
-        // bundle via `gjsify dlx`; node/bun/deno run its `--app node`
-        // bundle on that runtime. Validated against the showcase's
-        // declared `gjsify.example.runtimes` — a GTK-only showcase
-        // requested under node fails with a clear message, not a crash.
+        // Runtime selector, mirroring `gjsify storybook --runtime`. gjs
+        // runs the showcase's GJS bundle via `gjsify dlx`; node/bun/deno
+        // run its `--app node` bundle on that runtime. Validated against
+        // the showcase's declared `gjsify.example.runtimes` — a GTK-only
+        // showcase requested under node fails with a clear message, not
+        // a crash.
+        //
+        // NO eager yargs `default:` — it is resolved in the handler via
+        // `defaultExampleRuntime()` (gjs when gjs is installed, else the
+        // host runtime). Two reasons: yargs evaluates a `default:` while
+        // BUILDING the command, before we know a showcase was even
+        // named, and resolving it probes PATH — work that must not
+        // happen for `gjsify showcase` in list mode.
         type: 'string',
         choices: EXAMPLE_RUNTIMES,
-        default: hostRuntime(),
-        defaultDescription: 'host runtime (gjs on gjs, else node/bun/deno)',
-        description: 'Runtime to run the showcase on: gjs | node | bun | deno (default: the host runtime). node/bun/deno run its `--app node` bundle.',
+        defaultDescription: 'gjs when gjs is installed, else the host runtime',
+        description: 'Runtime to run the showcase on: gjs | node | bun | deno (default: gjs when installed, else the host runtime). node/bun/deno run its `--app node` bundle.',
     }),
     handler: async (args) => {
         // List mode: no name given, or --list flag
@@ -116,7 +120,7 @@ export const showcaseCommand = {
             // `return` — bare `process.exit` falls through under GJS (see above).
             return process.exit(1);
         }
-        const runtime = (args.runtime ?? hostRuntime());
+        const runtime = (args.runtime ?? defaultExampleRuntime());
         if (!isExampleRuntime(runtime)) {
             console.error(`Unknown --runtime "${runtime}" (expected: ${EXAMPLE_RUNTIMES.join(', ')}).`);
             // `return` — bare `process.exit` falls through under GJS (see above).

package/lib/commands/storybook.js

@@ -181,9 +181,12 @@ export const storybookCommand = {
             // typelib env wired like `gjsify run`. All three need @gjsify/node-gi
             // (the storybook uses gi://), kept external by the bundler.
             const { computeNativeEnvForBundle } = await import('../utils/run-gjs.js');
-            const { resolveNodeGi, nodeBinary } = await import('../utils/run-node.js');
+            const { resolveNodeGiForBundle, nodeBinary } = await import('../utils/run-node.js');
             const { RUNTIMES } = await import('../utils/runtimes.js');
-            if (!resolveNodeGi(cwd)) {
+            // Same resolution base as `runRuntimeBundle`: the bundle's own dir
+            // first (that is where the runtime resolves the external specifier
+            // from), cwd as the fallback.
+            if (!resolveNodeGiForBundle(outPath, cwd)) {
                 throw new Error(`Cannot run the storybook on ${runtime}: \`@gjsify/node-gi\` is not installed. ` +
                     `Add @gjsify/node-gi as a dependency to run the storybook on ${runtime}.`);
             }

package/lib/utils/detect-native-packages.d.ts

@@ -1,7 +1,7 @@
 export interface NativePackage {
     /** npm package name, e.g. "@gjsify/webgl" */
     name: string;
-    /** Absolute path to the arch-specific prebuilds dir, e.g. "/…/@gjsify/webgl/prebuilds/linux-x86_64" */
+    /** Absolute path to the arch-specific prebuilds dir, e.g. "/…/@gjsify/webgl/prebuilds/linux-x64" */
     prebuildsDir: string;
 }
 /** The host target a resolution is performed for. Defaults to the running process. */
@@ -31,34 +31,39 @@ export interface NativeEnv {
     [key: string]: string | undefined;
 }
 /**
- * Canonical `<os>-<arch>` form so `linux-x64` and `linux-x86_64` — or
- * `darwin-arm64` and `darwin-aarch64` — compare equal. Only the *arch* half is
- * normalised; the OS half is always a `process.platform` token
- * (`linux`/`darwin`/`win32`), which has no competing spelling.
+ * Canonical `<os>-<arch>` form — the node spelling — so `linux-x86_64` and
+ * `linux-x64` compare equal. Only the *arch* half is normalised; the OS half
+ * is always a `process.platform` token (`linux`/`darwin`/`win32`), which has
+ * no competing spelling.
  */
 export declare function canonicalPlatformToken(token: string): string;
 /**
  * The prebuild directory names to probe for a host, most-specific first.
  *
- * There are two live spellings in this repo and neither can be declared the
- * winner:
+ * The canonical name is `${process.platform}-${process.arch}` — `linux-x64`,
+ * `linux-arm64`, `darwin-arm64`, `win32-x64`. Every package in the release
+ * train declares it (`gjsify.platforms`), `scripts/stage-prebuild.mjs` is the
+ * only thing that creates it, and `scripts/audit-runtimes.mjs --check` rejects
+ * any other spelling, so the three can no longer drift.
  *
- *   * the Vala/meson bridges stage `prebuilds/linux-x86_64/` — uname-style,
- *     because the meson jobs name the directory after `uname -m`;
- *   * `@gjsify/node-gi` (and `@gjsify/napi`'s prebuild staging) use
- *     `prebuilds/${process.platform}-${process.arch}/` — node-style
- *     (`linux-x64`, `darwin-arm64`, `win32-x64`).
+ * Two probes remain BEHIND that canonical name, and both are backward
+ * compatibility with tarballs already on npm — not a second convention:
  *
- * So we probe both, and — when the package declares `gjsify.platforms` — we
- * probe the package's OWN spelling first. That is strictly better than
- * guessing: a package that declares `darwin-arm64` tells us the exact
- * directory name it stages, whatever convention it picked.
+ *   1. **The package's own declared spelling.** A tarball published before the
+ *      rename declares (and ships) `linux-x86_64`; probing its declaration
+ *      first loads it without the CLI having to guess. This is also what makes
+ *      the rename work in the OTHER direction — an older CLI resolving a newer
+ *      package — because `canonicalPlatformToken` folds both spellings onto
+ *      one form at both ends.
+ *   2. **The legacy uname spelling.** Only reachable for a package that ships
+ *      a prebuild dir and declares NO `gjsify.platforms` at all — i.e. a
+ *      tarball predating the OS-axis audit, or a third-party package using
+ *      `gjsify.prebuilds` without the declaration. Inside this repo the audit
+ *      makes that state impossible.
  *
- * Ordering of the generic fallbacks is per-OS rather than fixed, so the first
- * probe is the spelling that platform's toolchain actually produces:
- * uname-style on Linux (`linux-x86_64`), node-style on macOS/Windows
- * (`darwin-arm64`, `win32-x64` — on Apple silicon `uname -m` also reports
- * `arm64`, so there node-style *is* the native spelling).
+ * Both are pure array entries matched against an already-read directory
+ * listing — no extra I/O — so tolerance on the READ side costs nothing, while
+ * the single spelling is enforced everywhere a name is WRITTEN.
  *
  * @param platform `process.platform` value.
  * @param arch `process.arch` value.