@gjsify/cli 0.36.0 → 0.37.0

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

@@ -1,25 +1,19 @@
 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.
- * A plain fs walk (works identically on Node and GJS) — Node's own resolver is
- * not available under the GJS-bundled CLI.
+ * Walk up from `startDir` for `<node_modules>/@gjsify/node-gi`, returning its package directory
+ * or null. A plain fs walk because Node's own resolver is not available under the GJS-bundled CLI.
  */
 export declare function resolveNodeGi(startDir: string): string | null;
 /**
- * Resolve `@gjsify/node-gi` for a bundle we are about to launch: from the
- * BUNDLE's own directory first, then from `cwd`.
+ * Resolve `@gjsify/node-gi` for a bundle about to launch: the BUNDLE's own directory first, then
+ * `cwd`.
  *
- * The bundle's directory is the correct base and cwd is the fallback, for the
- * same reason {@link computeNativeEnvForBundle} walks both: `@gjsify/node-gi` is
- * kept EXTERNAL, so what has to be satisfiable is the RUNTIME's resolution of a
- * bare specifier from inside the bundle — which Node performs relative to the
- * importing file, never relative to cwd. A dlx-cache layout
- * (`~/.cache/gjsify/dlx/<sha>/node_modules/<pkg>/dist/bundle.mjs`) has node-gi
- * sitting right beside the bundle and nothing at all under the user's cwd, so a
- * cwd-only probe rejected a run that would have worked. The cwd probe is kept
- * because a project-local `node_modules` legitimately satisfies a bundle built
- * into a `dist/` outside it (a `--outfile /tmp/…` build from a project root).
+ * The bundle's directory is the correct base for the same reason {@link computeNativeEnvForBundle}
+ * walks both: node-gi is kept EXTERNAL, so what must be satisfiable is the RUNTIME's resolution
+ * of a bare specifier from inside the bundle, which Node performs relative to the importing file,
+ * never to cwd. A dlx-cache layout has node-gi beside the bundle and nothing under the user's
+ * cwd, so a cwd-only probe rejected a run that would have worked. The cwd probe stays because a
+ * project-local `node_modules` legitimately satisfies a bundle built into a `dist/` outside it.
  */
 export declare function resolveNodeGiForBundle(bundlePath: string, cwd: string): string | null;
 /** Pick the node executable: the current one when on Node, else PATH `node`. */
@@ -31,29 +25,23 @@ export interface RunNodeBundleOptions {
     quiet?: boolean;
 }
 /**
- * Run a `--app node` bundle on Node.js, auto-setting LD_LIBRARY_PATH and
- * GI_TYPELIB_PATH for any installed native gjsify packages (same detection as
- * {@link runGjsBundle}). Verifies `@gjsify/node-gi` is resolvable first and
- * throws a clear, actionable error otherwise.
+ * Run a `--app node` bundle on Node.js with the native typelib env set (same detection as
+ * {@link runGjsBundle}). Throws when `@gjsify/node-gi` is not resolvable.
  */
 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.
+ * Whether a `--app node` bundle actually consumes `@gjsify/node-gi` — kept EXTERNAL, so a bundle
+ * using gi:// imports the shim by name. A plain Node app does NOT, and must run on node/bun/deno
+ * WITHOUT node-gi installed, which is why the check is conditional here and 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://.
+ * 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 for
+ * `gjsify run --runtime` and `gjsify showcase --runtime`. Native typelib env is wired as in
+ * {@link runGjsBundle}; `@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}.
+ * `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

@@ -1,26 +1,20 @@
 // Shared utility for running a `--app node` bundle on Node.js with the native
 // typelib env wired the same way `runGjsBundle` does.
 //
-// A `gjsify build --app node` bundle of a `gi://` source runs the GObject stack
-// through `@gjsify/node-gi` (the Axis-5 reverse bridge). Two things have to be
-// true at runtime:
+// A `--app node` bundle of a `gi://` source runs the GObject stack through `@gjsify/node-gi`
+// (the Axis-5 reverse bridge). Two things must hold at runtime:
 //
