@gjsify/cli 0.36.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.js

@@ -1,43 +1,30 @@
 // `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 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`).
 //
-// 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").
+// 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.
 //
-// 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.
+//   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.
 //
-// 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.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';
@@ -47,19 +34,14 @@ 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.
+ * 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 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.
+ * 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'];
@@ -81,12 +63,10 @@ export async function runNodeScript(file, extraArgs = [], options = {}) {
     }
     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.
+        // 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;
     }
@@ -110,7 +90,6 @@ export async function runNodeScript(file, extraArgs = [], options = {}) {
             `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.
+    // 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;