@gjsify/cli 0.13.1 → 0.14.0

package/lib/actions/build.js

@@ -2,7 +2,7 @@ import { runBundle, runWatch, bundleToChunks } from '../bundler-pick.js';
 import { gjsifyPlugin, textLoaderPlugin, resolveShebangLine, NODE_SHEBANG } from '@gjsify/rolldown-plugin-gjsify';
 import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { resolveUserPlugins } from '../utils/resolve-plugin-by-name.js';
-import { resolveGlobalsList, writeRegisterInjectFile, detectAutoGlobals } from '@gjsify/rolldown-plugin-gjsify/globals';
+import { resolveGlobalsList, writeRegisterInjectFile, detectAutoGlobals, detectNodeGiGlobals, } from '@gjsify/rolldown-plugin-gjsify/globals';
 import { pnpPlugin } from '@gjsify/rolldown-plugin-pnp';
 import { dirname, extname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -402,6 +402,36 @@ export class BuildAction {
             { extraGlobalsList: extras, excludeGlobals, cwd: process.cwd() }, bundleToChunks);
             pluginOpts.autoGlobalsInject = injectPath;
         }
+        else if (app === 'node' && autoMode) {
+            // `--app node` reverse direction: detect GJS ambient globals
+            // (`print`/`imports`/…) in the bundled, tree-shaken output and
+            // inject `@gjsify/node-gi/globals` only when present. A single
+            // in-memory analysis pass (the shim is external — no convergence
+            // loop). Gated on `autoMode` so `--globals none` opts out. The
+            // detection must run BEFORE the final build so the entry can be
+            // wrapped; nothing is injected when no globals are referenced (the
+            // eager-native-load regression guard).
+            const gjsifyPluginFactory = async (opts) => {
+                const cfg = await gjsifyPlugin({
+                    input: userBundler.input,
+                    output: { file: outfile, dir: outdir },
+                    userExternal,
+                    userBanner,
+                    userAliases: aliases,
+                    shebang: this.configData.shebang,
+                }, opts);
+                return { options: cfg.options, plugins: cfg.plugins };
+            };
+            const needsGiGlobals = await detectNodeGiGlobals({
+                input: userBundler.input,
+                plugins: [...pnpPlugins, ...userPlugins],
+                external: userBundler.external,
+                transform: userBundler.transform,
+                format,
+            }, pluginOpts, gjsifyPluginFactory, bundleToChunks);
+            if (needsGiGlobals)
+                pluginOpts.nodeGiGlobalsInject = true;
+        }
         else if (extras) {
             pluginOpts.autoGlobalsInject = await this.resolveGlobalsInject(app, extras, verbose);
         }

package/lib/commands/affected.js

@@ -119,8 +119,15 @@ const IGNORE = [
     /^refs\//,
     /^website\//,
     /^docs\//,
-    /^\.github\/workflows\/(deploy-docs|commitlint|release|audit-runtimes|prebuilds)\.yml$/,
+    /^\.github\/workflows\/(deploy-docs|commitlint|release|audit-runtimes|prebuilds|node-gi)\.yml$/,
     /^\.githooks\//,
+    // @gjsify/node-gi (the Node-native GObject-Introspection engine, Axis 5) is
+    // NOT a gjsify workspace member — the GJS-first install/foreach tooling can't
+    // build its node-gyp addon, so the main workflow neither builds nor tests it.
+    // Its own `.github/workflows/node-gi.yml` is the source of truth (built +
+    // tested on Node). Without this carve-out its files map to no workspace and
+    // land in `unmatched`, forcing a conservative full run on every node-gi PR.
+    /^packages\/node-gi\//,
     // Flatpak build/distribution tooling (SDK-extension manifest + metainfo).
     // Like `.githooks/`, it has no package-test consumers; its own
     // `tests/e2e/flatpak-sdk-extension` runs on `tests/e2e/**` / global triggers.

package/lib/commands/install.js

@@ -619,6 +619,11 @@ async function workspaceInstall(cwd, args, signal) {
             overrides,
             signal,
             progress,
+            // Workspace-named packages are symlinked above — the native backend
+            // must never fetch a same-named published version over those
+            // symlinks (e.g. a `types-dev/<lib>` workspace that also exists on
+            // npm and is pinned transitively in the lockfile).
+            workspaceNames: new Set(byName.keys()),
         });
     }
     else if (args.verbose) {
@@ -644,6 +649,7 @@ async function workspaceInstall(cwd, args, signal) {
             lockfile: !args.immutable,
             frozen: args.immutable,
             signal,
+            workspaceNames: new Set(byName.keys()),
         });
     }
     // Re-wire workspace symlinks once more now that the external + scoped