-//   1. `@gjsify/node-gi` must resolve FROM THE BUNDLE — it is kept EXTERNAL by
-//      the bundler (a native addon), so it has to physically exist in a
-//      node_modules the bundle's own directory can reach (that is where Node
-//      will look), with the CWD as a fallback. We verify this up front and emit
-//      a clear hint instead of letting Node throw `ERR_MODULE_NOT_FOUND` deep in
-//      the bundle. See `resolveNodeGiForBundle`.
-//   2. `gi://Gtk` / `gi://Adw` etc. must resolve. System typelibs come from the
-//      default GI search path, but any `@gjsify/*` Vala bridge a story pulls in
-//      ships its typelib in `prebuilds/` — so we reuse the SAME
-//      `computeNativeEnvForBundle()` walker `runGjsBundle` uses to prepend
-//      `GI_TYPELIB_PATH` / `LD_LIBRARY_PATH`. It is a no-op when no native
-//      gjsify packages are present (the storybook's common case).
+//   1. `@gjsify/node-gi` must resolve FROM THE BUNDLE — the bundler keeps it EXTERNAL (native
+//      addon), so it has to physically exist in a node_modules the bundle's own directory can
+//      reach, with the CWD as a fallback. Checked up front so the failure is a clear hint
+//      rather than an `ERR_MODULE_NOT_FOUND` deep in the bundle (`resolveNodeGiForBundle`).
+//   2. `gi://Gtk` / `gi://Adw` must resolve. System typelibs come from the default GI search
+//      path, but an `@gjsify/*` Vala bridge ships its typelib in `prebuilds/`, so the SAME
+//      `computeNativeEnvForBundle()` walker `runGjsBundle` uses prepends `GI_TYPELIB_PATH` /
+//      `LD_LIBRARY_PATH`. A no-op when no native gjsify packages are present.
 //
-// The node binary is `process.execPath` when the CLI itself runs under Node, and
-// the PATH `node` otherwise (under the committed GJS bundle `process.execPath` is
-// `gjs`, which cannot run a `--app node` bundle).
+// The node binary is `process.execPath` when the CLI runs under Node, else PATH `node` — under
+// the GJS bundle `process.execPath` is `gjs`, which cannot run a `--app node` bundle.
 import { spawn } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
