@gjsify/cli 0.34.0 → 0.36.0

package/lib/actions/build.d.ts

@@ -140,6 +140,25 @@ export declare class BuildAction {
         noCacheEnv?: string;
         /** Extra compile-time `define`s (e.g. rewrite the entry's `import.meta.url`). */
         define?: Record<string, string>;
+        /**
+         * Whether a fresh cached bundle may be reused (default true). Set
+         * false when the caller's input has a module graph the freshness
+         * check cannot see — the entry's own mtime plus the lockfile covers
+         * installed deps, not workspace sources. See `utils/node-script.ts`,
+         * which runs repo BUILD scripts and so cannot afford a stale one.
+         */
+        cache?: boolean;
+        /**
+         * Re-export the entry's `default` through the side-effect wrapper so
+         * the bundle IMPORTS as a library (default true — the plugin and
+         * config loaders both `import()` the result and read `.default`).
+         *
+         * A script is EXECUTED, not imported, and has no default export, so
+         * wrapping one only produces `IMPORT_IS_UNDEFINED: Import 'default'
+         * will always be undefined` on every build — a warning that says the
+         * wrapper does not apply here.
+         */
+        preserveDefaultExport?: boolean;
     }): Promise<string>;
     /** Application mode */
     buildApp(app?: App, opts?: {

package/lib/actions/build.js

@@ -468,7 +468,7 @@ export class BuildAction {
         const cacheDir = join(cwd, 'node_modules', '.cache', 'gjsify', opts.cacheSubdir);
         const safeName = opts.label.replace(/[^a-zA-Z0-9._-]/g, '_');
         const outfile = join(cacheDir, `${safeName}-${shortHash(inputPath)}.mjs`);
-        const cacheDisabled = opts.noCacheEnv ? isTruthyEnv(process.env[opts.noCacheEnv]) : false;
+        const cacheDisabled = opts.cache === false || (opts.noCacheEnv ? isTruthyEnv(process.env[opts.noCacheEnv]) : false);
         if (!cacheDisabled && (await isBundleFresh(outfile, inputPath, cwd))) {
             if (opts.verbose)
                 console.debug(`[gjsify] reusing cached GJS bundle ${outfile}`);
@@ -484,7 +484,7 @@ export class BuildAction {
                 output: { file: outfile },
                 ...(opts.define ? { transform: { define: opts.define } } : {}),
             },
-        }).buildApp('gjs', { preserveDefaultExport: true });
+        }).buildApp('gjs', { preserveDefaultExport: opts.preserveDefaultExport ?? true });
         return outfile;
     }
     /** Application mode */

package/lib/bundler-pick.js

@@ -111,16 +111,16 @@ function diagnoseNativeEngine() {
             'package, whose `lib/` no `gjsify install` produces. An installed package from npm is NOT affected — ' +
             'the published tarball does contain `lib/esm/index.js` (verified against 0.26.1), so a consumer that ' +
             'hit this message should report it.\n' +
-            'Building it needs a bundler, which is why it cannot bootstrap itself under GJS; the Node CLI entry ' +
-            'does it instead. From the gjsify repo root — NOTE both of these REQUIRE Node:\n' +
-            '  gjsify run build:infra                          # the full cold-tree chain (recommended)\n' +
-            '  node scripts/bootstrap-native-facades.mjs       # just the facades, if the rest is already built\n' +
-            'Both are idempotent and skip already-built facades in seconds.\n' +
-            'ON A NODE-LESS GJS HOST there is currently no in-repo way out, and saying so is the point — this ' +
-            'message used to recommend those two commands unconditionally, and on such a host BOTH fail (the ' +
-            "second directly, the first at `@gjsify/create-app`'s `node scripts/process-template.mjs`). Until " +
-            'that is closed, seed `lib/` from the published package — which ships it — or from a host that has ' +
-            'Node. Tracked in `status/open-todos.md` ("A Node-less host cannot bootstrap a fresh CLONE").');
+            'Build it from the gjsify repo root — both are idempotent and skip already-built facades in ' +
+            'seconds, and NEITHER requires Node any more:\n' +
+            '  gjsify run build:infra                                           # the full cold-tree chain\n' +
+            '  gjsify run --node-script scripts/bootstrap-native-facades.mjs    # just the facades\n' +
+            "Under Node the facades are built by the CLI's own Node entry (npm `rolldown`); under GJS by the " +
+            '`gjsify` on PATH, which carries its own engine when it was installed with `gjs -m install.mjs`.\n' +
+            'If you are READING THIS ON A GJS HOST, that global engine is what could not be reached: this ' +
+            'workspace symlink shadowed it, because `require.resolve` returned the package DIRECTORY instead ' +
+            'of failing. That is fixed in `@gjsify/module`, so a `gjsify` OLDER than the fix still stops here — ' +
+            'update it (`gjs -m install.mjs`), or seed `lib/` from the published package, which ships it.');
     }
     // Branch 3: installed AND built, so the typelib/prebuild LOOKUP failed.
     //