package/lib/commands/storybook.d.ts

@@ -5,6 +5,7 @@ interface StorybookCliOptions {
     title?: string;
     globals?: string;
     out?: string;
+    runtime?: string;
     watch: boolean;
     buildOnly: boolean;
 }

package/lib/commands/storybook.js

@@ -1,7 +1,14 @@
 // `gjsify storybook` — discover every *.story.ts in a project, generate a tiny
-// entry that registers them, then build (`--app gjs`) and launch the generic
+// entry that registers them, then build and launch the generic
 // @gjsify/storybook component browser. No per-project storybook app needed.
 //
+// `--runtime gjs` (default) builds `--app gjs` and runs it with `gjs -m`.
+// `--runtime node` builds `--app node` (gi:// → @gjsify/node-gi reverse bridge)
+// and runs it with `node` — the SAME storybook source rendering on Node.js. The
+// node path wires GI_TYPELIB_PATH/LD_LIBRARY_PATH like `gjsify run` (so any
+// native @gjsify bridge a story uses resolves) and requires `@gjsify/node-gi`
+// installed in the project (kept external by the bundler, a native addon).
+//
 // Dispatch is IN-PROCESS (runCli + runGjsBundle), not a re-spawn of the CLI:
 // the showcase-style `spawn(process.execPath, [cliBin, …])` pattern assumes
 // Node, but under the committed GJS bundle `process.execPath` is `gjs` and the