@@ -28,10 +22,8 @@ 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.
- * A plain fs walk (works identically on Node and GJS) — Node's own resolver is
- * not available under the GJS-bundled CLI.
+ * Walk up from `startDir` for `<node_modules>/@gjsify/node-gi`, returning its package directory
+ * or null. A plain fs walk because Node's own resolver is not available under the GJS-bundled CLI.
  */
 export function resolveNodeGi(startDir) {
     let dir = resolve(startDir);
@@ -46,19 +38,15 @@ export function resolveNodeGi(startDir) {
     }
 }
 /**
- * Resolve `@gjsify/node-gi` for a bundle we are about to launch: from the
- * BUNDLE's own directory first, then from `cwd`.
+ * Resolve `@gjsify/node-gi` for a bundle about to launch: the BUNDLE's own directory first, then
+ * `cwd`.
  *
- * The bundle's directory is the correct base and cwd is the fallback, for the
- * same reason {@link computeNativeEnvForBundle} walks both: `@gjsify/node-gi` is
- * kept EXTERNAL, so what has to be satisfiable is the RUNTIME's resolution of a
- * bare specifier from inside the bundle — which Node performs relative to the
- * importing file, never relative to cwd. A dlx-cache layout
- * (`~/.cache/gjsify/dlx/<sha>/node_modules/<pkg>/dist/bundle.mjs`) has node-gi
- * sitting right beside the bundle and nothing at all under the user's cwd, so a
- * cwd-only probe rejected a run that would have worked. The cwd probe is kept
- * because a project-local `node_modules` legitimately satisfies a bundle built
- * into a `dist/` outside it (a `--outfile /tmp/…` build from a project root).
+ * The bundle's directory is the correct base for the same reason {@link computeNativeEnvForBundle}
+ * walks both: node-gi is kept EXTERNAL, so what must be satisfiable is the RUNTIME's resolution
+ * of a bare specifier from inside the bundle, which Node performs relative to the importing file,
+ * never to cwd. A dlx-cache layout has node-gi beside the bundle and nothing under the user's
+ * cwd, so a cwd-only probe rejected a run that would have worked. The cwd probe stays because a
+ * project-local `node_modules` legitimately satisfies a bundle built into a `dist/` outside it.
  */
 export function resolveNodeGiForBundle(bundlePath, cwd) {
     const resolvedBundle = resolve(bundlePath);
@@ -69,10 +57,8 @@ export function nodeBinary() {
     return isNode() && process.execPath ? process.execPath : 'node';
 }
 /**
- * Run a `--app node` bundle on Node.js, auto-setting LD_LIBRARY_PATH and
- * GI_TYPELIB_PATH for any installed native gjsify packages (same detection as
- * {@link runGjsBundle}). Verifies `@gjsify/node-gi` is resolvable first and
- * throws a clear, actionable error otherwise.
+ * Run a `--app node` bundle on Node.js with the native typelib env set (same detection as
+ * {@link runGjsBundle}). Throws when `@gjsify/node-gi` is not resolvable.
  */
 export async function runNodeBundle(bundlePath, extraArgs = [], options = {}) {
     const cwd = process.cwd();
@@ -85,8 +71,7 @@ export async function runNodeBundle(bundlePath, extraArgs = [], options = {}) {
     const env = { ...process.env, ...nativeEnv };
     const nodeBin = nodeBinary();
     const nodeArgs = [bundlePath, ...extraArgs];
-    // Echo the exact command (stderr, so a child speaking a protocol on stdout
-    // stays uncontaminated) so users can reproduce the run without the wrapper.
+    // Echo on stderr, so a child speaking a protocol on stdout stays uncontaminated.
     const cmd = [nodeBin, ...nodeArgs.map((a) => (a.includes(' ') ? `"${a}"` : a))].join(' ');
     console.error(`$ ${envPrefix ? `${envPrefix} ` : ''}${cmd}`);
     const child = spawn(nodeBin, nodeArgs, { env, stdio: 'inherit' });
@@ -106,11 +91,10 @@ export async function runNodeBundle(bundlePath, extraArgs = [], options = {}) {
         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.
+ * Whether a `--app node` bundle actually consumes `@gjsify/node-gi` — kept EXTERNAL, so a bundle
+ * using gi:// imports the shim by name. A plain Node app does NOT, and must run on node/bun/deno
+ * WITHOUT node-gi installed, which is why the check is conditional here and not unconditional
+ * like the storybook path.
  */
 export function bundleRequiresNodeGi(bundlePath) {
     try {
@@ -121,15 +105,12 @@ export function bundleRequiresNodeGi(bundlePath) {
     }
 }
 /**
- * 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://.
+ * 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 for
+ * `gjsify run --runtime` and `gjsify showcase --runtime`. Native typelib env is wired as in
+ * {@link runGjsBundle}; `@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}.
+ * `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();
@@ -141,9 +122,9 @@ export async function runRuntimeBundle(runtime, bundlePath, extraArgs = [], opti
     }
     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).
+    // The shared RUNTIMES launch spec supplies the argv (deno's `--node-modules-dir=manual`
+    // etc.); the `node` runtime substitutes the resolved binary, since 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.
@@ -151,9 +132,9 @@ export async function runRuntimeBundle(runtime, bundlePath, extraArgs = [], opti
     if (!options.quiet)
         console.error(`$ ${envPrefix ? `${envPrefix} ` : ''}${shown}`);
     const child = spawn(cmd, launchArgs, { env, stdio: 'inherit' });
-    // Re-raise the CHILD's own code rather than a blanket 1 — same reason as
-    // `runGjsBundle`: a script run through `--node-script` reports its status
-    // through this path, and a caller that reads `$?` needs the real one.
+    // Re-raise the CHILD's own code rather than a blanket 1 — a script run through
+    // `--node-script` reports its status through this path, and a caller reading `$?` needs
+    // the real one.
     let failed = false;
     let childCode = 1;
     await new Promise((resolvePromise, reject) => {
@@ -170,11 +151,9 @@ export async function runRuntimeBundle(runtime, bundlePath, extraArgs = [], opti
         console.error(err.message);
         failed = true;
     });
-    // `return process.exit(…)`, and the flag rather than an exit inside the
-    // `catch`: under GJS `process.exit()` is deferred and RETURNS, so a bare
-    // call in the catch fell through to the `exitOnSuccess` line below and
-    // scheduled a second exit — the same fall-through `runGjsBundle` and
-    // `commands/run.ts` already carry this shape for.
+    // `return process.exit(…)`, and a flag rather than an exit inside the `catch`: under GJS
+    // `process.exit()` is deferred and RETURNS, so a bare call in the catch fell through to the
+    // `exitOnSuccess` line below and scheduled a second exit.
     if (failed) {
         process.exitCode = childCode;
         return process.exit(childCode);

package/lib/utils/runtimes.d.ts

@@ -16,10 +16,9 @@ export interface RuntimeSpec {
     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`.
+ * 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? */
@@ -34,22 +33,18 @@ export declare function buildAppForRuntime(runtime: ExampleRuntime): 'gjs' | 'no
  * `--app gjs` bundle" and "needs a gjs interpreter" are the same fact, and a
  * hand-written second list drifts the first time a runtime is added.
  *
- * The caller must resolve the runtime BEFORE gating on it. `gjsify showcase`
- * called `runMinimalChecks()` — which marks `gjs` `required` — three statements
- * ABOVE the line resolving `args.runtime`, so `--runtime node` aborted with
- * "Missing system dependencies: ✗ GJS" before reaching the `runtime !== 'gjs'`
- * branch that never touches gjs. Every showcase was unreachable on a host
- * without gjs (Windows, plain Node/bun/deno) — including the default path,
- * since `defaultExampleRuntime()` falls back to the host runtime for exactly
- * those hosts.
+ * The caller must resolve the runtime BEFORE gating on it. Calling
+ * `runMinimalChecks()` (which marks `gjs` `required`) above the line that resolves
+ * `args.runtime` made every showcase unreachable on a host without gjs — `--runtime
+ * node` aborted with "Missing system dependencies: ✗ GJS" before reaching the
+ * branch that never touches gjs, the default path included.
  */
 export declare function requiresGjsSystemDeps(runtime: ExampleRuntime): boolean;
 /** 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
+ * Whether a specific runtime is runnable here. The HOST runtime needs no PATH probe
+ * — the CLI is executing on it; every other runtime is probed via
  * `<binary> --version`.
  */
 export declare function isRuntimeAvailable(runtime: ExampleRuntime): boolean;
@@ -59,20 +54,17 @@ export declare function availableRuntimes(): ExampleRuntime[];
  * The default `--runtime` for running a prebuilt EXAMPLE/SHOWCASE: `gjs`
  * whenever gjs is runnable here, else the host runtime.
  *
- * This is deliberately NOT a plain `hostRuntime()`. A showcase's canonical
- * artifact is its `--app gjs` bundle (`gjsify.main`) — that is what every
- * showcase ships, what the `gjs` path installs via `gjsify dlx`, and what the
- * docs call the default. Following the host instead means `npx @gjsify/cli
- * showcase <name>` (host = node) silently asks for the `--app node` bundle,
- * which most showcases do not ship and which additionally needs
- * `@gjsify/node-gi` in the consumer's project — so the FIRST-RUN experience of
- * the primary documented entry point failed on a missing file.
+ * Deliberately NOT a plain `hostRuntime()`. A showcase's canonical artifact is its
+ * `--app gjs` bundle (`gjsify.main`) — what every showcase ships and what `gjsify
+ * dlx` installs. Following the host instead makes `npx @gjsify/cli showcase <name>`
+ * (host = node) ask for the `--app node` bundle, which most showcases do not ship
+ * and which also needs `@gjsify/node-gi` in the consumer's project, so the
+ * first-run experience of the primary documented entry point failed on a missing
+ * file.
  *
- * Same rule `gjsify run` already applies in its bare-file path, where a
- * `--app gjs` bundle stays on gjs regardless of host (`isLikelyGjsBundle`);
- * here the "is it a gjs artifact" question is answered by the command instead
- * of by sniffing the file. `--runtime` still overrides explicitly, and a host
- * WITHOUT gjs (a plain Node/bun/deno box) keeps following the host so the
+ * Same rule `gjsify run` applies in its bare-file path (`isLikelyGjsBundle`), with
+ * "is it a gjs artifact" answered by the command rather than by sniffing the file.
+ * `--runtime` still overrides, and a host WITHOUT gjs keeps following the host so
  * node-capable showcases stay runnable there.
  */
 export declare function defaultExampleRuntime(): ExampleRuntime;
@@ -82,10 +74,9 @@ interface ExampleGjsifyField {
     };
 }
 /**
- * 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).
+ * A package's declared example runtimes, or `null` when it declares none (the
+ * permissive case). Unknown entries are dropped so a future runtime name does not
+ * hard-error against an older CLI.
  */
 export declare function readDeclaredRuntimes(pkg: {
     gjsify?: ExampleGjsifyField;
@@ -96,10 +87,9 @@ export interface RuntimeSupportResult {
     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.
+ * Validate a requested runtime against a package's declaration; a `null`
+ * declaration is permissive. Returns a message rather than throwing, so callers
+ * print it and exit cleanly.
  */
 export declare function checkRuntimeSupported(runtime: ExampleRuntime, declared: ExampleRuntime[] | null, name: string): RuntimeSupportResult;
 export {};

package/lib/utils/runtimes.js

@@ -1,27 +1,24 @@
 // 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.
+// Both the CLI (`gjsify run` / `gjsify showcase --runtime`) and the examples (the
+// node-gi `harness.mjs`) consume this, 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.
+// Intentionally PURE (only `node:child_process` and the side-effect-free
+// `@gjsify/rolldown-plugin-gjsify/runtime` host detector, no `gi://` or native
+// imports) so an external example can deep-import it from the installed CLI
+// (`@gjsify/cli/lib/utils/runtimes.js`) without pulling in the whole bundler — the
+// same deep-import precedent as `@gjsify/cli/lib/utils/run-gjs.js`.
 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`.
+ * 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]] },
@@ -49,14 +46,11 @@ export function buildAppForRuntime(runtime) {
  * `--app gjs` bundle" and "needs a gjs interpreter" are the same fact, and a
  * hand-written second list drifts the first time a runtime is added.
  *
- * The caller must resolve the runtime BEFORE gating on it. `gjsify showcase`
- * called `runMinimalChecks()` — which marks `gjs` `required` — three statements
- * ABOVE the line resolving `args.runtime`, so `--runtime node` aborted with
- * "Missing system dependencies: ✗ GJS" before reaching the `runtime !== 'gjs'`
- * branch that never touches gjs. Every showcase was unreachable on a host
- * without gjs (Windows, plain Node/bun/deno) — including the default path,
- * since `defaultExampleRuntime()` falls back to the host runtime for exactly
- * those hosts.
+ * The caller must resolve the runtime BEFORE gating on it. Calling
+ * `runMinimalChecks()` (which marks `gjs` `required`) above the line that resolves
+ * `args.runtime` made every showcase unreachable on a host without gjs — `--runtime
+ * node` aborted with "Missing system dependencies: ✗ GJS" before reaching the
+ * branch that never touches gjs, the default path included.
  */
 export function requiresGjsSystemDeps(runtime) {
     return buildAppForRuntime(runtime) === 'gjs';
@@ -72,9 +66,8 @@ export function isRuntimeOnPath(probe) {
     }
 }
 /**
- * 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
+ * Whether a specific runtime is runnable here. The HOST runtime needs no PATH probe
+ * — the CLI is executing on it; every other runtime is probed via
  * `<binary> --version`.
  */
 export function isRuntimeAvailable(runtime) {
@@ -88,30 +81,26 @@ export function availableRuntimes() {
  * The default `--runtime` for running a prebuilt EXAMPLE/SHOWCASE: `gjs`
  * whenever gjs is runnable here, else the host runtime.
  *
- * This is deliberately NOT a plain `hostRuntime()`. A showcase's canonical
- * artifact is its `--app gjs` bundle (`gjsify.main`) — that is what every
- * showcase ships, what the `gjs` path installs via `gjsify dlx`, and what the
- * docs call the default. Following the host instead means `npx @gjsify/cli
- * showcase <name>` (host = node) silently asks for the `--app node` bundle,
- * which most showcases do not ship and which additionally needs
- * `@gjsify/node-gi` in the consumer's project — so the FIRST-RUN experience of
- * the primary documented entry point failed on a missing file.
+ * Deliberately NOT a plain `hostRuntime()`. A showcase's canonical artifact is its
+ * `--app gjs` bundle (`gjsify.main`) — what every showcase ships and what `gjsify
+ * dlx` installs. Following the host instead makes `npx @gjsify/cli showcase <name>`
+ * (host = node) ask for the `--app node` bundle, which most showcases do not ship
+ * and which also needs `@gjsify/node-gi` in the consumer's project, so the
+ * first-run experience of the primary documented entry point failed on a missing
+ * file.
  *
- * Same rule `gjsify run` already applies in its bare-file path, where a
- * `--app gjs` bundle stays on gjs regardless of host (`isLikelyGjsBundle`);
- * here the "is it a gjs artifact" question is answered by the command instead
- * of by sniffing the file. `--runtime` still overrides explicitly, and a host
- * WITHOUT gjs (a plain Node/bun/deno box) keeps following the host so the
+ * Same rule `gjsify run` applies in its bare-file path (`isLikelyGjsBundle`), with
+ * "is it a gjs artifact" answered by the command rather than by sniffing the file.
+ * `--runtime` still overrides, and a host WITHOUT gjs keeps following the host so
  * node-capable showcases stay runnable there.
  */
 export function defaultExampleRuntime() {
     return isRuntimeAvailable('gjs') ? 'gjs' : hostRuntime();
 }
 /**
- * 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).
+ * A package's declared example runtimes, or `null` when it declares none (the
+ * permissive case). Unknown entries are dropped so a future runtime name does not
+ * hard-error against an older CLI.
  */
 export function readDeclaredRuntimes(pkg) {
     const list = pkg?.gjsify?.example?.runtimes;
@@ -120,10 +109,9 @@ export function readDeclaredRuntimes(pkg) {
     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.
+ * Validate a requested runtime against a package's declaration; a `null`
+ * declaration is permissive. Returns a message rather than throwing, so callers
+ * print it and exit cleanly.
  */
 export function checkRuntimeSupported(runtime, declared, name) {
     if (declared === null)