@gjsify/cli 0.18.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/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/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/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-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 {};

package/lib/utils/runtimes.js

@@ -0,0 +1,97 @@
+// Shared runtime-selector tooling for running gjsify examples/showcases across
+// the FOUR runtimes gjsify targets: gjs, node, bun, deno.
+//
+// This is the single source of truth generalized from the node-gi quad-runtime
+// example's `harness.mjs`. Both the CLI (`gjsify run`/`gjsify showcase
+// --runtime`) and the examples (the node-gi `harness.mjs`) consume it — so the
+// RUNTIMES map, the runtime→build-target mapping and `availableRuntimes()` live
+// in ONE place instead of a per-example copy.
+//
+// The module is intentionally PURE (only `node:child_process` and the pure,
+// side-effect-free `@gjsify/rolldown-plugin-gjsify/runtime` host detector, no
+// `gi://` / native imports) so an external example can deep-import it from the
+// installed CLI (`@gjsify/cli/lib/utils/runtimes.js`) without pulling the whole
+// bundler in. Mirrors the existing `@gjsify/cli/lib/utils/run-gjs.js`
+// deep-import precedent used by the dlx e2e suites.
+import { execFileSync } from 'node:child_process';
+import { hostRuntime } from '@gjsify/rolldown-plugin-gjsify/runtime';
+/** All runtimes, in canonical order (gjs first — it is the reference). */
+export const EXAMPLE_RUNTIMES = ['gjs', 'node', 'bun', 'deno'];
+/**
+ * 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 const RUNTIMES = {
+    gjs: { probe: 'gjs', buildApp: 'gjs', launch: (e, a = []) => ['gjs', ['-m', e, ...a]] },
+    node: { probe: 'node', buildApp: 'node', launch: (e, a = []) => ['node', [e, ...a]] },
+    bun: { probe: 'bun', buildApp: 'node', launch: (e, a = []) => ['bun', [e, ...a]] },
+    deno: {
+        probe: 'deno',
+        buildApp: 'node',
+        launch: (e, a = []) => ['deno', ['run', '-A', '--node-modules-dir=manual', e, ...a]],
+    },
+};
+/** Type guard: is `value` one of the four known runtimes? */
+export function isExampleRuntime(value) {
+    return EXAMPLE_RUNTIMES.includes(value);
+}
+/** The `gjsify build --app <target>` a runtime consumes (`gjs`, else `node`). */
+export function buildAppForRuntime(runtime) {
+    return RUNTIMES[runtime].buildApp;
+}
+/** Whether `<probe> --version` succeeds (i.e. the runtime binary is on PATH). */
+export function isRuntimeOnPath(probe) {
+    try {
+        execFileSync(probe, ['--version'], { stdio: 'ignore', timeout: 15000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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 function isRuntimeAvailable(runtime) {
+    return runtime === hostRuntime() ? true : isRuntimeOnPath(RUNTIMES[runtime].probe);
+}
+/** Which of gjs/node/bun/deno are runnable on this host. */
+export function availableRuntimes() {
+    return EXAMPLE_RUNTIMES.filter((rt) => isRuntimeAvailable(rt));
+}
+/**
+ * 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 function readDeclaredRuntimes(pkg) {
+    const list = pkg?.gjsify?.example?.runtimes;
+    if (!Array.isArray(list))
+        return null;
+    return list.filter((v) => typeof v === 'string' && isExampleRuntime(v));
+}
+/**
+ * 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 function checkRuntimeSupported(runtime, declared, name) {
+    if (declared === null)
+        return { ok: true };
+    if (declared.includes(runtime))
+        return { ok: true };
+    const supported = declared.length > 0 ? declared.join(', ') : '(none)';
+    return {
+        ok: false,
+        message: `"${name}" does not support --runtime ${runtime}.\n` +
+            `  Declared runtimes: ${supported}.\n` +
+            `  Run it on one of the declared runtimes, e.g. --runtime ${declared[0] ?? 'gjs'}.`,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/cli",
-    "version": "0.18.0",
+    "version": "0.19.0",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -113,6 +113,9 @@
         "chmod": "chmod +x ./lib/index.js",
         "build:test:node": "node lib/index.js build src/test.mts --app node --outfile dist/test.node.mjs",
         "test:node": "node dist/test.node.mjs",
+        "test:bun": "bun dist/test.node.mjs",
+        "test:deno": "deno run -A --no-lock --node-modules-dir=none dist/test.node.mjs",
+        "test:cross-runtime": "gjsify run build:test:node && gjsify run test:node && gjsify run test:bun && gjsify run test:deno",
         "test": "gjsify run build:test:node && gjsify run test:node"
     },
     "keywords": [
@@ -122,19 +125,19 @@
         "cli"
     ],
     "dependencies": {
-        "@gjsify/buffer": "^0.18.0",
-        "@gjsify/create-app": "^0.18.0",
-        "@gjsify/node-globals": "^0.18.0",
-        "@gjsify/node-polyfills": "^0.18.0",
-        "@gjsify/npm-registry": "^0.18.0",
-        "@gjsify/resolve-npm": "^0.18.0",
-        "@gjsify/rolldown-plugin-gjsify": "^0.18.0",
-        "@gjsify/rolldown-plugin-pnp": "^0.18.0",
-        "@gjsify/semver": "^0.18.0",
-        "@gjsify/tar": "^0.18.0",
-        "@gjsify/tsc": "^0.18.0",
-        "@gjsify/web-polyfills": "^0.18.0",
-        "@gjsify/workspace": "^0.18.0",
+        "@gjsify/buffer": "^0.19.0",
+        "@gjsify/create-app": "^0.19.0",
+        "@gjsify/node-globals": "^0.19.0",
+        "@gjsify/node-polyfills": "^0.19.0",
+        "@gjsify/npm-registry": "^0.19.0",
+        "@gjsify/resolve-npm": "^0.19.0",
+        "@gjsify/rolldown-plugin-gjsify": "^0.19.0",
+        "@gjsify/rolldown-plugin-pnp": "^0.19.0",
+        "@gjsify/semver": "^0.19.0",
+        "@gjsify/tar": "^0.19.0",
+        "@gjsify/tsc": "^0.19.0",
+        "@gjsify/web-polyfills": "^0.19.0",
+        "@gjsify/workspace": "^0.19.0",
         "cosmiconfig": "^9.0.2",
         "get-tsconfig": "^4.14.0",
         "pkg-types": "^2.3.1",
@@ -142,13 +145,13 @@
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@gjsify/unit": "^0.18.0",
+        "@gjsify/unit": "^0.19.0",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/oxfmt-native": "^0.18.0",
-        "@gjsify/rolldown-native": "^0.18.0"
+        "@gjsify/oxfmt-native": "^0.19.0",
+        "@gjsify/rolldown-native": "^0.19.0"
     },
     "peerDependenciesMeta": {
         "@gjsify/oxfmt-native": {