@gjsify/cli 0.25.1 → 0.26.0

package/lib/cli-app.js

@@ -10,7 +10,7 @@
 // build`, and `gjsify run build:types → gjsify tsc → gjs tsc.gjs.mjs`), so on
 // CI's few cores the multiplier oversubscribes and the build thrashes. Letting
 // `gjsify run` dispatch the inner `gjsify <cmd>` in-process collapses two gjs
-// into one. See STATUS.md.
+// into one. See status/open-todos.md.
 //
 // This module MUST NOT execute anything at load time (no top-level
 // `parseAsync`) — `run.ts` imports it, and a top-level run would re-dispatch
@@ -28,15 +28,12 @@ import { ensureGjsifyShimOnPath } from './utils/gjsify-shim.js';
 // GJS's @gjsify/process shim — fake `process.versions.node` for npm
 // compatibility, so a plain Node probe is a false positive on either.
 function runtimeLabel() {
-    try {
-        const sysVersion = gjsSystemVersion();
-        if (sysVersion !== undefined) {
-            const v = Number(sysVersion);
-            return `GJS ${Math.floor(v / 10000)}.${Math.floor((v % 10000) / 100)}.${v % 100} (SpiderMonkey)`;
-        }
-    }
-    catch {
-        /* not GJS */
+    // Off GJS `gjsSystemVersion()` RETURNS undefined (an optional-chained
+    // `globalThis.imports` read, same probe as `isGjs()`) — it never throws.
+    const sysVersion = gjsSystemVersion();
+    if (sysVersion !== undefined) {
+        const v = Number(sysVersion);
+        return `GJS ${Math.floor(v / 10000)}.${Math.floor((v % 10000) / 100)}.${v % 100} (SpiderMonkey)`;
     }
     if (isBun()) {
         const version = globalThis.Bun?.version ?? process.versions.bun;

package/lib/commands/affected.js

@@ -343,7 +343,16 @@ function runGitDiff(cwd, base, head) {
         // Surface a clear error — caller (CI) will fall back to full run
         // via `continue-on-error: true` on the classify step.
         process.stderr.write(`gjsify affected: git diff failed (${r.status}): ${r.stderr.trim()}\n`);
+        // Under GJS `process.exit()` is DEFERRED (no atexit — the call
+        // returns), so in this synchronous, value-returning helper a bare
+        // exit fell through to the `return` below and handed the caller a
+        // diff parsed from a failed git run. `return process.exit(…)` cannot
+        // help here either — it would hand the caller the pending exit
+        // promise as a `string[]`. The throw is what actually stops the
+        // caller; on Node the exit(2) halts first and the throw is dead.
+        // oxlint-disable-next-line gjsify/deferred-process-exit -- the throw below IS the halt for the GJS path; see the comment above.
         process.exit(2);
+        throw new Error(`gjsify affected: git diff failed (${r.status})`);
     }
     return r.stdout.split('\n').filter(Boolean);
 }
@@ -409,8 +418,11 @@ function assertShellSafeWorkspaceName(name) {
         `  \`include-args\` token (the value is consumed by an UNQUOTED $INCLUDE_ARGS expansion — see the\n` +
         `  contract at the top of commands/affected.ts). Rename the workspace, or teach this command a\n` +
         `  transport the consumers can unquote. Refusing to emit a filter that would silently mis-match.\n`);
+    // NOT unreachable under GJS: `process.exit()` is DEFERRED there (no atexit
+    // — the call returns), so the throw below is what actually stops an unsafe
+    // name from reaching the emit site; the exit code rides the scheduled
+    // teardown. On Node the exit(2) halts first and the throw is dead code.
+    // oxlint-disable-next-line gjsify/deferred-process-exit -- the throw below IS the halt for the GJS path; see the comment above.
     process.exit(2);
-    // Unreachable — `process.exit` terminates. Present so this function has no
-    // fall-through path that could ever return an unsafe name.
     throw new Error(`gjsify affected: unsafe workspace name ${name}`);
 }

package/lib/commands/check.js

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

package/lib/commands/create.js

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

package/lib/commands/debug.js

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

package/lib/commands/flatpak/check.js

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

package/lib/commands/flatpak/diff.js

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

package/lib/commands/flatpak/sources.js

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

package/lib/commands/foreach.js

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

package/lib/commands/generate-installer.js

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

package/lib/commands/install.js

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

package/lib/commands/login.js

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

package/lib/commands/onboard.js

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

package/lib/commands/publish.js

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

package/lib/commands/self-update.js

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

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