@gjsify/cli 0.30.0 → 0.32.0

package/lib/commands/install.js

@@ -31,7 +31,7 @@ import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, rmSync, syml
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
-import { gjsExit } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { forceExit } from '../utils/force-exit.js';
 import { discoverWorkspaces } from '@gjsify/workspace';
 import { buildInstallCommand, detectPackageManager, runMinimalChecks } from '../utils/check-system-deps.js';
 import { detectNativePackages } from '../utils/detect-native-packages.js';
@@ -42,7 +42,7 @@ import { acquireInstallLock } from '../utils/install-lock.js';
 import { nodeBinary } from '../utils/run-node.js';
 import { spawnToCompletion } from '../utils/spawn.js';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
-import { binDirOnPath, defaultGlobalLayout, installGjsEnginePackages, linkGlobalBins, specToPackageName, } from '../utils/install-global.js';
+import { binDirOnPath, BUNDLER_ENGINE_PACKAGE, defaultGlobalLayout, hasBundlerEngineInstalled, installGjsEnginePackages, linkGlobalBins, specToPackageName, } from '../utils/install-global.js';
 import { addDependencyEntry, defaultRangeFromVersion, parseSpec, projectSpecsFromPackageJson, readPackageJson, writePackageJson, } from '../utils/pkg-json-edit.js';
 /**
  * Link type for the workspace↔workspace directory links.
@@ -198,7 +198,7 @@ export const installCommand = {
         const backend = args.backend ?? process.env.GJSIFY_INSTALL_BACKEND ?? 'native';
         if (backend === 'npm') {
             await projectInstallViaNpm(args);
-            await runPostInstallChecks();
+            await runPostInstallChecks(args);
             return;
         }
         // Overall wall-clock budget for the install (default 30 min — big
@@ -263,7 +263,7 @@ export const installCommand = {
         hardExitTimerId?.unref?.();
         try {
             await projectInstallNative(args, overallController?.signal);
-            await runPostInstallChecks();
+            await runPostInstallChecks(args);
         }
         catch (err) {
             if (overallController !== null && overallController.signal.aborted && isAbortedFromOverallTimeout(err)) {
@@ -345,21 +345,6 @@ function isAbortedFromOverallTimeout(err) {
         return true;
     return false;
 }
-/**
- * Force a non-zero process exit that is honored on BOTH runtimes.
- *
- * Node exits at natural shutdown once `process.exitCode` is set, but GJS has
- * no atexit hook, so `imports.system.exit` is called directly there —
- * SpiderMonkey raises its uncatchable exit exception from any context,
- * including the `setTimeout` continuation the backstop timer runs in. Mirrors
- * the entry wrapper (`index.ts`) and `setOxcExitCode` (`oxc-resolve.ts`).
- */
-function forceExit(code) {
-    process.exitCode = code;
-    if (gjsExit(code))
-        return;
-    process.exit(code);
-}
 const CLI_PACKAGE_NAME = '@gjsify/cli';
 /** Read a `version` from a package.json IFF its `name` is `@gjsify/cli`. */
 function readCliVersionFrom(pkgJsonPath) {
@@ -1419,7 +1404,33 @@ function reportLinkedBins(created, binDir) {
             `Add it to your shell rc file:\n  export PATH="${binDir}:$PATH"`);
     }
 }
