@gjsify/cli 0.13.2 → 0.15.1

package/lib/commands/foreach.d.ts

@@ -13,6 +13,7 @@ interface ForeachOptions {
     verbose?: boolean;
     jobs?: number;
     exec?: boolean;
+    cached?: boolean;
 }
 export declare const foreachCommand: Command<unknown, ForeachOptions>;
 export {};

package/lib/commands/foreach.js

@@ -14,6 +14,7 @@ import { cpus } from 'node:os';
 import { buildDependencyGraph, discoverWorkspaces, filterWorkspaces, topologicalSort, } from '@gjsify/workspace';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
 import { prefixLines } from '../utils/prefixed-output.js';
+import { BuildCacheRunner, buildCacheEnabledByEnv } from '../utils/build-cache.js';
 import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
 // Every child spawned by spawnPrefixed registers here so fail-fast can
 // terminate the whole in-flight set instead of waiting on it. On CI a
@@ -238,6 +239,10 @@ export const foreachCommand = {
         description: 'Treat <script> [args..] as an arbitrary command (yarn `workspaces foreach exec`-equivalent) instead of a package.json script lookup. Workspace filtering by script presence is skipped. Use `-- <cmd> <args...>` to pass flags to the command without yargs intercepting them.',
         type: 'boolean',
         default: false,
+    })
+        .option('cached', {
+        description: 'Content-hash build cache (ADR 0006): skip a workspace whose inputs (src/**, package.json, tsconfig*.json, transitive workspace deps, toolchain versions) are unchanged and restore its stored outputs instead; on miss run the script and store the output dirs it modified. Script mode only. Default from GJSIFY_BUILD_CACHE=1.',
+        type: 'boolean',
     })
         .option('shard', {
         description: 'Run only a deterministic slice "<index>/<total>" (1-based) of the matched workspaces, e.g. --shard 2/4. For fanning a long run across parallel CI jobs. Partitions by sorted name (round-robin) so the shards are disjoint and their union is the full set; order-independent, so safe for tests but NOT for ordered builds.',
@@ -352,20 +357,43 @@ export const foreachCommand = {
         // `cmd` is guaranteed string at this point — both branches above
         // exit on undefined, but TS doesn't narrow through them.
         const finalCmd = cmd;
+        // Content-hash build cache (ADR 0006 phase 1). Explicit --cached /
+        // --no-cached wins; GJSIFY_BUILD_CACHE=1 is the env default so a
+        // whole root-script chain (`gjsify run build`) can opt in without
+        // editing every nested invocation. Keys are computed against ALL
+        // discovered workspaces (a dep outside the --include filter still
+        // participates in its dependents' keys).
+        const cached = args.cached ?? buildCacheEnabledByEnv();
+        if (args.cached === true && exec) {
+            // Only the EXPLICIT flag errors — the GJSIFY_BUILD_CACHE env
+            // default covers whole script chains (CI sets it once for the
+            // build job) where an --exec invocation is simply not cacheable.
+            console.error('gjsify foreach: --cached only applies to script mode, not --exec.');
+            process.exit(1);
+        }
+        const cache = cached && !exec
+            ? new BuildCacheRunner({
+                root: cwd,
+                workspaces: allWorkspaces,
+                script: finalCmd,
+                args: cmdArgs,
+                targets: selected.map((w) => w.name),
+            })
+            : undefined;
         try {
             if (args.parallel && !args.topological && !args['topological-dev']) {
                 const jobs = args.jobs && args.jobs > 0 ? args.jobs : cpus().length;
-                await runParallel(selected, finalCmd, cmdArgs, jobs, verbose, exec);
+                await runParallel(selected, finalCmd, cmdArgs, jobs, verbose, exec, cache);
             }
             else if (args.parallel) {
                 // Topological + parallel: each workspace starts as soon as its
                 // deps (in the selected set) have finished. Yarn calls this
                 // "topological order with concurrency"; we cap at --jobs.
                 const jobs = args.jobs && args.jobs > 0 ? args.jobs : cpus().length;
-                await runTopologicalParallel(selected, finalCmd, cmdArgs, jobs, verbose, args['topological-dev'] === true, exec);
+                await runTopologicalParallel(selected, finalCmd, cmdArgs, jobs, verbose, args['topological-dev'] === true, exec, cache);
             }
             else {
-                await runSequential(selected, finalCmd, cmdArgs, verbose, exec);
+                await runSequential(selected, finalCmd, cmdArgs, verbose, exec, cache);
             }
         }
         catch (err) {
@@ -382,25 +410,25 @@ export const foreachCommand = {
         process.exit(0);
     },
 };
-async function runSequential(workspaces, script, args, verbose, exec) {
+async function runSequential(workspaces, script, args, verbose, exec, cache) {
     for (const ws of workspaces) {
-        await runOne(ws, script, args, /* prefixOutput */ false, verbose, exec);
+        await runOne(ws, script, args, /* prefixOutput */ false, verbose, exec, cache);
     }
 }
-async function runParallel(workspaces, script, args, concurrency, verbose, exec) {
+async function runParallel(workspaces, script, args, concurrency, verbose, exec, cache) {
     let cursor = 0;
     const workers = [];
     for (let w = 0; w < concurrency; w++) {
         workers.push((async () => {
             while (cursor < workspaces.length) {
                 const i = cursor++;
-                await runOne(workspaces[i], script, args, /* prefixOutput */ true, verbose, exec);
+                await runOne(workspaces[i], script, args, /* prefixOutput */ true, verbose, exec, cache);
             }
         })());
     }
     await Promise.all(workers);
 }
-async function runTopologicalParallel(workspaces, script, args, concurrency, verbose, includeDev, exec) {
+async function runTopologicalParallel(workspaces, script, args, concurrency, verbose, includeDev, exec, cache) {
     const selectedNames = new Set(workspaces.map((w) => w.name));
     const remaining = new Map();
     for (const ws of workspaces) {
@@ -439,9 +467,7 @@ async function runTopologicalParallel(workspaces, script, args, concurrency, ver
     return new Promise((resolve, reject) => {
         let error = null;
         let lastActivity = Date.now();
-        const describeInflight = () => [...inflightStarts.entries()]
-            .map(([n, t]) => `${n} (${Math.round((Date.now() - t) / 1000)}s)`)
-            .join(', ');
+        const describeInflight = () => [...inflightStarts.entries()].map(([n, t]) => `${n} (${Math.round((Date.now() - t) / 1000)}s)`).join(', ');
         const failFast = (e) => {
             // First error wins. KILL the in-flight siblings instead of
             // waiting for them (yarn waits — but a sibling's nested build
@@ -488,7 +514,7 @@ async function runTopologicalParallel(workspaces, script, args, concurrency, ver
                 if (liveProgress) {
                     console.error(`[gjsify foreach] start ${next} (${done.size}/${total} done, ${inflight} in flight)`);
                 }
-                runOne(byName.get(next), script, args, /* prefixOutput */ true, verbose, exec)
+                runOne(byName.get(next), script, args, /* prefixOutput */ true, verbose, exec, cache)
                     .then(() => {
                     done.add(next);
                 })
@@ -528,7 +554,7 @@ async function runTopologicalParallel(workspaces, script, args, concurrency, ver
         pump();
     });
 }
-async function runOne(ws, script, args, prefixOutput, verbose, exec) {
+async function runOne(ws, script, args, prefixOutput, verbose, exec, cache) {
     if (exec) {
         // Arbitrary-command mode: spawn `<script> <args...>` directly
         // (yarn `workspaces foreach exec`-equivalent). Used by callers
@@ -540,6 +566,13 @@ async function runOne(ws, script, args, prefixOutput, verbose, exec) {
         await spawnPrefixed(script, args, ws.location, prefixOutput ? `[${ws.name}] ` : null);
         return;
     }
+    // Content-hash build cache: on a key hit the stored outputs are
+    // restored and the script is skipped entirely; on a miss the output
+    // dirs are snapshotted so only the dirs the script MODIFIED are stored
+    // after it succeeds (never a committed, no-build lib/).
+    if (cache && cache.tryRestore(ws))
+        return;
+    const before = cache?.snapshotOutputs(ws);
     // Use the same package manager that invoked us — yarn under yarn,
     // npm under npm, gjsify under gjsify. Default to `npm` for portability
     // when nothing is detectable; the script-runner (D.5) will replace
@@ -550,6 +583,8 @@ async function runOne(ws, script, args, prefixOutput, verbose, exec) {
         console.error(`[${ws.name}] $ ${runner} ${argv.join(' ')}`);
     }
     await spawnPrefixed(runner, argv, ws.location, prefixOutput ? `[${ws.name}] ` : null);
+    if (cache && before)
+        cache.storeAfterSuccess(ws, before);
 }
 function detectPackageManager() {
     // Under GJS there is no Node — neither `npm` nor `yarn` can run scripts, so

package/lib/commands/install.js

@@ -15,9 +15,18 @@
 // Workspace install (`gjsify install` in a monorepo root with a
 // `"workspaces"` field) hoists every workspace's externals into the root
 // `node_modules/` and symlinks `workspace:*` / `workspace:^` / `workspace:~`
-// refs to their target source. Open follow-ups (see STATUS.md "Open TODOs"):
-// per-workspace dedup of conflicting transitive version ranges (first-match
-// wins today).
+// refs to their target source. Conflicting version ranges of the same
+// external dep from different workspaces still share ONE hoisted root copy
+// (a real per-workspace dedup pass is Phase D.8, see STATUS.md), but since
+// ADR 0001 step 3 the resolver surfaces every such conflict loudly —
+// `[gjsify] warning: version conflict for <pkg> …` names both ranges, the
+// workspaces that requested them, and the version that actually won.
+//
+// Concurrency (ADR 0001 step 2): every mutation of an install prefix —
+// project node_modules/, gjsify-lock.json, the user-global prefix — runs
+// under a per-prefix cross-process lock (utils/install-lock.ts). Installs
+// into different prefixes stay parallel; the shared XDG tarball/packument
+// caches need no lock because their writes are atomic tmp+rename.
 import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative } from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
@@ -25,6 +34,8 @@ import { discoverWorkspaces } from '@gjsify/workspace';
 import { buildInstallCommand, detectPackageManager, runMinimalChecks } from '../utils/check-system-deps.js';
 import { detectNativePackages } from '../utils/detect-native-packages.js';
 import { installPackages, makeProgressReporter } from '../utils/install-backend.js';
+import { atomicWriteStrict } from '../utils/install-cache-fs.js';
+import { acquireInstallLock } from '../utils/install-lock.js';
 import { binDirOnPath, defaultGlobalLayout, installGjsEnginePackages, linkGlobalBins, specToPackageName, } from '../utils/install-global.js';
 import { addDependencyEntry, defaultRangeFromVersion, parseSpec, projectSpecsFromPackageJson, readPackageJson, writePackageJson, } from '../utils/pkg-json-edit.js';
 // Default 30min wall-clock budget for the full install. Big workspaces
@@ -268,40 +279,50 @@ async function projectInstallNative(args, signal) {
     const progress = makeProgressReporter({
         enabled: !args.verbose && !args.quiet && args.progress !== false,
     });
-    const result = await installPackages({
-        prefix: cwd,
-        specs,
-        verbose: args.verbose,
-        // --immutable consumes the lockfile verbatim and must NOT rewrite
-        // it (the whole point is byte-stability under CI).
-        lockfile: !args.immutable,
-        frozen: args.immutable,
-        refreshLockfile: args['refresh-lockfile'],
-        signal,
-        progress,
-    });
-    // Update package.json only when the user passed explicit packages
-    // (the `gjsify install <pkg>...` add-a-dep flow). The no-args refresh
-    // flow doesn't mutate manifest entries.
-    if (args.packages && args.packages.length > 0 && pkg) {
-        const kind = depKindFromArgs(args);
-        for (const spec of args.packages) {
-            const { name, range } = parseSpec(spec);
-            const installed = result.installed.find((r) => r.name === name);
-            const finalRange = range ?? (installed ? defaultRangeFromVersion(installed.version) : 'latest');
-            addDependencyEntry(pkg, name, finalRange, kind);
-        }
-        writePackageJson(pkgPath, pkg);
-        // Re-sync the lockfile's `requested` field with what
-        // `projectSpecsFromPackageJson()` will return on the next
-        // invocation. Without this, a `gjsify install foo` (bare name,
-        // lockfile records `"foo"`) followed by `gjsify install
-        // --immutable` (reads package.json → spec `"foo@^1.2.3"`) would
-        // surface a spurious drift error.
-        if (!args.immutable) {
-            syncLockfileRequested(cwd, projectSpecsFromPackageJson(pkg));
+    // Hold the per-prefix lock across the install AND the manifest/lockfile
+    // sync that follows, so a concurrent `gjsify install <pkg>` in the same
+    // project can't interleave its package.json / gjsify-lock.json writes
+    // with ours. `installPackages` re-acquires the same lock re-entrantly.
+    const lock = await acquireInstallLock(cwd, { signal });
+    try {
+        const result = await installPackages({
+            prefix: cwd,
+            specs,
+            verbose: args.verbose,
+            // --immutable consumes the lockfile verbatim and must NOT rewrite
+            // it (the whole point is byte-stability under CI).
+            lockfile: !args.immutable,
+            frozen: args.immutable,
+            refreshLockfile: args['refresh-lockfile'],
+            signal,
+            progress,
+        });
+        // Update package.json only when the user passed explicit packages
+        // (the `gjsify install <pkg>...` add-a-dep flow). The no-args refresh
+        // flow doesn't mutate manifest entries.
+        if (args.packages && args.packages.length > 0 && pkg) {
+            const kind = depKindFromArgs(args);
+            for (const spec of args.packages) {
+                const { name, range } = parseSpec(spec);
+                const installed = result.installed.find((r) => r.name === name);
+                const finalRange = range ?? (installed ? defaultRangeFromVersion(installed.version) : 'latest');
+                addDependencyEntry(pkg, name, finalRange, kind);
+            }
+            writePackageJson(pkgPath, pkg);
+            // Re-sync the lockfile's `requested` field with what
+            // `projectSpecsFromPackageJson()` will return on the next
+            // invocation. Without this, a `gjsify install foo` (bare name,
+            // lockfile records `"foo"`) followed by `gjsify install
+            // --immutable` (reads package.json → spec `"foo@^1.2.3"`) would
+            // surface a spurious drift error.
+            if (!args.immutable) {
+                syncLockfileRequested(cwd, projectSpecsFromPackageJson(pkg));
+            }
         }
     }
+    finally {
+        lock.release();
+    }
 }
 function syncLockfileRequested(cwd, specs) {
     const lockPath = join(cwd, 'gjsify-lock.json');
@@ -315,7 +336,9 @@ function syncLockfileRequested(cwd, specs) {
             return; // Already in sync; preserve byte-stability.
         }
         lock.requested = specs;
-        writeFileSync(lockPath, JSON.stringify(lock, null, 2) + '\n');
+        // Atomic tmp+rename — same rationale as the backend's lockfile
+        // writer: a torn gjsify-lock.json breaks the next `--immutable`.
+        atomicWriteStrict(lockPath, JSON.stringify(lock, null, 2) + '\n');
     }
     catch {
         // Best-effort sync; if the lockfile is malformed, the next
@@ -328,23 +351,45 @@ function syncLockfileRequested(cwd, specs) {
  *   2. Aggregate the union of their external (non-`workspace:`) deps.
  *   3. Run the native install backend ONCE at the root prefix so all
  *      externals land in a single `node_modules/` (poor-man's hoisting —
- *      we don't deduplicate version-range conflicts yet, the BFS resolver
- *      picks first-match).
+ *      workspaces with conflicting ranges of the same dep share one hoisted
+ *      copy; the resolver emits a loud `[gjsify] warning: version conflict`
+ *      naming both sides and the version that won).
  *   4. For every `workspace:` reference, symlink the target workspace's
  *      directory into the requesting workspace's `node_modules/<dep>`
  *      so `import '@gjsify/utils'` resolves to the local source.
  *
  * Hoisting strategy is intentionally minimal — per-workspace dedup +
- * nested `node_modules/` for version conflicts are tracked as a follow-up
- * in STATUS.md "Open TODOs".
+ * nested `node_modules/` for cross-workspace version conflicts are the
+ * Phase D.8 follow-up tracked in STATUS.md.
  */
 async function workspaceInstall(cwd, args, signal) {
+    // Hold the root-prefix lock for the WHOLE workspace flow: bin shims,
+    // workspace symlinks and the external install all mutate the root
+    // node_modules/, and a second concurrent workspace install interleaving
+    // its rm+symlink/extract steps with ours corrupts both. The inner
+    // `installPackages` calls re-acquire the same lock re-entrantly (root
+    // prefix) or take the child-workspace lock (scoped overrides) — always
+    // in root→child order, so there is no lock-ordering cycle.
+    const lock = await acquireInstallLock(cwd, { signal });
+    try {
+        await workspaceInstallLocked(cwd, args, signal);
+    }
+    finally {
+        lock.release();
+    }
+}
+/** Body of {@link workspaceInstall}, run while holding the root-prefix lock. */
+async function workspaceInstallLocked(cwd, args, signal) {
     const workspaces = discoverWorkspaces(cwd, { includeRoot: true });
     if (workspaces.length === 0) {
         throw new Error(`gjsify install: ${cwd} has a "workspaces" field but no workspaces were discovered`);
     }
     const byName = new Map(workspaces.map((w) => [w.name, w]));
     const externalSpecs = new Set();
+    // Which workspace(s) declared each external spec — `"<name>@<range>"` →
+    // workspace names. Feeds the resolver's version-conflict warning so it
+    // can attribute both sides of a cross-workspace range conflict.
+    const specOrigins = new Map();
     const symlinks = [];
     for (const ws of workspaces) {
         const m = ws.manifest;
@@ -391,7 +436,14 @@ async function workspaceInstall(cwd, args, signal) {
                 }
                 if (/^(link|file|portal|git\+|https?):/.test(spec))
                     continue;
-                externalSpecs.add(`${depName}@${spec}`);
+                const specKey = `${depName}@${spec}`;
+                externalSpecs.add(specKey);
+                let origins = specOrigins.get(specKey);
+                if (!origins) {
+                    origins = new Set();
+                    specOrigins.set(specKey, origins);
+                }
+                origins.add(ws.name);
             }
         }
     }
@@ -624,6 +676,7 @@ async function workspaceInstall(cwd, args, signal) {
             // 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()),
+            specOrigins: new Map([...specOrigins].map(([k, v]) => [k, [...v]])),
         });
     }
     else if (args.verbose) {
@@ -926,28 +979,42 @@ async function installGlobalAndLink(specs, opts) {
     mkdirSync(layout.prefix, { recursive: true });
     console.log(`gjsify install --global  → ${layout.prefix}`);
     console.log(`                  bins → ${layout.binDir}`);
-    const result = await installPackages({
-        prefix: layout.prefix,
-        specs,
-        verbose: opts.verbose,
-    });
-    const packageNames = specs.map(specToPackageName);
-    // A global GJS install of `@gjsify/cli` must also lay down the GJS-native
-    // bundler engine (`@gjsify/rolldown-native`) + the sibling format/CSS
-    // bridges. They are declared OPTIONAL peers of `@gjsify/cli` (so plain
-    // `npm install @gjsify/cli` on Node doesn't force a linux prebuild), and
-    // the native backend doesn't resolve peerDependencies at all — so without
-    // this they'd never be installed, and `gjsify build` would hard-fail under
-    // GJS ("no usable bundler engine"). Installed best-effort at the cli's
-    // resolved version so they move in lockstep with the bundle; a platform
-    // with no published prebuild degrades to a warning. Must run BEFORE
-    // linkGlobalBins so the launcher's detectNativePackages() bakes the
-    // engine's prebuild dirs into the wrapper's GI_TYPELIB_PATH/LD_LIBRARY_PATH.
-    if (packageNames.includes('@gjsify/cli')) {
-        const cliVersion = result.installed.find((r) => r.name === '@gjsify/cli')?.version ?? 'latest';
-        await installGjsEnginePackages(layout.prefix, cliVersion, { verbose: opts.verbose });
+    // The global prefix is SHARED user-wide state — two concurrent
+    // `gjsify install -g` runs (e.g. parallel agent sessions bootstrapping
+    // tooling) used to interleave rm+extract on the same package dirs and
+    // race the launcher writes in ~/.local/bin. Hold the prefix lock across
+    // the install, the engine-package top-up AND the bin linking (ADR 0001).
+    const lock = await acquireInstallLock(layout.prefix, {});
+    try {
+        const result = await installPackages({
+            prefix: layout.prefix,
+            specs,
+            verbose: opts.verbose,
+        });
+        const packageNames = specs.map(specToPackageName);
+        // A global GJS install of `@gjsify/cli` must also lay down the GJS-native
+        // bundler engine (`@gjsify/rolldown-native`) + the sibling format/CSS
+        // bridges. They are declared OPTIONAL peers of `@gjsify/cli` (so plain
+        // `npm install @gjsify/cli` on Node doesn't force a linux prebuild), and
+        // the native backend doesn't resolve peerDependencies at all — so without
+        // this they'd never be installed, and `gjsify build` would hard-fail under
+        // GJS ("no usable bundler engine"). Installed best-effort at the cli's
+        // resolved version so they move in lockstep with the bundle; a platform
+        // with no published prebuild degrades to a warning. Must run BEFORE
+        // linkGlobalBins so the launcher's detectNativePackages() bakes the
+        // engine's prebuild dirs into the wrapper's GI_TYPELIB_PATH/LD_LIBRARY_PATH.
+        if (packageNames.includes('@gjsify/cli')) {
+            const cliVersion = result.installed.find((r) => r.name === '@gjsify/cli')?.version ?? 'latest';
+            await installGjsEnginePackages(layout.prefix, cliVersion, { verbose: opts.verbose });
+        }
+        const created = linkGlobalBins(packageNames, layout);
+        reportLinkedBins(created, layout.binDir);
+    }
+    finally {
+        lock.release();
     }
-    const created = linkGlobalBins(packageNames, layout);
+}
+function reportLinkedBins(created, binDir) {
     if (created.length === 0) {
         console.warn('\nNo bins declared (neither `gjsify.bin` nor `bin` in package.json) — nothing was symlinked.');
     }
@@ -957,9 +1024,9 @@ async function installGlobalAndLink(specs, opts) {
             console.log(`  • ${e.link}  →  ${e.target}`);
         }
     }
-    if (created.length > 0 && !binDirOnPath(layout.binDir)) {
-        console.warn(`\nNote: ${layout.binDir} is not on your PATH.\n` +
-            `Add it to your shell rc file:\n  export PATH="${layout.binDir}:$PATH"`);
+    if (created.length > 0 && !binDirOnPath(binDir)) {
+        console.warn(`\nNote: ${binDir} is not on your PATH.\n` +
+            `Add it to your shell rc file:\n  export PATH="${binDir}:$PATH"`);
     }
 }
 async function runPostInstallChecks() {

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/commands/workspace.d.ts

@@ -7,6 +7,7 @@ interface WorkspaceCmdOptions {
     'continue-on-error'?: boolean;
     'include-dev'?: boolean;
     verbose?: boolean;
+    cached?: boolean;
 }
 export declare const workspaceCommand: Command<unknown, WorkspaceCmdOptions>;
 export {};