@gjsify/cli 0.35.0 → 0.37.0

package/lib/utils/force-exit.js

@@ -1,39 +1,28 @@
 // The one way to end the CLI with a chosen exit code on BOTH runtimes.
 //
-// Node exits at natural shutdown once `process.exitCode` is set. GJS does not:
-// it has no atexit hook, and `process.exit()` there is not immediate — its
-// `exitProcess` IDLE-SCHEDULES `quitMainLoop()` + `imports.system.exit()` (see
-// `utils/spawn.ts` for the main-loop machinery this rides on). From inside an
-// asynchronous continuation — a `child.on('close'|'error')` handler, a
-// `setTimeout`, a promise callback — that idle can lose the race with the
-// module's own shutdown, and gjs then exits **0** no matter what code was
-// requested. `imports.system.exit` has no such gap: SpiderMonkey raises its
-// uncatchable exit exception from any context.
+// Node exits at natural shutdown once `process.exitCode` is set. GJS has no
+// atexit hook, and its `process.exit()` is not immediate — `exitProcess`
+// idle-schedules `quitMainLoop()` + `imports.system.exit()`. From an async
+// continuation (a `child.on('close'|'error')` handler, a `setTimeout`, a promise
+// callback) that idle can lose the race with module shutdown, and gjs then exits
+// **0** no matter what code was requested. `imports.system.exit` has no such
+// gap: SpiderMonkey raises its uncatchable exit exception from any context.
 //
-// This is not theoretical. `gjsify tsc` spawned the compiler and ended both its
-// `close` and `error` handlers with a bare `process.exit(…)`. Under the GJS
-// bundle every one of those exits was dropped, so the command reported SUCCESS
+// Incident: `gjsify tsc` ended its `close` and `error` handlers with a bare
+// `process.exit(…)`, so under the GJS bundle the command reported SUCCESS
 // whatever the compiler did — a type error exited 0, and so did "no compiler