-async function runPostInstallChecks() {
+export async function ensureProjectGjsEngine(args, gjsFound, deps = {}) {
+    const cwd = deps.cwd ?? process.cwd();
+    const hasEngine = deps.hasEngineFn ?? hasBundlerEngineInstalled;
+    if (!existsSync(join(cwd, 'node_modules', '@gjsify', 'cli', 'package.json')))
+        return;
+    if (!gjsFound)
+        return;
+    if (hasEngine(cwd))
+        return;
+    if (args.immutable) {
+        // Name the DURABLE fix, not a transient one: a frozen CI install cannot
+        // be repaired by anything that happens at this moment, so the answer is
+        // to put the engine in the lockfile.
+        console.warn(`\nWarning: \`gjsify build\` will fail under GJS — ${BUNDLER_ENGINE_PACKAGE} is not installed, and\n` +
+            '  --immutable cannot add it (the lockfile does not name it). Declare it so the lockfile carries it:\n' +
+            `    gjsify install ${BUNDLER_ENGINE_PACKAGE}\n` +
+            '  Under Node the npm `rolldown` engine is used instead and this does not apply.');
+        return;
+    }
+    const cliVersion = readCliVersionFrom(join(cwd, 'node_modules', '@gjsify', 'cli', 'package.json')) ?? 'latest';
+    console.log(`\n${BUNDLER_ENGINE_PACKAGE} is missing and this host can run gjs, so \`gjsify build\` would have no\n` +
+        `  bundler engine (there is no npm \`rolldown\` fallback under GJS). Installing the GJS engine set at\n` +
+        `  ${cliVersion}, in lockstep with the CLI.`);
+    const install = deps.installFn ?? installGjsEnginePackages;
+    await install(cwd, cliVersion, { verbose: args.verbose });
+}
+async function runPostInstallChecks(args) {
     console.log('\n--- gjsify post-install checks ---');
     // 1. System deps that GJS apps typically need.
     const results = runMinimalChecks();
@@ -1437,8 +1448,14 @@ async function runPostInstallChecks() {
     else {
         console.log('System dependencies OK.');
     }
-    // 2. Surface @gjsify/* packages with native prebuilds — `gjsify run`
+    // 2. Close #1005 before reporting the prebuild set, so the report reflects
+    //    what the tree ACTUALLY has rather than what it had a moment ago.
+    await ensureProjectGjsEngine(args, results.find((r) => r.id === 'gjs')?.found ?? false);
+    // 3. Surface @gjsify/* packages with native prebuilds — `gjsify run`
     //    will set LD_LIBRARY_PATH / GI_TYPELIB_PATH for these automatically.
+    //    Runs AFTER step 2 on purpose: an engine installed a moment ago belongs
+    //    in this list, and a consumer reading "Detected N …" needs it to be the
+    //    tree's current state rather than its state on entry.
     const native = detectNativePackages(process.cwd());
     if (native.length > 0) {
         console.log(`\nDetected ${native.length} @gjsify/* package(s) with native prebuilds:`);

package/lib/commands/run.js

@@ -296,12 +296,15 @@ async function runScript(script, extraArgs, cwd = process.cwd()) {
     if (monorepoRoot && monorepoRoot !== cwd) {
         binDirs.push(join(monorepoRoot, 'node_modules', '.bin'));
     }
-    // Under GJS, the GJS-runnable `gjsify` shim (see `ensureGjsifyShimOnPath`)
-    // MUST shadow the workspace `node_modules/.bin/gjsify`, which is the Node
-    // entry and unusable in a node-free sandbox. So put the shim dir ahead of
-    // the `.bin` dirs in the child's PATH — otherwise a compound script like
-    // `gjsify run a && gjsify run b` resolves `gjsify` to the Node bin and
-    // fails. `GJSIFY_SHIM_DIR` is only set under GJS, so this is a no-op on Node.
+    // The self-shim (see `ensureGjsifyShimOnPath`) MUST shadow the workspace
+    // `node_modules/.bin/gjsify`, so put its dir ahead of the `.bin` dirs in the
+    // child's PATH — otherwise a compound script like `gjsify run a && gjsify
+    // run b` resolves `gjsify` to the workspace bin. Two trees need that:
+    // under GJS the bin is the Node entry and is unusable in a node-free
+    // sandbox, and under a BOOTSTRAP Node CLI (npx / global install) the bin
+    // dispatches to build outputs that a cold tree has not produced yet.
+    // `GJSIFY_SHIM_DIR` is unset whenever the tree's own CLI is the one
+    // running, which keeps that case byte-for-byte unchanged.
     if (process.env.GJSIFY_SHIM_DIR) {
         binDirs.unshift(process.env.GJSIFY_SHIM_DIR);
     }
@@ -342,6 +345,22 @@ async function runScript(script, extraArgs, cwd = process.cwd()) {
         process.env.npm_package_version = env.npm_package_version;
         if (env.FORCE_COLOR !== undefined)
             process.env.FORCE_COLOR = env.FORCE_COLOR;
+        // …and the working directory, for the same reason. The spawn path below
+        // passes `cwd` to `spawn()`; this path used to pass it nowhere, so a
+        // `gjsify run -w <ws> <script>` resolved the WORKSPACE and then ran the
+        // command in the CALLER's directory. Every relative path in the script
+        // — `src/app/main.ts`, `dist/…`, `tests/test.mts` — then resolved
+        // against the monorepo root.
+        //
+        // Only this branch was affected, which is why it survived: the fast path
+        // fires exactly when the script is a SINGLE `gjsify <subcommand>`, so a
+        // compound script (`a && b`) took the shell path and worked. Measured on
+        // the two consumers: bauplaner's cli scripts are all single commands and
+        // it documents the gap in its AGENTS.md, sidestepping it with
+        // `cd cli && …`; buchhaltung's one `-w` use is `build:meson`, a compound
+        // command, and it works.
+        if (cwd !== process.cwd())
+            process.chdir(cwd);
         // Track the failure LOCALLY rather than through `process.exitCode`.
         // Under GJS `process.exit()` is deferred (see the note below), so the
         // `process.exit(1)` that used to live in the catch returned instead of

package/lib/commands/self-update.d.ts

@@ -6,4 +6,31 @@ interface SelfUpdateOptions {
     skipDeps?: boolean;
 }
 export declare const selfUpdateCommand: Command<unknown, SelfUpdateOptions>;
+/** Verdict of the post-install "did this change what runs?" check. */
+export type PathVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Compare where PATH sends `binName` against the `binDir` we just linked into.
+ *
+ * Pure so the three outcomes are unit-testable off-host — the interesting two
+ * are exactly the ones a developer's own machine never produces, since a working
+ * install resolves to its own `binDir` by definition.
+ *
+ * Path comparison is case-INSENSITIVE on win32: `C:\Users\X\.local\bin` and
+ * `c:\users\x\.local\bin` are one directory there, and a case-sensitive compare
+ * would report a correct install as shadowed.
+ */
+export declare function verifyPathResolution(opts: {
+    binName: string;
+    binDir: string;
+    resolvedBin: string | null;
+    /** `null` is what `readCurrentVersion()` returns when it cannot tell. */
+    runningVersion: string | null | undefined;
+    targetVersion: string;
+    platform?: NodeJS.Platform;
+}): PathVerdict;
 export {};

package/lib/commands/self-update.js

@@ -11,12 +11,21 @@
 // `defaultGlobalLayout().prefix` (i.e. via `gjsify install -g` or via the
 // `install.mjs` bootstrap). Installs from `npm install -g @gjsify/cli` land
 // elsewhere and we don't try to chase them — we print a warning and exit.
+//
+// AND THE WARNING IS NOT ENOUGH ON ITS OWN (#1064). This command's whole job is
+// to change which binary the user's next `gjsify` runs, so success has to be
+// measured on PATH, not on the prefix it wrote. Reported from a Windows host:
+// the pre-install warning fired, the install succeeded, `Updated @gjsify/cli to
+// v0.31.0` printed — and the shell kept resolving a v0.26.0 npm-global install,
+// so the very next command re-hit the `dlx` EPERM fixed three releases earlier.
+// A silent no-op that reports success is worse than a clean failure, so the
+// post-link verification below is fatal.
 import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join, posix, resolve, win32 } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { fetchPackument } from '@gjsify/npm-registry';
 import { installPackages, makeProgressReporter } from '../utils/install-backend.js';
-import { defaultGlobalLayout, hasBundlerEngineInstalled, installGjsEnginePackages, linkGlobalBins, } from '../utils/install-global.js';
+import { defaultGlobalLayout, globalLayoutIsDefault, hasBundlerEngineInstalled, installGjsEnginePackages, linkGlobalBins, resolveBinOnPath, } from '../utils/install-global.js';
 const PACKAGE_NAME = '@gjsify/cli';
 export const selfUpdateCommand = {
     command: 'self-update',
@@ -157,6 +166,27 @@ export const selfUpdateCommand = {
                 console.log(`  • ${bin.link}  →  ${bin.target}`);
             }
         }
+        // Did the update change what `gjsify` RUNS? Everything above only proves
+        // we wrote the prefix. See the #1064 note at the top of this file.
+        //
+        // Only for the user's OWN layout: a caller that redirected the install
+        // with GJSIFY_GLOBAL_PREFIX/_BIN_DIR manages placement itself, and
+        // telling a harness that installed into a temp prefix "your PATH still
+        // points elsewhere" is true and useless.
+        if (globalLayoutIsDefault()) {
+            const verdict = verifyPathResolution({
+                binName: BIN_NAME,
+                binDir: layout.binDir,
+                resolvedBin: resolveBinOnPath(BIN_NAME),
+                runningVersion: currentVersion,
+                targetVersion: target,
+            });
+            if (!verdict.ok) {
+                console.error(`\nInstalled ${PACKAGE_NAME} v${target} at ${layout.prefix}`);
+                console.error(verdict.message);
+                return process.exit(1);
+            }
+        }
         console.log(`\nUpdated ${PACKAGE_NAME} to v${target}.`);
         if (pullDeps) {
             console.log('Runtime dependencies were resolved alongside the bundle.');
@@ -166,6 +196,51 @@ export const selfUpdateCommand = {
         }
     },
 };
+/** The bin `@gjsify/cli` installs, and the name a user types. */
+const BIN_NAME = 'gjsify';
+/**
+ * Compare where PATH sends `binName` against the `binDir` we just linked into.
+ *
+ * Pure so the three outcomes are unit-testable off-host — the interesting two
+ * are exactly the ones a developer's own machine never produces, since a working
+ * install resolves to its own `binDir` by definition.
+ *
+ * Path comparison is case-INSENSITIVE on win32: `C:\Users\X\.local\bin` and
+ * `c:\users\x\.local\bin` are one directory there, and a case-sensitive compare
+ * would report a correct install as shadowed.
+ */
+export function verifyPathResolution(opts) {
+    const platform = opts.platform ?? process.platform;
+    // The TARGET platform's path module, never the host's — see `pathFor` in
+    // `utils/install-global.ts` for why (`resolve('C:\\x')` on posix is wrong).
+    const p = platform === 'win32' ? win32 : posix;
+    const norm = (v) => (platform === 'win32' ? p.resolve(v).toLowerCase() : p.resolve(v));
+    if (opts.resolvedBin === null) {
+        return {
+            ok: false,
+            message: `BUT nothing named \`${opts.binName}\` is on PATH, so the update cannot take effect.\n\n` +
+                `  Add the bin dir to PATH:\n    ${opts.binDir}`,
+        };
+    }
+    if (norm(p.dirname(opts.resolvedBin)) === norm(opts.binDir))
+        return { ok: true };
+    // Deliberately NOT split into "a rival install" vs "a transient runner"
+    // (npx/dlx, whose temp bin wins PATH for the length of the run). Both are the
+    // same fact — `gjsify` does not currently mean the tree we just wrote — and
+    // guessing which one it is would be a heuristic that can only be wrong. So
+    // the finding is stated and both remedies are offered.
+    const running = opts.runningVersion ? ` (v${opts.runningVersion})` : '';
+    return {
+        ok: false,
+        message: `BUT \`${opts.binName}\` on PATH resolves to\n    ${opts.resolvedBin}${running}\n` +
+            `which is NOT the install that was just updated, so the next \`${opts.binName}\`\n` +
+            `you run will not be v${opts.targetVersion}.\n\n` +
+            `  If that is another install, remove it (e.g. \`npm uninstall -g ${PACKAGE_NAME}\`)\n` +
+            `  or put ${opts.binDir} ahead of it on PATH.\n` +
+            `  If you ran this through npx/dlx, that temporary copy owns the name only for\n` +
+            `  this run — open a new shell and check \`${opts.binName} --version\`.`,
+    };
+}
 /**
  * Resolve the CLI's own `package.json#version`. Walks up from
  * `import.meta.url` (the bundle file under GJS, or `lib/index.js` under

package/lib/commands/showcase.d.ts

@@ -1,4 +1,6 @@
 import type { Command } from '../types/index.js';
+import { type Packument } from '@gjsify/npm-registry';
+import { type ExampleRuntime } from '../utils/runtimes.js';
 /**
  * Pinned invocations for the three runners that cache an unpinned bin.
  *
@@ -22,4 +24,16 @@ interface ShowcaseOptions {
     runtime?: string;
 }
 export declare const showcaseCommand: Command<unknown, ShowcaseOptions>;
+/**
+ * The pure half of {@link preflightDeclaredRuntimes}: pick the version whose
+ * declaration decides, and read it.
+ *
+ * Separate from the fetch so the fail-safe direction is unit-testable — that
+ * contract ("never fail a run that would have worked") is the only thing that
+ * makes a pre-install check safe, and it lives entirely in which branches return
+ * `undefined`.
+ *
+ * @param cliVersion the CLI's own version; `showcase` pins the showcase to it.
+ */
+export declare function declaredRuntimesFromPackument(packument: Packument, cliVersion: string | undefined): ExampleRuntime[] | null | undefined;
 export {};

package/lib/commands/showcase.js

@@ -4,6 +4,8 @@ import { createRequire } from 'node:module';
 import { dirname } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { ensurePkgDir } from './dlx.js';
+import { fetchPackument } from '@gjsify/npm-registry';
+import { loadNpmrc } from '../utils/load-npmrc.js';
 import { parseSpec } from '../utils/parse-spec.js';
 import { resolveNodeEntry } from '../utils/resolve-gjs-entry.js';
 import { runRuntimeBundle } from '../utils/run-node.js';
@@ -212,15 +214,9 @@ export const showcaseCommand = {
  */
 async function resolveShowcaseDir(showcase, cliVersion, extraSpecs = []) {
     // Local-first: a workspace showcase resolves via its own package name.
-    try {
-        const req = createRequire(import.meta.url);
-        const localPkgJson = req.resolve(`${showcase.packageName}/package.json`);
-        if (existsSync(localPkgJson))
-            return dirname(localPkgJson);
-    }
-    catch {
-        // Not resolvable locally — fall through to dlx install.
-    }
+    const local = resolveLocalShowcaseDir(showcase);
+    if (local)
+        return local;
     const spec = cliVersion ? `${showcase.packageName}@${cliVersion}` : showcase.packageName;
     const { pkgDir } = await ensurePkgDir(parseSpec(spec), {
         verbose: false,
@@ -230,6 +226,117 @@ async function resolveShowcaseDir(showcase, cliVersion, extraSpecs = []) {
     });
     return pkgDir;
 }
+/**
+ * The LOCAL (workspace / node_modules) directory of a showcase, or `null`.
+ *
+ * Factored out because two callers need the same question answered: the resolver
+ * below, and the pre-flight, which must know whether an install is even going to
+ * happen before deciding to spend a registry request avoiding it.
+ */
+function resolveLocalShowcaseDir(showcase) {
+    try {
+        const req = createRequire(import.meta.url);
+        const localPkgJson = req.resolve(`${showcase.packageName}/package.json`);
+        if (existsSync(localPkgJson))
+            return dirname(localPkgJson);
+    }
+    catch {
+        // Not resolvable locally — the caller falls back to a dlx install.
+    }
+    return null;
+}
+/**
+ * The batteries-included GTK runtime to add to a showcase's dlx tree, if any.
+ *
+ * WHY THE LAUNCHER AND NOT THE PACKAGE. `@gjsify/node-gi` deliberately declares
+ * no bundle: making one its dependency is #910, where a from-source addon met a
+ * foreign GTK and produced wrong method entries and a 29-minute timeout. The rule
+ * that replaced it is "whoever SHIPS an app declares the bundle" — and for a
+ * showcase, the shipper is this command, which assembles the dlx tree. Same
+ * reasoning, same place, as the `@gjsify/node-gi` spec beside it.
+ *
+ * Only where a system GTK is not a given, which is exactly where a bundle is
+ * built: Windows has none at all (#1063 — every `gi://` showcase died in
+ * `ERR_DLOPEN_FAILED` on a clean host), and macOS has Homebrew's, which is
+ * measurably not findable. On Linux the distribution's GTK is the tested
+ * combination and node-gi's own policy prefers it, so pulling ~80 MB nobody would
+ * use would be waste.
+ *
+ * The tree only ever holds the PUBLISHED PREBUILD, never a from-source build, so
+ * the mismatch #910 hit cannot arise here by construction.
+ */
+function gtkRuntimeSpecs(cliVersion) {
+    const target = `${process.platform}-${process.arch}`;
+    const shipped = ['win32-x64', 'darwin-arm64', 'darwin-x64'];
+    if (!shipped.includes(target))
+        return [];
+    const name = `@gjsify/gtk-runtime-${target}`;
+    return [cliVersion ? `${name}@${cliVersion}` : name];
+}
+/**
+ * Read a showcase's declared runtimes from the REGISTRY, with no install (#1069).
+ *
+ * WHY. `--runtime node` on a gjs-only showcase used to resolve and download the
+ * whole dlx tree — plus the pinned native `@gjsify/node-gi` bridge, added
+ * BECAUSE `--runtime node` was requested — and only then read the declaration
+ * that rejects the run. Measured for `adwaita-storybook`: a 310 KB showcase with
+ * no runtime deps, and 3.77 MB of `node-gi` fetched to support a runtime the
+ * package was about to refuse. The full packument carries
+ * `gjsify.example.runtimes` verbatim, so one metadata GET answers it.
+ *
+ * NOT solved by putting `runtimes` in `showcases.json`: that is a second copy of
+ * a declaration the package already owns, maintained by hand. See the
+ * `needsWebgl` post-mortem in `utils/discover-showcases.ts` — "a field nobody
+ * reads is a field nobody maintains", proven by a showcase that shipped
+ * `"needsWebgl": false` while its engine was WebGL2-only.
+ *
+ * FAIL-SAFE DIRECTION, and it is the whole contract: this may only ever turn a
+ * run that WOULD have failed into a faster failure. It must never fail a run
+ * that would have worked, so every uncertain branch — offline, unpublished
+ * version, missing field, malformed document — returns `undefined` and lets the
+ * install proceed to the authoritative on-disk check.
+ *
+ * @returns the declared list, `null` for a package that declares none
+ *   (unconstrained), or `undefined` when the question could not be answered.
+ */
+async function preflightDeclaredRuntimes(showcase, cliVersion) {
+    try {
+        // `fullMetadata` is REQUIRED: the abbreviated (corgi) document omits
+        // custom fields, so `gjsify.example` is simply absent there — the same
+        // shape as the `libc` note in `@gjsify/npm-registry`'s PackumentVersion.
+        const packument = await fetchPackument(showcase.packageName, {
+            npmrc: await loadNpmrc(process.cwd()),
+            fullMetadata: true,
+        });
+        return declaredRuntimesFromPackument(packument, cliVersion);
+    }
+    catch {
+        // Offline, private registry, auth failure, 404 — all "cannot say".
+        return undefined;
+    }
+}
+/**
+ * The pure half of {@link preflightDeclaredRuntimes}: pick the version whose
+ * declaration decides, and read it.
+ *
+ * Separate from the fetch so the fail-safe direction is unit-testable — that
+ * contract ("never fail a run that would have worked") is the only thing that
+ * makes a pre-install check safe, and it lives entirely in which branches return
+ * `undefined`.
+ *
+ * @param cliVersion the CLI's own version; `showcase` pins the showcase to it.
+ */
+export function declaredRuntimesFromPackument(packument, cliVersion) {
+    // A pinned version that is NOT published is "cannot say", never "ask latest":
+    // a different version's declaration is a different answer, and a wrong
+    // "unsupported" is precisely the failure this must not introduce. (A dev or
+    // pre-release CLI is the normal way to reach this.)
+    const version = cliVersion ?? packument['dist-tags']?.latest;
+    const entry = version ? packument.versions?.[version] : undefined;
+    if (!entry)
+        return undefined;
+    return readDeclaredRuntimes(entry);
+}
 /**
  * Run a showcase on a non-gjs runtime (node/bun/deno). Resolves the package,
  * validates it against the showcase's `gjsify.example.runtimes` declaration
@@ -237,6 +344,19 @@ async function resolveShowcaseDir(showcase, cliVersion, extraSpecs = []) {
  * node), resolves its `--app node` bundle and launches it via the shared runner.
  */
 async function runShowcaseOnRuntime(showcase, runtime, cliVersion) {
+    // PRE-FLIGHT, before anything is downloaded. Only for the dlx path: a local
+    // showcase resolves with no network and no install, so there is nothing to
+    // pre-empt there and the on-disk check below is already free.
+    if (resolveLocalShowcaseDir(showcase) === null) {
+        const preflight = await preflightDeclaredRuntimes(showcase, cliVersion);
+        if (preflight !== undefined) {
+            const support = checkRuntimeSupported(runtime, preflight, showcase.name);
+            if (!support.ok) {
+                console.error(support.message);
+                return process.exit(1);
+            }
+        }
+    }
     let pkgDir;
     try {
         // `@gjsify/node-gi` is the `gi://` bridge the `--app node` bundle
@@ -248,7 +368,7 @@ async function runShowcaseOnRuntime(showcase, runtime, cliVersion) {
         // it supplies the bridge. Pinned to the CLI's version like the showcase
         // itself, so the bridge and the bundle move together.
         const nodeGiSpec = cliVersion ? `@gjsify/node-gi@${cliVersion}` : '@gjsify/node-gi';
-        pkgDir = await resolveShowcaseDir(showcase, cliVersion, [nodeGiSpec]);
+        pkgDir = await resolveShowcaseDir(showcase, cliVersion, [nodeGiSpec, ...gtkRuntimeSpecs(cliVersion)]);
     }
     catch (err) {
         console.error(`Could not resolve showcase "${showcase.name}": ${err.message}`);

package/lib/commands/test.js

@@ -194,10 +194,10 @@ async function runTestBundle(outfile, runtime) {
         return;
     }
     await new Promise((resolvePromise, reject) => {
-        // `nodeBinary()`, never a bare `'node'`: under the committed GJS bundle
-        // `process.execPath` is the bundle itself, and on a host without Node a
-        // bare literal dies `spawn node ENOENT` — which is how a fully passing
-        // GJS suite was reported as a failed run.
+        // `nodeBinary()`, never a bare `'node'`: under GJS `process.execPath` is
+        // the `gjs` interpreter, which cannot run a `--app node` bundle, and on a
+        // host without Node a bare literal dies `spawn node ENOENT` — which is
+        // how a fully passing GJS suite was reported as a failed run.
         const child = spawn(nodeBinary(), [outfile], { stdio: 'inherit' });
         child.on('error', reject);
         child.on('exit', (code) => {

package/lib/commands/tsc.js

@@ -22,6 +22,10 @@ import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { detectNativePackages, buildNativeEnv } from '../utils/detect-native-packages.js';
+import { isOnPath } from '../utils/check-system-deps.js';
+import { existsSync } from 'node:fs';
+import { forceExit } from '../utils/force-exit.js';
+import { nodeBinary } from '../utils/run-node.js';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
 export const tscCommand = {
     command: 'tsc [tscArgs..]',
@@ -104,9 +108,12 @@ 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`).');
-            // `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);
+            // `return` — the handler must not fall through and try to spawn a
+            // compiler that is not there. `forceExit` and not `process.exit`
+            // because the latter is idle-scheduled under GJS, and NOTHING here
+            // armed a main loop to deliver it: the process would reach natural
+            // shutdown and report 0 while printing the message above.
+            return forceExit(1);
         }
         // Mirror `gjsify run`'s native-env composition so any future
         // typescript-the-bundle code path that reaches a native bridge
@@ -118,13 +125,54 @@ export const tscCommand = {
             ...process.env,
             ...nativeEnv,
         };
-        // Run upstream `typescript` under this Node — the Node-only fallback.
+        // Run upstream `typescript` under Node — the Node fallback.
+        //
+        // `nodeBinary()`, NEVER a bare `process.execPath`: under the GJS bundle
+        // `process.execPath` is the GJS interpreter (`/proc/self/exe` →
+        // `gjs-console`), so `spawn(process.execPath, [tsc.js])` hands
+        // TypeScript's CommonJS CLI to GJS, which dies on the first `module`
+        // reference — or, where execPath resolves to a gjsify launcher instead,
+        // re-executes the CLI with the tsc entry as an unknown argument. Both
+        // were reached from a COLD tree: `@gjsify/tsc`'s `dist/tsc.gjs.mjs` is a
+        // build output, and `build:infra` builds `@gjsify/create-app` (its first
+        // `gjsify tsc` caller) long before `@gjsify/tsc` produces it, so the
+        // fallback below is the NORMAL path there, not an edge case.
+        // `run-node.ts` owns the one correct answer; every other spawn site in
+        // this CLI already routes through it.
         const runNodeTsc = () => {
-            const child = spawn(process.execPath, [nodeTscPath, ...tscArgs], { env, stdio: 'inherit' });
-            child.on('close', (code) => process.exit(code ?? 1));
+            const nodeBin = nodeBinary();
+            // PRE-FLIGHT, deliberately NOT the spawn's `'error'` event.
+            //
+            // Under the GJS bundle that event is not delivered when the program
+            // is missing: the handler below never runs, the command returns
+            // normally, and `gjsify tsc` exits **0 in total silence** having
+            // compiled nothing. Measured in CI by `tests/e2e/tsc-node-fallback`'s
+            // "FAILS LOUDLY …" case, whose assertion printed an EMPTY captured
+            // output — no stderr at all, so nothing had reported anything.
+            //
+            // Deciding it here, synchronously, is what makes the failure
+            // reportable: the exit happens on the caller's own stack rather than
+            // in a continuation that may never be scheduled.
+            const runnable = nodeBin.includes('/') || nodeBin.includes('\\') ? existsSync(nodeBin) : isOnPath(nodeBin);
+            if (!runnable) {
+                console.error(`gjsify tsc: the @gjsify/tsc GJS bundle is unavailable and \`${nodeBin}\` cannot be run, ` +
+                    'so upstream `typescript` cannot run either.');
+                console.error('  Build the bundle with: gjsify workspace @gjsify/tsc build');
+                console.error('  …or install Node.js so the upstream `typescript` fallback can be spawned.');
+                return forceExit(1);
+            }
+            const child = spawn(nodeBin, [nodeTscPath, ...tscArgs], { env, stdio: 'inherit' });
+            child.on('close', (code) => forceExit(code ?? 1));
             child.on('error', (err) => {
-                console.error(`gjsify tsc (node typescript): ${err.message}`);
-                process.exit(1);
+                if (err.code === 'ENOENT') {
+                    console.error('gjsify tsc: the @gjsify/tsc GJS bundle is unavailable and `node` is not on PATH, ' +
+                        'so upstream `typescript` cannot run either.');
+                    console.error('  Build the bundle with: gjsify workspace @gjsify/tsc build');
+                }
+                else {
+                    console.error(`gjsify tsc (node typescript): ${err.message}`);
+                }
+                forceExit(1);
             });
         };
         // Prefer GJS — the Node-free @gjsify/tsc bundle — when it resolves. If
@@ -144,7 +192,7 @@ export const tscCommand = {
                 child.on('close', (code) => {
                     if (gjsSpawnFailed)
                         return;
-                    process.exit(code ?? 1);
+                    forceExit(code ?? 1);
                 });
                 child.on('error', (err) => {
                     gjsSpawnFailed = true;
@@ -155,11 +203,11 @@ export const tscCommand = {
                     else if (err.code === 'ENOENT') {
                         console.error('gjsify tsc: `gjs` not found on PATH and no npm `typescript` fallback.');
                         console.error('  Install GJS (e.g. `dnf install gjs`), or add `typescript` to the project.');
-                        process.exit(1);
+                        forceExit(1);
                     }
                     else {
                         console.error(`gjsify tsc: ${err.message}`);
-                        process.exit(1);
+                        forceExit(1);
                     }
                 });
                 // Never resolves naturally — process.exit() above terminates the

package/lib/commands/workspace.js

@@ -24,6 +24,7 @@ import { buildDependencyGraph, discoverWorkspaces, topologicalSort } from '@gjsi
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
 import { BuildCacheRunner, buildCacheEnabledByEnv } from '../utils/build-cache.js';
 import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { usingSelfShim } from '../utils/gjsify-shim.js';
 import { suggestClosest } from '../utils/suggest.js';
 export const workspaceCommand = {
     command: 'workspace <name> <script> [args..]',
@@ -279,6 +280,18 @@ export function detectPackageManager() {
     // orchestration work in the Flatpak sandbox.
     if (isGjs())
         return 'gjsify';
+    // Same answer for a BOOTSTRAP CLI on Node, for a reason one level deeper
+    // than it looks. `ensureGjsifyShimOnPath()` puts a working `gjsify` ahead of
+    // the tree's `node_modules/.bin` — but npm RE-PREPENDS `node_modules/.bin`
+    // for every lifecycle script it starts, so delegating to npm here restores
+    // the tree's not-yet-built shim one level down and undoes the repair.
+    // Measured on a cold tree: `run build:infra` cleared its first clause and
+    // then died inside `npm run build` with `Cannot find module
+    // …/packages/infra/cli/lib/index.js`. Running the script ourselves keeps the
+    // bootstrap CLI's identity all the way down — which is exactly what the GJS
+    // branch above already relies on, and why Linux CI never saw this.
+    if (usingSelfShim())
+        return 'gjsify';
     const ua = process.env.npm_config_user_agent ?? '';
     if (ua.startsWith('yarn/'))
         return 'yarn';