package/lib/commands/run.d.ts

@@ -4,6 +4,7 @@ interface RunOptions {
     args: string[];
     workspace?: string;
     runtime?: string;
+    nodeScript?: boolean;
 }
 export declare const runCommand: Command<unknown, RunOptions>;
 export {};

package/lib/commands/run.js

@@ -19,6 +19,8 @@ import { spawn } from 'node:child_process';
 import { runGjsBundle } from '../utils/run-gjs.js';
 import { runRuntimeBundle } from '../utils/run-node.js';
 import { readPackageJson } from '../utils/pkg-json-edit.js';
+import { runNodeScript } from '../utils/node-script.js';
+import { nodeShimDir } from '../utils/gjsify-shim.js';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
 import { discoverWorkspaces } from '@gjsify/workspace';
 import { isGjs, hostRuntime } from '@gjsify/rolldown-plugin-gjsify/runtime';
@@ -47,6 +49,16 @@ export const runCommand = {
         alias: 'w',
         type: 'string',
         description: 'Run <target> as a script in the named workspace (by name or path), like `npm run <script> -w <name>`.',
+    })
+        .option('node-script', {
+        // Run an UNBUNDLED `.mjs` that imports `node:*` builtins on the
+        // host runtime — bundling it for GJS first when that is the host.
+        // Declared here so yargs captures it instead of forwarding it to
+        // the target (this command routes unknown flags to the child).
+        // Forces file mode, like --runtime.
+        type: 'boolean',
+        default: false,
+        description: 'Treat <target> as an unbundled Node-style script (imports `node:` builtins) and run it on the host runtime. Under GJS the file is bundled `--app gjs` on the fly first, which is what makes a repo script runnable on a host that has no Node.',
     })
         .option('runtime', {
         // Runtime selector for a BUNDLE FILE. `gjs` (default) launches
@@ -99,6 +111,22 @@ export const runCommand = {
         const positionalArgs = args.args ?? [];
         const doubleDashArgs = (args['--'] ?? []).filter((v) => typeof v === 'string');
         const extraArgs = [...positionalArgs, ...doubleDashArgs];
+        // `--node-script` (explicit) → run an UNBUNDLED Node-style script on the
+        // host runtime; under GJS it is bundled `--app gjs` on the fly first.
+        // Checked before `--runtime` and `--workspace`: it is a file mode, and
+        // combining it with either is a caller error rather than a precedence
+        // question (`--runtime` picks a launcher for a PREBUILT bundle,
+        // `--workspace` names a package.json script).
+        if (args.nodeScript === true) {
+            const isSet = (v) => typeof v === 'string' && v.length > 0;
+            const clash = isSet(args.runtime) ? '--runtime' : isSet(args.workspace) ? '--workspace' : null;
+            if (clash) {
+                console.error(`gjsify run: --node-script cannot be combined with ${clash}.`);
+                return process.exit(1);
+            }
+            await runNodeScript(target, extraArgs, { exitOnSuccess: true });
+            return;
+        }
         // `--runtime <gjs|node|bun|deno>` (explicit) → run a BUNDLE FILE on the
         // chosen runtime. This FORCES file mode: the runtime selector only makes
         // sense for a prebuilt bundle, and it must beat the script-name lookup.
@@ -308,6 +336,15 @@ async function runScript(script, extraArgs, cwd = process.cwd()) {
     if (process.env.GJSIFY_SHIM_DIR) {
         binDirs.unshift(process.env.GJSIFY_SHIM_DIR);
     }
+    // The `node` shim (see `nodeShimDir`) reaches PACKAGE SCRIPTS and nothing
+    // else. A script saying `node scripts/x.mjs` means "run this script", which
+    // gjsify can serve on a host with no Node; the CLI's own internals asking for
+    // `node` mean "I need a real Node", and answering those turned
+    // `gjsify tsc`'s honest "not on PATH" diagnosis into a bundling error two
+    // layers down (tests/e2e/tsc-node-fallback caught exactly that).
+    const nodeShim = nodeShimDir();
+    if (nodeShim)
+        binDirs.unshift(nodeShim);
     // Default FORCE_COLOR=1 when not already set, matching yarn / npm
     // script-runner behaviour. Without this, tools that check
     // `process.stdout.isTTY` (chalk, picocolors, biome, …) disable colors

package/lib/utils/check-system-deps.d.ts

@@ -130,6 +130,22 @@ export declare function runAllChecks(cwd: string): DepCheck[];
  * Used by `gjsify showcase` for examples that have no native deps.
  */
 export declare function runMinimalChecks(): DepCheck[];
+/**
+ * Is a blueprint-compiler reachable, by the SAME rule the build uses?
+ *
+ * Delegates to `@gjsify/vite-plugin-blueprint/resolve` rather than probing PATH
+ * here, because the two answers must not be able to disagree: on win32 the
+ * compiler is normally an MSYS2 script that is deliberately NOT on PATH, so a
+ * PATH-only check would report "missing" on a host where every `.blp` builds
+ * fine — a check failing for the wrong reason, which is the failure mode this
+ * file's own history is made of.
+ *
+ * `--version` is not run. MSYS2 ships blueprint-compiler as a shebang script
+ * with no `.exe`, so `checkBinary` cannot execute it on Windows; presence of the
+ * resolved pair is the honest answer, and the `source` is worth reporting
+ * because "found via msys2" explains an install PATH does not show.
+ */
+export declare function checkBlueprintCompiler(requiredBy?: string[]): DepCheck;
 /** Check gwebgl npm package (project first, CLI fallback). Optional — only needed by @gjsify/webgl users. */
 export declare function checkGwebgl(cwd: string): DepCheck;
 /**

package/lib/utils/check-system-deps.js

@@ -15,6 +15,9 @@ import { dirname, join, resolve } from 'node:path';
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
 import { readFileSync, existsSync, readdirSync } from 'node:fs';
+// The zero-dependency subpath, deliberately: importing the plugin root would
+// pull vite/execa/minify-xml into a system CHECK.
+import { resolveBlueprintCompiler } from '@gjsify/vite-plugin-blueprint/resolve';
 /** Run a binary and return its stdout trimmed, or null if it fails. */
 function tryExecFile(binary, args) {
     try {
@@ -392,6 +395,32 @@ export function runMinimalChecks() {
         results.push(checkMsvcRuntime());
     return results;
 }
+/**
+ * Is a blueprint-compiler reachable, by the SAME rule the build uses?
+ *
+ * Delegates to `@gjsify/vite-plugin-blueprint/resolve` rather than probing PATH
+ * here, because the two answers must not be able to disagree: on win32 the
+ * compiler is normally an MSYS2 script that is deliberately NOT on PATH, so a
+ * PATH-only check would report "missing" on a host where every `.blp` builds
+ * fine — a check failing for the wrong reason, which is the failure mode this
+ * file's own history is made of.
+ *
+ * `--version` is not run. MSYS2 ships blueprint-compiler as a shebang script
+ * with no `.exe`, so `checkBinary` cannot execute it on Windows; presence of the
+ * resolved pair is the honest answer, and the `source` is worth reporting
+ * because "found via msys2" explains an install PATH does not show.
+ */
+export function checkBlueprintCompiler(requiredBy) {
+    const resolved = resolveBlueprintCompiler();
+    return {
+        id: 'blueprint-compiler',
+        name: 'blueprint-compiler (.blp templates)',
+        found: resolved !== null,
+        version: resolved ? `found via ${resolved.source}` : undefined,
+        severity: 'optional',
+        requiredBy,
+    };
+}
 /** Check gwebgl npm package (project first, CLI fallback). Optional — only needed by @gjsify/webgl users. */
 export function checkGwebgl(cwd) {
     return checkNpmPackage('gwebgl', 'gwebgl (@gjsify/webgl)', '@gjsify/webgl', cwd, 'optional', ['@gjsify/webgl']);
@@ -454,7 +483,13 @@ function runNativeBuildToolchainChecks() {
     // Narrower on purpose: only the three bridges that link an upstream Rust
     // crate by Cargo path-dependency need a Rust toolchain.
     const rustBridges = ['@gjsify/lightningcss-native', '@gjsify/oxfmt-native', '@gjsify/rolldown-native'];
+    // Every showcase/app whose window comes from a `.blp` template. NOT a Vala
+    // bridge and nothing to do with meson — it is a BUILD-time toolchain in the
+    // same sense, and it belongs here so `gjsify system-check` names it before a
+    // build does.
+    const blueprintConsumers = ['@gjsify/vite-plugin-blueprint'];
     return [
+        checkBlueprintCompiler(blueprintConsumers),
         checkBinary('ninja', 'Ninja', 'ninja', ['--version'], 'optional', undefined, valaBridges),
         checkBinary('vala', 'Vala', 'valac', ['--version'], 'optional', (out) => out.replace(/^Vala\s+/i, ''), valaBridges),
         checkBinary('cargo', 'Cargo (Rust)', 'cargo', ['--version'], 'optional', (out) => out.replace(/^cargo\s+/i, '').split(' ')[0] ?? out, rustBridges),
@@ -697,11 +732,24 @@ export function buildInstallCommand(pm, missing) {
     const pkgMap = PM_PACKAGES[pm];
     const pkgs = [];
     const npmDeps = [];
+    const standalone = [];
     for (const dep of missing) {
         if (dep.id === 'gwebgl') {
             npmDeps.push('@gjsify/webgl');
             continue;
         }
+        // blueprint-compiler on Windows is the one dep whose install command is
+        // not this host's package manager. winget has no package for it, and it
+        // cannot get one that works: the tool needs PyGObject, which publishes
+        // no Windows wheel, so MSYS2 — which ships Python, PyGObject and the
+        // typelibs already fitted together — is the only source. Its command is
+        // not `winget install`-shaped, so it cannot live in PM_PACKAGES without
+        // producing a line that looks right and fails.
+        if (dep.id === 'blueprint-compiler' && process.platform === 'win32') {
+            standalone.push('pacman -S mingw-w64-ucrt-x86_64-blueprint-compiler mingw-w64-ucrt-x86_64-gtk4 ' +
+                'mingw-w64-ucrt-x86_64-libadwaita   # inside MSYS2; found automatically afterwards');
+            continue;
+        }
         if (dep.id === 'nodejs')
             continue; // can't be missing if we're running
         const pkg = pkgMap[dep.id];
@@ -715,6 +763,7 @@ export function buildInstallCommand(pm, missing) {
     if (npmDeps.length > 0) {
         lines.push(`npm install ${npmDeps.join(' ')}`);
     }
+    lines.push(...standalone);
     return lines.length > 0 ? lines.join('\n  ') : null;
 }
 /**

package/lib/utils/gjsify-shim.d.ts

@@ -31,3 +31,24 @@ export declare function needsSelfShim(opts: {
  * reuse it instead of creating their own.
  */
 export declare function ensureGjsifyShimOnPath(): void;
+/**
+ * Directory carrying a `node` that runs the file through
+ * `gjsify run --node-script`, or null when this host needs none.
+ *
+ * **It is NOT on `process.env.PATH`, and that is the whole point.** Only
+ * `runScript` puts it on the PATH of a PACKAGE SCRIPT's child (`commands/run.ts`).
+ *
+ * The first version did prepend it globally, and CI named the cost immediately:
+ * `gjsify tsc`'s Node fallback spawns a real `node` to run typescript's CJS
+ * entry, and `tests/e2e/tsc-node-fallback` asserts that on a PATH without one it
+ * FAILS LOUDLY naming the missing interpreter — the assertion exists because a
+ * silent exit 0 there once let `set-bin-mode.mjs` run against a `lib/index.js`
+ * tsc never wrote. A global shim answered that spawn, so the CLI stopped being
+ * able to see that Node was missing at all.
+ *
+ * The line the subdirectory draws: a PACKAGE SCRIPT saying `node x.mjs` means
+ * "run this script", and gjsify can serve that. The CLI's own internals asking
+ * for `node` mean "I need a real Node", and lying to them turns an honest
+ * diagnosis into a confusing one two layers down.
+ */
+export declare function nodeShimDir(): string | null;

package/lib/utils/gjsify-shim.js

@@ -59,12 +59,13 @@
 // shim IS the CLI the tree wants, and today's dispatch (GJS bundle first on a
 // host with `gjs`) stays byte-for-byte unchanged. Widening this to every Node
 // invocation would silently move in-repo nested builds off the GJS bundle.
-import { mkdtempSync, writeFileSync, chmodSync, existsSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, chmodSync, existsSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, delimiter, relative, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { buildLauncherShims } from './bin-shim.js';
+import { resolveBinOnPath } from './install-global.js';
 import { findWorkspaceRoot } from './workspace-root.js';
 let _ensured = false;
 let _selfShimActive = false;
@@ -158,4 +159,91 @@ export function ensureGjsifyShimOnPath() {
     _selfShimActive = true;
     process.env.GJSIFY_SHIM_DIR = dir;
     process.env.PATH = dir + delimiter + (process.env.PATH ?? '');
+    writeNodeShim(dir, gjs, selfEntry);
+}
+/**
+ * Subdirectory holding the `node` shim. Deliberately NOT the shim dir itself —
+ * see {@link nodeShimDir}.
+ */
+const NODE_SHIM_SUBDIR = 'node-shim';
+/**
+ * Directory carrying a `node` that runs the file through
+ * `gjsify run --node-script`, or null when this host needs none.
+ *
+ * **It is NOT on `process.env.PATH`, and that is the whole point.** Only
+ * `runScript` puts it on the PATH of a PACKAGE SCRIPT's child (`commands/run.ts`).
+ *
+ * The first version did prepend it globally, and CI named the cost immediately:
+ * `gjsify tsc`'s Node fallback spawns a real `node` to run typescript's CJS
+ * entry, and `tests/e2e/tsc-node-fallback` asserts that on a PATH without one it
+ * FAILS LOUDLY naming the missing interpreter — the assertion exists because a
+ * silent exit 0 there once let `set-bin-mode.mjs` run against a `lib/index.js`
+ * tsc never wrote. A global shim answered that spawn, so the CLI stopped being
+ * able to see that Node was missing at all.
+ *
+ * The line the subdirectory draws: a PACKAGE SCRIPT saying `node x.mjs` means
+ * "run this script", and gjsify can serve that. The CLI's own internals asking
+ * for `node` mean "I need a real Node", and lying to them turns an honest
+ * diagnosis into a confusing one two layers down.
+ */
+export function nodeShimDir() {
+    const dir = process.env.GJSIFY_SHIM_DIR;
+    if (!dir)
+        return null;
+    const sub = join(dir, NODE_SHIM_SUBDIR);
+    return existsSync(join(sub, 'node')) ? sub : null;
+}
+/**
+ * Write a `node` that runs the file through `gjsify run --node-script`, when the
+ * host is GJS and there is NO REAL `node`.
+ *
+ * WHY A SHIM AND NOT A MANIFEST REWRITE
+ *
+ * Every `node scripts/*.mjs` left in this repo's build chain imports nothing but
+ * `node:fs` / `node:path` / `node:url`, all of which gjsify polyfills, so the
+ * only thing stopping them on a Node-less host is that GJS's ESM loader cannot
+ * resolve `node:` for a file on disk. `--node-script` solves that — but spelling
+ * it in `package.json` does NOT work, for a structural reason rather than an
+ * aesthetic one: CI bootstraps a cold tree with
+ * `gjs -m "$GJSIFY_BOOTSTRAP" run build:infra`, and `$GJSIFY_BOOTSTRAP` is the
+ * PREVIOUS RELEASE's CLI (`.github/workflows/release-cut.yml` documents the same
+ * trap for its own step). A manifest using a flag the last release does not know
+ * reds every cold-cache CI run until a release ships — and the release runs that
+ * same chain to build itself.
+ *
+ * A shim has neither problem. The manifests keep saying `node scripts/x.mjs`, so
+ * an older CLI behaves exactly as it does today, and a Node-less host gets a
+ * `node` that works. It also covers what a per-script rewrite cannot: COMPOUND
+ * scripts (`gjsify tsc && node scripts/build-assets.mjs`) are executed through
+ * `/bin/sh`, which resolves `node` from PATH — as does anything those scripts
+ * spawn in turn.
+ *
+ * Two things keep it from shadowing anything: it is written only when `node`
+ * resolves NOWHERE, and it is reachable only from a package script's PATH (see
+ * {@link nodeShimDir}).
+ */
+function writeNodeShim(dir, gjs, selfEntry) {
+    if (!gjs)
+        return;
+    const sub = join(dir, NODE_SHIM_SUBDIR);
+    if (existsSync(join(sub, 'node')))
+        return; // inherited from a parent gjsify
+    if (resolveBinOnPath('node'))
+        return; // a real Node is present — leave it alone
+    const interpreter = process.env.GJS_CONSOLE || 'gjs';
+    // A leading FLAG is refused rather than forwarded. `node --test x.mjs` wants
+    // Node's own test runner and `node -e '…'` an eval; neither is something
+    // `--node-script` can honour, and yargs would silently take `--test` FOR the
+    // script path (`unknown-options-as-args` turns an unknown flag into a
+    // positional). A refusal naming the limit beats a mis-parse naming a file.
+    mkdirSync(sub, { recursive: true });
+    const shim = join(sub, 'node');
+    writeFileSync(shim, '#!/bin/sh\n' +
+        'case "$1" in\n' +
+        '  -*) echo "gjsify: this host has no node; the gjsify shim runs a SCRIPT FILE only" >&2\n' +
+        '      echo "gjsify: got: node $*" >&2\n' +
+        '      exit 127 ;;\n' +
+        'esac\n' +
+        `exec "${interpreter}" -m "${selfEntry}" run --node-script "$@"\n`, { mode: 0o755 });
+    chmodSync(shim, 0o755);
 }

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

@@ -0,0 +1,12 @@
+export interface RunNodeScriptOptions {
+    /** Exit the process when the script succeeds. See `RunGjsBundleOptions.exitOnSuccess`. */
+    exitOnSuccess?: boolean;
+}
+/**
+ * Run `file` — an unbundled ESM script that imports `node:` builtins — on the
+ * CLI's own host runtime, bundling it for GJS first when that is where we are.
+ *
+ * Terminal callers pass `exitOnSuccess` (a GJS main loop armed by the spawn
+ * parks the process otherwise); see {@link runGjsBundle}.
+ */
+export declare function runNodeScript(file: string, extraArgs?: string[], options?: RunNodeScriptOptions): Promise<void>;

package/lib/utils/node-script.js

@@ -0,0 +1,116 @@
+// `gjsify run --node-script <file>` — run an UNBUNDLED `.mjs`/`.js` that imports
+// `node:*` builtins, on whatever runtime the CLI itself is executing on.
+//
+// WHY THIS EXISTS
+//
+// A repo script like `scripts/build-assets.mjs` imports only `node:fs` /
+// `node:path` / `node:url` — every one of which gjsify polyfills — so nothing
+// about it is intrinsically Node-bound. What was missing is a way to RUN one
+// under GJS: GJS's ESM loader has no `node:` URI scheme and no node_modules
+// walker, so `gjs -m scripts/build-assets.mjs` dies on the first import. That
+// single gap is why a Node-less host could install gjsify, resolve every native
+// prebuild, and then fail `build:infra` at `node scripts/process-template.mjs`
+// (`status/open-todos.md`, "A Node-less host cannot bootstrap a fresh CLONE").
+//
+// The alternative that was considered and rejected: commit a `dist/*.gjs.mjs`
+// for each script. That is one more artifact per script under the committed-
+// bundle freshness gate, and it scales with the number of scripts. This is ONE
+// mechanism that serves every script in the repo and every consumer's too.
+//
+// WHAT IT DOES
+//
+//   node / bun / deno host → spawn the file on that runtime. Byte-for-byte what
+//                            `node <file>` did before; no bundling, no cost.
+//   gjs host               → bundle the file `--app gjs` (which is what maps
+//                            `node:fs` → `@gjsify/fs`, injects the globals the
+//                            script reads, and resolves bare specifiers), then
+//                            run the bundle.
+//
+// `import.meta.url` IS THE WHOLE TRICK
+//
+// The bundle does not live where the source lives, and a script's own location
+// is how it finds what it operates on — all four scripts this was built for open
+// with `dirname(fileURLToPath(import.meta.url))` and derive their package root
+// from it. Left alone, `import.meta.url` in the bundle is the BUNDLE's URL, so
+// every one of them would write its output into the cache directory. So the
+// source file's URL is baked in as a compile-time define, exactly as
+// `config.ts`'s `loadConfigViaGjsBundle` does for a `gjsify.config.js` that
+// reads its own siblings. `process.argv` needs no such care: the `--app gjs`
+// bundle already exposes `[gjs, <bundle>, ...args]`, so `argv.slice(2)` and
+// `argv.includes('--flag')` behave as they do on Node.
+import { existsSync, statSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { hostRuntime } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { runGjsBundle } from './run-gjs.js';
+import { runRuntimeBundle } from './run-node.js';
+/**
+ * Whether the on-the-fly GJS bundle may be reused across runs.
+ *
+ * OFF by default, and that is deliberate. The cache `bundleFileForGjsCached`
+ * implements invalidates on the ENTRY file's mtime plus the project lockfile —
+ * which covers a plugin or a config (both leaf-ish, both consuming installed
+ * deps) but NOT a repo script, whose imports are workspace packages that change
+ * without any lockfile write. A stale bundle there does not fail loudly: the
+ * script runs and EMITS BUILD OUTPUT from code that no longer exists in the
+ * tree. That is the failure this repo has paid for repeatedly under a different
+ * name ("it never runs the source you just edited"), and a build script is the
+ * worst place to reintroduce it.
+ *
+ * The cost of being right is one bundle per invocation, and only under GJS —
+ * node/bun/deno never bundle at all. `GJSIFY_NODE_SCRIPT_CACHE=1` opts in for a
+ * host that would rather have the seconds back.
+ */
+function scriptCacheEnabled() {
+    const v = process.env['GJSIFY_NODE_SCRIPT_CACHE'];
+    return v === '1' || v === 'true' || v === 'yes';
+}
+/**
+ * Run `file` — an unbundled ESM script that imports `node:` builtins — on the
+ * CLI's own host runtime, bundling it for GJS first when that is where we are.
+ *
+ * Terminal callers pass `exitOnSuccess` (a GJS main loop armed by the spawn
+ * parks the process otherwise); see {@link runGjsBundle}.
+ */
+export async function runNodeScript(file, extraArgs = [], options = {}) {
+    const scriptPath = resolve(file);
+    if (!existsSync(scriptPath) || !statSync(scriptPath).isFile()) {
+        console.error(`gjsify run --node-script: no such file: ${scriptPath}`);
+        // `return process.exit` — a bare exit falls through under GJS (see run.ts).
+        return process.exit(1);
+    }
+    const host = hostRuntime();
+    if (host !== 'gjs') {
+        // Node/bun/deno can load the file as-is; bundling would only add a step
+        // and a way to differ from what the runtime would have done itself.
+        // `quiet`: the echo would print `node <file>` — which is exactly what the
+        // package.json script already reads — behind ~2 kB of native-library env
+        // that a build script never loads. Nothing is lost by leaving it out, and
+        // a build chain calls this a dozen times.
+        await runRuntimeBundle(host, scriptPath, extraArgs, { exitOnSuccess: options.exitOnSuccess, quiet: true });
+        return;
+    }
+    // Dynamic import keeps the bundler machinery out of the eager module graph
+    // of every `gjsify run`, matching how config.ts pulls it.
+    const { BuildAction } = await import('../actions/build.js');
+    let bundlePath;
+    try {
+        bundlePath = await BuildAction.bundleFileForGjsCached(scriptPath, {
+            cacheSubdir: 'node-scripts',
+            label: basename(scriptPath),
+            cache: scriptCacheEnabled(),
+            // A script is executed, never imported — no default export to preserve.
+            preserveDefaultExport: false,
+            define: { 'import.meta.url': JSON.stringify(pathToFileURL(scriptPath).href) },
+        });
+    }
+    catch (err) {
+        throw new Error(`gjsify run --node-script: failed to bundle ${scriptPath} for GJS. ` +
+            `The script must import only what gjsify can provide under GJS (node: builtins, ` +
+            `workspace packages, pure-JS npm deps). (${err.message})`);
+    }
+    // Quiet for the same reason as the node path above; the bundle's location is
+    // deterministic (`node_modules/.cache/gjsify/node-scripts/<name>-<hash>.mjs`)
+    // for anyone who needs to inspect it.
+    await runGjsBundle(bundlePath, extraArgs, { exitOnSuccess: options.exitOnSuccess, quiet: true });
+}

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

@@ -28,5 +28,12 @@ export interface RunGjsBundleOptions {
      * truncated `gjsify test` after the first gjs bundle.
      */
     exitOnSuccess?: boolean;
+    /**
+     * Suppress the `$ <env> gjs -m …` echo. The echo exists so a user can
+     * copy-paste the exact command, which is worth ~2 kB of env prefix for a
+     * one-shot `gjsify run <bundle>` — and is pure noise for a build script the
+     * chain invokes a dozen times (`utils/node-script.ts`).
+     */
+    quiet?: boolean;
 }
 export declare function runGjsBundle(bundlePath: string, extraArgs?: string[], options?: RunGjsBundleOptions): Promise<void>;

package/lib/utils/run-gjs.js

@@ -68,12 +68,23 @@ export async function runGjsBundle(bundlePath, extraArgs = [], options = {}) {
     // Use stderr so that children speaking a protocol on stdout (e.g. an
     // MCP stdio server) receive an uncontaminated stdout stream.
     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, so it can be re-raised verbatim. A spawn error
+    // (no `gjs` on PATH) has no code of its own and falls back to 1.
+    //
+    // Collapsing every failure to 1 lost information a caller acts on: a script
+    // run through `gjsify run --node-script` reports ITS status (the bootstrap
+    // scripts all end `process.exit(r.status ?? 1)`, forwarding a child's code),
+    // and a chain that reads `$?` to distinguish "tool failed" from "tool says
+    // no" saw the same 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 {
@@ -94,8 +105,8 @@ export async function runGjsBundle(bundlePath, extraArgs = [], options = {}) {
         // 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);
+        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-node.d.ts

@@ -27,6 +27,8 @@ 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

package/lib/utils/run-node.js

@@ -148,20 +148,37 @@ export async function runRuntimeBundle(runtime, bundlePath, extraArgs = [], opti
     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 — same reason as
+    // `runGjsBundle`: a script run through `--node-script` reports its status
+    // through this path, and a caller that reads `$?` needs the real one.
+    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 the flag rather than an exit inside the
+    // `catch`: under GJS `process.exit()` is deferred and RETURNS, so a bare
+    // call in the catch fell through to the `exitOnSuccess` line below and
+    // scheduled a second exit — the same fall-through `runGjsBundle` and
+    // `commands/run.ts` already carry this shape for.
+    if (failed) {
+        process.exitCode = childCode;
+        return process.exit(childCode);
+    }
     if (options.exitOnSuccess)
-        process.exit(0);
+        return process.exit(0);
 }