@gjsify/cli 0.17.0 → 0.19.0

package/lib/commands/storybook.js

@@ -19,6 +19,7 @@
 import { spawn } from 'node:child_process';
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
+import { hostRuntime } from '@gjsify/rolldown-plugin-gjsify/runtime';
 function readPackage(cwd) {
     try {
         return JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
@@ -91,11 +92,15 @@ export const storybookCommand = {
         type: 'string',
     })
         .option('runtime', {
-        description: 'Runtime to build for and launch on: gjs (default) or node (via @gjsify/node-gi). ' +
-            'node requires @gjsify/node-gi installed in the project.',
+        description: 'Runtime to build for and launch on: gjs | node | bun | deno (default: the host runtime). ' +
+            'node/bun/deno build the same `--app node` bundle (gi:// → @gjsify/node-gi) and require ' +
+            '@gjsify/node-gi installed in the project.',
         type: 'string',
-        choices: ['gjs', 'node'],
-        default: 'gjs',
+        choices: ['gjs', 'node', 'bun', 'deno'],
+        // No yargs `default: 'gjs'` — a yargs default clobbers the
+        // config-file value (`gjsify.storybook.runtime`). The host
+        // default is applied in the handler: flag > config > host.
+        defaultDescription: 'host runtime (gjs on gjs, else node/bun/deno)',
     })
         .option('watch', {
         description: 'Rebuild and relaunch when a story file changes',
@@ -111,12 +116,15 @@ export const storybookCommand = {
         const applicationId = args.appId ?? config.applicationId ?? deriveAppId(pkg.name);
         const title = args.title ?? config.title;
         const globals = args.globals ?? config.globals ?? 'auto';
-        const runtime = (args.runtime ?? config.runtime ?? 'gjs');
+        // Default FOLLOWS the host runtime the CLI executes in. Precedence: CLI
+        // flag > `gjsify.storybook.runtime` config > host default (`hostRuntime()`).
+        const runtime = (args.runtime ?? config.runtime ?? hostRuntime());
         // The runtime drives BOTH the build target (`gjsify build --app <app>`)
-        // and the launcher: `gjs` builds an `--app gjs` bundle run by `gjs -m`,
-        // `node` builds an `--app node` bundle (gi:// → @gjsify/node-gi) run by
-        // `node`. Same generated entry + `--globals auto` for both.
-        const app = runtime === 'node' ? 'node' : 'gjs';
+        // and the launcher: `gjs` builds an `--app gjs` bundle run by `gjs -m`;
+        // `node`/`bun`/`deno` build the SAME `--app node` bundle (gi:// →
+        // @gjsify/node-gi) run on that runtime. Same generated entry +
+        // `--globals auto` for all.
+        const app = runtime === 'gjs' ? 'gjs' : 'node';
         const cacheDir = join(cwd, 'node_modules', '.cache', 'gjsify-storybook');
         mkdirSync(cacheDir, { recursive: true });
         const entryPath = join(cacheDir, 'entry.ts');
@@ -137,13 +145,20 @@ export const storybookCommand = {
         const { runCli } = await import('../cli-app.js');
         const buildBundle = () => runCli(['build', entryPath, '--app', app, '--globals', globals, '--outfile', outPath]);
         const launch = async () => {
-            if (runtime === 'node') {
+            if (runtime === 'gjs') {
+                const { runGjsBundle } = await import('../utils/run-gjs.js');
+                await runGjsBundle(outPath, [], { exitOnSuccess: true });
+            }
+            else if (runtime === 'node') {
                 const { runNodeBundle } = await import('../utils/run-node.js');
                 await runNodeBundle(outPath, [], { exitOnSuccess: true });
             }
             else {
-                const { runGjsBundle } = await import('../utils/run-gjs.js');
-                await runGjsBundle(outPath, [], { exitOnSuccess: true });
+                // bun / deno — run the SAME `--app node` bundle via the shared
+                // runner (Node-API is their common ABI). node-gi is required
+                // because the storybook uses gi:// (checked in runRuntimeBundle).
+                const { runRuntimeBundle } = await import('../utils/run-node.js');
+                await runRuntimeBundle(runtime, outPath, [], { exitOnSuccess: true });
             }
         };
         if (!args.watch) {
@@ -159,17 +174,29 @@ export const storybookCommand = {
         // enough and stays killable for relaunch.
         const { watch } = await import('node:fs');
         const spawnChild = async () => {
+            if (runtime === 'gjs') {
+                return spawn('gjs', ['-m', outPath], { stdio: 'inherit' });
+            }
+            // node / bun / deno — run the `--app node` bundle with the native
+            // typelib env wired like `gjsify run`. All three need @gjsify/node-gi
+            // (the storybook uses gi://), kept external by the bundler.
+            const { computeNativeEnvForBundle } = await import('../utils/run-gjs.js');
+            const { resolveNodeGi, nodeBinary } = await import('../utils/run-node.js');
+            const { RUNTIMES } = await import('../utils/runtimes.js');
+            if (!resolveNodeGi(cwd)) {
+                throw new Error(`Cannot run the storybook on ${runtime}: \`@gjsify/node-gi\` is not installed. ` +
+                    `Add @gjsify/node-gi as a dependency to run the storybook on ${runtime}.`);
+            }
+            const { env: nativeEnv } = computeNativeEnvForBundle(outPath, cwd);
+            const env = { ...process.env, ...nativeEnv };
+            // `node` uses the resolved node binary (under a GJS-hosted CLI
+            // `process.execPath` is gjs); bun/deno launch via the shared spec
+            // (deno's `--node-modules-dir=manual`, etc.).
             if (runtime === 'node') {
-                const { computeNativeEnvForBundle } = await import('../utils/run-gjs.js');
-                const { resolveNodeGi, nodeBinary } = await import('../utils/run-node.js');
-                if (!resolveNodeGi(cwd)) {
-                    throw new Error('Cannot run the storybook on Node: `@gjsify/node-gi` is not installed. ' +
-                        'Add @gjsify/node-gi as a dependency to run the storybook on Node.');
-                }
-                const { env: nativeEnv } = computeNativeEnvForBundle(outPath, cwd);
-                return spawn(nodeBinary(), [outPath], { stdio: 'inherit', env: { ...process.env, ...nativeEnv } });
+                return spawn(nodeBinary(), [outPath], { stdio: 'inherit', env });
             }
-            return spawn('gjs', ['-m', outPath], { stdio: 'inherit' });
+            const [cmd, launchArgs] = RUNTIMES[runtime].launch(outPath);
+            return spawn(cmd, launchArgs, { stdio: 'inherit', env });
         };
         let child = null;
         let rebuilding = false;

package/lib/config.js

@@ -2,7 +2,8 @@ import { APP_NAME } from './constants.js';
 import { cosmiconfig } from 'cosmiconfig';
 import { basename } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { isGjs, hostRuntime } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { buildAppForRuntime } from './utils/runtimes.js';
 /**
  * Does the failed `import()` of a config look like a MODULE-RESOLUTION failure
  * (the config imports something GJS's ESM loader can't resolve for an external
@@ -227,6 +228,16 @@ export class Config {
         configData.exclude = cliArgs.exclude || [];
         if (cliArgs.consoleShim !== undefined)
             configData.consoleShim = cliArgs.consoleShim;
+        // Default `--app` FOLLOWS the host runtime the CLI executes in: gjs when
+        // run under gjs, node when run under node/bun/deno (both consume the
+        // `--app node` bundle). Applied post-merge (not as a yargs `default:`)
+        // so a `gjsify.app` declared in package.json#gjsify / `.gjsifyrc.*`
+        // survives — a yargs default is indistinguishable from a user value and
+        // would clobber the config one. Precedence: CLI flag > config file >
+        // host default (same pattern as `globals` / `bundler.input`).
+        if (cliArgs.app !== undefined)
+            configData.app = cliArgs.app;
+        configData.app ??= buildAppForRuntime(hostRuntime());
         if (cliArgs.globals !== undefined)
             configData.globals = cliArgs.globals;
         // Fallback applied post-merge (not as a yargs `default:`) so a

package/lib/index.js

@@ -6,6 +6,7 @@
 // This file is just the executable wrapper around `runCli`.
 import { hideBin } from 'yargs/helpers';
 import { runCli } from './cli-app.js';
+import { gjsExit } from '@gjsify/rolldown-plugin-gjsify/runtime';
 try {
     await runCli(hideBin(process.argv));
 }
@@ -23,6 +24,5 @@ catch (err) {
     // atexit hook and would exit 0 at natural shutdown, so force a non-zero exit
     // via `imports.system.exit` there (no-op on Node, where `imports` is unset).
     process.exitCode = 1;
-    const gjs = globalThis.imports;
-    gjs?.system?.exit?.(1);
+    gjsExit(1);
 }

package/lib/types/config-data.d.ts

@@ -1,4 +1,5 @@
 import type { RolldownOptions, OutputOptions, RolldownPluginOption } from 'rolldown';
+import type { App } from '@gjsify/rolldown-plugin-gjsify';
 import type { ConfigDataLibrary, ConfigDataTypescript } from './index.js';
 /**
  * Plugin entry resolvable by package name from the project's `node_modules`.
@@ -64,6 +65,14 @@ export interface LegacyEsbuildOptions {
 export interface ConfigData {
     /** Switch on the verbose mode */
     verbose?: boolean;
+    /**
+     * The build target for an application build (`gjs` | `node` | `browser` |
+     * `nativescript`). Resolved in `Config.forBuild` as CLI flag (`--app`) >
+     * `package.json#gjsify.app` > host-runtime default (`gjs` when the CLI runs
+     * under gjs, `node` when it runs under node/bun/deno). Consumed by the build
+     * handler and passed to `BuildAction.start`.
+     */
+    app?: App;
     /**
      * Bundler-level options forwarded to Rolldown. Replaces the legacy
      * `esbuild` field. The orchestrator applies platform-specific defaults

package/lib/utils/detect-native-packages.js

@@ -10,8 +10,9 @@
 //     their full transitive prebuild set picked up automatically. The
 //     transitive walk is what makes `gjsify showcase` / `gjsify dlx` work
 //     for packages whose Vala typelibs live in *indirect* deps.
-import { readdirSync, existsSync, readFileSync } from 'node:fs';
+import { readdirSync, existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
+import { readPackageJson } from './pkg-json.js';
 /** Map Node.js process.arch values to the convention used in prebuilds/ directories. */
 function nodeArchToLinuxArch(arch) {
     const map = {
@@ -22,15 +23,6 @@ function nodeArchToLinuxArch(arch) {
     };
     return map[arch] ?? arch;
 }
-/** Read a package.json file and return its parsed content, or null on error. */
-function readPackageJson(pkgJsonPath) {
-    try {
-        return JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
-    }
-    catch {
-        return null;
-    }
-}
 /**
  * Scan all packages in a node_modules directory for gjsify native prebuilds.
  * Handles scoped packages (@scope/name) as well as flat packages.

package/lib/utils/discover-showcases.js

@@ -9,8 +9,16 @@ import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 function manifestPath() {
-    // `showcases.json` lives at the package root: ../../showcases.json from lib/utils/.
-    return join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'showcases.json');
+    const here = dirname(fileURLToPath(import.meta.url));
+    // `showcases.json` lives at the CLI package root. Its position relative to
+    // this module depends on how the CLI is loaded:
+    //   - `lib/utils/discover-showcases.js` (Node/Bun/Deno) → `../../showcases.json`.
+    //   - the committed `dist/cli.gjs.mjs` GJS bundle (`gjsify showcase` under
+    //     gjs) → `import.meta.url` is `dist/cli.gjs.mjs`, so the manifest is one
+    //     level up (`../showcases.json`), not two — without this the gjs CLI
+    //     finds no manifest and `showcase` wrongly reports "No showcases found".
+    const candidates = [join(here, '..', '..', 'showcases.json'), join(here, '..', 'showcases.json')];
+    return candidates.find((c) => existsSync(c)) ?? candidates[0];
 }
 /**
  * Read the curated showcase list from `showcases.json`. Returns showcases

package/lib/utils/node-version.js

@@ -7,7 +7,7 @@
 // confusing crash with no actionable message (observed: Node 22 in a Fedora
 // container segfaults `gjsify install --backend native` during download/extract).
 // This preflight turns that into a clear, actionable error.
-import { isNode } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { isNode, gjsSystemVersion } from '@gjsify/rolldown-plugin-gjsify/runtime';
 /**
  * Minimum Node.js major the native install backend supports — its prebuilt native
  * modules are ABI-locked to this line (kept in sync with `.nvmrc`).
@@ -39,7 +39,7 @@ function onRealNode() {
     // GJS exposes `imports.system.version`; @gjsify/process fakes
     // `process.versions.node = '20.0.0'` for compat, so check GJS FIRST — a plain
     // `process.versions.node` read would be a false Node positive under GJS.
-    const sysVersion = globalThis.imports?.system?.version;
+    const sysVersion = gjsSystemVersion();
     if (sysVersion !== undefined)
         return false;
     return isNode();

package/lib/utils/oxc-resolve.js

@@ -54,7 +54,7 @@ import { pathToFileURL } from 'node:url';
 import { findWorkspaceRoot } from './workspace-root.js';
 import { resolveNpmPackage } from './resolve-npm-package.js';
 import { nodeBinary } from './run-node.js';
-import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { isGjs, gjsExit } from '@gjsify/rolldown-plugin-gjsify/runtime';
 /**
  * Map Node.js `process.platform` + `arch` (+ musl on Linux) to the
  * napi-rs binding-package suffix oxc uses, e.g. `linux-x64-gnu`,
@@ -408,9 +408,7 @@ export function setOxcExitCode(code) {
     process.exitCode = code;
     if (code === 0)
         return;
-    const gjs = globalThis.imports;
-    if (gjs?.system?.exit)
-        gjs.system.exit(code);
+    gjsExit(code);
 }
 /**
  * Has the given oxc tool's npm package (or its companion) been declared in the

package/lib/utils/pkg-json-edit.d.ts

@@ -11,6 +11,8 @@ export interface PackageJson {
     devDependencies?: Record<string, string>;
     peerDependencies?: Record<string, string>;
     optionalDependencies?: Record<string, string>;
+    scripts?: Record<string, string>;
+    private?: boolean;
     [key: string]: unknown;
 }
 export declare function readPackageJson(pkgPath: string): PackageJson | null;

package/lib/utils/pkg-json.d.ts

@@ -0,0 +1,6 @@
+import type { PackageJson } from './pkg-json-edit.js';
+/**
+ * Read + parse a `package.json` at `pkgPath`. Permissive: any error (missing
+ * file, unreadable, invalid JSON) yields `null`.
+ */
+export declare function readPackageJson(pkgPath: string): PackageJson | null;

package/lib/utils/pkg-json.js

@@ -0,0 +1,24 @@
+// Single permissive reader for `package.json` files, shared by the CLI's
+// workspace- and dependency-discovery paths (`gjsify run`/`workspace`/`foreach`/
+// `check`, native-prebuild scanning). Returns `null` when the file is missing
+// OR unparseable — discovery must degrade gracefully on a stray or corrupt
+// manifest rather than crash the whole command.
+//
+// The install-save path keeps its own STRICTER reader in `pkg-json-edit.ts`
+// (`readPackageJson` there): it returns `null` only when the file is absent but
+// THROWS on invalid JSON, so a corrupt manifest is never silently overwritten
+// during `gjsify install <pkg>`. That contract is intentional and load-bearing
+// — do not fold it into this one.
+import { readFileSync } from 'node:fs';
+/**
+ * Read + parse a `package.json` at `pkgPath`. Permissive: any error (missing
+ * file, unreadable, invalid JSON) yields `null`.
+ */
+export function readPackageJson(pkgPath) {
+    try {
+        return JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}

package/lib/utils/resolve-gjs-entry.d.ts

@@ -4,4 +4,15 @@ interface ResolvedEntry {
     fromFallback: boolean;
 }
 export declare function resolveGjsEntry(pkgDir: string, binName: string | null): ResolvedEntry;
+/**
+ * Resolve the `--app node` bundle of a package for the non-gjs runtimes
+ * (node/bun/deno all consume it). Resolution order:
+ *   1. explicit `gjsify.example.node` (a package can name its node bundle)
+ *   2. convention: the node twin of the GJS entry — swap the `<name>.gjs.<ext>`
+ *      infix to `<name>.node.<ext>` and probe `.node.{mjs,js,cjs}` (gjsify's
+ *      `build:node → dist/<name>.node.mjs` convention; the GJS entry is
+ *      `dist/<name>.gjs.js`, so the extension can differ).
+ * Hard-fails with an actionable hint when neither is found.
+ */
+export declare function resolveNodeEntry(pkgDir: string): string;
 export {};

package/lib/utils/resolve-gjs-entry.js

@@ -63,3 +63,45 @@ export function resolveGjsEntry(pkgDir, binName) {
     }
     return { bundlePath, binName: resolvedBin, fromFallback };
 }
+/**
+ * Resolve the `--app node` bundle of a package for the non-gjs runtimes
+ * (node/bun/deno all consume it). Resolution order:
+ *   1. explicit `gjsify.example.node` (a package can name its node bundle)
+ *   2. convention: the node twin of the GJS entry — swap the `<name>.gjs.<ext>`
+ *      infix to `<name>.node.<ext>` and probe `.node.{mjs,js,cjs}` (gjsify's
+ *      `build:node → dist/<name>.node.mjs` convention; the GJS entry is
+ *      `dist/<name>.gjs.js`, so the extension can differ).
+ * Hard-fails with an actionable hint when neither is found.
+ */
+export function resolveNodeEntry(pkgDir) {
+    const pkgJsonPath = join(pkgDir, 'package.json');
+    if (!existsSync(pkgJsonPath)) {
+        throw new Error(`no package.json found at ${pkgDir}`);
+    }
+    const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+    // 1. Explicit declaration wins.
+    const explicit = pkg.gjsify?.example?.node;
+    if (explicit) {
+        const p = resolve(pkgDir, explicit);
+        if (!existsSync(p)) {
+            throw new Error(`declared node entry not found: ${p} (gjsify.example.node)`);
+        }
+        return p;
+    }
+    // 2. Derive from the GJS entry.
+    const gjsEntry = pkg.gjsify?.main ?? (pkg.gjsify?.bin ? Object.values(pkg.gjsify.bin)[0] : undefined) ?? pkg.main;
+    if (!gjsEntry) {
+        throw new Error(`package "${pkg.name ?? pkgDir}" has no entry to derive a node bundle from — ` +
+            'set `gjsify.example.node` to its `--app node` bundle path.');
+    }
+    const stem = gjsEntry.replace(/\.gjs\.(js|mjs|cjs)$/, '').replace(/\.(js|mjs|cjs)$/, '');
+    const candidates = [`${stem}.node.mjs`, `${stem}.node.js`, `${stem}.node.cjs`];
+    for (const c of candidates) {
+        const p = resolve(pkgDir, c);
+        if (existsSync(p))
+            return p;
+    }
+    throw new Error(`package "${pkg.name ?? pkgDir}" has no \`--app node\` bundle — looked for ${candidates.join(', ')}.\n` +
+        '  Build one (e.g. `gjsify build src/app.ts --app node --outfile dist/app.node.mjs`) ' +
+        'or set `gjsify.example.node` to its path.');
+}

package/lib/utils/run-gjs.js

@@ -53,6 +53,7 @@ export async function runGjsBundle(bundlePath, extraArgs = [], options = {}) {
     const gjsCommand = ['gjs', ...gjsArgs.map((a) => (a.includes(' ') ? `"${a}"` : a))].join(' ');
     console.error(`$ ${envPrefix ? `${envPrefix} ` : ''}${gjsCommand}`);
     const child = spawn('gjs', gjsArgs, { env, stdio: 'inherit' });
+    let failed = false;
     await new Promise((resolvePromise, reject) => {
         child.on('close', (code) => {
             if (code !== 0) {
@@ -65,10 +66,22 @@ export async function runGjsBundle(bundlePath, extraArgs = [], options = {}) {
         child.on('error', reject);
     }).catch((err) => {
         console.error(err.message);
-        process.exit(1);
+        failed = true;
     });
+    if (failed) {
+        // Set `process.exitCode` synchronously BEFORE exiting: under GJS
+        // `process.exit()` is deferred (the GLib main loop is armed), so when
+        // this runs via run.ts's in-process script dispatch, execution returns
+        // to the caller, which propagates by reading `process.exitCode`. Without
+        // this, `gjsify run <script>` whose body is `gjsify run <bundle>`
+        // swallowed a non-zero gjs exit and returned 0 — masking a failing
+        // `test:gjs` in the `test` script chain (and, via `gjsify foreach test`,
+        // in CI). The `return` guards against a fall-through second `exit`.
+        process.exitCode = 1;
+        return process.exit(1);
+    }
     // See RunGjsBundleOptions.exitOnSuccess — terminal callers opt in,
     // mid-flow callers (test.ts's runtime loop) keep the process alive.
     if (options.exitOnSuccess)
-        process.exit(0);
+        return process.exit(0);
 }

package/lib/utils/run-node.d.ts

@@ -1,3 +1,4 @@
+import { type ExampleRuntime } from './runtimes.js';
 /**
  * Walk up from `startDir` looking for `<node_modules>/@gjsify/node-gi`. Returns
  * the package directory, or null when it is not installed anywhere on the chain.
@@ -18,3 +19,23 @@ export interface RunNodeBundleOptions {
  * throws a clear, actionable error otherwise.
  */
 export declare function runNodeBundle(bundlePath: string, extraArgs?: string[], options?: RunNodeBundleOptions): Promise<void>;
+/**
+ * Whether a `--app node` bundle actually consumes `@gjsify/node-gi` (the gi://
+ * reverse bridge is kept EXTERNAL, so a bundle that uses gi:// imports the shim
+ * by name). A plain Node app (express, a pure `node:*` program) does NOT, and
+ * must run on node/bun/deno WITHOUT node-gi installed — so the node-gi check is
+ * conditional on this, not unconditional like the storybook path.
+ */
+export declare function bundleRequiresNodeGi(bundlePath: string): boolean;
+/**
+ * Run a built bundle on a non-gjs runtime (node / bun / deno). All three consume
+ * the SAME `--app node` bundle (Node-API is their common ABI), so this is the
+ * shared launcher `gjsify run --runtime` and `gjsify showcase --runtime` use for
+ * node/bun/deno. The native typelib env is wired exactly like {@link runGjsBundle}
+ * (so a bundle pulling an `@gjsify/*` Vala bridge resolves its prebuild), and
+ * `@gjsify/node-gi` is required ONLY when the bundle actually uses gi://.
+ *
+ * `gjs` is intentionally NOT handled here — the caller dispatches it to
+ * {@link runGjsBundle}.
+ */
+export declare function runRuntimeBundle(runtime: Exclude<ExampleRuntime, 'gjs'>, bundlePath: string, extraArgs?: string[], options?: RunNodeBundleOptions): Promise<void>;

package/lib/utils/run-node.js

@@ -20,10 +20,11 @@
 // the PATH `node` otherwise (under the committed GJS bundle `process.execPath` is
 // `gjs`, which cannot run a `--app node` bundle).
 import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { isNode } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { computeNativeEnvForBundle } from './run-gjs.js';
+import { RUNTIMES } from './runtimes.js';
 /**
  * Walk up from `startDir` looking for `<node_modules>/@gjsify/node-gi`. Returns
  * the package directory, or null when it is not installed anywhere on the chain.
@@ -83,3 +84,63 @@ export async function runNodeBundle(bundlePath, extraArgs = [], options = {}) {
     if (options.exitOnSuccess)
         process.exit(0);
 }
+/**
+ * Whether a `--app node` bundle actually consumes `@gjsify/node-gi` (the gi://
+ * reverse bridge is kept EXTERNAL, so a bundle that uses gi:// imports the shim
+ * by name). A plain Node app (express, a pure `node:*` program) does NOT, and
+ * must run on node/bun/deno WITHOUT node-gi installed — so the node-gi check is
+ * conditional on this, not unconditional like the storybook path.
+ */
+export function bundleRequiresNodeGi(bundlePath) {
+    try {
+        return readFileSync(bundlePath, 'utf-8').includes('@gjsify/node-gi');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Run a built bundle on a non-gjs runtime (node / bun / deno). All three consume
+ * the SAME `--app node` bundle (Node-API is their common ABI), so this is the
+ * shared launcher `gjsify run --runtime` and `gjsify showcase --runtime` use for
+ * node/bun/deno. The native typelib env is wired exactly like {@link runGjsBundle}
+ * (so a bundle pulling an `@gjsify/*` Vala bridge resolves its prebuild), and
+ * `@gjsify/node-gi` is required ONLY when the bundle actually uses gi://.
+ *
+ * `gjs` is intentionally NOT handled here — the caller dispatches it to
+ * {@link runGjsBundle}.
+ */
+export async function runRuntimeBundle(runtime, bundlePath, extraArgs = [], options = {}) {
+    const cwd = process.cwd();
+    const resolvedBundle = resolve(bundlePath);
+    if (bundleRequiresNodeGi(resolvedBundle) && !resolveNodeGi(cwd)) {
+        throw new Error(`Cannot run this bundle on ${runtime}: it uses gi:// via \`@gjsify/node-gi\`, which is not installed.\n` +
+            'Add @gjsify/node-gi as a dependency to run gi:// code off GJS, e.g.:\n' +
+            '  "dependencies": { "@gjsify/node-gi": "^0.13.0" }');
+    }
+    const { env: nativeEnv, envPrefix } = computeNativeEnvForBundle(resolvedBundle, cwd);
+    const env = { ...process.env, ...nativeEnv };
+    // Reuse the shared RUNTIMES launch spec for the argv (deno's
+    // `--node-modules-dir=manual`, etc.), substituting the resolved node binary
+    // for the `node` runtime (under a GJS-hosted CLI `process.execPath` is gjs).
+    const [, launchArgs] = RUNTIMES[runtime].launch(resolvedBundle, extraArgs);
+    const cmd = runtime === 'node' ? nodeBinary() : RUNTIMES[runtime].probe;
+    // Echo on stderr so a child speaking a protocol on stdout stays clean.
+    const shown = [cmd, ...launchArgs.map((a) => (a.includes(' ') ? `"${a}"` : a))].join(' ');
+    console.error(`$ ${envPrefix ? `${envPrefix} ` : ''}${shown}`);
+    const child = spawn(cmd, launchArgs, { env, stdio: 'inherit' });
+    await new Promise((resolvePromise, reject) => {
+        child.on('close', (code) => {
+            if (code !== 0)
+                reject(new Error(`${runtime} exited with code ${code}`));
+            else
+                resolvePromise();
+        });
+        child.on('error', reject);
+    }).catch((err) => {
+        console.error(err.message);
+        process.exit(1);
+    });
+    if (options.exitOnSuccess)
+        process.exit(0);
+}

package/lib/utils/runtimes.d.ts

@@ -0,0 +1,66 @@
+/** The runtimes a built gjsify example/showcase can run on. `gjs` is the reference. */
+export type ExampleRuntime = 'gjs' | 'node' | 'bun' | 'deno';
+/** All runtimes, in canonical order (gjs first — it is the reference). */
+export declare const EXAMPLE_RUNTIMES: readonly ExampleRuntime[];
+export interface RuntimeSpec {
+    /** Binary probed on PATH to decide availability (`<probe> --version`). */
+    readonly probe: string;
+    /**
+     * The `gjsify build --app <buildApp>` target this runtime consumes. `gjs`
+     * runs the native `--app gjs` bundle; node/bun/deno all reuse the SAME
+     * `--app node` bundle (gi:// → `@gjsify/node-gi`; Node-API is their common
+     * ABI), so bun/deno never need their own build target.
+     */
+    readonly buildApp: 'gjs' | 'node';
+    /** argv to launch a built `entry` (+ optional extra args) under this runtime. */
+    readonly launch: (entry: string, extraArgs?: readonly string[]) => [string, string[]];
+}
+/**
+ * The runtime map — the generalization of the node-gi harness's `RUNTIMES`.
+ * `deno` uses `--node-modules-dir=manual`: `auto` would re-resolve the example's
+ * heavy build-time dep tree (`@gjsify/cli` + platform binaries) and hang, when
+ * the app only needs the already-linked runtime dep `@gjsify/node-gi`.
+ */
+export declare const RUNTIMES: Record<ExampleRuntime, RuntimeSpec>;
+/** Type guard: is `value` one of the four known runtimes? */
+export declare function isExampleRuntime(value: string): value is ExampleRuntime;
+/** The `gjsify build --app <target>` a runtime consumes (`gjs`, else `node`). */
+export declare function buildAppForRuntime(runtime: ExampleRuntime): 'gjs' | 'node';
+/** Whether `<probe> --version` succeeds (i.e. the runtime binary is on PATH). */
+export declare function isRuntimeOnPath(probe: string): boolean;
+/**
+ * Whether a specific runtime is runnable here. The HOST runtime (the one the
+ * CLI itself executes in — gjs / node / bun / deno) is always available: we are
+ * running on it, so no PATH probe is needed. Every other runtime is probed via
+ * `<binary> --version`.
+ */
+export declare function isRuntimeAvailable(runtime: ExampleRuntime): boolean;
+/** Which of gjs/node/bun/deno are runnable on this host. */
+export declare function availableRuntimes(): ExampleRuntime[];
+interface ExampleGjsifyField {
+    example?: {
+        runtimes?: unknown;
+    };
+}
+/**
+ * Read a package's declared example runtimes. Returns the (validated) list, or
+ * `null` when the package declares none — the "unconstrained / permissive" case.
+ * Unknown entries in the list are dropped (so a future runtime name doesn't hard
+ * error against an older CLI).
+ */
+export declare function readDeclaredRuntimes(pkg: {
+    gjsify?: ExampleGjsifyField;
+} | null | undefined): ExampleRuntime[] | null;
+export interface RuntimeSupportResult {
+    ok: boolean;
+    /** A clear, actionable message when `ok === false`; undefined otherwise. */
+    message?: string;
+}
+/**
+ * Validate a requested runtime against a package's declaration. A `null`
+ * declaration is permissive (always ok). When the runtime is not in the
+ * declared set, returns a clear, actionable error message (never throws) so
+ * callers can print it and exit cleanly.
+ */
+export declare function checkRuntimeSupported(runtime: ExampleRuntime, declared: ExampleRuntime[] | null, name: string): RuntimeSupportResult;
+export {};