@gjsify/cli 0.24.2 → 0.26.0

package/lib/commands/showcase.d.ts

@@ -1,4 +1,20 @@
 import type { Command } from '../types/index.js';
+/**
+ * Pinned invocations for the three runners that cache an unpinned bin.
+ *
+ * The deno line carries TWO flags because deno stacks two independent refusals,
+ * and dropping either one leaves the hint broken in exactly the window where it
+ * is reached most: `--reload` busts the `DENO_DIR` copy, and `--min-dep-age 0`
+ * waives deno's supply-chain policy of refusing any version published within
+ * the last 24 h (`minimumDependencyAge`, default `24h`). Without the second
+ * flag `@latest` silently resolves to the newest release OLDER THAN A DAY — so
+ * a user who hits a bug, is told to run `@latest`, and does, gets the SAME
+ * pre-fix binary back and a stale error message with it. Measured twice on one
+ * day against 0.25.1 (minutes old) falling back to 0.24.1. `@latest` is kept
+ * rather than a baked version so the hint cannot go stale itself; the age
+ * waiver is what makes `@latest` mean latest.
+ */
+export declare const PIN_HINT: string;
 interface ShowcaseOptions {
     name?: string;
     json: boolean;

package/lib/commands/showcase.js

@@ -7,7 +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 { EXAMPLE_RUNTIMES, isExampleRuntime, readDeclaredRuntimes, checkRuntimeSupported, defaultExampleRuntime, } from '../utils/runtimes.js';
+import { EXAMPLE_RUNTIMES, isExampleRuntime, readDeclaredRuntimes, checkRuntimeSupported, defaultExampleRuntime, requiresGjsSystemDeps, } from '../utils/runtimes.js';
 function readCliVersion() {
     try {
         const pkgUrl = new URL('../../package.json', import.meta.url);
@@ -34,11 +34,25 @@ function readCliVersion() {
 function runningAs(cliVersion) {
     return cliVersion ? `[gjsify ${cliVersion}] ` : '';
 }
-/** Pinned invocations for the three runners that cache an unpinned bin. */
-const PIN_HINT = 'A package runner reuses a CACHED copy of an unpinned bin. Force the current one:\n' +
+/**
+ * Pinned invocations for the three runners that cache an unpinned bin.
+ *
+ * The deno line carries TWO flags because deno stacks two independent refusals,
+ * and dropping either one leaves the hint broken in exactly the window where it
+ * is reached most: `--reload` busts the `DENO_DIR` copy, and `--min-dep-age 0`
+ * waives deno's supply-chain policy of refusing any version published within
+ * the last 24 h (`minimumDependencyAge`, default `24h`). Without the second
+ * flag `@latest` silently resolves to the newest release OLDER THAN A DAY — so
+ * a user who hits a bug, is told to run `@latest`, and does, gets the SAME
+ * pre-fix binary back and a stale error message with it. Measured twice on one
+ * day against 0.25.1 (minutes old) falling back to 0.24.1. `@latest` is kept
+ * rather than a baked version so the hint cannot go stale itself; the age
+ * waiver is what makes `@latest` mean latest.
+ */
+export const PIN_HINT = 'A package runner reuses a CACHED copy of an unpinned bin. Force the current one:\n' +
     '    npx @gjsify/cli@latest showcase <name>\n' +
     '    bunx @gjsify/cli@latest showcase <name>\n' +
-    '    deno run -A --reload npm:@gjsify/cli@latest showcase <name>';
+    '    deno run -A --reload --min-dep-age 0 npm:@gjsify/cli@latest showcase <name>';
 export const showcaseCommand = {
     command: 'showcase [name]',
     description: 'List or run curated gjsify showcase applications.',
@@ -119,33 +133,39 @@ export const showcaseCommand = {
             // `m_should_exit` core dump. Returning halts the handler here.
             return process.exit(1);
         }
+        // Resolve the runtime BEFORE the system-dependency gate: that gate is a
+        // question ABOUT the runtime, and asking it first gated every showcase
+        // on a gjs binary (see `requiresGjsSystemDeps`).
+        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).
+            return process.exit(1);
+        }
         // System dependency check before delegating — only system libs (gjs,
-        // gtk4, …). The showcase's npm deps (incl. `@gjsify/webgl` with the
+        // gtk4, …), and only for a runtime that consumes the `--app gjs`
+        // bundle. The showcase's npm deps (incl. `@gjsify/webgl` with the
         // gwebgl Vala prebuild) are fetched by `gjsify dlx` into the npm
         // cache, and `runGjsBundle()` picks the prebuild up from the bundle
         // dir via `detectNativePackages()`. Pre-flight-checking npm deps
         // here would fail for `npx @gjsify/cli showcase` (no project
         // node_modules, CLI doesn't dep on the showcase libs).
-        const results = runMinimalChecks();
-        const missingHard = results.filter((r) => !r.found && r.severity === 'required');
-        if (missingHard.length > 0) {
-            console.error('Missing system dependencies:\n');
-            for (const dep of missingHard) {
-                console.error(`  ✗  ${dep.name}`);
-            }
-            const pm = detectPackageManager();
-            const cmd = buildInstallCommand(pm, missingHard);
-            if (cmd) {
-                console.error(`\nInstall with:\n  ${cmd}`);
+        if (requiresGjsSystemDeps(runtime)) {
+            const results = runMinimalChecks();
+            const missingHard = results.filter((r) => !r.found && r.severity === 'required');
+            if (missingHard.length > 0) {
+                console.error('Missing system dependencies:\n');
+                for (const dep of missingHard) {
+                    console.error(`  ✗  ${dep.name}`);
+                }
+                const pm = detectPackageManager();
+                const cmd = buildInstallCommand(pm, missingHard);
+                if (cmd) {
+                    console.error(`\nInstall with:\n  ${cmd}`);
+                }
+                // `return` — bare `process.exit` falls through under GJS (see above).
+                return process.exit(1);
             }
-            // `return` — bare `process.exit` falls through under GJS (see above).
-            return process.exit(1);
-        }
-        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).
-            return process.exit(1);
         }
         const cliVersion = readCliVersion();
         // Non-gjs runtime: resolve the showcase's `--app node` bundle and run it
@@ -266,6 +286,17 @@ async function runShowcaseOnRuntime(showcase, runtime, cliVersion) {
         return process.exit(1);
     }
     console.log(`Running showcase: ${showcase.name} ${runningAs(cliVersion)}on ${runtime} (${entry})\n`);
-    // Terminal call — exit on success.
-    await runRuntimeBundle(runtime, entry, [], { exitOnSuccess: true });
+    // Terminal call — exit on success. Failures are reported here rather than
+    // thrown: an exception escaping the handler makes yargs dump the command's
+    // full `--help` above the message, which buries it.
+    try {
+        await runRuntimeBundle(runtime, entry, [], { exitOnSuccess: true });
+    }
+    catch (err) {
+        console.error(`${err.message}\n\n` +
+            `  The showcase and the \`@gjsify/node-gi\` bridge it needs are both installed by THIS CLI\n` +
+            `  (gjsify ${cliVersion ?? '(unknown)'}) into its own cache, so a missing bridge points at the CLI\n` +
+            `  rather than at anything in your project.\n\n  ${PIN_HINT}`);
+        return process.exit(1);
+    }
 }

package/lib/commands/storybook.js

@@ -136,8 +136,22 @@ export const storybookCommand = {
         };
         const initialCount = writeEntry();
         if (initialCount === 0) {
-            console.error(`No *.story.ts files found under ${relative(cwd, storiesDir) || storiesDir}`);
-            process.exit(1);
+            // `return process.exit()`: a bare `process.exit()` does NOT halt
+            // synchronously under GJS (no atexit, the GLib loop is still
+            // armed), so execution fell through to the "Found 0 story file(s)"
+            // log and on into the build — and the deferred exit never carried
+            // its code, so `gjsify storybook` in a directory with no stories
+            // printed BOTH messages and exited 0. Measured: exit 1 under bun,
+            // exit 0 under gjs, same command. Same trap as `showcase.ts`.
+            console.error(`No *.story.ts files found under ${relative(cwd, storiesDir) || storiesDir}\n\n` +
+                `  \`gjsify storybook\` renders the stories of the CURRENT project: it discovers\n` +
+                `  \`*.story.ts\` files and launches a component browser over them. Point it at a\n` +
+                `  different directory with --stories <dir> (or \`gjsify.storybook.stories\` in\n` +
+                `  package.json) if yours live elsewhere.\n\n` +
+                `  To SEE a storybook without authoring one first, run the curated Libadwaita\n` +
+                `  component browser — it is a showcase, so it needs no project at all:\n\n` +
+                `      gjsify showcase adwaita-storybook`);
+            return process.exit(1);
         }
         console.log(`Found ${initialCount} story file(s) under ${relative(cwd, storiesDir) || '.'} (runtime: ${runtime})`);
         // In-process build — runtime-agnostic (Node uses npm rolldown, GJS uses

package/lib/commands/system-check.js

@@ -18,8 +18,7 @@ export const systemCheckCommand = {
         if (args.json) {
             console.log(JSON.stringify({ packageManager: pm, deps: results }, null, 2));
             // Only required deps influence the exit code.
-            process.exit(missingRequired.length > 0 ? 1 : 0);
-            return;
+            return process.exit(missingRequired.length > 0 ? 1 : 0);
         }
         console.log('System dependency check\n');
         const required = results.filter((r) => r.severity === 'required');

package/lib/commands/test.js

@@ -60,7 +60,9 @@ export const testCommand = {
             console.error(`[gjsify test] no test entry at ${relative(cwd, entry)} — ` +
                 `add an \`src/test.mts\` that aggregates your \`@gjsify/unit\` suites, ` +
                 `or set \`gjsify.test.entry\` in package.json.`);
-            process.exit(1);
+            // `return` — a bare `process.exit()` is deferred under GJS and the
+            // handler would try to build the missing entry anyway.
+            return process.exit(1);
         }
         const requested = args.runtime === 'gjs'
             ? ['gjs']
@@ -124,7 +126,9 @@ export const testCommand = {
         console.log(`[gjsify test] ${summary}`);
         const anyFailed = results.some((r) => !r.ok);
         if (anyFailed) {
-            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);
         }
         // Explicit success exit: under GJS the spawn-armed main loop would
         // otherwise park this process after the summary. (runGjsBundle

package/lib/commands/trust.js

@@ -79,7 +79,9 @@ export const trustCommand = {
         const npmrc = await loadNpmrc(cwd);
         if (!hasAnyCredential(npmrc)) {
             console.error('gjsify trust: no npm token configured. Run `gjsify login` first.');
-            process.exit(1);
+            // `return` — a bare `process.exit()` is deferred under GJS and the
+            // handler would keep going without credentials.
+            return process.exit(1);
         }
         // Pre-flight: a present-but-DEAD token would otherwise surface as a
         // confusing per-package `401 "You must be logged in to publish
@@ -97,13 +99,13 @@ export const trustCommand = {
                 console.error(`gjsify trust: npm auth check failed (${msg}).\n` +
                     'Your ~/.npmrc token is dead or revoked — refresh it with `npm login`, then re-run.\n' +
                     '(`gjsify trust` uses the ~/.npmrc bearer token directly — unlike `npm trust`, which logs in via the browser.)');
-                process.exit(1);
-                return;
+                return process.exit(1);
             }
             if (!who.username) {
                 console.error('gjsify trust: your npm token appears dead or revoked (registry returned an empty whoami).\n' +
                     'Refresh it with `npm login`, then re-run.');
-                process.exit(1);
+                // `return` — see the deferred-exit note on the guard above.
+                return process.exit(1);
             }
             console.log(`gjsify trust: authenticated as ${who.username}`);
         }
@@ -117,11 +119,13 @@ export const trustCommand = {
         if (!repository) {
             console.error('gjsify trust: could not determine the GitHub repository.\n' +
                 'Pass --repository owner/repo (no `origin` remote to infer from).');
-            process.exit(1);
+            // `return` — see the deferred-exit note on the guard above.
+            return process.exit(1);
         }
         if (!validateRepository(repository)) {
             console.error(`gjsify trust: --repository must be "owner/repo", got "${repository}".`);
-            process.exit(1);
+            // `return` — see the deferred-exit note on the guard above.
+            return process.exit(1);
         }
         const workflow = normalizeWorkflowFile(args.workflow);
         const environment = args.environment;
@@ -148,7 +152,8 @@ export const trustCommand = {
         }).filter((ws) => ws.name);
         if (selected.length === 0) {
             console.error('gjsify trust: no publishable packages matched.');
-            process.exit(1);
+            // `return` — see the deferred-exit note on the guard above.
+            return process.exit(1);
         }
         console.log(`gjsify trust: ${selected.length} package(s) | repo=${repository} workflow=${workflow}`);
         if (dryRun)

package/lib/commands/tsc.js

@@ -104,7 +104,9 @@ export const tscCommand = {
         if (!bundlePath && !nodeTscPath) {
             console.error('gjsify tsc: neither @gjsify/tsc (GJS bundle) nor npm `typescript` (Node) is installed.');
             console.error('  Install with: gjsify install --save-dev @gjsify/tsc   (or add `typescript`).');
-            process.exit(1);
+            // `return` — a bare `process.exit()` is deferred under GJS and the
+            // handler would try to spawn a compiler that is not there.
+            return process.exit(1);
         }
         // Mirror `gjsify run`'s native-env composition so any future
         // typescript-the-bundle code path that reaches a native bridge

package/lib/commands/uninstall.js

@@ -46,8 +46,7 @@ export const uninstallCommand = {
         if (!args.global) {
             console.error('gjsify uninstall currently only supports --global. ' +
                 'For project-local removal, edit package.json + re-run `gjsify install`.');
-            process.exit(1);
-            return;
+            return process.exit(1);
         }
         const layout = defaultGlobalLayout();
         const dryRun = args['dry-run'] ?? false;

package/lib/commands/whoami.js

@@ -69,7 +69,9 @@ export const whoamiCommand = {
                     'Then verify:  gjsify whoami',
                 ].join('\n') + '\n');
             }
-            process.exit(1);
+            // `return` — a bare `process.exit()` is deferred under GJS and the
+            // handler would probe the registry without a token.
+            return process.exit(1);
         }
         let result;
         try {
@@ -85,8 +87,9 @@ export const whoamiCommand = {
                 process.stderr.write(`gjsify whoami: ${message}\n`);
                 process.stderr.write(`Registry: ${registryClean}\n`);
             }
-            process.exit(1);
-            return; // unreachable but pleases the type narrower
+            // `return process.exit` also keeps the type narrower happy: the
+            // never-typed call marks this branch as terminated.
+            return process.exit(1);
         }
         if (result.username && result.username.length > 0) {
             // Branch 1 — live token.

package/lib/utils/dlx-cache.js

@@ -92,11 +92,10 @@ export function symlinkSwap(cacheDir, prepareDir) {
     catch (err) {
         const code = err.code;
         if (code === 'EBUSY' || code === 'EPERM' || code === 'EEXIST') {
-            // Race lost — clean up our tmp and use whoever won.
-            try {
-                rmSync(tmpLink);
-            }
-            catch { }
+            // Race lost — clean up our tmp and use whoever won. force:true is
+            // the non-throwing spelling of "remove if still there"; any other
+            // failure on our own pid-unique link is real and should surface.
+            rmSync(tmpLink, { force: true });
             return realpathSync(linkPath);
         }
         throw err;

package/lib/utils/install-backend-native.js

@@ -458,7 +458,7 @@ specOrigins) {
  *
  * This makes the current single-root-slot behavior honest instead of silent;
  * the real fix — a per-workspace dedup pass that gives each conflicting
- * requester its own nested copy — is Phase D.8 (see STATUS.md).
+ * requester its own nested copy — is Phase D.8 (see status/open-todos.md).
  */
 function emitTopLevelConflictWarnings(topLevelRanges, root) {
     for (const [name, ranges] of topLevelRanges) {

package/lib/utils/install-lock.js

@@ -84,13 +84,11 @@ function lockingDisabled() {
  * we cannot prove abandoned; the mtime staleness budget still applies).
  */
 function isPidAlive(pid) {
-    try {
-        if (existsSync('/proc/self'))
-            return existsSync(`/proc/${pid}`);
-    }
-    catch {
-        /* fall through to the signal probe */
-    }
+    // `existsSync` never throws by contract: Node returns false on any error,
+    // and the GJS shim is a typeof guard + Gio `query_exists` (both without a
+    // throw path in the GIR). Off Linux the `if` is simply false.
+    if (existsSync('/proc/self'))
+        return existsSync(`/proc/${pid}`);
     try {
         process.kill(pid, 0);
         return true;

package/lib/utils/install-tarball-cache.js

@@ -30,6 +30,7 @@
 // same hex bytes share the same cache entry; that is the invariant pnpm
 // relies on too. Tarballs without an integrity hash (older registries)
 // fall through to a no-op cache and download every time.
+import { Buffer } from 'node:buffer';
 import { existsSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -53,14 +54,10 @@ function parseSri(integrity) {
         return null;
     const algorithm = integrity.slice(0, dashIdx);
     const b64 = integrity.slice(dashIdx + 1).replace(/=+$/, '');
-    // Decode base64 → hex; throws on malformed input which we swallow.
-    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/utils/node-bundle-guard.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The GJS ambient globals referenced as BARE identifiers in `code`, sorted.
+ *
+ * Empty for a bundle that only uses the `globalThis.imports` isomorphic-guard
+ * shape — that form is a runtime probe, not a dependency, and the detector
+ * ignores it for exactly that reason.
+ */
+export declare function findUnshimmedGjsGlobals(code: string): string[];
+/**
+ * Throw when a `--app node` bundle references GJS ambient globals but was built
+ * without the `@gjsify/node-gi/globals` shim.
+ *
+ * @param code     the emitted bundle source
+ * @param outfile  path of the bundle, for the error message
+ */
+export declare function assertNodeBundleGlobalsShimmed(code: string, outfile: string): void;

package/lib/utils/node-bundle-guard.js

@@ -0,0 +1,69 @@
+// Build-time guard: a `--app node` bundle that USES the GJS ambient globals
+// must also have been given `@gjsify/node-gi/globals`.
+//
+// `print`/`printerr`/`log`/`logError`/`ARGV`/`imports` exist implicitly under
+// gjs and nowhere else. On the node target they are seeded by the side-effect
+// shim `@gjsify/node-gi/globals`, which the CLI injects when — and only when —
+// `detectNodeGiGlobals` finds one of them in an analysis bundle. Injecting it
+// unconditionally is not an option: it eagerly loads the native node-gi addon,
+// so a cross-platform package's node bundle would stop loading on plain Node.
+//
+// That makes the decision a PREDICTION about an artifact that does not exist
+// yet, and a prediction can be wrong. It was: the analysis pass used to run
+// before the explicit-`--globals` register stub was resolved, and that stub is
+// one of the two signals `isGjsSourceBuild()` reads — so the analysis bundle
+// routed `/register` subpaths to `@gjsify/empty` and emptied `@girs/*` while the
+// REAL build resolved them for real. Every ambient global reachable only through
+// a register module was therefore invisible to the detector. The build exited 0
+// and the emitted bundle died at its first canvas op with
+//
+//   ReferenceError: imports is not defined
+//       at CanvasRenderingContext2D._toDataURL
+//
+// on node AND bun (the excalibur-jelly-jumper showcase), while gjs — where the
+// globals are ambient — ran fine. Nothing between `gjsify build --app node` and
+// a user running the bundle ever looked at the artifact.
+//
+// So this is a POST-condition on what was actually emitted: whatever the
+// detector predicted, check it against the bundle. It is deliberately NOT a
+// second detector — it runs the SAME `detectGjsAmbientGlobals` over the SAME
+// kind of input (bundled, tree-shaken output, parsed by acorn, bare identifiers
+// only). Two passes over one oracle that must agree; when they don't, the graph
+// they saw differed, which is a bug in the build pipeline, not in user code.
+//
+// Scope: only when the CLI decided NOT to inject (`--globals auto`, no shim).
+// `--globals none` opts out of the whole mechanism explicitly and is skipped.
+import { detectGjsAmbientGlobals } from '@gjsify/rolldown-plugin-gjsify/globals';
+/**
+ * The GJS ambient globals referenced as BARE identifiers in `code`, sorted.
+ *
+ * Empty for a bundle that only uses the `globalThis.imports` isomorphic-guard
+ * shape — that form is a runtime probe, not a dependency, and the detector
+ * ignores it for exactly that reason.
+ */
+export function findUnshimmedGjsGlobals(code) {
+    return [...detectGjsAmbientGlobals(code)].sort();
+}
+/**
+ * Throw when a `--app node` bundle references GJS ambient globals but was built
+ * without the `@gjsify/node-gi/globals` shim.
+ *
+ * @param code     the emitted bundle source
+ * @param outfile  path of the bundle, for the error message
+ */
+export function assertNodeBundleGlobalsShimmed(code, outfile) {
+    const offenders = findUnshimmedGjsGlobals(code);
+    if (offenders.length === 0)
+        return;
+    throw new Error(`gjsify build --app node: ${outfile} references ${offenders.length} GJS ambient global(s) that ` +
+        'nothing installs on node/bun/deno, so the bundle throws `ReferenceError: <name> is not defined` ' +
+        'the first time that code runs:\n' +
+        offenders.map((s) => `  - ${s}`).join('\n') +
+        '\n\nThe `@gjsify/node-gi/globals` shim seeds them, but it is injected only when the pre-build ' +
+        'detection pass finds them — and that pass did not. The two passes therefore disagreed about the ' +
+        'module graph. Either the detection ran against a different graph than the one emitted (check that ' +
+        'anything feeding `isGjsSourceBuild()` — the `--globals` register stub, `nodeGiGlobalsInject` — is ' +
+        'settled BEFORE `detectNodeGiGlobals`), or the offending package should stop reaching for the ' +
+        'legacy `imports` object: `gi://<Ns>` and the bare `system`/`gettext`/`cairo` built-ins resolve on ' +
+        'both runtimes, `imports` does not.');
+}

package/lib/utils/oxc-resolve.js

@@ -45,7 +45,7 @@
 // `gjsify/register-class-order` rule wired via `.oxlintrc.json` jsPlugins)
 // lives in the Node launcher, so a native oxlint bridge could only run the
 // Rust rule subset. Lint stays Node-spawned until that trade-off is decided
-// (tracked in STATUS.md Open TODOs).
+// (tracked in status/open-todos.md).
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { createRequire } from 'node:module';

package/lib/utils/prompt.js

@@ -82,7 +82,12 @@ async function runRawSession(fn) {
                 out.write(r.echo);
             if (r.interrupt) {
                 cleanup();
-                process.exit(130);
+                // `return` — a bare `process.exit()` is deferred under GJS (no
+                // atexit), so the loop kept consuming the rest of the chunk
+                // after Ctrl-C and could still resolve the pending prompt.
+                // Returning stops input handling here; the deferred exit then
+                // carries 130 on the way out.
+                return process.exit(130);
             }
             if (r.done) {
                 const { resolve } = pending;

package/lib/utils/runtimes.d.ts

@@ -26,6 +26,24 @@ export declare const RUNTIMES: Record<ExampleRuntime, RuntimeSpec>;
 export declare function isExampleRuntime(value: string): value is ExampleRuntime;
 /** The `gjsify build --app <target>` a runtime consumes (`gjs`, else `node`). */
 export declare function buildAppForRuntime(runtime: ExampleRuntime): 'gjs' | 'node';
+/**
+ * Does running an example/showcase on `runtime` require the GJS SYSTEM
+ * dependencies — i.e. a `gjs` binary on PATH?
+ *
+ * DERIVED from `buildApp`, deliberately not a second table: "consumes the
+ * `--app gjs` bundle" and "needs a gjs interpreter" are the same fact, and a
+ * hand-written second list drifts the first time a runtime is added.
+ *
+ * The caller must resolve the runtime BEFORE gating on it. `gjsify showcase`
+ * called `runMinimalChecks()` — which marks `gjs` `required` — three statements
+ * ABOVE the line resolving `args.runtime`, so `--runtime node` aborted with
+ * "Missing system dependencies: ✗ GJS" before reaching the `runtime !== 'gjs'`
+ * branch that never touches gjs. Every showcase was unreachable on a host
+ * without gjs (Windows, plain Node/bun/deno) — including the default path,
+ * since `defaultExampleRuntime()` falls back to the host runtime for exactly
+ * those hosts.
+ */
+export declare function requiresGjsSystemDeps(runtime: ExampleRuntime): boolean;
 /** Whether `<probe> --version` succeeds (i.e. the runtime binary is on PATH). */
 export declare function isRuntimeOnPath(probe: string): boolean;
 /**

package/lib/utils/runtimes.js

@@ -41,6 +41,26 @@ export function isExampleRuntime(value) {
 export function buildAppForRuntime(runtime) {
     return RUNTIMES[runtime].buildApp;
 }
+/**
+ * Does running an example/showcase on `runtime` require the GJS SYSTEM
+ * dependencies — i.e. a `gjs` binary on PATH?
+ *
+ * DERIVED from `buildApp`, deliberately not a second table: "consumes the
+ * `--app gjs` bundle" and "needs a gjs interpreter" are the same fact, and a
+ * hand-written second list drifts the first time a runtime is added.
+ *
+ * The caller must resolve the runtime BEFORE gating on it. `gjsify showcase`
+ * called `runMinimalChecks()` — which marks `gjs` `required` — three statements
+ * ABOVE the line resolving `args.runtime`, so `--runtime node` aborted with
+ * "Missing system dependencies: ✗ GJS" before reaching the `runtime !== 'gjs'`
+ * branch that never touches gjs. Every showcase was unreachable on a host
+ * without gjs (Windows, plain Node/bun/deno) — including the default path,
+ * since `defaultExampleRuntime()` falls back to the host runtime for exactly
+ * those hosts.
+ */
+export function requiresGjsSystemDeps(runtime) {
+    return buildAppForRuntime(runtime) === 'gjs';
+}
 /** Whether `<probe> --version` succeeds (i.e. the runtime binary is on PATH). */
 export function isRuntimeOnPath(probe) {
     try {

package/lib/utils/stdin.js

@@ -75,14 +75,13 @@ function readStdinTextGioFile() {
         throw new Error('Gio.File.load_contents("/dev/stdin") returned false');
     return new TextDecoder().decode(contents);
 }
-/** The GJS `imports.gi` namespace, or `undefined` when not running on GJS. */
+/**
+ * The GJS `imports.gi` namespace, or `undefined` when not running on GJS.
+ * Same optional-chained probe as `isGjs()` — off GJS `imports` is simply
+ * absent and the read yields `undefined`; there is no throw path.
+ */
 function giNamespace() {
-    try {
-        return globalThis.imports?.gi;
-    }
-    catch {
-        return undefined;
-    }
+    return globalThis.imports?.gi;
 }
 /**
  * Read the whole of stdin as UTF-8. Works on Node and under the GJS bundle.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/cli",
-    "version": "0.24.2",
+    "version": "0.26.0",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -130,19 +130,19 @@
         "cli"
     ],
     "dependencies": {
-        "@gjsify/buffer": "^0.24.2",
-        "@gjsify/create-app": "^0.24.2",
-        "@gjsify/node-globals": "^0.24.2",
-        "@gjsify/node-polyfills": "^0.24.2",
-        "@gjsify/npm-registry": "^0.24.2",
-        "@gjsify/resolve-npm": "^0.24.2",
-        "@gjsify/rolldown-plugin-gjsify": "^0.24.2",
-        "@gjsify/rolldown-plugin-pnp": "^0.24.2",
-        "@gjsify/semver": "^0.24.2",
-        "@gjsify/tar": "^0.24.2",
-        "@gjsify/tsc": "^0.24.2",
-        "@gjsify/web-polyfills": "^0.24.2",
-        "@gjsify/workspace": "^0.24.2",
+        "@gjsify/buffer": "^0.26.0",
+        "@gjsify/create-app": "^0.26.0",
+        "@gjsify/node-globals": "^0.26.0",
+        "@gjsify/node-polyfills": "^0.26.0",
+        "@gjsify/npm-registry": "^0.26.0",
+        "@gjsify/resolve-npm": "^0.26.0",
+        "@gjsify/rolldown-plugin-gjsify": "^0.26.0",
+        "@gjsify/rolldown-plugin-pnp": "^0.26.0",
+        "@gjsify/semver": "^0.26.0",
+        "@gjsify/tar": "^0.26.0",
+        "@gjsify/tsc": "^0.26.0",
+        "@gjsify/web-polyfills": "^0.26.0",
+        "@gjsify/workspace": "^0.26.0",
         "cosmiconfig": "^9.0.2",
         "get-tsconfig": "^4.14.0",
         "pkg-types": "^2.3.1",
@@ -150,13 +150,13 @@
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@gjsify/unit": "^0.24.2",
+        "@gjsify/unit": "^0.26.0",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/oxfmt-native": "^0.24.2",
-        "@gjsify/rolldown-native": "^0.24.2"
+        "@gjsify/oxfmt-native": "^0.26.0",
+        "@gjsify/rolldown-native": "^0.26.0"
     },
     "peerDependenciesMeta": {
         "@gjsify/oxfmt-native": {