-// could be spawned at all". A release-cut on a cold tree then ran
-// `node scripts/process-template.mjs && gjsify tsc && node scripts/set-bin-mode.mjs`
-// to completion and died in `set-bin-mode.mjs` on a `lib/index.js` that `tsc`
-// had never written — pointing the blame two steps past the actual failure.
-//
-// Two copies of this logic already existed (`commands/install.ts`'s local
-// `forceExit`, `utils/oxc-resolve.ts`'s `setOxcExitCode`) and a third call site
-// simply did without. One exported helper is the point: a new async exit path
-// gets it right by importing it rather than by remembering the rule.
+// could be spawned at all". A release-cut then died two steps later, in
+// `set-bin-mode.mjs`, on a `lib/index.js` that `tsc` had never written.
 import { gjsExit } from '@gjsify/rolldown-plugin-gjsify/runtime';
 /**
  * Exit the process with `code`, honoured on Node and GJS alike.
  *
  * Safe to call from any context, including an async callback where a bare
  * `process.exit()` would be dropped under GJS. Does not return.
- *
- * `process.exitCode` is set FIRST so that a host which somehow reaches natural
- * shutdown anyway still reports the right code.
  */
 export function forceExit(code) {
+    // Set first, so a host that somehow reaches natural shutdown anyway still
+    // reports the right code.
     process.exitCode = code;
     // Under GJS this does not return — `imports.system.exit` unwinds via
     // SpiderMonkey's uncatchable exit exception.

package/lib/utils/gi-search-path.d.ts

@@ -3,32 +3,24 @@ import { type NativePackage } from './detect-native-packages.js';
  * Put every detected prebuild directory on girepository's typelib AND library
  * search paths. Idempotent — the first call decides, later ones return it.
  *
- * This is THE LAUNCHER'S ENVIRONMENT, APPLIED TO THE PROCESS THAT IS ALREADY
- * RUNNING: it feeds on the same `detectNativePackages()` whose output the
- * `gjsify` bin turns into `GI_TYPELIB_PATH` + the host library-path variable
- * (`buildNativeEnv`), so the two mechanisms cannot resolve different sets. That
- * symmetry is also why this is not per-bridge: there is no list of covered
- * engines to maintain, and a bridge added later is covered without touching
- * this file. Today it covers all three the CLI loads in-process —
- * `rolldown-native`, `lightningcss-native` (via the `css-as-string` plugin) and
- * `oxfmt-native`.
+ * The launcher's environment applied to the already-running process: it feeds on
+ * the same `detectNativePackages()` whose output the `gjsify` bin turns into
+ * `GI_TYPELIB_PATH` + the host library-path variable (`buildNativeEnv`), so the two
+ * mechanisms cannot resolve different sets and a bridge added later needs no change
+ * here.
  *
- * TWO ANCHORS, merged first-wins exactly as `computeNativeEnvForBundle()` does
- * it: the cwd, and the directory this module itself lives in. The second is not
- * redundant — with a GLOBAL CLI the engine sits next to the bundle while the cwd
- * is an unrelated project, which is the same case `tryLoadNative()` documents
- * needing its `bundleUrl` anchor for. After bundling, every CLI module collapses
- * into `dist/cli.gjs.mjs`, so `import.meta.url` is the bundle's own URL, which
- * is precisely the "where does the CLI live" question being asked.
+ * TWO ANCHORS, merged first-wins as `computeNativeEnvForBundle()` does: the cwd, and
+ * this module's own directory. The second is not redundant — with a GLOBAL CLI the
+ * engine sits next to the bundle while the cwd is an unrelated project (the case
+ * `tryLoadNative()` needs its `bundleUrl` anchor for), and after bundling
+ * `import.meta.url` is the bundle's own URL.
  *
- * Called from the native-load paths, which are themselves memoized, so the
- * node_modules sweep (~65 ms per anchor on this 960-workspace tree, far less in
- * a consumer) is paid at most once per process and only by a command that
- * actually wants an engine. Deliberately NOT skipped when the launcher already
- * exported the same directories: that check can be wrong, prepending a
- * directory that already resolves changes nothing, and a guard whose job is
- * watching another mechanism is the shape `docs/governance.md` § simplicity
- * warns about.
+ * Callers are memoized, so the node_modules sweep (~65 ms per anchor on this
+ * 960-workspace tree) is paid at most once per process, by a command that wants an
+ * engine. Deliberately NOT skipped when the launcher already exported the same
+ * directories: that check can be wrong, prepending an already-resolving directory
+ * changes nothing, and a guard watching another mechanism is the shape
+ * `docs/governance.md` § simplicity warns about.
  *
  * @returns the packages activated — empty when there is no repository to write
  *   to (Node, or GLib < 2.86), which every caller reads as "carry on".

package/lib/utils/gi-search-path.js

@@ -1,9 +1,8 @@
 // Make the native prebuilds this process can see resolvable to the RUNNING GJS
 // process, with nothing exported into the environment beforehand. ADR 0021.
 //
-// THE MEASUREMENT (gjs 1.88.1 / GLib 2.88.3, importing `gi://GjsifyRolldown`
-// from a bare `gjs -m`) — there are TWO lookups, not one, and they fail
-// differently:
+// There are TWO lookups, not one, and they fail differently (measured on gjs
+// 1.88.1 / GLib 2.88.3, importing `gi://GjsifyRolldown` from a bare `gjs -m`):
 //
 //   neither var       "Typelib file for namespace 'GjsifyRolldown' (any
 //                      version) not found"
@@ -12,30 +11,22 @@
 //                      "Unsupported type void, deriving from fundamental void"
 //   both              loads
 //
-// The received answer was "the typelib lookup happens inside the GJS runtime,
-// so those must be set BEFORE the process starts — the CLI cannot repair it
-// from the inside". Half of that is permanently true: `LD_LIBRARY_PATH` cannot
-// be changed in-process because ld.so freezes its search path at startup, which
-// is an OS property and is why the `gjsify` launcher still exists for user
-// bundles.
-//
-// It is the wrong frame, because girepository delegates NEITHER lookup to the
-// loader's environment. It keeps a typelib search path AND a library search
-// path of its own, consults both before falling back to the system loader, and
-// both are writable at runtime. `prepend_library_path()` is the half nobody
-// went looking for: `LD_LIBRARY_PATH` was assumed to BE the mechanism when it
-// is only girepository's fallback — which is exactly what the middle row above
+// girepository delegates NEITHER lookup to the loader's environment: it keeps a
+// typelib search path AND a library search path of its own, consults both before
+// falling back to the system loader, and both are writable at runtime.
+// `LD_LIBRARY_PATH` is only girepository's fallback — which the middle row above
 // proves, since girepository's own library path starts empty and no environment
-// variable seeds it.
+// variable seeds it. That variable genuinely cannot be changed in-process (ld.so
+// freezes its search path at startup), which is why the `gjsify` launcher still
+// exists for user bundles — but it is not this lookup's mechanism.
 //
-// NOT an rpath problem, and the rpath is not the fix. `libgjsifyrolldown.so`
-// already carries `RUNPATH=$ORIGIN` (every bridge's `meson.build` sets it so
-// the Vala library finds the Rust cdylib shipped beside it — on macOS nothing
-// sets `DYLD_LIBRARY_PATH`, so it is the only thing that does). It structurally
-// cannot help gjs FIND `libgjsifyrolldown.so` itself: the typelib names it by
-// bare SONAME, and `dlopen()` of a bare name searches the RPATH/RUNPATH of the
-// CALLING object — libgirepository, whose `$ORIGIN` is /usr/lib64. An rpath on
-// the callee is never consulted to find the callee, so no artifact changes.
+// NOT an rpath problem, and the rpath is not the fix. `libgjsifyrolldown.so` already
+// carries `RUNPATH=$ORIGIN` (every bridge's `meson.build` sets it so the Vala library
+// finds the Rust cdylib beside it). That structurally cannot help gjs FIND
+// `libgjsifyrolldown.so` itself: the typelib names it by bare SONAME, and `dlopen()`
+// of a bare name searches the RPATH/RUNPATH of the CALLING object — libgirepository,
+// whose `$ORIGIN` is /usr/lib64. An rpath on the callee is never consulted to find
+// the callee, so no artifact changes.
 import { dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { detectNativePackages } from './detect-native-packages.js';
@@ -43,18 +34,15 @@ import { detectNativePackages } from './detect-native-packages.js';
  * girepository's process-global default repository — the one GJS's own `gi://`
  * importer resolves against — or `null` when there is none to write to.
  *
- * `globalThis.imports?.gi` is both the GJS probe (`.oxlintrc.json` sanctions
- * exactly this spelling for a runtime probe) and the correct CONDITION, which
- * is why there is no `isGjs()` beside it: the question is "is there a
- * GIRepository to prepend to", and a Node host answers no all by itself. That
- * is the required no-op — on Node the CLI uses the npm `rolldown` crate and
- * never wants a prebuild.
+ * `globalThis.imports?.gi` is both the sanctioned GJS probe spelling
+ * (`.oxlintrc.json`) and the correct CONDITION, so no `isGjs()` beside it: the
+ * question is "is there a GIRepository to prepend to", and a Node host answers
+ * no by itself — the required no-op, since on Node the CLI uses the npm
+ * `rolldown` crate and never wants a prebuild.
  *
- * `dup_default()` is GLib >= 2.86. A capability probe rather than a try/catch
- * because this is a KNOWN host property with a defined answer, not an
- * exceptional one: an older GLib simply keeps today's behaviour (the launcher's
- * environment, or an unchanged diagnosis), so the change cannot make any host
- * worse than it is.
+ * `dup_default()` is GLib >= 2.86, probed as a capability rather than caught:
+ * an older GLib simply keeps today's behaviour (the launcher's environment, or
+ * an unchanged diagnosis), so no host can be made worse.
  */
 function defaultRepository() {
     const gi = globalThis.imports?.gi;
@@ -68,32 +56,24 @@ let activated = null;
  * Put every detected prebuild directory on girepository's typelib AND library
  * search paths. Idempotent — the first call decides, later ones return it.
  *
- * This is THE LAUNCHER'S ENVIRONMENT, APPLIED TO THE PROCESS THAT IS ALREADY
- * RUNNING: it feeds on the same `detectNativePackages()` whose output the
- * `gjsify` bin turns into `GI_TYPELIB_PATH` + the host library-path variable
- * (`buildNativeEnv`), so the two mechanisms cannot resolve different sets. That
- * symmetry is also why this is not per-bridge: there is no list of covered
- * engines to maintain, and a bridge added later is covered without touching
- * this file. Today it covers all three the CLI loads in-process —
- * `rolldown-native`, `lightningcss-native` (via the `css-as-string` plugin) and
- * `oxfmt-native`.
+ * The launcher's environment applied to the already-running process: it feeds on
+ * the same `detectNativePackages()` whose output the `gjsify` bin turns into
+ * `GI_TYPELIB_PATH` + the host library-path variable (`buildNativeEnv`), so the two
+ * mechanisms cannot resolve different sets and a bridge added later needs no change
+ * here.
  *
- * TWO ANCHORS, merged first-wins exactly as `computeNativeEnvForBundle()` does
- * it: the cwd, and the directory this module itself lives in. The second is not
- * redundant — with a GLOBAL CLI the engine sits next to the bundle while the cwd
- * is an unrelated project, which is the same case `tryLoadNative()` documents
- * needing its `bundleUrl` anchor for. After bundling, every CLI module collapses
- * into `dist/cli.gjs.mjs`, so `import.meta.url` is the bundle's own URL, which
- * is precisely the "where does the CLI live" question being asked.
+ * TWO ANCHORS, merged first-wins as `computeNativeEnvForBundle()` does: the cwd, and
+ * this module's own directory. The second is not redundant — with a GLOBAL CLI the
+ * engine sits next to the bundle while the cwd is an unrelated project (the case
+ * `tryLoadNative()` needs its `bundleUrl` anchor for), and after bundling
+ * `import.meta.url` is the bundle's own URL.
  *
- * Called from the native-load paths, which are themselves memoized, so the
- * node_modules sweep (~65 ms per anchor on this 960-workspace tree, far less in
- * a consumer) is paid at most once per process and only by a command that
- * actually wants an engine. Deliberately NOT skipped when the launcher already
- * exported the same directories: that check can be wrong, prepending a
- * directory that already resolves changes nothing, and a guard whose job is
- * watching another mechanism is the shape `docs/governance.md` § simplicity
- * warns about.
+ * Callers are memoized, so the node_modules sweep (~65 ms per anchor on this
+ * 960-workspace tree) is paid at most once per process, by a command that wants an
+ * engine. Deliberately NOT skipped when the launcher already exported the same
+ * directories: that check can be wrong, prepending an already-resolving directory
+ * changes nothing, and a guard watching another mechanism is the shape
+ * `docs/governance.md` § simplicity warns about.
  *
  * @returns the packages activated — empty when there is no repository to write
  *   to (Node, or GLib < 2.86), which every caller reads as "carry on".
@@ -101,10 +81,9 @@ let activated = null;
 export function activateNativePrebuilds() {
     if (activated)
         return activated;
-    // Memoized BEFORE the work, so every outcome — including a throw — is
-    // decided once and every later caller gets an answer instead of a repeat
-    // attempt. `diagnoseNativeEngine()` depends on exactly that: it documents
-    // that nothing it calls may throw while explaining a failure.
+    // Memoized BEFORE the work, so every outcome — including a throw — is decided
+    // once. `diagnoseNativeEngine()` depends on that: nothing it calls may throw
+    // while explaining a failure.
     activated = [];
     try {
         const repository = defaultRepository();
@@ -121,26 +100,19 @@ export function activateNativePrebuilds() {
         activated = packages;
     }
     catch {
-        // TWO REAL THROW PATHS, named because a catch without one is the
-        // anti-pattern this repo measures:
-        //
-        //   1. `imports.gi.GIRepository` LOADS the namespace. GJS raises
-        //      "Requiring GIRepository, version none: Typelib file for namespace
-        //      'GIRepository' (any version) not found" when that typelib is
-        //      absent — verified by probe. It is a SEPARATE FILE from the
-        //      girepository library GJS links against, and distributions split
-        //      them (Debian ships `gir1.2-girepository-3.0` apart from
+        // Two real throw paths:
+        //   1. `imports.gi.GIRepository` LOADS the namespace, and that typelib is
+        //      a SEPARATE FILE from the girepository library GJS links against —
+        //      distributions split them (Debian's `gir1.2-girepository-3.0` vs
         //      `libgirepository-2.0-0`), so a lean host can have the second
-        //      without the first.
-        //   2. The two `detectNativePackages()` walks are filesystem I/O and can
-        //      raise (EACCES on an unreadable node_modules, a dir removed
-        //      mid-walk).
+        //      without the first and GJS raises "Typelib file for namespace
+        //      'GIRepository' (any version) not found".
+        //   2. The two `detectNativePackages()` walks are filesystem I/O (EACCES
+        //      on an unreadable node_modules, a dir removed mid-walk).
         //
-        // Both mean the same thing — no activation — and swallowing is the
-        // CORRECT handling rather than a hidden failure: the caller ends up
-        // exactly where it was before this function existed (the launcher's
-        // environment, and the unchanged diagnosis if that is absent too), so
-        // no host can be made worse by it.
+        // Both mean no activation, and swallowing leaves the caller exactly where
+        // it was before this function existed (the launcher's environment, or the
+        // unchanged diagnosis), so no host can be made worse by it.
     }
     return activated;
 }

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

@@ -8,14 +8,11 @@ export interface GuardedChunk {
 /**
  * Bare `node:` specifiers a `--app gjs` bundle may keep as static imports.
  *
- * Deliberately EMPTY. Every Node builtin has an `@gjsify/*` polyfill that
- * `--app gjs` aliases to, so there is no specifier that both survives into the
- * module graph and loads under GJS. Reading the graph instead of the text is
- * what keeps this list empty — the entries an earlier text-scanning version
- * needed (`node:module`, `node:process`) were quoted lookalikes, never imports.
+ * Deliberately EMPTY: every Node builtin has an `@gjsify/*` polyfill that `--app gjs`
+ * aliases to, so no specifier both survives into the module graph and loads under GJS.
  *
- * Add an entry ONLY with a comment naming why GJS can resolve it. Each one is a
- * specifier this guard can no longer catch for real.
+ * Add an entry ONLY with a comment naming why GJS can resolve it. Each one is a specifier
+ * this guard can no longer catch for real.
  */
 export declare const GJS_ALLOWED_NODE_IMPORTS: readonly string[];
 /**
@@ -23,10 +20,5 @@ export declare const GJS_ALLOWED_NODE_IMPORTS: readonly string[];
  * allowlist. Sorted, so the error message and any test are stable.
  */
 export declare function findDisallowedNodeImports(chunks: readonly GuardedChunk[], allowed?: readonly string[]): string[];
-/**
- * Throw when a built `--app gjs` bundle statically imports Node builtins.
- *
- * @param chunks   the emitted chunks, as reported by the bundler
- * @param outfile  path of the bundle, for the error message
- */
+/** Throw when a built `--app gjs` bundle statically imports Node builtins. */
 export declare function assertGjsBundleLoadable(chunks: readonly GuardedChunk[], outfile: string): void;

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

@@ -1,67 +1,50 @@
 // Build-time guard: a `--app gjs` bundle must not keep bare `node:` imports.
 //
-// Stock GJS has NO `node:` module loader. A single surviving
-// `import … from "node:fs"` makes it abort the ENTIRE module graph before one
-// line executes:
+// Stock GJS has NO `node:` module loader. A single surviving `import … from "node:fs"`
+// makes it abort the ENTIRE module graph before one line executes, with
+// "ImportError: Unsupported URI scheme for importing: node".
 //
-//   Gjs-WARNING **: JS ERROR: ImportError: Unsupported URI scheme for importing: node
-//   Gjs-CRITICAL **: Failed to resolve imports for module: '…/dist/cli.gjs.mjs'
+// `--app gjs` maps every Node builtin to its `@gjsify/*` polyfill, so a healthy bundle has
+// ZERO of them. But when an alias TARGET cannot be resolved — classically a workspace
+// checkout whose `@gjsify/*` packages have no built `lib/`, so `exports["."]` points at a
+// file that does not exist — the bundler falls back to external and re-emits the ORIGINAL
+// `node:*` specifier. That is a WARNING, not an error: the build "succeeds" and writes a
+// bundle that cannot load anywhere. It cost three red CI jobs to notice, because nothing
+// between `gjsify build` and CI ever executes the emitted GJS bundle (tsc, lint, format and
+// the unit/e2e suites all run the Node entry). The pre-commit hook makes it worse rather
+// than better: it rebuilds and AUTO-STAGES `dist/affected.gjs.mjs`, built through this same
+// `--app gjs` path, so a developer whose checkout cannot resolve the polyfills commits a
+// broken artifact without ever seeing it.
 //
-// `--app gjs` maps every Node builtin to its `@gjsify/*` polyfill, so a healthy
-// bundle has ZERO of them. But when an alias TARGET cannot be resolved — the
-// classic case being a workspace checkout whose `@gjsify/*` packages have no
-// built `lib/`, so `exports["."]` points at a file that does not exist — the
-// bundler falls back to treating the import as external and re-emits the
-// ORIGINAL `node:*` specifier. That is a WARNING, not an error: the build
-// "succeeds" and writes a bundle that cannot load anywhere. It cost three red
-// CI jobs to notice, because nothing between `gjsify build` and CI ever
-// executes the emitted GJS bundle (tsc, lint, format and the unit/e2e suites
-// all run the Node entry).
-//
-// The pre-commit hook makes it worse rather than better: it rebuilds and
-// AUTO-STAGES `dist/cli.gjs.mjs`, so a developer whose checkout cannot resolve
-// the polyfills commits a broken artifact without ever seeing it.
-//
-// So the refusal belongs at build time, in `gjsify build --app gjs` itself —
-// not in a git hook and not in one package's `build:gjs-bundle` script. The
-// invariant is a property of the ARTIFACT, and every showcase, every downstream
-// app (buchhaltung, bauplaner, Learn6502) and CI all produce it through this
-// one code path. A hook would protect only commits in this repo; a per-package
-// script would protect one package.
+// So the refusal belongs at build time, in `gjsify build --app gjs` itself — not in a git
+// hook and not in one package's `build:gjs-bundle` script. The invariant is a property of
+// the ARTIFACT, and every showcase, every downstream app (buchhaltung, bauplaner,
+// Learn6502) and CI all produce it through this one code path.
 //
 // ## The oracle is the module graph, NOT the emitted text
 //
-// The first cut of this guard grepped the output for `from "node:…"`. That is
-// wrong, and CI caught it: `@gjsify/process`'s own test bundle names a case
-//
-//   await it(`named-import hrtime (from "node:process") preserves .bigint`, …)
-//
-// so the phrase appears verbatim inside a STRING, in a bundle that loads and
-// runs under GJS perfectly well. The same trap sits in `@gjsify/cli`'s own
+// The first cut grepped the output for `from "node:…"`, and CI caught it:
+// `@gjsify/process`'s own test bundle names a case `named-import hrtime (from
+// "node:process") preserves .bigint`, so the phrase appears verbatim inside a STRING in a
+// bundle that runs under GJS perfectly well. The same trap sits in `@gjsify/cli`'s own
 // bundle, which embeds `giNodeShimSource()`'s `--app node` codegen template
-// (`import { createRequire } from 'node:module';`). Telling a statement from a
-// quoted lookalike needs a JS lexer — but the bundler already did that work:
-// every chunk carries the list of external specifiers it actually imports. That
-// list is exact, engine-independent (npm `rolldown` returns it directly,
-// `@gjsify/rolldown-native` forwards it through `synthRolldownOutput`), and
-// free.
+// (`import { createRequire } from 'node:module';`). Telling a statement from a quoted
+// lookalike needs a JS lexer — but the bundler already did that work: every chunk carries
+// the external specifiers it actually imports, exact and engine-independent (npm `rolldown`
+// returns it directly, `@gjsify/rolldown-native` forwards it via `synthRolldownOutput`).
 //
-// Scope is STATIC imports, which is precisely the failure mode above: they are
-// resolved when GJS links the module, so one bad specifier kills the whole
-// bundle. A dynamic `import('node:x')` throws lazily at its call site instead —
-// a real bug, but not "the artifact cannot load", and not what this gate is
-// for.
+// Scope is STATIC imports, which is the failure mode above: they are resolved when GJS
+// links the module, so one bad specifier kills the whole bundle. A dynamic
+// `import('node:x')` throws lazily at its call site — a real bug, but not "the artifact
+// cannot load", and not what this gate is for.
 /**
  * Bare `node:` specifiers a `--app gjs` bundle may keep as static imports.
  *
- * Deliberately EMPTY. Every Node builtin has an `@gjsify/*` polyfill that
- * `--app gjs` aliases to, so there is no specifier that both survives into the
- * module graph and loads under GJS. Reading the graph instead of the text is
- * what keeps this list empty — the entries an earlier text-scanning version
- * needed (`node:module`, `node:process`) were quoted lookalikes, never imports.
+ * Deliberately EMPTY: every Node builtin has an `@gjsify/*` polyfill that `--app gjs`
+ * aliases to, so no specifier both survives into the module graph and loads under GJS.
  *
- * Add an entry ONLY with a comment naming why GJS can resolve it. Each one is a
- * specifier this guard can no longer catch for real.
+ * Add an entry ONLY with a comment naming why GJS can resolve it. Each one is a specifier
+ * this guard can no longer catch for real.
  */
 export const GJS_ALLOWED_NODE_IMPORTS = [];
 /**
@@ -81,12 +64,7 @@ export function findDisallowedNodeImports(chunks, allowed = GJS_ALLOWED_NODE_IMP
     }
     return [...found].sort();
 }
-/**
- * Throw when a built `--app gjs` bundle statically imports Node builtins.
- *
- * @param chunks   the emitted chunks, as reported by the bundler
- * @param outfile  path of the bundle, for the error message
- */
+/** Throw when a built `--app gjs` bundle statically imports Node builtins. */
 export function assertGjsBundleLoadable(chunks, outfile) {
     const offenders = findDisallowedNodeImports(chunks);
     if (offenders.length === 0)

package/lib/utils/gjs-source-escape.d.ts

@@ -1,8 +1,8 @@
 /**
  * Replace every raw U+0000 in `code` with the `\x00` escape.
  *
- * Returns the rewritten code and how many were replaced, so the caller can skip
- * writing the file (and reporting) in the overwhelmingly common zero case.
+ * Reports how many were replaced so the caller can skip writing the file (and reporting)
+ * in the overwhelmingly common zero case.
  */
 export declare function escapeRawNulForGjs(code: string): {
     code: string;

package/lib/utils/gjs-source-escape.js

@@ -1,49 +1,31 @@
 // Build-time rewrite: a `--app gjs` bundle must not contain a raw U+0000 byte.
 //
-// GJS hands module source to SpiderMonkey as a NUL-TERMINATED C string, so a raw
-// U+0000 in the emitted file truncates it at that point. Everything after is
-// silently discarded and the error names whatever construct happened to be open
-// when the text ran out:
-//
-//   SyntaxError: `` literal not terminated before end of script
-//
-// which points at the wrong place entirely and never mentions a NUL.
-//
-// This is easy to hit and hard to diagnose. `'\u0000'` in TypeScript source is an
-// ESCAPE — six harmless ASCII characters — but the minifier is free to inline the
-// constant and emit the CHARACTER:
-//
-//   const P = '\u0000'; … return `${P}${i}${P}`   // source: escaped, loads fine
-//   … return`<NUL>${e}<NUL>`                      // minified: raw byte, will not load
-//
-// so the same code builds and runs unminified and breaks under `--minify`, which is
-// the default. A real consumer hit exactly this with an IMAP literal marker — NUL
-// being the one byte that cannot occur in IMAP response text is precisely why it
-// was chosen as the marker.
-//
-// Node and browsers load a raw NUL in source without complaint (U+0000 is a legal
-// source character per the spec), so no other target notices and nothing upstream
-// is going to change. Escaping it on the way out is gjsify's job.
-//
-// The rewrite is safe as a plain text substitution: in valid JS a raw NUL can only
-// appear inside a string, a template literal, a regex or a comment, and `\x00`
-// denotes exactly U+0000 in all four — so the meaning is preserved wherever it sits.
-//
-// `\x00` and NOT `\0`: `\0` followed by a digit is a legacy octal escape, which is a
-// SyntaxError in a template literal and under strict mode. A digit right after the
-// marker is exactly the shape that triggered this (`\0${index}\0`), so `\0` would
-// trade one unloadable bundle for another.
+// GJS hands module source to SpiderMonkey as a NUL-TERMINATED C string, so a raw U+0000
+// truncates the file there. Everything after is silently discarded and the error names
+// whatever construct happened to be open when the text ran out — "SyntaxError: `` literal
+// not terminated before end of script" — never the NUL.
+//
+// Easy to hit by accident: `'\u0000'` in TypeScript source is a six-character ESCAPE, but
+// the minifier may inline the constant and emit the CHARACTER, so the same code runs
+// unminified and breaks under `--minify` (the default). A consumer hit this with an IMAP
+// literal marker — NUL cannot occur in IMAP response text, which is why it was the marker.
+// Node and browsers load a raw NUL in source per spec, so no other target notices and
+// nothing upstream will change; escaping it on the way out is gjsify's job.
+//
+// Safe as a plain text substitution: in valid JS a raw NUL can only sit inside a string, a
+// template literal, a regex or a comment, and `\x00` denotes U+0000 in all four. NOT `\0`,
+// which is a legacy octal escape when followed by a digit — a SyntaxError in a template
+// literal and under strict mode, and `\0${index}\0` is exactly the shape that triggered it.
 /**
  * Replace every raw U+0000 in `code` with the `\x00` escape.
  *
- * Returns the rewritten code and how many were replaced, so the caller can skip
- * writing the file (and reporting) in the overwhelmingly common zero case.
+ * Reports how many were replaced so the caller can skip writing the file (and reporting)
+ * in the overwhelmingly common zero case.
  */
 export function escapeRawNulForGjs(code) {
-    // split/join rather than a regex: a NUL inside a regex is exactly what oxlint's
-    // `no-control-regex` exists to flag, and the rule is right in general even though this use
-    // is deliberate. Building the needle with fromCharCode also keeps THIS file free of the raw
-    // byte it exists to remove.
+    // split/join rather than a regex: a NUL inside a regex is what oxlint's `no-control-regex`
+    // exists to flag, and the rule is right in general even though this use is deliberate.
+    // fromCharCode also keeps THIS file free of the raw byte it exists to remove.
     const parts = code.split(String.fromCharCode(0));
     return { code: parts.join('\\x00'), replaced: parts.length - 1 };
 }

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

@@ -3,18 +3,18 @@
  * a self-shim rather than through the workspace's `node_modules/.bin/gjsify`.
  *
  * `detectPackageManager()` reads this: a bootstrap CLI must run package scripts
- * ITSELF, because npm re-prepends `node_modules/.bin` for every lifecycle
- * script it starts — which puts the tree's dead shim back ahead of the shim dir
- * this module placed on PATH, and undoes the whole repair one level down.
+ * ITSELF, because npm re-prepends `node_modules/.bin` for every lifecycle script it
+ * starts — putting the tree's dead shim back ahead of this module's shim dir and
+ * undoing the repair one level down.
  */
 export declare function usingSelfShim(): boolean;
 /**
- * Does this invocation need its own `gjsify` on PATH, rather than the
- * workspace's npm bin?
+ * Does this invocation need its own `gjsify` on PATH, rather than the workspace's
+ * npm bin?
  *
- * Pure, and takes the host facts as PARAMETERS rather than reading them
- * ambiently — the same shape `platform-check.ts` documents, and what lets the
- * Windows-relevant branch be tested from a Linux host.
+ * Host facts are PARAMETERS rather than read ambiently — the shape
+ * `platform-check.ts` documents, and what lets the Windows branch be tested from
+ * a Linux host.
  *
  * @param gjs           running under GJS (the npm bin is the Node entry there)
  * @param selfEntry     absolute path of the CLI entry currently executing
@@ -31,3 +31,21 @@ 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`).
+ * Prepending it globally breaks the CLI's ability to SEE a missing Node: `gjsify
+ * tsc`'s Node fallback spawns a real `node` for typescript's CJS entry, and
+ * `tests/e2e/tsc-node-fallback` asserts that on a PATH without one it fails loudly
+ * naming the missing interpreter — an assertion that exists because a silent exit
+ * 0 there once let `set-bin-mode.mjs` run against a `lib/index.js` tsc never wrote.
+ *
+ * The line the subdirectory draws: a PACKAGE SCRIPT saying `node x.mjs` means "run
+ * this script", which gjsify can serve; 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;