@gjsify/cli 0.35.0 → 0.37.0

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,27 +122,42 @@ 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.
     const shown = [cmd, ...launchArgs.map((a) => (a.includes(' ') ? `"${a}"` : a))].join(' ');
-    console.error(`$ ${envPrefix ? `${envPrefix} ` : ''}${shown}`);
+    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 — 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) => {
         child.on('close', (code) => {
-            if (code !== 0)
+            if (code !== 0) {
+                childCode = code ?? 1;
                 reject(new Error(`${runtime} exited with code ${code}`));
+            }
             else
                 resolvePromise();
         });
         child.on('error', reject);
     }).catch((err) => {
         console.error(err.message);
-        process.exit(1);
+        failed = true;
     });
+    // `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);
+    }
     if (options.exitOnSuccess)
-        process.exit(0);
+        return process.exit(0);
 }

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)

package/lib/utils/spawn.d.ts

@@ -2,12 +2,10 @@ import type { ChildProcess } from 'node:child_process';
 /**
  * What the calling command does once this spawn settles.
  *
- * - `'exit'` — the command terminates the process itself (`process.exit(…)`,
- *   `forceExit(…)`, …). The armed GJS main loop is quit by that exit, so the
- *   streaming async `spawn` is safe on both hosts.
- * - `'return'` — the command returns normally and lets the CLI unwind. Under
- *   GJS that MUST NOT leave a main loop armed, so the child is run on the
- *   blocking `spawnSync` path instead.
+ * - `'exit'` — the command terminates the process itself, which quits the armed GJS
+ *   main loop, so the streaming async `spawn` is safe on both hosts.
+ * - `'return'` — the command returns and lets the CLI unwind. Under GJS that must
+ *   not leave a main loop armed, so the child runs on the blocking `spawnSync` path.
  *
  * See the module header for the full rationale.
  */
@@ -17,59 +15,48 @@ export interface SpawnToCompletionOptions {
     completion: SpawnCompletionContract;
     /** Working directory for the child. Defaults to the parent's. */
     cwd?: string;
-    /**
-     * Environment for the child. Omit to inherit the parent's environment
-     * verbatim (what `spawn` does with no `env`).
-     */
+    /** Environment for the child. Omit to inherit the parent's verbatim. */
     env?: NodeJS.ProcessEnv;
     /**
-     * Seed `FORCE_COLOR=1` (on top of `env` ?? `process.env`) unless the user
-     * explicitly set `FORCE_COLOR` or `NO_COLOR`, so tools that key on
-     * `process.stdout.isTTY` (chalk, picocolors, …) still emit ANSI when their
-     * stdout is a pipe. Mirrors yarn / npm. Default `false`.
+     * Seed `FORCE_COLOR=1` unless `FORCE_COLOR`/`NO_COLOR` is already set, so tools
+     * keying on `process.stdout.isTTY` still emit ANSI into a pipe. Mirrors
+     * yarn/npm. Default `false`.
      */
     color?: boolean;
     /**
-     * `'inherit'` (default) forwards the parent's stdio. `'pipe'` gives the
-     * caller `child.stdout` / `child.stderr` via {@link onSpawn} — only
-     * meaningful together with `completion: 'exit'` (see {@link onSpawn}).
+     * `'inherit'` (default) forwards the parent's stdio; `'pipe'` gives the caller
+     * `child.stdout`/`child.stderr` via {@link onSpawn}, so it needs
+     * `completion: 'exit'`.
      *
-     * `'inherit-stderr'` inherits, but routes the child's **stdout to the
-     * parent's stderr**. For a parent whose own stdout is a machine-readable
-     * stream: `gjsify pack --json` emits JSON there, and a lifecycle script's
-     * log lines interleaved into it make the result unparseable for every
-     * caller that pipes it into `JSON.parse`.
+     * `'inherit-stderr'` inherits but routes the child's **stdout to the parent's
+     * stderr**, for a parent whose own stdout is machine-readable: `gjsify pack
+     * --json` emits JSON there, and interleaved lifecycle-script log lines make it
+     * unparseable for anything piping into `JSON.parse`.
      */
     stdio?: 'inherit' | 'pipe' | 'inherit-stderr';
     /**
-     * Run `cmd` through the platform shell, so `&&`, `|` and env-var
-     * references work. `cmd` is then a whole command LINE and `args` must be
-     * empty — that is npm/yarn script semantics.
-     *
-     * Skips the win32 command rewrite by design, per this file's own rule:
-     * Node routes a `shell: true` spawn through `%COMSPEC%`, which finds
-     * `.cmd` shims on its own, so rewriting the string would corrupt it.
+     * Run `cmd` through the platform shell so `&&`, `|` and env-var references work.
+     * `cmd` is then a whole command LINE and `args` must be empty — npm/yarn script
+     * semantics. Skips the win32 rewrite by design: Node routes it through
+     * `%COMSPEC%`, which finds `.cmd` shims itself, so rewriting would corrupt it.
      */
     shell?: boolean;
     /**
-     * Invoked synchronously with the live `ChildProcess` right after a
-     * successful async spawn — the seam for kill-tracking registries and for
-     * wiring piped output forwarders.
-     *
-     * ONLY fires on the streaming path: the blocking `spawnSync` path has no
-     * `ChildProcess` handle at all. A site that needs the handle must
-     * therefore declare `completion: 'exit'`.
+     * Called synchronously with the live `ChildProcess` after a successful async
+     * spawn — the seam for kill-tracking registries and piped output forwarders.
+     * ONLY fires on the streaming path (the blocking path has no handle), so a site
+     * needing the handle must declare `completion: 'exit'`.
      */
     onSpawn?: (child: ChildProcess) => void;
     /**
-     * Map an `ENOENT` spawn failure (command not on PATH) to a domain error
-     * carrying an install hint. Other spawn errors are rejected as-is.
+     * Map an `ENOENT` spawn failure to a domain error carrying an install hint.
+     * Other spawn errors are rejected as-is.
      */
     notFound?: (err: NodeJS.ErrnoException) => Error;
     /**
-     * Capture ceiling for the blocking path. Defaults to 64 MiB — a
-     * full-workspace lint with many findings runs well past Node's 1 MB
-     * default, and an overflow would silently truncate diagnostics.
+     * Capture ceiling for the blocking path, default 64 MiB: a full-workspace lint
+     * with many findings runs well past Node's 1 MB default, and an overflow would
+     * silently truncate diagnostics.
      */
     maxBuffer?: number;
 }
@@ -82,13 +69,10 @@ export interface SpawnCompletion {
 /**
  * Run `cmd args…` to completion and resolve with its exit code and signal.
  *
- * Resolves for ANY child exit — a non-zero code is data, not an error, so each
- * call site keeps its own failure message. Rejects only when the child could
- * not be started at all (mapped through {@link SpawnToCompletionOptions.notFound}
- * for ENOENT).
- *
- * Picks the streaming async path or the blocking captured path per the GJS
- * teardown contract documented at the top of this file.
+ * Resolves for ANY child exit — a non-zero code is data, not an error, so each call
+ * site keeps its own failure message. Rejects only when the child could not be
+ * started (ENOENT mapped through {@link SpawnToCompletionOptions.notFound}). Picks
+ * the streaming or blocking path per the teardown contract in the module header.
  */
 export declare function spawnToCompletion(cmd: string, args: readonly string[], opts: SpawnToCompletionOptions): Promise<SpawnCompletion>;
 /**