@gjsify/cli 0.35.0 → 0.37.0

package/lib/utils/library-output.js

@@ -1,27 +1,20 @@
 // Guard against the recurring "library build leaks into src/" footgun.
 //
-// `BuildAction.buildLibrary` derives its output directory from
-// `dirname(package.json "module" ?? "main")`. When a package points `main`
-// at its runtime SOURCE entry (`src/index.ts` — the intended entry for
-// Vite/gjsify-compiled consumers, e.g. `@gjsify/adwaita-web`), that derived
-// outdir is `src/`, so `gjsify build --library` writes the compiled `.js`
-// tree straight next to the sources: `src/*.js` / `*2.js` duplicates, a
-// `src/_virtual/` helper dir, and a nested `src/<pkg>/src/**` preserve-modules
-// tree. These pure helpers let the build action refuse that up front instead
-// of silently corrupting the source tree.
+// `BuildAction.buildLibrary` derives its outdir from `dirname(package.json "module" ?? "main")`.
+// When a package points `main` at its runtime SOURCE entry (`src/index.ts` — the intended entry
+// for Vite/gjsify-compiled consumers, e.g. `@gjsify/adwaita-web`), that outdir is `src/`, so
+// `gjsify build --library` writes the compiled tree next to the sources: `src/*.js` / `*2.js`
+// duplicates, a `src/_virtual/` helper dir, and a nested `src/<pkg>/src/**` preserve-modules
+// tree. These pure helpers let the build action refuse that up front.
 import { dirname, extname, isAbsolute, relative, resolve } from 'node:path';
 /**
- * The literal (non-glob) base directories the build's input source files live
- * in, derived from the bundler `input` patterns. A file entry maps to its
- * containing dir, a glob is reduced to the literal prefix before the first
- * wildcard:
- *   - `src/index.ts`   → `<cwd>/src`
- *   - `src/**` + `/*.ts` → `<cwd>/src`
- *   - `src`            → `<cwd>/src`
+ * The literal (non-glob) base directories the input source files live in, derived from the
+ * bundler `input` patterns: a file entry maps to its containing dir, a glob is reduced to the
+ * literal prefix before the first wildcard (`src/index.ts`, `src` and `src/**` + `/*.ts` all
+ * give `<cwd>/src`).
  *
- * The project root itself is intentionally excluded — a flat library that
- * keeps its source at the project root and emits there is an explicit layout,
- * not the `src/`-subdir footgun this guard targets.
+ * The project root is intentionally excluded — a flat library keeping its source at the root and
+ * emitting there is an explicit layout, not the `src/`-subdir footgun this guard targets.
  */
 export function inputSourceDirs(input, cwd) {
     const patterns = [];
@@ -39,18 +32,16 @@ export function inputSourceDirs(input, cwd) {
     const dirs = new Set();
     for (const raw of patterns) {
         const norm = raw.replace(/\\/g, '/');
-        // Cut the pattern at the first glob metacharacter — everything before
-        // it is a literal path prefix.
+        // Everything before the first glob metacharacter is a literal path prefix.
         const globIdx = norm.search(/[*?{}[\]()!+@]/);
         let base = globIdx === -1 ? norm : norm.slice(0, globIdx);
         if (globIdx === -1) {
-            // Whole pattern is literal: a file path collapses to its dirname,
-            // a bare directory stays as-is.
+            // Wholly literal: a file path collapses to its dirname, a bare directory stays.
             base = extname(base) ? dirname(base) : base;
         }
         else {
-            // The glob cut mid-segment (`src/`, `src/fo*`) — drop the trailing
-            // partial segment so we keep only the complete literal directory.
+            // The glob cut mid-segment (`src/fo*`) — drop the trailing partial segment so only
+            // the complete literal directory remains.
             base = base.replace(/\/[^/]*$/, '');
         }
         const abs = resolve(root, base || '.');
@@ -65,23 +56,14 @@ function isInsideOrEqual(child, parent) {
     return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
 }
 /**
- * `true` when writing library output to `outdir` would land build artifacts
- * inside (or directly on top of) the input source tree. Unsafe iff `outdir`
- * equals, or is nested under, any input source directory.
- *
- *   isOutdirInsideSource('src',      ['<cwd>/src'])       → true   (leak)
- *   isOutdirInsideSource('src/nest', ['<cwd>/src'])       → true   (leak)
- *   isOutdirInsideSource('dist/esm', ['<cwd>/src'])       → false  (safe)
- *   isOutdirInsideSource('lib',      ['<cwd>/src'])       → false  (safe)
+ * `true` when library output written to `outdir` would land inside (or on top of) the input
+ * source tree — i.e. `outdir` equals, or is nested under, any input source directory.
  */
 export function isOutdirInsideSource(outdir, sourceDirs, cwd) {
     const absOut = resolve(cwd, outdir);
     return sourceDirs.some((dir) => isInsideOrEqual(absOut, dir));
 }
-/**
- * The error thrown when a `--library` build would emit into its own source
- * tree. Names both remedies so the fix is actionable at the point of failure.
- */
+/** The error thrown when a `--library` build would emit into its own source tree. */
 export function libraryOutputLeakError(outdir) {
     return new Error(`gjsify build --library: refusing to write output into "${outdir}", which holds the ` +
         `input source — a library build there produces src/*.js duplicates, *2.js, a ` +

package/lib/utils/load-npmrc.d.ts

@@ -1,14 +1,13 @@
 import { type NpmrcConfig } from '@gjsify/npm-registry';
 export declare function loadNpmrc(cwd: string): Promise<NpmrcConfig>;
 /**
- * True iff the parsed npmrc contains *any* `_authToken` entry. Cheap helper
- * for commands that want a clear "no token configured" error message
- * instead of a generic 401/empty response.
+ * True iff the parsed npmrc contains *any* `_authToken` entry — lets a command
+ * say "no token configured" instead of relaying a generic 401.
  */
 export declare function hasAnyAuthToken(npmrc: NpmrcConfig): boolean;
 /**
- * True iff the parsed npmrc has *any* credential (bearer token or basic
- * auth). Used by `gjsify whoami` to differentiate "no token configured"
- * from "token configured but rejected by the registry".
+ * True iff the parsed npmrc has *any* credential (bearer token or basic auth).
+ * `gjsify whoami` uses it to tell "no token configured" apart from "token
+ * configured but rejected by the registry".
  */
 export declare function hasAnyCredential(npmrc: NpmrcConfig): boolean;

package/lib/utils/load-npmrc.js

@@ -1,25 +1,17 @@
-// Shared npmrc loader for `gjsify publish` / `gjsify whoami` / future
-// auth-aware commands. Mirrors npm CLI's resolution order so a maintainer's
-// `~/.npmrc` token AND a CI-injected `NPM_CONFIG_USERCONFIG` token both
-// reach the registry call.
+// Shared npmrc loader for the auth-aware commands (`gjsify publish`,
+// `gjsify whoami`, …), so that both a maintainer's `~/.npmrc` token and a
+// CI-injected `NPM_CONFIG_USERCONFIG` token reach the registry call.
+// `actions/setup-node` writes its auth-token npmrc to `$RUNNER_TEMP/.npmrc` and
+// exports `NPM_CONFIG_USERCONFIG` at it — it never touches `~/.npmrc`, so
+// honouring that env var is what makes CI authentication work, and `${VAR}`
+// placeholders must be expanded on read (npm's own behaviour):
+// `_authToken=${NODE_AUTH_TOKEN}` arrives as a literal placeholder.
 //
-// Resolution order (lowest → highest precedence — last write wins on key
-// collisions because the sources are concatenated and re-parsed):
-//   1. globalconfig:  /etc/npmrc  (system; intentionally NOT read here —
-//                     gjsify's user-facing commands operate on per-user
-//                     credentials, matching `npm whoami`'s behavior)
-//   2. userconfig:    $NPM_CONFIG_USERCONFIG  (overrides ~/.npmrc)
-//                     or ~/.npmrc  (default)
-//   3. projectconfig: ./.npmrc  (closest workspace)
-//
-// `actions/setup-node` writes the auth-token npmrc to $RUNNER_TEMP/.npmrc
-// and exports NPM_CONFIG_USERCONFIG pointing at it — it does NOT touch
-// ~/.npmrc. Honor the env var so CI authentication works end-to-end.
-//
-// `${VAR}` placeholders are expanded inline (npm CLI's expand-on-read
-// behavior). The auth-token npmrc from actions/setup-node ships
-// `_authToken=${NODE_AUTH_TOKEN}` as a literal placeholder; the env var is
-// set on the publish step.
+// `/etc/npmrc` (globalconfig) is deliberately NOT read — these commands operate
+// on per-user credentials, matching `npm whoami`. The remaining sources are
+// concatenated and re-parsed, so LAST WRITE WINS on a key collision: appended
+// project-first then user, the user/CI config overrides the project `.npmrc`,
+// which is the inverse of npm's own precedence.
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -44,17 +36,16 @@ export async function loadNpmrc(cwd) {
     return parseNpmrc(merged);
 }
 /**
- * True iff the parsed npmrc contains *any* `_authToken` entry. Cheap helper
- * for commands that want a clear "no token configured" error message
- * instead of a generic 401/empty response.
+ * True iff the parsed npmrc contains *any* `_authToken` entry — lets a command
+ * say "no token configured" instead of relaying a generic 401.
  */
 export function hasAnyAuthToken(npmrc) {
     return Object.keys(npmrc.authTokens).length > 0;
 }
 /**
- * True iff the parsed npmrc has *any* credential (bearer token or basic
- * auth). Used by `gjsify whoami` to differentiate "no token configured"
- * from "token configured but rejected by the registry".
+ * True iff the parsed npmrc has *any* credential (bearer token or basic auth).
+ * `gjsify whoami` uses it to tell "no token configured" apart from "token
+ * configured but rejected by the registry".
  */
 export function hasAnyCredential(npmrc) {
     return hasAnyAuthToken(npmrc) || Object.keys(npmrc.basicAuth).length > 0;

package/lib/utils/node-bundle-guard.d.ts

@@ -1,16 +1,12 @@
 /**
  * The GJS ambient globals referenced as BARE identifiers in `code`, sorted.
  *
- * Empty for a bundle that only uses the `globalThis.imports` isomorphic-guard
- * shape — that form is a runtime probe, not a dependency, and the detector
- * ignores it for exactly that reason.
+ * Empty for a bundle that only uses the `globalThis.imports` isomorphic-guard shape — that
+ * form is a runtime probe, not a dependency, and the detector ignores it for that reason.
  */
 export declare function findUnshimmedGjsGlobals(code: string): string[];
 /**
- * Throw when a `--app node` bundle references GJS ambient globals but was built
- * without the `@gjsify/node-gi/globals` shim.
- *
- * @param code     the emitted bundle source
- * @param outfile  path of the bundle, for the error message
+ * Throw when a `--app node` bundle references GJS ambient globals but was built without
+ * the `@gjsify/node-gi/globals` shim.
  */
 export declare function assertNodeBundleGlobalsShimmed(code: string, outfile: string): void;

package/lib/utils/node-bundle-guard.js

@@ -1,35 +1,25 @@
 // Build-time guard: a `--app node` bundle that USES the GJS ambient globals
 // must also have been given `@gjsify/node-gi/globals`.
 //
-// `print`/`printerr`/`log`/`logError`/`ARGV`/`imports` exist implicitly under
-// gjs and nowhere else. On the node target they are seeded by the side-effect
-// shim `@gjsify/node-gi/globals`, which the CLI injects when — and only when —
-// `detectNodeGiGlobals` finds one of them in an analysis bundle. Injecting it
-// unconditionally is not an option: it eagerly loads the native node-gi addon,
-// so a cross-platform package's node bundle would stop loading on plain Node.
+// `print`/`printerr`/`log`/`logError`/`ARGV`/`imports` exist implicitly under gjs and
+// nowhere else. On the node target the side-effect shim `@gjsify/node-gi/globals` seeds
+// them, injected only when `detectNodeGiGlobals` finds one in an analysis bundle —
+// injecting unconditionally would eagerly load the native node-gi addon, so a
+// cross-platform package's node bundle would stop loading on plain Node.
 //
-// That makes the decision a PREDICTION about an artifact that does not exist
-// yet, and a prediction can be wrong. It was: the analysis pass used to run
-// before the explicit-`--globals` register stub was resolved, and that stub is
-// one of the two signals `isGjsSourceBuild()` reads — so the analysis bundle
-// routed `/register` subpaths to `@gjsify/empty` and emptied `@girs/*` while the
-// REAL build resolved them for real. Every ambient global reachable only through
-// a register module was therefore invisible to the detector. The build exited 0
-// and the emitted bundle died at its first canvas op with
+// That makes the decision a PREDICTION about an artifact that does not exist yet, and it
+// was wrong once: the analysis pass ran before the explicit-`--globals` register stub was
+// resolved, and that stub is one of the two signals `isGjsSourceBuild()` reads, so the
+// analysis bundle routed `/register` subpaths to `@gjsify/empty` and emptied `@girs/*`
+// while the REAL build resolved them — making every ambient global reachable only through
+// a register module invisible to the detector. The build exited 0 and the bundle died at
+// its first canvas op with `ReferenceError: imports is not defined` on node AND bun (the
+// excalibur-jelly-jumper showcase), while gjs ran fine.
 //
-//   ReferenceError: imports is not defined
-//       at CanvasRenderingContext2D._toDataURL
-//
-// on node AND bun (the excalibur-jelly-jumper showcase), while gjs — where the
-// globals are ambient — ran fine. Nothing between `gjsify build --app node` and
-// a user running the bundle ever looked at the artifact.
-//
-// So this is a POST-condition on what was actually emitted: whatever the
-// detector predicted, check it against the bundle. It is deliberately NOT a
-// second detector — it runs the SAME `detectGjsAmbientGlobals` over the SAME
-// kind of input (bundled, tree-shaken output, parsed by acorn, bare identifiers
-// only). Two passes over one oracle that must agree; when they don't, the graph
-// they saw differed, which is a bug in the build pipeline, not in user code.
+// So this is a POST-condition on what was actually emitted, deliberately NOT a second
+// detector: it runs the SAME `detectGjsAmbientGlobals` over the SAME kind of input
+// (bundled, tree-shaken output, parsed by acorn, bare identifiers only). Two passes over
+// one oracle that must agree; a disagreement is a bug in the build pipeline, not user code.
 //
 // Scope: only when the CLI decided NOT to inject (`--globals auto`, no shim).
 // `--globals none` opts out of the whole mechanism explicitly and is skipped.
@@ -37,19 +27,15 @@ import { detectGjsAmbientGlobals } from '@gjsify/rolldown-plugin-gjsify/globals'
 /**
  * The GJS ambient globals referenced as BARE identifiers in `code`, sorted.
  *
- * Empty for a bundle that only uses the `globalThis.imports` isomorphic-guard
- * shape — that form is a runtime probe, not a dependency, and the detector
- * ignores it for exactly that reason.
+ * Empty for a bundle that only uses the `globalThis.imports` isomorphic-guard shape — that
+ * form is a runtime probe, not a dependency, and the detector ignores it for that reason.
  */
 export function findUnshimmedGjsGlobals(code) {
     return [...detectGjsAmbientGlobals(code)].sort();
 }
 /**
- * Throw when a `--app node` bundle references GJS ambient globals but was built
- * without the `@gjsify/node-gi/globals` shim.
- *
- * @param code     the emitted bundle source
- * @param outfile  path of the bundle, for the error message
+ * Throw when a `--app node` bundle references GJS ambient globals but was built without
+ * the `@gjsify/node-gi/globals` shim.
  */
 export function assertNodeBundleGlobalsShimmed(code, outfile) {
     const offenders = findUnshimmedGjsGlobals(code);

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,95 @@
+// `gjsify run --node-script <file>` — run an UNBUNDLED `.mjs`/`.js` that imports
+// `node:*` builtins, on whatever runtime the CLI itself is executing on.
+//
+// A repo script that imports only `node:fs`/`node:path`/`node:url` — all polyfilled — is not
+// intrinsically Node-bound; what was missing is a way to RUN one under GJS, whose ESM loader
+// has no `node:` URI scheme and no node_modules walker, so `gjs -m <script>.mjs` dies on the
+// first import. That 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` (see
+// `status/open-todos.md`).
+//
+// Rejected alternative: commit a `dist/*.gjs.mjs` per script — one more artifact each under
+// the committed-bundle freshness gate, scaling with the number of scripts. This is ONE
+// mechanism serving every script in the repo and every consumer's too.
+//
+//   node / bun / deno host → spawn the file on that runtime; no bundling, no cost.
+//   gjs host               → bundle `--app gjs` (which 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 derive their package root from `dirname(fileURLToPath(import.meta.url))`. Left
+// alone that is the BUNDLE's URL, so every one would write its output into the cache
+// directory; the source file's URL is therefore 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]`.
+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: `bundleFileForGjsCached` invalidates on the ENTRY file's mtime plus the
+ * project lockfile, which covers a plugin or a config 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, and a build script is the worst place to reintroduce that.
+ *
+ * The cost is one bundle per invocation, and only under GJS. `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 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` because the echo
+        // would print `node <file>` — what the package.json script already reads — behind
+        // ~2 kB of native-library env, a dozen times per build chain.
+        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`).
+    await runGjsBundle(bundlePath, extraArgs, { exitOnSuccess: options.exitOnSuccess, quiet: true });
+}

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

@@ -1,21 +1,12 @@
-/**
- * Minimum Node.js major the native install backend supports — its prebuilt native
- * modules are ABI-locked to this line (kept in sync with `.nvmrc`).
- */
+/** Minimum Node major the native install backend supports — keep 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.
+ * The preflight verdict, factored out so it can be unit-tested without spawning a
+ * foreign Node. `null` (pass) on a supported Node, under GJS, and on a version
+ * string that does not parse — an unparseable version must not block an install.
  */
 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.
- */
+/** Throw the preflight verdict as an error; no-op under GJS and on a supported Node. */
 export declare function assertNativeBackendNodeVersion(): void;

package/lib/utils/node-version.js

@@ -1,28 +1,22 @@
 // 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.
+// Its prebuilt binaries are ABI-locked to the Node line gjsify targets (`.nvmrc`).
+// On an older major they load a mismatched ABI and SIGSEGV mid-install instead of
+// failing cleanly — measured: Node 22 in a Fedora container segfaults
+// `gjsify install --backend native` during download/extract. This turns that into
+// an actionable error.
 import { isNode, gjsSystemVersion } 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`).
- */
+/** Minimum Node major the native install backend supports — keep 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.
+ * The preflight verdict, factored out so it can be unit-tested without spawning a
+ * foreign Node. `null` (pass) on a supported Node, under GJS, and on a version
+ * string that does not parse — an unparseable version must not block an install.
  */
 export function nativeBackendNodeError(version, onRealNode) {
     if (!onRealNode)
@@ -34,21 +28,18 @@ export function nativeBackendNodeError(version, onRealNode) {
         `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`. */
+/**
+ * True when the CLI runs on real Node. GJS must be ruled out FIRST: `@gjsify/process`
+ * fakes `process.versions.node = '20.0.0'` for compat, so reading that field would
+ * be a false Node positive there (and a false preflight failure, since 20 < 24).
+ */
 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 = gjsSystemVersion();
     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.
- */
+/** Throw the preflight verdict as an error; no-op under GJS and on a supported Node. */
 export function assertNativeBackendNodeVersion() {
     const message = nativeBackendNodeError(process.versions.node, onRealNode());
     if (message)

package/lib/utils/normalize-bundler-options.d.ts

@@ -1,17 +1,13 @@
 import type { ConfigData, BundlerOptions } from '../types/config-data.js';
 export declare function normalizeBundlerOptions(configData: ConfigData): BundlerOptions;
 /**
- * Shallow merge with deep-merge of `output`, `transform`, and `resolve`. The
- * second argument wins on conflicts, matching `merge(target, ...sources)`
- * semantics from `@gjsify/rolldown-plugin-gjsify/utils/merge`.
+ * Shallow merge with deep-merge of `output`, `transform` and `resolve`; `overrides` wins,
+ * matching `merge(target, ...sources)` from `@gjsify/rolldown-plugin-gjsify/utils/merge`. `base`
+ * is the orchestrator's Rolldown-generic shape, `overrides` the user's config plus CLI flags.
  *
- * `base` is typically the Rolldown-generic shape returned by the orchestrator;
- * `overrides` is the user's `BundlerOptions` from `.gjsifyrc.js` plus CLI
- * flag merges. Single-output assumption matches `BundlerOptions['output']`.
- *
- * The orchestrator-side `input` is authoritative — it's the post-glob-expansion
- * value. Overriding it with the user's raw glob string would re-introduce
- * unresolved glob patterns into the final Rolldown call. Same for `external`,
- * which the orchestrator concatenates with platform defaults already.
+ * The orchestrator's `input` is authoritative because it is the post-glob-expansion value —
+ * taking the user's raw glob string would re-introduce unresolved patterns into the Rolldown
+ * call. Same for `external`, which the orchestrator has already concatenated with the platform
+ * defaults.
  */
 export declare function mergeBundlerOptions(base: BundlerOptions, overrides: BundlerOptions): BundlerOptions;

package/lib/utils/normalize-bundler-options.js

@@ -1,24 +1,18 @@
-// One-release deprecation shim: maps the legacy `esbuild?: BuildOptions`
-// field on `.gjsifyrc.js` / `package.json#gjsify` into the equivalent
-// `bundler?: RolldownOptions` shape. Logs a single warning per build.
+// Deprecation shim: maps the legacy `esbuild?: BuildOptions` field on `.gjsifyrc.js` /
+// `package.json#gjsify` into the equivalent `bundler?: RolldownOptions` shape, warning once per
+// build. It was slated for removal in 0.5.0 and is still here at 0.35.0 — the warning text it
+// prints still names 0.5.0, so removing the shim means fixing that string too.
 //
-// Also handles the top-level `bundler.define` alias: Rolldown reads
-// `transform.define`, not a top-level `define`. A user who flat-renames
-// `esbuild: { define: {...} }` → `bundler: { define: {...} }` puts `define`
-// at the top level where Rolldown silently ignores it, causing
-// `ReferenceError: <TOKEN> is not defined` at GJS load time. We auto-map
-// top-level `bundler.define` into `bundler.transform.define` and emit a
-// one-time warning so the user can correct their config.
-//
-// Drop `esbuild` shim in 0.5.0; the `bundler.define` alias is permanent.
+// Also handles the top-level `bundler.define` alias, which is PERMANENT: Rolldown reads
+// `transform.define`, so a user who flat-renames `esbuild: { define }` → `bundler: { define }`
+// lands `define` at the top level where Rolldown silently ignores it, producing
+// `ReferenceError: <TOKEN> is not defined` at GJS load time.
 let warnedOnce = false;
 let warnedDefineOnce = false;
 export function normalizeBundlerOptions(configData) {
     const raw = (configData.bundler ?? {});
-    // --- Top-level bundler.define alias ------------------------------------------
-    // Rolldown only reads `transform.define`; a top-level `define` key is silently
-    // ignored. Detect it, warn once, and move it into `transform.define` so the
-    // user's flat esbuild→bundler rename of `define` Just Works.
+    // Rolldown reads only `transform.define`, so a top-level `define` is moved there (warning
+    // once) rather than being silently ignored — see the header.
     let fromBundler = raw;
     if (typeof raw['define'] === 'object' &&
         raw['define'] !== null) {
@@ -49,11 +43,9 @@ export function normalizeBundlerOptions(configData) {
             "Rename it to 'bundler' (typed as RolldownOptions). See the migration notes in the gjsify CHANGELOG.");
     }
     const fromEsbuild = legacyEsbuildToRolldown(configData.esbuild);
-    // Plain user-config merge — we deliberately do NOT call
-    // `mergeBundlerOptions` here, because that function strips `input` and
-    // `external` from its overrides arg (it assumes the *orchestrator* is
-    // the override source and the user the base). Here both inputs are
-    // user-provided config and `input` must survive the merge.
+    // Deliberately NOT `mergeBundlerOptions`: that strips `input`/`external` from its overrides
+    // arg because it assumes the ORCHESTRATOR is the override source. Here both sides are user
+    // config, and `input` must survive the merge.
     const out = { ...fromEsbuild, ...fromBundler };
     if (fromEsbuild.output || fromBundler.output) {
         out.output = { ...fromEsbuild.output, ...fromBundler.output };
@@ -111,33 +103,23 @@ function legacyEsbuildToRolldown(esb) {
         out.transform = transform;
     if (Object.keys(resolve).length > 0)
         out.resolve = resolve;
-    // Discarded (handled elsewhere):
-    //   esb.inject  — esbuild's array-of-side-effect-files; surfaced at the
-    //                 CLI layer instead, via input expansion.
-    //   esb.loader  — replaced by top-level `gjsify.loaders` (see ConfigData);
-    //                 migration: `esbuild.loader: { '.png': 'dataurl', '.glsl': 'text' }`
-    //                 → `loaders: { '.png': 'dataurl', '.glsl': 'text' }`.
+    // Discarded, handled elsewhere: `esb.inject` (surfaced at the CLI layer via input
+    // expansion) and `esb.loader` (replaced by top-level `gjsify.loaders`, see ConfigData).
     return out;
 }
 /**
- * Shallow merge with deep-merge of `output`, `transform`, and `resolve`. The
- * second argument wins on conflicts, matching `merge(target, ...sources)`
- * semantics from `@gjsify/rolldown-plugin-gjsify/utils/merge`.
- *
- * `base` is typically the Rolldown-generic shape returned by the orchestrator;
- * `overrides` is the user's `BundlerOptions` from `.gjsifyrc.js` plus CLI
- * flag merges. Single-output assumption matches `BundlerOptions['output']`.
+ * Shallow merge with deep-merge of `output`, `transform` and `resolve`; `overrides` wins,
+ * matching `merge(target, ...sources)` from `@gjsify/rolldown-plugin-gjsify/utils/merge`. `base`
+ * is the orchestrator's Rolldown-generic shape, `overrides` the user's config plus CLI flags.
  *
- * The orchestrator-side `input` is authoritative — it's the post-glob-expansion
- * value. Overriding it with the user's raw glob string would re-introduce
- * unresolved glob patterns into the final Rolldown call. Same for `external`,
- * which the orchestrator concatenates with platform defaults already.
+ * The orchestrator's `input` is authoritative because it is the post-glob-expansion value —
+ * taking the user's raw glob string would re-introduce unresolved patterns into the Rolldown
+ * call. Same for `external`, which the orchestrator has already concatenated with the platform
+ * defaults.
  */
 export function mergeBundlerOptions(base, overrides) {
-    // Strip fields the orchestrator owns authoritatively — the user has
-    // already had their say via the orchestrator's `userExternal` / input
-    // expansion; merging the raw values back on top would clobber the
-    // post-processing.
+    // Strip the fields the orchestrator owns: the user already had their say through
+    // `userExternal` / input expansion, and merging the raw values back would clobber it.
     const { input: _ignoredInput, external: _ignoredExternal, ...overridesRest } = overrides;
     const out = { ...base, ...overridesRest };
     if (base.output || overrides.output) {