@@ -82,6 +89,13 @@ export const storybookCommand = {
         .option('out', {
         description: 'Output bundle path (default: node_modules/.cache/gjsify-storybook)',
         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.',
+        type: 'string',
+        choices: ['gjs', 'node'],
+        default: 'gjs',
     })
         .option('watch', {
         description: 'Rebuild and relaunch when a story file changes',
@@ -97,10 +111,16 @@ 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');
+        // 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';
         const cacheDir = join(cwd, 'node_modules', '.cache', 'gjsify-storybook');
         mkdirSync(cacheDir, { recursive: true });
         const entryPath = join(cacheDir, 'entry.ts');
-        const outPath = args.out ? resolve(cwd, args.out) : join(cacheDir, 'storybook.gjs.mjs');
+        const outPath = args.out ? resolve(cwd, args.out) : join(cacheDir, `storybook.${app}.mjs`);
         const writeEntry = () => {
             const files = findStoryFiles(storiesDir).sort();
             writeFileSync(entryPath, generateEntry(files, applicationId, title));
@@ -111,24 +131,46 @@ export const storybookCommand = {
             console.error(`No *.story.ts files found under ${relative(cwd, storiesDir) || storiesDir}`);
             process.exit(1);
         }
-        console.log(`Found ${initialCount} story file(s) under ${relative(cwd, storiesDir) || '.'}`);
+        console.log(`Found ${initialCount} story file(s) under ${relative(cwd, storiesDir) || '.'} (runtime: ${runtime})`);
         // In-process build — runtime-agnostic (Node uses npm rolldown, GJS uses
         // the @gjsify/rolldown-native facade), no re-spawn of the CLI binary.
         const { runCli } = await import('../cli-app.js');
-        const buildBundle = () => runCli(['build', entryPath, '--app', 'gjs', '--globals', globals, '--outfile', outPath]);
+        const buildBundle = () => runCli(['build', entryPath, '--app', app, '--globals', globals, '--outfile', outPath]);
+        const launch = async () => {
+            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 });
+            }
+        };
         if (!args.watch) {
             await buildBundle();
             if (args.buildOnly)
                 return;
-            const { runGjsBundle } = await import('../utils/run-gjs.js');
-            await runGjsBundle(outPath, [], { exitOnSuccess: true });
+            await launch();
             return;
         }
         // Watch mode: rebuild + relaunch on any change under the stories dir.
         // The storybook bundle only needs system Gtk/Adw typelibs at runtime
-        // (no @gjsify native bridges), so a plain `gjs -m` child is enough and
-        // stays killable for relaunch.
+        // (no @gjsify native bridges), so a plain `gjs -m` / `node` child is
+        // enough and stays killable for relaunch.
         const { watch } = await import('node:fs');
+        const spawnChild = async () => {
+            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('gjs', ['-m', outPath], { stdio: 'inherit' });
+        };
         let child = null;
         let rebuilding = false;
         let pending = false;
@@ -146,7 +188,7 @@ export const storybookCommand = {
                 }
                 await buildBundle();
                 if (!args.buildOnly) {
-                    child = spawn('gjs', ['-m', outPath], { stdio: 'inherit' });
+                    child = await spawnChild();
                 }
             }
             catch (err) {

package/lib/utils/install-backend-native.js

@@ -21,6 +21,7 @@ import { DEFAULT_REGISTRY, fetchPackument, fetchPackumentConditional, fetchTarba
 import { extractTarball } from '@gjsify/tar';
 import { getCachedTarball, getForeignCachedTarball, putCachedTarball, } from './install-tarball-cache.js';
 import { getCachedPackument, putCachedPackument } from './install-packument-cache.js';
+import { assertNativeBackendNodeVersion } from './node-version.js';
 // 16-wide download pool. Matched to the shared Soup.Session's lifted
 // `max-conns-per-host` (see @gjsify/fetch `getSharedSession`) — a higher pool
 // here only translates into real concurrency because that cap was raised from
@@ -30,6 +31,9 @@ const DEFAULT_CONCURRENCY = Number(process.env.GJSIFY_INSTALL_CONCURRENCY ?? '16
 const LOCKFILE_NAME = 'gjsify-lock.json';
 const LOCKFILE_VERSION = 2;
 export async function installPackagesNative(opts) {
+    // Fail clearly on an unsupported Node major BEFORE touching the ABI-locked
+    // native deps — otherwise they SIGSEGV mid-extract with no actionable message.
+    assertNativeBackendNodeVersion();
     if (opts.specs.length === 0) {
         throw new Error('installPackagesNative: empty specs list');
     }
@@ -72,12 +76,29 @@ export async function installPackagesNative(opts) {
         // (and silently bumping transitive deps) on a one-package add.
         const preferred = !opts.refreshLockfile && existingLock ? buildPreferredVersions(existingLock) : undefined;
         log('install: resolving %d top-level spec(s) → %s%s', opts.specs.length, opts.prefix, preferred ? ` (preserving ${preferred.size} locked name(s))` : '');
-        nodes = await resolveDeps(opts.specs, npmrc, log, opts.overrides, opts.skipDeps, opts.signal, progress, preferred);
+        nodes = await resolveDeps(opts.specs, npmrc, log, opts.overrides, opts.skipDeps, opts.signal, progress, preferred, opts.workspaceNames);
         if (opts.lockfile) {
             writeLockfile(lockfilePath, opts.specs, nodes);
             log('install: wrote %s (%d entries)', LOCKFILE_NAME, nodes.length);
         }
     }
+    // A package whose name is one of the monorepo's own workspaces is provided
+    // by a workspace symlink (wired by `workspaceInstall`), NOT by a registry
+    // tarball — even when the lockfile or a transitive edge pins a same-named
+    // published version. Drop those nodes from the fetch/extract set so
+    // `extractOne` never `rm`s + overwrites the workspace source symlink (its
+    // data-loss guard would otherwise abort the whole install). This keeps
+    // `--immutable` robust against a committed lockfile that still carries such
+    // registry entries (it is built from the lockfile verbatim and never runs
+    // `resolveDeps`); a fresh resolve additionally skips them at the source.
+    if (opts.workspaceNames && opts.workspaceNames.size > 0) {
+        const before = nodes.length;
+        nodes = nodes.filter((n) => !opts.workspaceNames.has(n.name));
+        const dropped = before - nodes.length;
+        if (dropped > 0) {
+            log('install: %d workspace-provided package(s) symlinked, not fetched', dropped);
+        }
+    }
     log('install: downloading %d tarball(s)', nodes.length);
     await downloadAndExtractAll(nodes, opts.prefix, npmrc, log, opts.signal, progress);
     await linkBins(nodes, opts.prefix, log);
@@ -143,7 +164,14 @@ async function resolveDeps(specs, npmrc, log, overrides, skipDeps, signal, progr
  * Undefined ⇒ a fresh resolve that always picks the newest in-range version
  * (first install, or an explicit `--refresh-lockfile`).
  */
-preferredVersions) {
+preferredVersions, 
+/**
+ * Names of the monorepo's own workspace packages. An edge whose name is in
+ * this set is satisfied by the workspace symlink, so it is skipped here —
+ * the published version (and its subtree) never enters the resolved tree or
+ * the lockfile.
+ */
+workspaceNames) {
     progress?.beginPhase('resolve', specs.length);
     const applyOverride = (name, range) => {
         if (!overrides)
@@ -209,6 +237,11 @@ preferredVersions) {
         // cache instead of blocking on a fresh round-trip.
         for (let wi = 0; wi < wave.length; wi++) {
             const edge = wave[wi];
+            // A workspace member is satisfied by its workspace symlink, never by
+            // a registry tarball — skip the edge so the published version (and
+            // its subtree) never enters the resolved tree or the lockfile.
+            if (workspaceNames?.has(edge.name))
+                continue;
             // Walk the ancestor chain to see whether a satisfying placement is
             // already visible from the requester's `node_modules` lookup. npm's
             // resolver does this — each level of nesting acts as a fallback.

package/lib/utils/install-backend.d.ts

@@ -70,6 +70,19 @@ export interface InstallOptions {
      * to override.
      */
     progress?: ProgressReporter;
+    /**
+     * Native backend only: the names of the monorepo's own workspace packages.
+     * A package whose name is in this set is materialised as a symlink to its
+     * workspace source by `workspaceInstall`, never fetched from the registry —
+     * even when the lockfile or a transitive edge references a same-named
+     * published version (e.g. a `types-dev/<lib>` workspace that ALSO exists on
+     * npm). The native backend drops such names from `resolveDeps` AND from the
+     * fetch/extract set, so `extractOne` never tries to `rm` + overwrite a
+     * workspace source symlink (its data-loss guard would otherwise abort the
+     * whole install). The `npm` backend ignores this — npm resolves workspaces
+     * itself.
+     */
+    workspaceNames?: Set<string>;
 }
 export interface InstallResult {
     /** Top-level packages that were requested, with the version each

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

@@ -0,0 +1,21 @@
+/**
+ * Minimum Node.js major the native install backend supports — its prebuilt native
+ * modules are ABI-locked to this line (kept in sync with `.nvmrc`).
+ */
+export declare const MIN_NODE_MAJOR = 24;
+/** Parse the major from a `process.versions.node`-style string (`'24.18.0'` → 24). */
+export declare function parseNodeMajor(version: string): number;
+/**
+ * The preflight verdict for the native install backend, factored out so it can be
+ * unit-tested without spawning a foreign Node. Returns an error message when the
+ * runtime is real Node older than {@link MIN_NODE_MAJOR}, else `null` — i.e. on a
+ * supported Node, on GJS (which fakes `process.versions.node` and does not use
+ * these prebuilds), or on a version string that does not parse.
+ */
+export declare function nativeBackendNodeError(version: string, onRealNode: boolean): string | null;
+/**
+ * Guard the native install backend: throw a clear error on an unsupported Node
+ * major instead of letting the ABI-mismatched prebuilds SIGSEGV mid-install.
+ * No-op under GJS and on supported Node.
+ */
+export declare function assertNativeBackendNodeVersion(): void;

package/lib/utils/node-version.js

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: MIT
+// Node-version preflight for the native install backend.
+//
+// The native backend composes native deps whose prebuilt binaries are ABI-locked
+// to the Node line gjsify targets (see `.nvmrc`). On an older Node major they load
+// a mismatched ABI and SIGSEGV mid-install instead of failing cleanly — a
+// confusing crash with no actionable message (observed: Node 22 in a Fedora
+// container segfaults `gjsify install --backend native` during download/extract).
+// This preflight turns that into a clear, actionable error.
+import { isNode } from '@gjsify/rolldown-plugin-gjsify/runtime';
+/**
+ * Minimum Node.js major the native install backend supports — its prebuilt native
+ * modules are ABI-locked to this line (kept in sync with `.nvmrc`).
+ */
+export const MIN_NODE_MAJOR = 24;
+/** Parse the major from a `process.versions.node`-style string (`'24.18.0'` → 24). */
+export function parseNodeMajor(version) {
+    return Number.parseInt(String(version).split('.', 1)[0] ?? '', 10);
+}
+/**
+ * The preflight verdict for the native install backend, factored out so it can be
+ * unit-tested without spawning a foreign Node. Returns an error message when the
+ * runtime is real Node older than {@link MIN_NODE_MAJOR}, else `null` — i.e. on a
+ * supported Node, on GJS (which fakes `process.versions.node` and does not use
+ * these prebuilds), or on a version string that does not parse.
+ */
+export function nativeBackendNodeError(version, onRealNode) {
+    if (!onRealNode)
+        return null;
+    const major = parseNodeMajor(version);
+    if (!Number.isFinite(major) || major >= MIN_NODE_MAJOR)
+        return null;
+    return (`gjsify install (native backend) requires Node ≥ ${MIN_NODE_MAJOR}, but this is Node ${version}. ` +
+        `Its prebuilt native modules are ABI-locked to Node ${MIN_NODE_MAJOR} and crash on older majors. ` +
+        `Use Node ${MIN_NODE_MAJOR} (nvm/asdf locally, actions/setup-node in CI), or run with --backend npm.`);
+}
+/** True when the CLI runs on real Node — NOT GJS, which fakes `process.versions.node`. */
+function onRealNode() {
+    // GJS exposes `imports.system.version`; @gjsify/process fakes
+    // `process.versions.node = '20.0.0'` for compat, so check GJS FIRST — a plain
+    // `process.versions.node` read would be a false Node positive under GJS.
+    const sysVersion = globalThis.imports?.system?.version;
+    if (sysVersion !== undefined)
+        return false;
+    return isNode();
+}
+/**
+ * Guard the native install backend: throw a clear error on an unsupported Node
+ * major instead of letting the ABI-mismatched prebuilds SIGSEGV mid-install.
+ * No-op under GJS and on supported Node.
+ */
+export function assertNativeBackendNodeVersion() {
+    const message = nativeBackendNodeError(process.versions.node, onRealNode());
+    if (message)
+        throw new Error(message);
+}

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

@@ -0,0 +1,20 @@
+/**
+ * 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.
+ */
+export declare function resolveNodeGi(startDir: string): string | null;
+/** Pick the node executable: the current one when on Node, else PATH `node`. */
+export declare function nodeBinary(): string;
+export interface RunNodeBundleOptions {
+    /** Exit this process with code 0 once the child succeeds (terminal callers). */
+    exitOnSuccess?: 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.
+ */
+export declare function runNodeBundle(bundlePath: string, extraArgs?: string[], options?: RunNodeBundleOptions): Promise<void>;

package/lib/utils/run-node.js

@@ -0,0 +1,85 @@
+// 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:
+//
+//   1. `@gjsify/node-gi` must resolve from the project — it is kept EXTERNAL by
+//      the bundler (a native addon), so it has to physically exist in the
+//      consumer's node_modules. We verify this up front and emit a clear hint
+//      instead of letting Node throw `ERR_MODULE_NOT_FOUND` deep in the bundle.
+//   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).
+//
+// 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).
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { isNode } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { computeNativeEnvForBundle } from './run-gjs.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.
+ */
+export function resolveNodeGi(startDir) {
+    let dir = resolve(startDir);
+    while (true) {
+        const candidate = join(dir, 'node_modules', '@gjsify', 'node-gi', 'package.json');
+        if (existsSync(candidate))
+            return join(dir, 'node_modules', '@gjsify', 'node-gi');
+        const parent = resolve(dir, '..');
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/** Pick the node executable: the current one when on Node, else PATH `node`. */
+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.
+ */
+export async function runNodeBundle(bundlePath, extraArgs = [], options = {}) {
+    const cwd = process.cwd();
+    if (!resolveNodeGi(cwd)) {
+        throw new Error('Cannot run the storybook on Node: `@gjsify/node-gi` is not installed.\n' +
+            'Add @gjsify/node-gi as a dependency to run the storybook on Node, e.g.:\n' +
+            '  "devDependencies": { "@gjsify/node-gi": "^0.13.0" }');
+    }
+    const { env: nativeEnv, envPrefix } = computeNativeEnvForBundle(bundlePath, cwd);
+    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.
+    const cmd = [nodeBin, ...nodeArgs.map((a) => (a.includes(' ') ? `"${a}"` : a))].join(' ');
+    console.error(`$ ${envPrefix ? `${envPrefix} ` : ''}${cmd}`);
+    const child = spawn(nodeBin, nodeArgs, { env, stdio: 'inherit' });
+    await new Promise((resolvePromise, reject) => {
+        child.on('close', (code) => {
+            if (code !== 0)
+                reject(new Error(`node 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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/cli",
-    "version": "0.13.1",
+    "version": "0.14.0",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -108,6 +108,7 @@
         "start": "node lib/index.js",
         "build": "tsc && mkdir -p lib/templates/flatpak && cp -L src/templates/install.mjs.tmpl lib/templates/install.mjs.tmpl && cp src/templates/flatpak/*.tmpl lib/templates/flatpak/ && cp src/templates/oxlintrc.json.tmpl lib/templates/oxlintrc.json.tmpl && cp src/templates/oxfmtrc.tmpl lib/templates/oxfmtrc.tmpl && gjsify run chmod",
         "build:gjs-bundle": "node lib/index.js build src/index.ts --app gjs --outfile dist/cli.gjs.mjs --shebang",
+        "build:affected-bundle": "node lib/index.js build src/affected-entry.ts --app gjs --outfile dist/affected.gjs.mjs",
         "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",
@@ -120,19 +121,19 @@
         "cli"
     ],
     "dependencies": {
-        "@gjsify/buffer": "^0.13.1",
-        "@gjsify/create-app": "^0.13.1",
-        "@gjsify/node-globals": "^0.13.1",
-        "@gjsify/node-polyfills": "^0.13.1",
-        "@gjsify/npm-registry": "^0.13.1",
-        "@gjsify/resolve-npm": "^0.13.1",
-        "@gjsify/rolldown-plugin-gjsify": "^0.13.1",
-        "@gjsify/rolldown-plugin-pnp": "^0.13.1",
-        "@gjsify/semver": "^0.13.1",
-        "@gjsify/tar": "^0.13.1",
-        "@gjsify/tsc": "^0.13.1",
-        "@gjsify/web-polyfills": "^0.13.1",
-        "@gjsify/workspace": "^0.13.1",
+        "@gjsify/buffer": "^0.14.0",
+        "@gjsify/create-app": "^0.14.0",
+        "@gjsify/node-globals": "^0.14.0",
+        "@gjsify/node-polyfills": "^0.14.0",
+        "@gjsify/npm-registry": "^0.14.0",
+        "@gjsify/resolve-npm": "^0.14.0",
+        "@gjsify/rolldown-plugin-gjsify": "^0.14.0",
+        "@gjsify/rolldown-plugin-pnp": "^0.14.0",
+        "@gjsify/semver": "^0.14.0",
+        "@gjsify/tar": "^0.14.0",
+        "@gjsify/tsc": "^0.14.0",
+        "@gjsify/web-polyfills": "^0.14.0",
+        "@gjsify/workspace": "^0.14.0",
         "cosmiconfig": "^9.0.2",
         "get-tsconfig": "^4.14.0",
         "pkg-types": "^2.3.1",
@@ -140,13 +141,13 @@
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@gjsify/unit": "^0.13.1",
+        "@gjsify/unit": "^0.14.0",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/oxfmt-native": "^0.13.1",
-        "@gjsify/rolldown-native": "^0.13.1"
+        "@gjsify/oxfmt-native": "^0.14.0",
+        "@gjsify/rolldown-native": "^0.14.0"
     },
     "peerDependenciesMeta": {
         "@gjsify/oxfmt-native": {