@gjsify/cli 0.17.0 → 0.19.0

package/lib/actions/build.d.ts

@@ -18,11 +18,22 @@ export declare class BuildAction {
     private parseGlobalsValue;
     /**
      * Resolve the `--globals` CLI list into a pre-computed inject stub path
-     * that the orchestrator appends to its input list. Only runs for
-     * `--app gjs` — Node and browser builds rely on native globals.
+     * that the orchestrator appends to its input list. Runs for `--app gjs`
+     * AND `--app node`: on gjs the registers install our polyfills over the
+     * bare GJS runtime; on node an EXPLICIT list is the reverse bridge's
+     * DOM-surface request (a genuine GJS source built via `@gjsify/node-gi`
+     * needs the same `@gjsify/*` registers — document, HTMLCanvasElement, … —
+     * it gets under `--app gjs`, backed by gi:// through node-gi). Browser
+     * builds rely on native globals.
      *
-     * Used only for the explicit-only path (no `auto` token in the value).
-     * The auto path is handled in `buildApp` via the iterative multi-pass build.
+     * Node is EXPLICIT-ONLY by design: plain `--globals auto` never injects
+     * web/dom registers into a node bundle (cross-platform packages' node
+     * builds must stay loadable on plain Node without node-gi), so the
+     * `@gjsify/empty` routing is only lifted when the USER names the globals.
+     *
+     * Used for the explicit-only path (no `auto` token) and, on node, for the
+     * `auto,<extras>` extras. The gjs auto path is handled in `buildApp` via
+     * the iterative multi-pass build.
      */
     private resolveGlobalsInject;
     /**

package/lib/actions/build.js

@@ -207,21 +207,38 @@ export class BuildAction {
     }
     /**
      * Resolve the `--globals` CLI list into a pre-computed inject stub path
-     * that the orchestrator appends to its input list. Only runs for
-     * `--app gjs` — Node and browser builds rely on native globals.
+     * that the orchestrator appends to its input list. Runs for `--app gjs`
+     * AND `--app node`: on gjs the registers install our polyfills over the
+     * bare GJS runtime; on node an EXPLICIT list is the reverse bridge's
+     * DOM-surface request (a genuine GJS source built via `@gjsify/node-gi`
+     * needs the same `@gjsify/*` registers — document, HTMLCanvasElement, … —
+     * it gets under `--app gjs`, backed by gi:// through node-gi). Browser
+     * builds rely on native globals.
      *
-     * Used only for the explicit-only path (no `auto` token in the value).
-     * The auto path is handled in `buildApp` via the iterative multi-pass build.
+     * Node is EXPLICIT-ONLY by design: plain `--globals auto` never injects
+     * web/dom registers into a node bundle (cross-platform packages' node
+     * builds must stay loadable on plain Node without node-gi), so the
+     * `@gjsify/empty` routing is only lifted when the USER names the globals.
+     *
+     * Used for the explicit-only path (no `auto` token) and, on node, for the
+     * `auto,<extras>` extras. The gjs auto path is handled in `buildApp` via
+     * the iterative multi-pass build.
      */
     async resolveGlobalsInject(app, globals, verbose) {
-        if (app !== 'gjs')
+        if (app !== 'gjs' && app !== 'node')
             return undefined;
         if (!globals)
             return undefined;
         const registerPaths = resolveGlobalsList(globals);
         if (registerPaths.size === 0)
             return undefined;
-        const injectPath = await writeRegisterInjectFile(registerPaths, process.cwd());
+        // On `--app node` (the reverse bridge) the injected register bodies must
+        // OVERRIDE the runtime-native web globals gjsify owns (the `fetch`
+        // family — undici rejects the root-relative `/res/...` asset paths a GJS
+        // app uses). See writeRegisterInjectFile / REVERSE_BRIDGE_NATIVE_OVERRIDE_IDENTS.
+        const injectPath = await writeRegisterInjectFile(registerPaths, process.cwd(), {
+            reverseBridgeOverride: app === 'node',
+        });
         if (verbose && injectPath) {
             console.debug(`[gjsify] globals: injected ${registerPaths.size} register module(s) from --globals ${globals}`);
         }
@@ -517,6 +534,17 @@ export class BuildAction {
             }, pluginOpts, gjsifyPluginFactory, bundleToChunks);
             if (needsGiGlobals)
                 pluginOpts.nodeGiGlobalsInject = true;
+            // Explicit extras on a node build (`--globals auto,dom,…`) are the
+            // reverse bridge's DOM-surface request: inject the SAME register
+            // modules the gjs target would for those identifiers, so a genuine
+            // GJS source (an Excalibur/WebGLBridge app) gets document /
+            // HTMLCanvasElement / matchMedia / … on Node via node-gi. The
+            // orchestrator lifts the `@gjsify/empty` register routing only when
+            // this inject stub is present (see app/node.ts) — plain `auto`
+            // node builds are byte-unchanged.
+            if (extras) {
+                pluginOpts.autoGlobalsInject = await this.resolveGlobalsInject(app, extras, verbose);
+            }
         }
         else if (extras) {
             pluginOpts.autoGlobalsInject = await this.resolveGlobalsInject(app, extras, verbose);

package/lib/cli-app.js

@@ -21,23 +21,31 @@ import { fileURLToPath } from 'node:url';
 import yargs from 'yargs';
 import { buildCommand as build, testCommand as test, runCommand as run, infoCommand as info, systemCheckCommand as systemCheck, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, gsettingsCommand as gsettings, flatpakCommand as flatpak, dlxCommand as dlx, installCommand as install, foreachCommand as foreach, workspaceCommand as workspace, packCommand as pack, publishCommand as publish, whoamiCommand as whoami, loginCommand as login, logoutCommand as logout, trustCommand as trust, onboardCommand as onboard, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, uninstallCommand as uninstall, formatCommand as format, lintCommand as lint, fixCommand as fix, upgradeCommand as upgrade, barrelsCommand as barrels, tscCommand as tsc, affectedCommand as affected, storybookCommand as storybook, debugCommand as debug, browseCommand as browse, } from './commands/index.js';
 import { APP_NAME } from './constants.js';
-import { isNode } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { isBun, isDeno, isNode, gjsSystemVersion } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { ensureGjsifyShimOnPath } from './utils/gjsify-shim.js';
-// Detect which runtime is executing the CLI (GJS or Node.js).
-// GJS MUST be checked first because @gjsify/process sets
-// `process.versions.node = '20.0.0'` for compatibility — a plain
-// `process.versions.node` check would be a false Node positive under GJS.
+// Detect which runtime is executing the CLI (GJS, Node.js, Bun or Deno) for the
+// help epilogue. Bun and Deno MUST be checked before Node because both — like
+// 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 sys = globalThis.imports?.system;
-        if (sys?.version !== undefined) {
-            const v = Number(sys.version);
+        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 */
     }
+    if (isBun()) {
+        const version = globalThis.Bun?.version ?? process.versions.bun;
+        return `Bun ${version ?? ''}`.trim();
+    }
+    if (isDeno()) {
+        const version = globalThis.Deno?.version?.deno;
+        return `Deno ${version ?? ''}`.trim();
+    }
     if (isNode()) {
         return `Node.js ${process.version}`;
     }

package/lib/commands/build.js

@@ -39,11 +39,17 @@ export const buildCommand = {
             default: false,
         })
             .option('app', {
-            description: 'Use this if you want to build an application, the platform node is usually only used for tests',
+            description: 'Build target for an application. Defaults to the target of the HOST runtime running the CLI: gjs when run under gjs, node when run under node/bun/deno (both consume the --app node bundle). Set `gjsify.app` in package.json#gjsify to override the host default.',
             type: 'string',
             choices: ['gjs', 'node', 'browser', 'nativescript'],
             normalize: true,
-            default: 'gjs',
+            // No yargs `default: 'gjs'` — a yargs default is
+            // indistinguishable from a user-set value and would clobber
+            // `package.json#gjsify.app` in config.ts (same footgun as
+            // `globals`/`entryPoints`). The host-derived fallback is applied
+            // post-merge in `Config.forBuild`: CLI flag > config file > host
+            // default (`buildAppForRuntime(hostRuntime())`).
+            defaultDescription: 'host runtime target (gjs on gjs, else node)',
         })
             .option('format', {
             description: 'Override the default output format',
@@ -160,7 +166,11 @@ export const buildCommand = {
         const action = new BuildAction(configData);
         await action.start({
             library: args.library,
-            app: args.app,
+            // `configData.app` carries the CLI-flag > config-file > host-default
+            // resolution done in `Config.forBuild` (the yargs `--app` default was
+            // dropped so the config-file value survives). `BuildAction.start`
+            // falls back to 'gjs' only if this is somehow undefined.
+            app: configData.app,
             watch: args.watch,
         });
     },

package/lib/commands/check.js

@@ -16,22 +16,11 @@
 // (since the typescript-check binding is positional `[paths..]`).
 import { spawn, spawnSync } from 'node:child_process';
 import { prefixLines } from '../utils/prefixed-output.js';
-import { existsSync, readFileSync } from 'node:fs';
+import { readPackageJson } from '../utils/pkg-json.js';
 import { join } from 'node:path';
 import { cpus } from 'node:os';
 import { discoverWorkspaces, filterWorkspaces } from '@gjsify/workspace';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
-function readPackageJson(dir) {
-    const path = join(dir, 'package.json');
-    if (!existsSync(path))
-        return null;
-    try {
-        return JSON.parse(readFileSync(path, 'utf-8'));
-    }
-    catch {
-        return null;
-    }
-}
 /**
  * Run a single workspace's `check` script. Returns the exit code; non-zero
  * indicates failure. Output is forwarded to the parent's stdout/stderr,
@@ -108,7 +97,7 @@ export const checkCommand = {
         // through gjsify so the command surface stays uniform with format/
         // lint/fix.
         if (workspaceRoot && cwd !== workspaceRoot) {
-            const pkg = readPackageJson(cwd);
+            const pkg = readPackageJson(join(cwd, 'package.json'));
             if (pkg?.scripts?.check) {
                 if (args.verbose) {
                     console.log(`[check] cwd=${cwd}  → npm run check`);

package/lib/commands/dlx.d.ts

@@ -1,4 +1,5 @@
 import type { Command } from '../types/index.js';
+import { type ParsedSpec } from '../utils/parse-spec.js';
 interface DlxOptions {
     spec: string;
     binOrArg?: string;
@@ -10,4 +11,20 @@ interface DlxOptions {
     registry?: string;
 }
 export declare const dlxCommand: Command<unknown, DlxOptions>;
+export interface EnsureOpts {
+    verbose: boolean;
+    registry?: string;
+    cacheMaxAge: number;
+    frozen: boolean;
+}
+/**
+ * Resolve (installing + caching when remote) the on-disk directory of a package
+ * spec — the shared "get me this package's files" step behind `gjsify dlx` and
+ * `gjsify showcase`. Local paths resolve directly; remote specs install into the
+ * per-key dlx cache (atomic symlink-swap) and reuse a fresh cache entry.
+ */
+export declare function ensurePkgDir(parsed: ParsedSpec, opts: EnsureOpts): Promise<{
+    pkgDir: string;
+    cachedPkgName: string | null;
+}>;
 export {};

package/lib/commands/dlx.js

@@ -96,7 +96,13 @@ export const dlxCommand = {
         await runGjsBundle(entry.bundlePath, extraArgs, { exitOnSuccess: true });
     },
 };
-async function ensurePkgDir(parsed, opts) {
+/**
+ * Resolve (installing + caching when remote) the on-disk directory of a package
+ * spec — the shared "get me this package's files" step behind `gjsify dlx` and
+ * `gjsify showcase`. Local paths resolve directly; remote specs install into the
+ * per-key dlx cache (atomic symlink-swap) and reuse a fresh cache entry.
+ */
+export async function ensurePkgDir(parsed, opts) {
     if (parsed.kind === 'local') {
         return { pkgDir: parsed.path, cachedPkgName: null };
     }

package/lib/commands/install.js

@@ -31,12 +31,14 @@ import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, rmSync, syml
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawn, spawnSync } from 'node:child_process';
+import { gjsExit } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { discoverWorkspaces } from '@gjsify/workspace';
 import { buildInstallCommand, detectPackageManager, runMinimalChecks } from '../utils/check-system-deps.js';
 import { detectNativePackages } from '../utils/detect-native-packages.js';
 import { installPackages, makeProgressReporter } from '../utils/install-backend.js';
 import { atomicWriteStrict } from '../utils/install-cache-fs.js';
 import { acquireInstallLock } from '../utils/install-lock.js';
+import { nodeBinary } from '../utils/run-node.js';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
 import { binDirOnPath, defaultGlobalLayout, installGjsEnginePackages, linkGlobalBins, specToPackageName, } from '../utils/install-global.js';
 import { addDependencyEntry, defaultRangeFromVersion, parseSpec, projectSpecsFromPackageJson, readPackageJson, writePackageJson, } from '../utils/pkg-json-edit.js';
@@ -247,11 +249,8 @@ function isAbortedFromOverallTimeout(err) {
  */
 function forceExit(code) {
     process.exitCode = code;
-    const gjs = globalThis.imports;
-    if (gjs?.system?.exit) {
-        gjs.system.exit(code);
+    if (gjsExit(code))
         return;
-    }
     process.exit(code);
 }
 const CLI_PACKAGE_NAME = '@gjsify/cli';
@@ -1221,7 +1220,13 @@ function maybeInstallGitHooks() {
     if (!existsSync(join(cwd, '.git')))
         return;
     try {
-        const result = spawnSync(process.execPath, [scriptPath, '--quiet'], {
+        // `nodeBinary()`, NOT `process.execPath`: under the committed GJS bundle
+        // `process.execPath` is `gjs`, so `spawnSync(process.execPath, [script])`
+        // ran `gjs cli.gjs.mjs install-git-hooks.mjs` (wrong argv). The hook
+        // installer is a plain Node ESM script; run it with a real node binary
+        // (PATH `node` under GJS, the current node otherwise). Best-effort —
+        // wrapped in try/catch, so a missing node just warns and continues.
+        const result = spawnSync(nodeBinary(), [scriptPath, '--quiet'], {
             cwd,
             stdio: 'inherit',
             env: process.env,

package/lib/commands/run.d.ts

@@ -3,6 +3,7 @@ interface RunOptions {
     target: string;
     args: string[];
     workspace?: string;
+    runtime?: string;
 }
 export declare const runCommand: Command<unknown, RunOptions>;
 export {};

package/lib/commands/run.js

@@ -13,14 +13,16 @@
 // extension, or that resolves to an existing path on disk is treated
 // as a bundle file. Everything else is a script name. Users who want
 // to disambiguate can pass `./<file>` explicitly.
-import { statSync } from 'node:fs';
+import { readFileSync, statSync } from 'node:fs';
 import { basename, delimiter, join, resolve } from 'node:path';
 import { spawn } from 'node:child_process';
 import { runGjsBundle } from '../utils/run-gjs.js';
+import { runRuntimeBundle } from '../utils/run-node.js';
 import { readPackageJson } from '../utils/pkg-json-edit.js';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
 import { discoverWorkspaces } from '@gjsify/workspace';
-import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { isGjs, hostRuntime } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { EXAMPLE_RUNTIMES, isExampleRuntime, readDeclaredRuntimes, checkRuntimeSupported, } from '../utils/runtimes.js';
 export const runCommand = {
     command: 'run <target> [args..]',
     description: 'Run a script from package.json (yarn-run-style) or a GJS bundle file. If <target> resolves to a file on disk (or has a path-like prefix), it is launched via gjs with LD_LIBRARY_PATH + GI_TYPELIB_PATH set for native packages. Otherwise it is looked up in the current package.json `scripts`.',
@@ -45,6 +47,18 @@ export const runCommand = {
         alias: 'w',
         type: 'string',
         description: 'Run <target> as a script in the named workspace (by name or path), like `npm run <script> -w <name>`.',
+    })
+        .option('runtime', {
+        // Runtime selector for a BUNDLE FILE. `gjs` (default) launches
+        // the `--app gjs` bundle via `gjs -m`; node/bun/deno launch the
+        // `--app node` bundle on that runtime (Node-API is their common
+        // ABI, so bun/deno reuse the same node bundle). Declaring it here
+        // means yargs captures the flag instead of forwarding it to the
+        // target (this command routes unknown flags to the child).
+        // Passing --runtime FORCES file mode.
+        type: 'string',
+        choices: EXAMPLE_RUNTIMES,
+        description: 'Runtime to launch a bundle FILE on: gjs (default, `--app gjs` bundle) | node | bun | deno (the `--app node` bundle). Forces file mode.',
     })
         // Pass-through runner: the TARGET owns its whole flag namespace, so
         // disable gjsify's own `--version` / `--help` for THIS command. Without
@@ -85,6 +99,24 @@ export const runCommand = {
         const positionalArgs = args.args ?? [];
         const doubleDashArgs = (args['--'] ?? []).filter((v) => typeof v === 'string');
         const extraArgs = [...positionalArgs, ...doubleDashArgs];
+        // `--runtime <gjs|node|bun|deno>` (explicit) → run a BUNDLE FILE on the
+        // chosen runtime. This FORCES file mode: the runtime selector only makes
+        // sense for a prebuilt bundle, and it must beat the script-name lookup.
+        // gjs → `runGjsBundle` (gjs -m); node/bun/deno → `runRuntimeBundle` (the
+        // `--app node` bundle; bun/deno reuse it). Default gjs keeps back-compat.
+        const runtimeArg = args.runtime;
+        if (typeof runtimeArg === 'string' && runtimeArg.length > 0) {
+            if (typeof args.workspace === 'string' && args.workspace.length > 0) {
+                console.error('gjsify run: --runtime cannot be combined with --workspace (file mode vs script mode).');
+                return process.exit(1);
+            }
+            if (!isExampleRuntime(runtimeArg)) {
+                console.error(`gjsify run: unknown --runtime "${runtimeArg}" (expected: ${EXAMPLE_RUNTIMES.join(', ')}).`);
+                return process.exit(1);
+            }
+            await runTargetOnRuntime(runtimeArg, target, extraArgs);
+            return;
+        }
         // `-w <name>` (npm/yarn parity): run <target> as a script in the named
         // workspace's directory rather than the current one. Never file mode.
         if (typeof args.workspace === 'string' && args.workspace.length > 0) {
@@ -101,14 +133,87 @@ export const runCommand = {
         const hasScript = pkg?.scripts && typeof pkg.scripts[target] === 'string';
         if (!hasScript && looksLikeFile(target)) {
             const file = resolve(target);
-            // Terminal call — exit on success, or the GJS main loop parks
+            // The default runtime for a bare `gjsify run <file>` FOLLOWS the host
+            // runtime the CLI executes in: gjs (global install) → gjs; node/bun/
+            // deno (npx/bunx/deno) → that runtime. EXCEPTION: a `--app gjs` bundle
+            // can only run on gjs (its gi:// imports are externalized, there is no
+            // node-gi shim), so it is always launched on gjs regardless of the
+            // host — this keeps `gjsify run dist/index.gjs.js` working when the
+            // CLI itself runs under node (e.g. `gjsify foreach test` for the
+            // node-cli examples). Pass `--runtime` explicitly to override.
+            const host = hostRuntime();
+            const runtime = host === 'gjs' || isLikelyGjsBundle(file) ? 'gjs' : host;
+            // Terminal calls — exit on success, or the GJS main loop parks
             // this process forever (see RunGjsBundleOptions.exitOnSuccess).
-            await runGjsBundle(file, extraArgs, { exitOnSuccess: true });
+            if (runtime === 'gjs') {
+                await runGjsBundle(file, extraArgs, { exitOnSuccess: true });
+            }
+            else {
+                await runRuntimeBundle(runtime, file, extraArgs, { exitOnSuccess: true });
+            }
             return;
         }
         await runScript(target, extraArgs);
     },
 };
+/**
+ * Run a bundle-file `target` on `runtime`. Validates that the target looks like
+ * a file (the runtime selector is for prebuilt bundles, not script names) and,
+ * best-effort, that the cwd package's `gjsify.example.runtimes` declaration
+ * permits the runtime — turning "this showcase can't run on node yet" into a
+ * clean, actionable error instead of a deep bundle crash. gjs → `runGjsBundle`;
+ * node/bun/deno → `runRuntimeBundle` (the shared `--app node` launcher).
+ */
+async function runTargetOnRuntime(runtime, target, extraArgs) {
+    if (!looksLikeFile(target)) {
+        console.error(`gjsify run: --runtime ${runtime} needs a bundle FILE, but "${target}" is not a path.\n` +
+            `  Build first (e.g. \`gjsify build src/app.ts --app ${runtime === 'gjs' ? 'gjs' : 'node'} --outfile dist/app.${runtime === 'gjs' ? 'gjs' : 'node'}.mjs\`), then run the output file.`);
+        return process.exit(1);
+    }
+    // Best-effort declaration check against the cwd package (the example dir).
+    const pkg = readPackageJson(join(process.cwd(), 'package.json'));
+    const declared = readDeclaredRuntimes(pkg);
+    const support = checkRuntimeSupported(runtime, declared, pkg?.name ?? target);
+    if (!support.ok) {
+        console.error(`gjsify run: ${support.message}`);
+        return process.exit(1);
+    }
+    const file = resolve(target);
+    // Terminal call — exit on success (the GJS/GLib loop would otherwise park).
+    if (runtime === 'gjs') {
+        await runGjsBundle(file, extraArgs, { exitOnSuccess: true });
+    }
+    else {
+        await runRuntimeBundle(runtime, file, extraArgs, { exitOnSuccess: true });
+    }
+}
+/**
+ * Whether `file` is a `--app gjs` bundle (which can ONLY run on gjs — its
+ * `gi://` imports stay as external string literals and boots through a `gjs -m`
+ * shebang / `imports.system` stub). Used to keep such a bundle on gjs even when
+ * the host is node/bun/deno, so the host-following default in the bare-file run
+ * path never sends a gjs bundle to a runtime it cannot load.
+ *
+ * A `--app node` bundle (even a node-gi reverse-bridge one) rewrites `gi://` to
+ * `@gjsify/node-gi` and never keeps a `gi://` import literal, so it is NOT
+ * matched here and follows the host runtime.
+ */
+function isLikelyGjsBundle(file) {
+    // Fast path on the conventional `.gjs.js` / `.gjs.mjs` naming.
+    if (/\.gjs\.[mc]?js$/.test(file))
+        return true;
+    try {
+        // gi:// imports + the process/system stub are hoisted to the top of the
+        // bundle, so a bounded prefix is enough — bundles can be several MB.
+        const head = readFileSync(file, 'utf-8').slice(0, 65536);
+        return (head.startsWith('#!/usr/bin/env -S gjs') ||
+            /(?:from|import)\s*["']gi:\/\//.test(head) ||
+            /\bimports\.(?:gi|system)\b/.test(head));
+    }
+    catch {
+        return false;
+    }
+}
 function looksLikeFile(target) {
     if (target.startsWith('./') || target.startsWith('../') || target.startsWith('/'))
         return true;

package/lib/commands/showcase.d.ts

@@ -3,6 +3,7 @@ interface ShowcaseOptions {
     name?: string;
     json: boolean;
     list: boolean;
+    runtime?: string;
 }
 export declare const showcaseCommand: Command<unknown, ShowcaseOptions>;
 export {};

package/lib/commands/showcase.js

@@ -1,8 +1,14 @@
 import { discoverShowcases, findShowcase } from '../utils/discover-showcases.js';
 import { runMinimalChecks, detectPackageManager, buildInstallCommand } from '../utils/check-system-deps.js';
-import { spawn } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { ensurePkgDir } from './dlx.js';
+import { parseSpec } from '../utils/parse-spec.js';
+import { resolveNodeEntry } from '../utils/resolve-gjs-entry.js';
+import { runRuntimeBundle } from '../utils/run-node.js';
+import { hostRuntime } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { EXAMPLE_RUNTIMES, isExampleRuntime, readDeclaredRuntimes, checkRuntimeSupported, } from '../utils/runtimes.js';
 function readCliVersion() {
     try {
         const pkgUrl = new URL('../../package.json', import.meta.url);
@@ -30,6 +36,20 @@ export const showcaseCommand = {
         description: 'List available showcases',
         type: 'boolean',
         default: false,
+    })
+        .option('runtime', {
+        // Runtime selector, mirroring `gjsify storybook --runtime`. The
+        // default FOLLOWS the host runtime the CLI executes in (gjs under
+        // gjs, node under node/bun/deno). gjs runs the showcase's GJS
+        // bundle via `gjsify dlx`; node/bun/deno run its `--app node`
+        // bundle on that runtime. Validated against the showcase's
+        // declared `gjsify.example.runtimes` — a GTK-only showcase
+        // requested under node fails with a clear message, not a crash.
+        type: 'string',
+        choices: EXAMPLE_RUNTIMES,
+        default: hostRuntime(),
+        defaultDescription: 'host runtime (gjs on gjs, else node/bun/deno)',
+        description: 'Runtime to run the showcase on: gjs | node | bun | deno (default: the host runtime). node/bun/deno run its `--app node` bundle.',
     }),
     handler: async (args) => {
         // List mode: no name given, or --list flag
@@ -67,7 +87,12 @@ export const showcaseCommand = {
         if (!showcase) {
             console.error(`Unknown showcase: "${args.name}"`);
             console.error('Run "gjsify showcase" to list available showcases.');
-            process.exit(1);
+            // `return process.exit()`: a bare `process.exit()` does NOT halt
+            // synchronously under GJS (no atexit, GLib loop still armed), so
+            // execution would fall through to `showcase.packageName` below on an
+            // undefined `showcase` → throw racing the scheduled exit → the
+            // `m_should_exit` core dump. Returning halts the handler here.
+            return process.exit(1);
         }
         // System dependency check before delegating — only system libs (gjs,
         // gtk4, …). The showcase's npm deps (incl. `@gjsify/webgl` with the
@@ -88,11 +113,25 @@ export const showcaseCommand = {
             if (cmd) {
                 console.error(`\nInstall with:\n  ${cmd}`);
             }
-            process.exit(1);
+            // `return` — bare `process.exit` falls through under GJS (see above).
+            return process.exit(1);
+        }
+        const runtime = (args.runtime ?? hostRuntime());
+        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
+        // on node/bun/deno. Handled in-process (not via the GJS-only `dlx`).
+        if (runtime !== 'gjs') {
+            await runShowcaseOnRuntime(showcase, runtime, cliVersion);
+            return;
         }
-        // Delegate to `gjsify dlx <package>@<cli-version>` — same npm-cache,
-        // same atomic symlink-swap, same `gjsify.main` resolution. Re-spawning
-        // the CLI keeps the dlx logic in one place.
+        // gjs runtime: delegate to `gjsify dlx <package>@<cli-version>` — same
+        // npm-cache, same atomic symlink-swap, same `gjsify.main` resolution.
+        // Dispatched in-process to keep the dlx logic in one place.
         //
         // Pinning to the CLI's own version is load-bearing: showcases ship in
         // lockstep with the CLI, so users running `npx @gjsify/cli@X showcase
@@ -102,26 +141,87 @@ export const showcaseCommand = {
         // and the user gets a stale showcase that may be missing deps the
         // newer CLI assumes (the `@gjsify/http-soup-bridge` regression
         // reported against `@gjsify/cli@0.3.17`).
-        const cliVersion = readCliVersion();
         const dlxSpec = cliVersion ? `${showcase.packageName}@${cliVersion}` : showcase.packageName;
         console.log(`Running showcase: ${showcase.name} (via gjsify dlx ${dlxSpec})\n`);
-        const cliBin = fileURLToPath(new URL('../index.js', import.meta.url));
-        const child = spawn(process.execPath, [cliBin, 'dlx', dlxSpec], {
-            stdio: 'inherit',
-        });
-        await new Promise((resolvePromise, reject) => {
-            child.on('close', (code) => {
-                if (code !== 0) {
-                    reject(new Error(`gjsify dlx exited with code ${code}`));
-                }
-                else {
-                    resolvePromise();
-                }
-            });
-            child.on('error', reject);
-        }).catch((err) => {
+        // Dispatch `dlx` IN-PROCESS (not `spawn(process.execPath, [cliBin, …])`):
+        // under the committed GJS bundle `process.execPath` is `gjs` and
+        // `../index.js` is the Node entry, so the spawn ran `gjs cli.gjs.mjs
+        // index.js dlx …` (yargs saw `index.js` as the command) — the
+        // CLAUDE.md-flagged trap. In-process runCli works identically under Node
+        // and GJS and stays node-free (same fix `gjsify storybook` uses).
+        try {
+            const { runCli } = await import('../cli-app.js');
+            await runCli(['dlx', dlxSpec]);
+        }
+        catch (err) {
             console.error(err.message);
             process.exit(1);
-        });
+        }
     },
 };
+/**
+ * Resolve a showcase package's on-disk directory. Prefers a LOCAL install (a
+ * workspace member symlinked in node_modules — no network, and it runs the
+ * in-tree build), falling back to `gjsify dlx`'s install-into-cache for a
+ * published showcase. Returns the directory containing the package.json.
+ */
+async function resolveShowcaseDir(showcase, cliVersion) {
+    // 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 spec = cliVersion ? `${showcase.packageName}@${cliVersion}` : showcase.packageName;
+    const { pkgDir } = await ensurePkgDir(parseSpec(spec), {
+        verbose: false,
+        cacheMaxAge: 60 * 24 * 7,
+        frozen: false,
+    });
+    return pkgDir;
+}
+/**
+ * Run a showcase on a non-gjs runtime (node/bun/deno). Resolves the package,
+ * validates it against the showcase's `gjsify.example.runtimes` declaration
+ * (clean error if the runtime is unsupported — e.g. a GTK/Adw showcase under
+ * node), resolves its `--app node` bundle and launches it via the shared runner.
+ */
+async function runShowcaseOnRuntime(showcase, runtime, cliVersion) {
+    let pkgDir;
+    try {
+        pkgDir = await resolveShowcaseDir(showcase, cliVersion);
+    }
+    catch (err) {
+        console.error(`Could not resolve showcase "${showcase.name}": ${err.message}`);
+        return process.exit(1);
+    }
+    // Declaration check — clear, actionable error for an unsupported runtime.
+    let pkg = {};
+    try {
+        pkg = JSON.parse(readFileSync(`${pkgDir}/package.json`, 'utf-8'));
+    }
+    catch {
+        // Fall through — no declaration means permissive.
+    }
+    const declared = readDeclaredRuntimes(pkg);
+    const support = checkRuntimeSupported(runtime, declared, showcase.name);
+    if (!support.ok) {
+        console.error(support.message);
+        return process.exit(1);
+    }
+    let entry;
+    try {
+        entry = resolveNodeEntry(pkgDir);
+    }
+    catch (err) {
+        console.error(`Cannot run showcase "${showcase.name}" on ${runtime}: ${err.message}`);
+        return process.exit(1);
+    }
+    console.log(`Running showcase: ${showcase.name} on ${runtime} (${entry})\n`);
+    // Terminal call — exit on success.
+    await runRuntimeBundle(runtime, entry, [], { exitOnSuccess: true });
+}