@gjsify/cli 0.35.0 → 0.37.0

package/lib/utils/resolve-plugin-by-name.js

@@ -8,10 +8,9 @@
 //     ]
 //   }
 //
-// Lets `package.json#gjsify` describe the full plugin chain without dropping
-// to a JS-form config file (`gjsify.config.mjs`). Resolution is anchored at
-// the project root (where the config lives) so the project's own
-// `node_modules` wins over the CLI's own dependencies.
+// Lets `package.json#gjsify` describe the full plugin chain without dropping to a JS-form config
+// file (`gjsify.config.mjs`). Resolution is anchored at the project root, so the project's own
+// `node_modules` wins over the CLI's dependencies.
 import { createRequire } from 'node:module';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -22,9 +21,8 @@ export function isPluginByName(value) {
     return (typeof value === 'object' &&
         value !== null &&
         typeof value.name === 'string' &&
-        // RolldownPluginOption can be `false | null | undefined | Plugin | Promise<Plugin>`.
-        // A real plugin always has a function-shape behavior; `name` alone is shared
-        // with our shape, so we additionally require absence of plugin-shape fields.
+        // `name` alone does not discriminate — a real Rolldown plugin has it too — so the
+        // absence of every plugin-shape hook is what separates the two.
         !('apply' in value) &&
         !('resolveId' in value) &&
         !('load' in value) &&
@@ -33,13 +31,10 @@ export function isPluginByName(value) {
         !('generateBundle' in value));
 }
 /**
- * Resolve a list of mixed user plugins. Entries that are already plugin
- * objects pass through unchanged; entries shaped like `PluginByName` get
- * dynamically imported, instantiated with their `options`, and returned in
- * the same position. Resolution is anchored at `projectDir`.
- *
- * Throws when a name fails to resolve, when the chosen export is not a
- * function, or when the factory returns nothing.
+ * Resolve a list of mixed user plugins, anchored at `projectDir`. Plugin objects pass through
+ * unchanged; `PluginByName` entries are imported, instantiated with their `options`, and returned
+ * in the same position. Throws when a name fails to resolve, the chosen export is not a function,
+ * or the factory returns nothing.
  */
 export async function resolveUserPlugins(plugins, projectDir, options = {}) {
     const loadModule = options.loadModule ?? defaultLoadModule;

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

@@ -1,32 +1,34 @@
 import { type NativeEnv } from './detect-native-packages.js';
 /**
- * Pure env computation for a given bundle. Returns the typelib +
- * shared-library search paths that {@link runGjsBundle} would inject into the
- * spawned `gjs` process, plus the formatted env-prefix string used for the
- * `$ …` echo. Which library variable is set is host-dependent
- * (`LD_LIBRARY_PATH` / `DYLD_LIBRARY_PATH` / `PATH`) — see `buildNativeEnv`.
+ * Pure env computation: the typelib + shared-library search paths {@link runGjsBundle} would
+ * inject into the spawned `gjs`, plus the formatted prefix for the `$ …` echo. Which library
+ * variable is set is host-dependent (`LD_LIBRARY_PATH` / `DYLD_LIBRARY_PATH` / `PATH`) — see
+ * `buildNativeEnv`.
  */
 export declare function computeNativeEnvForBundle(bundlePath: string, cwd?: string, inherited?: Record<string, string | undefined>): {
     env: NativeEnv;
     envPrefix: string;
 };
 /**
- * Run a GJS bundle, automatically setting LD_LIBRARY_PATH and GI_TYPELIB_PATH
- * for any installed native gjsify packages discoverable from either the CWD
- * or the bundle's own node_modules tree.
+ * Options for {@link runGjsBundle}, which runs a GJS bundle with `GI_TYPELIB_PATH` and the
+ * host's library variable set for any native gjsify packages discoverable from the CWD or the
+ * bundle's own node_modules tree.
  */
 export interface RunGjsBundleOptions {
     /**
-     * Exit this process with code 0 once the child succeeds. Under GJS,
-     * `ensureMainLoop()` (armed by spawn) keeps the parent's GLib loop alive
-     * after the child exits — a TERMINAL caller (`gjsify run <file>`, `dlx`)
-     * must opt in here or it parks forever (this exact gap hung CI's
-     * "Test WebGL conformance" for 83 min: the suite finished in 1.35 s, the
-     * parent `gjsify run conformance.gjs.js` never exited). Callers that
-     * continue after the bundle (e.g. `gjsify test`'s multi-runtime
-     * aggregation loop) MUST leave this false — an unconditional exit here
-     * truncated `gjsify test` after the first gjs bundle.
+     * Exit this process with code 0 once the child succeeds. Under GJS, `ensureMainLoop()`
+     * (armed by spawn) keeps the parent's GLib loop alive after the child exits, so a TERMINAL
+     * caller (`gjsify run <file>`, `dlx`) must opt in or it parks forever — this gap hung CI's
+     * WebGL conformance job for 83 min on a suite that finished in 1.35 s. Callers that
+     * continue after the bundle (`gjsify test`'s multi-runtime loop) MUST leave this false; an
+     * unconditional exit truncated `gjsify test` after the first gjs bundle.
      */
     exitOnSuccess?: boolean;
+    /**
+     * Suppress the `$ <env> gjs -m …` echo. Worth its ~2 kB of env prefix for a one-shot
+     * `gjsify run <bundle>`; pure noise for a build script invoked a dozen times per chain
+     * (`utils/node-script.ts`).
+     */
+    quiet?: boolean;
 }
 export declare function runGjsBundle(bundlePath: string, extraArgs?: string[], options?: RunGjsBundleOptions): Promise<void>;

package/lib/utils/run-gjs.js

@@ -1,30 +1,22 @@
 // Shared utility for running a GJS bundle with native package env vars.
 // Used by `gjsify run`, `gjsify dlx`, and the showcase command (via dlx).
 //
-// Detection runs the same exhaustive node_modules walker (`detectNativePackages`)
-// from two starting points and merges by package name (CWD shadows bundle):
+// Detection runs `detectNativePackages` from two starting points and merges by package name
+// (CWD shadows bundle): `process.cwd()` for native deps in the user's project, and
+// `dirname(bundlePath)` for those in whatever node_modules the bundle lives in — critical for
+// `gjsify dlx`, where the bundle sits under `~/.cache/gjsify/dlx/<sha>/…` and the user's CWD
+// is unrelated. The bundle-side walk also catches transitive deps' typelibs.
 //
-//   1. process.cwd()          — picks up native deps in the user's project
-//                               (yarn / pnpm / npm node_modules walking up).
-//   2. dirname(bundlePath)    — picks up native deps in whatever node_modules
-//                               the bundle lives in. Critical for `gjsify dlx`
-//                               where the bundle resides in
-//                               `~/.cache/gjsify/dlx/<sha>/.../node_modules/<pkg>/dist/`
-//                               and the user's CWD is unrelated. The bundle-side
-//                               walk also catches transitive deps' typelibs.
-//
-// Env composition is split out as `computeNativeEnvForBundle()` — a pure
-// function that takes a bundle path + cwd and returns the env it would inject.
-// This lets the e2e tests assert the env without spawning gjs.
+// Env composition is split out as the pure `computeNativeEnvForBundle()` so the e2e tests can
+// assert the env without spawning gjs.
 import { spawn } from 'node:child_process';
 import { dirname, resolve } from 'node:path';
 import { detectNativePackages, buildNativeEnv } from './detect-native-packages.js';
 /**
- * Pure env computation for a given bundle. Returns the typelib +
- * shared-library search paths that {@link runGjsBundle} would inject into the
- * spawned `gjs` process, plus the formatted env-prefix string used for the
- * `$ …` echo. Which library variable is set is host-dependent
- * (`LD_LIBRARY_PATH` / `DYLD_LIBRARY_PATH` / `PATH`) — see `buildNativeEnv`.
+ * Pure env computation: the typelib + shared-library search paths {@link runGjsBundle} would
+ * inject into the spawned `gjs`, plus the formatted prefix for the `$ …` echo. Which library
+ * variable is set is host-dependent (`LD_LIBRARY_PATH` / `DYLD_LIBRARY_PATH` / `PATH`) — see
+ * `buildNativeEnv`.
  */
 export function computeNativeEnvForBundle(bundlePath, cwd = process.cwd(), inherited = process.env) {
     const resolvedBundle = resolve(bundlePath);
@@ -32,23 +24,16 @@ export function computeNativeEnvForBundle(bundlePath, cwd = process.cwd(), inher
     const bundlePackages = detectNativePackages(dirname(resolvedBundle));
     const seen = new Set(cwdPackages.map((p) => p.name));
     const nativePackages = [...cwdPackages, ...bundlePackages.filter((p) => !seen.has(p.name))];
-    // `inherited` feeds BOTH halves — the composition and the comparison. Split
-    // them and the win32 branch disagrees with itself: `buildNativeEnv` writes
-    // the library variable back under the host's own spelling (`Path` in a
-    // stock env block), so a comparison keyed on the canonical `PATH` would
-    // look up a key that is not there and call every run a change.
+    // `inherited` feeds BOTH halves — composition and comparison. Split them and the win32
+    // branch disagrees with itself: `buildNativeEnv` writes the library variable back under
+    // the host's own spelling (`Path` in a stock env block), so a comparison keyed on the
+    // canonical `PATH` would look up a key that is not there and call every run a change.
     const env = buildNativeEnv(nativePackages, { env: inherited });
-    // Show only what this CLI actually CHANGED. `buildNativeEnv` prepends the
-    // detected directories to the inherited value and returns the result
-    // unconditionally, so with no native packages it hands back the host's own
-    // variable verbatim — and the echo then claimed the CLI had set it.
-    //
-    // Harmless on Linux, where `LD_LIBRARY_PATH` is usually unset and the empty
-    // filter caught it. On Windows the library variable IS `PATH`, which is
-    // never empty, so every run printed a ~2 kB dump of the host PATH in front
-    // of a command the user is invited to copy — burying the command, and
-    // claiming a change that never happened. Comparing against the inherited
-    // value is what makes the echo honest on both.
+    // Show only what this CLI actually CHANGED: `buildNativeEnv` prepends to the inherited
+    // value unconditionally, so with no native packages it hands back the host's own variable
+    // verbatim. Harmless on Linux, where `LD_LIBRARY_PATH` is usually unset; on Windows the
+    // library variable IS `PATH`, never empty, so every run printed a ~2 kB dump of the host
+    // PATH in front of a command the user is invited to copy.
     const envPrefix = Object.entries(env)
         .filter(([key, value]) => value !== undefined && value !== '' && value !== inherited[key])
         .map(([key, value]) => `${key}=${value}`)
@@ -62,18 +47,21 @@ export async function runGjsBundle(bundlePath, extraArgs = [], options = {}) {
         ...nativeEnv,
     };
     const gjsArgs = ['-m', bundlePath, ...extraArgs];
-    // Print the exact command being executed so users can copy-paste it to
-    // run gjs directly without the wrapper. Env vars are only shown if we
-    // actually set any (i.e. native gjsify packages were detected).
-    // Use stderr so that children speaking a protocol on stdout (e.g. an
-    // MCP stdio server) receive an uncontaminated stdout stream.
+    // Echo the exact command so users can copy-paste it and run gjs without the wrapper.
+    // stderr, so children speaking a protocol on stdout (an MCP stdio server) keep a clean one.
     const gjsCommand = ['gjs', ...gjsArgs.map((a) => (a.includes(' ') ? `"${a}"` : a))].join(' ');
-    console.error(`$ ${envPrefix ? `${envPrefix} ` : ''}${gjsCommand}`);
+    if (!options.quiet)
+        console.error(`$ ${envPrefix ? `${envPrefix} ` : ''}${gjsCommand}`);
     const child = spawn('gjs', gjsArgs, { env, stdio: 'inherit' });
     let failed = false;
+    // The CHILD's own exit code, re-raised verbatim; a spawn error (no `gjs` on PATH) has none
+    // of its own and falls back to 1. Collapsing every failure to 1 lost information callers
+    // act on — a chain reading `$?` to tell "tool failed" from "tool says no" saw 1 for both.
+    let childCode = 1;
     await new Promise((resolvePromise, reject) => {
         child.on('close', (code) => {
             if (code !== 0) {
+                childCode = code ?? 1;
                 reject(new Error(`gjs exited with code ${code}`));
             }
             else {
@@ -86,16 +74,14 @@ export async function runGjsBundle(bundlePath, extraArgs = [], options = {}) {
         failed = true;
     });
     if (failed) {
-        // Set `process.exitCode` synchronously BEFORE exiting: under GJS
-        // `process.exit()` is deferred (the GLib main loop is armed), so when
-        // this runs via run.ts's in-process script dispatch, execution returns
-        // to the caller, which propagates by reading `process.exitCode`. Without
-        // this, `gjsify run <script>` whose body is `gjsify run <bundle>`
-        // swallowed a non-zero gjs exit and returned 0 — masking a failing
-        // `test:gjs` in the `test` script chain (and, via `gjsify foreach test`,
-        // in CI). The `return` guards against a fall-through second `exit`.
-        process.exitCode = 1;
-        return process.exit(1);
+        // Set `process.exitCode` synchronously BEFORE exiting: under GJS `process.exit()` is
+        // deferred (the GLib main loop is armed), so under run.ts's in-process script dispatch
+        // execution returns to the caller, which propagates by reading `process.exitCode`.
+        // Without it, `gjsify run <script>` wrapping `gjsify run <bundle>` swallowed a non-zero
+        // gjs exit and returned 0 — masking a failing `test:gjs` in the `test` chain, and via
+        // `gjsify foreach test` in CI. The `return` guards a fall-through second `exit`.
+        process.exitCode = childCode;
+        return process.exit(childCode);
     }
     // See RunGjsBundleOptions.exitOnSuccess — terminal callers opt in,
     // mid-flow callers (test.ts's runtime loop) keep the process alive.

package/lib/utils/run-lifecycle-script.d.ts

@@ -2,20 +2,16 @@ export interface RunLifecycleScriptOptions {
     /** When true, do not throw on missing scripts — return `false` instead. */
     optional?: boolean;
     /**
-     * Stdio inheritance for the spawned script. Default `'inherit'` so output
-     * appears in the parent's terminal. Pass `'inherit-stderr'` to mirror
-     * inheritance but redirect the child's stdout → parent's stderr — used by
-     * `gjsify pack --json` and `gjsify publish` so the parent's stdout stays
-     * a clean JSON stream (script log lines would otherwise corrupt the
-     * machine-readable output that callers `JSON.parse`).
+     * Stdio for the spawned script; default `'inherit'`. `'inherit-stderr'` redirects the
+     * child's stdout → parent's stderr, used by `gjsify pack --json` and `gjsify publish` so
+     * script log lines cannot corrupt the JSON stream callers `JSON.parse`.
      */
     stdio?: 'inherit' | 'inherit-stderr' | 'pipe' | 'ignore';
     /** Extra environment variables layered on top of the defaults. */
     env?: Record<string, string>;
 }
 /**
- * Run a lifecycle script defined in `pkg.scripts[name]` from `wsDir`.
- * Returns `true` if the script existed and exited 0. Returns `false` if
- * `optional: true` and the script is missing. Throws on non-zero exit.
+ * Run the lifecycle script `pkg.scripts[name]` from `wsDir`. `true` when it existed and exited
+ * 0, `false` when it is missing and `optional` is set; throws on a non-zero exit.
  */
 export declare function runLifecycleScript(wsDir: string, pkg: Record<string, unknown>, name: string, opts?: RunLifecycleScriptOptions): Promise<boolean>;

package/lib/utils/run-lifecycle-script.js

@@ -2,47 +2,31 @@
 // `postpack`, `postpublish`, …) from inside a `gjsify pack` / `gjsify
 // publish` flow.
 //
-// Why this exists separately from `gjsify run`: `gjsify run <script>` ends
-// with `process.exit(<code>)` so it can be used as a CLI entrypoint that
-// behaves like `yarn run` / `npm run`. That's wrong for the embedded use
-// case where pack/publish needs the lifecycle script to finish, then keep
-// running its own logic. This helper resolves to a Promise that settles
-// when the child exits.
+// Separate from `gjsify run` because that ends with `process.exit(<code>)` so it can act as a
+// CLI entrypoint like `yarn run`. Pack/publish instead needs the lifecycle script to finish and
+// then keep running its own logic, so this settles a Promise when the child exits.
 //
-// ## Not calling `process.exit()` is what ARMED the hang, not what avoided it
-//
-// This header used to end "no process.exit, no GLib-mainloop intermingling
-// from `ensureMainLoop`". The second half was exactly backwards, and it is why
-// nobody looked here for #1010.
-//
-// `@gjsify/child_process`'s async `spawn()` calls `ensureMainLoop()`
-// unconditionally — the caller has no say. That arms a GJS main-loop hook whose
-// blocking `g_main_loop_run()` only `process.exit()` tears down. So a helper
-// that spawns asynchronously and deliberately does NOT exit leaves the loop
-// armed forever: `gjsify pack` on a package with a `prepack` wrote its tarball,
-// printed its complete JSON, and then parked at 0% CPU until killed at 5m30s.
-// A package with no lifecycle script exited in under a second, and the same
-// pack under Node exited in 0.68s.
-//
-// `utils/spawn.ts` already owns that contract and makes every call site DECLARE
-// which side of it they are on. This helper was the one spawn in the CLI that
-// bypassed it — the seventh of the "six near-identical wrappers" that file was
-// written to consolidate. It now goes through it with `completion: 'return'`,
-// which is what "settle, then keep running our own logic" means.
+// NOT calling `process.exit()` is what ARMS a hang, not what avoids it (#1010):
+// `@gjsify/child_process`'s async `spawn()` calls `ensureMainLoop()` unconditionally — the
+// caller has no say — and that main-loop hook's blocking `g_main_loop_run()` is torn down only
+// by `process.exit()`. A helper that spawns asynchronously and deliberately does not exit
+// therefore leaves the loop armed forever: `gjsify pack` on a package with a `prepack` wrote
+// its tarball, printed its complete JSON, then parked at 0% CPU until killed at 5m30s (no
+// lifecycle script: under a second; the same pack under Node: 0.68s). `utils/spawn.ts` owns
+// that contract and makes every call site DECLARE which side of it it is on; this goes through
+// it with `completion: 'return'`.
 //
 // Matches yarn / npm script semantics:
 //   - `shell: true` so `&&` / `|` / env-var refs work
 //   - PATH prepended with `<wsDir>/node_modules/.bin` + monorepo-root bin
-//   - `npm_lifecycle_event` / `npm_package_name` / `npm_package_version`
-//     env vars set
+//   - `npm_lifecycle_event` / `npm_package_name` / `npm_package_version` set
 //   - FORCE_COLOR=1 default unless caller overrides
 import { delimiter, join } from 'node:path';
 import { describeExit, spawnToCompletion } from './spawn.js';
 import { findWorkspaceRoot } from './workspace-root.js';
 /**
- * Run a lifecycle script defined in `pkg.scripts[name]` from `wsDir`.
- * Returns `true` if the script existed and exited 0. Returns `false` if
- * `optional: true` and the script is missing. Throws on non-zero exit.
+ * Run the lifecycle script `pkg.scripts[name]` from `wsDir`. `true` when it existed and exited
+ * 0, `false` when it is missing and `optional` is set; throws on a non-zero exit.
  */
 export async function runLifecycleScript(wsDir, pkg, name, opts = {}) {
     const scripts = pkg.scripts ?? {};
@@ -57,11 +41,9 @@ export async function runLifecycleScript(wsDir, pkg, name, opts = {}) {
     if (monorepoRoot && monorepoRoot !== wsDir) {
         binDirs.push(join(monorepoRoot, 'node_modules', '.bin'));
     }
-    // Match yarn / npm color-forcing default — see runScript() in run.ts
-    // for the full reasoning. Without this, lifecycle scripts that call
-    // tools like biome / esbuild / tsc lose ANSI color in piped contexts
-    // (CI logs, redirected output) because `process.stdout.isTTY` is
-    // false for the spawned child.
+    // Match yarn / npm color-forcing — see `runScript()` in run.ts. Without it, scripts calling
+    // biome / esbuild / tsc lose ANSI color in piped contexts (CI logs, redirected output)
+    // because `process.stdout.isTTY` is false for the spawned child.
     const colorEnv = process.env.FORCE_COLOR !== undefined || process.env.NO_COLOR !== undefined ? {} : { FORCE_COLOR: '1' };
     const env = {
         ...process.env,
@@ -72,16 +54,15 @@ export async function runLifecycleScript(wsDir, pkg, name, opts = {}) {
         npm_package_version: pkg.version ?? '',
         ...opts.env,
     };
-    // `'ignore'` has no `spawnToCompletion` equivalent and no call site in the
-    // tree; folding it onto `'inherit'` would silently start printing where a
-    // caller asked for silence, so it is rejected rather than approximated.
+    // `'ignore'` has no `spawnToCompletion` equivalent and no call site; folding it onto
+    // `'inherit'` would start printing where a caller asked for silence, so it is rejected
+    // rather than approximated.
     if (opts.stdio === 'ignore') {
         throw new Error('gjsify lifecycle-script: stdio "ignore" is not supported — see utils/spawn.ts');
     }
     const result = await spawnToCompletion(literal, [], {
-        // The whole point of this helper: pack/publish waits for the script and
-        // then keeps running. Under GJS that is the blocking path, which is what
-        // keeps the armed main loop from outliving us — see the header.
+        // pack/publish waits for the script, then keeps running. Under GJS that is the blocking
+        // path, which is what keeps the armed main loop from outliving us — see the header.
         completion: 'return',
         cwd: wsDir,
         env: env,

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`. */
@@ -27,31 +21,27 @@ export declare function nodeBinary(): string;
 export interface RunNodeBundleOptions {
     /** Exit this process with code 0 once the child succeeds (terminal callers). */
     exitOnSuccess?: boolean;
+    /** Suppress the `$ <env> node …` echo — see `RunGjsBundleOptions.quiet`. */
+    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>;