@gjsify/cli 0.29.0 → 0.31.0

package/lib/commands/install.js

@@ -31,7 +31,7 @@ import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, rmSync, syml
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
-import { gjsExit } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { forceExit } from '../utils/force-exit.js';
 import { discoverWorkspaces } from '@gjsify/workspace';
 import { buildInstallCommand, detectPackageManager, runMinimalChecks } from '../utils/check-system-deps.js';
 import { detectNativePackages } from '../utils/detect-native-packages.js';
@@ -42,7 +42,7 @@ import { acquireInstallLock } from '../utils/install-lock.js';
 import { nodeBinary } from '../utils/run-node.js';
 import { spawnToCompletion } from '../utils/spawn.js';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
-import { binDirOnPath, defaultGlobalLayout, installGjsEnginePackages, linkGlobalBins, specToPackageName, } from '../utils/install-global.js';
+import { binDirOnPath, BUNDLER_ENGINE_PACKAGE, defaultGlobalLayout, hasBundlerEngineInstalled, installGjsEnginePackages, linkGlobalBins, specToPackageName, } from '../utils/install-global.js';
 import { addDependencyEntry, defaultRangeFromVersion, parseSpec, projectSpecsFromPackageJson, readPackageJson, writePackageJson, } from '../utils/pkg-json-edit.js';
 /**
  * Link type for the workspace↔workspace directory links.
@@ -198,7 +198,7 @@ export const installCommand = {
         const backend = args.backend ?? process.env.GJSIFY_INSTALL_BACKEND ?? 'native';
         if (backend === 'npm') {
             await projectInstallViaNpm(args);
-            await runPostInstallChecks();
+            await runPostInstallChecks(args);
             return;
         }
         // Overall wall-clock budget for the install (default 30 min — big
@@ -263,7 +263,7 @@ export const installCommand = {
         hardExitTimerId?.unref?.();
         try {
             await projectInstallNative(args, overallController?.signal);
-            await runPostInstallChecks();
+            await runPostInstallChecks(args);
         }
         catch (err) {
             if (overallController !== null && overallController.signal.aborted && isAbortedFromOverallTimeout(err)) {
@@ -345,21 +345,6 @@ function isAbortedFromOverallTimeout(err) {
         return true;
     return false;
 }
-/**
- * Force a non-zero process exit that is honored on BOTH runtimes.
- *
- * Node exits at natural shutdown once `process.exitCode` is set, but GJS has
- * no atexit hook, so `imports.system.exit` is called directly there —
- * SpiderMonkey raises its uncatchable exit exception from any context,
- * including the `setTimeout` continuation the backstop timer runs in. Mirrors
- * the entry wrapper (`index.ts`) and `setOxcExitCode` (`oxc-resolve.ts`).
- */
-function forceExit(code) {
-    process.exitCode = code;
-    if (gjsExit(code))
-        return;
-    process.exit(code);
-}
 const CLI_PACKAGE_NAME = '@gjsify/cli';
 /** Read a `version` from a package.json IFF its `name` is `@gjsify/cli`. */
 function readCliVersionFrom(pkgJsonPath) {
@@ -1419,7 +1404,33 @@ function reportLinkedBins(created, binDir) {
             `Add it to your shell rc file:\n  export PATH="${binDir}:$PATH"`);
     }
 }
-async function runPostInstallChecks() {
+export async function ensureProjectGjsEngine(args, gjsFound, deps = {}) {
+    const cwd = deps.cwd ?? process.cwd();
+    const hasEngine = deps.hasEngineFn ?? hasBundlerEngineInstalled;
+    if (!existsSync(join(cwd, 'node_modules', '@gjsify', 'cli', 'package.json')))
+        return;
+    if (!gjsFound)
+        return;
+    if (hasEngine(cwd))
+        return;
+    if (args.immutable) {
+        // Name the DURABLE fix, not a transient one: a frozen CI install cannot
+        // be repaired by anything that happens at this moment, so the answer is
+        // to put the engine in the lockfile.
+        console.warn(`\nWarning: \`gjsify build\` will fail under GJS — ${BUNDLER_ENGINE_PACKAGE} is not installed, and\n` +
+            '  --immutable cannot add it (the lockfile does not name it). Declare it so the lockfile carries it:\n' +
+            `    gjsify install ${BUNDLER_ENGINE_PACKAGE}\n` +
+            '  Under Node the npm `rolldown` engine is used instead and this does not apply.');
+        return;
+    }
+    const cliVersion = readCliVersionFrom(join(cwd, 'node_modules', '@gjsify', 'cli', 'package.json')) ?? 'latest';
+    console.log(`\n${BUNDLER_ENGINE_PACKAGE} is missing and this host can run gjs, so \`gjsify build\` would have no\n` +
+        `  bundler engine (there is no npm \`rolldown\` fallback under GJS). Installing the GJS engine set at\n` +
+        `  ${cliVersion}, in lockstep with the CLI.`);
+    const install = deps.installFn ?? installGjsEnginePackages;
+    await install(cwd, cliVersion, { verbose: args.verbose });
+}
+async function runPostInstallChecks(args) {
     console.log('\n--- gjsify post-install checks ---');
     // 1. System deps that GJS apps typically need.
     const results = runMinimalChecks();
@@ -1437,8 +1448,14 @@ async function runPostInstallChecks() {
     else {
         console.log('System dependencies OK.');
     }
-    // 2. Surface @gjsify/* packages with native prebuilds — `gjsify run`
+    // 2. Close #1005 before reporting the prebuild set, so the report reflects
+    //    what the tree ACTUALLY has rather than what it had a moment ago.
+    await ensureProjectGjsEngine(args, results.find((r) => r.id === 'gjs')?.found ?? false);
+    // 3. Surface @gjsify/* packages with native prebuilds — `gjsify run`
     //    will set LD_LIBRARY_PATH / GI_TYPELIB_PATH for these automatically.
+    //    Runs AFTER step 2 on purpose: an engine installed a moment ago belongs
+    //    in this list, and a consumer reading "Detected N …" needs it to be the
+    //    tree's current state rather than its state on entry.
     const native = detectNativePackages(process.cwd());
     if (native.length > 0) {
         console.log(`\nDetected ${native.length} @gjsify/* package(s) with native prebuilds:`);

package/lib/commands/run.js

@@ -296,12 +296,15 @@ async function runScript(script, extraArgs, cwd = process.cwd()) {
     if (monorepoRoot && monorepoRoot !== cwd) {
         binDirs.push(join(monorepoRoot, 'node_modules', '.bin'));
     }
-    // Under GJS, the GJS-runnable `gjsify` shim (see `ensureGjsifyShimOnPath`)
-    // MUST shadow the workspace `node_modules/.bin/gjsify`, which is the Node
-    // entry and unusable in a node-free sandbox. So put the shim dir ahead of
-    // the `.bin` dirs in the child's PATH — otherwise a compound script like
-    // `gjsify run a && gjsify run b` resolves `gjsify` to the Node bin and
-    // fails. `GJSIFY_SHIM_DIR` is only set under GJS, so this is a no-op on Node.
+    // The self-shim (see `ensureGjsifyShimOnPath`) MUST shadow the workspace
+    // `node_modules/.bin/gjsify`, so put its dir ahead of the `.bin` dirs in the
+    // child's PATH — otherwise a compound script like `gjsify run a && gjsify
+    // run b` resolves `gjsify` to the workspace bin. Two trees need that:
+    // under GJS the bin is the Node entry and is unusable in a node-free
+    // sandbox, and under a BOOTSTRAP Node CLI (npx / global install) the bin
+    // dispatches to build outputs that a cold tree has not produced yet.
+    // `GJSIFY_SHIM_DIR` is unset whenever the tree's own CLI is the one
+    // running, which keeps that case byte-for-byte unchanged.
     if (process.env.GJSIFY_SHIM_DIR) {
         binDirs.unshift(process.env.GJSIFY_SHIM_DIR);
     }
@@ -342,6 +345,22 @@ async function runScript(script, extraArgs, cwd = process.cwd()) {
         process.env.npm_package_version = env.npm_package_version;
         if (env.FORCE_COLOR !== undefined)
             process.env.FORCE_COLOR = env.FORCE_COLOR;
+        // …and the working directory, for the same reason. The spawn path below
+        // passes `cwd` to `spawn()`; this path used to pass it nowhere, so a
+        // `gjsify run -w <ws> <script>` resolved the WORKSPACE and then ran the
+        // command in the CALLER's directory. Every relative path in the script
+        // — `src/app/main.ts`, `dist/…`, `tests/test.mts` — then resolved
+        // against the monorepo root.
+        //
+        // Only this branch was affected, which is why it survived: the fast path
+        // fires exactly when the script is a SINGLE `gjsify <subcommand>`, so a
+        // compound script (`a && b`) took the shell path and worked. Measured on
+        // the two consumers: bauplaner's cli scripts are all single commands and
+        // it documents the gap in its AGENTS.md, sidestepping it with
+        // `cd cli && …`; buchhaltung's one `-w` use is `build:meson`, a compound
+        // command, and it works.
+        if (cwd !== process.cwd())
+            process.chdir(cwd);
         // Track the failure LOCALLY rather than through `process.exitCode`.
         // Under GJS `process.exit()` is deferred (see the note below), so the
         // `process.exit(1)` that used to live in the catch returned instead of

package/lib/commands/test.js

@@ -194,10 +194,10 @@ async function runTestBundle(outfile, runtime) {
         return;
     }
     await new Promise((resolvePromise, reject) => {
-        // `nodeBinary()`, never a bare `'node'`: under the committed GJS bundle
-        // `process.execPath` is the bundle itself, and on a host without Node a
-        // bare literal dies `spawn node ENOENT` — which is how a fully passing
-        // GJS suite was reported as a failed run.
+        // `nodeBinary()`, never a bare `'node'`: under GJS `process.execPath` is
+        // the `gjs` interpreter, which cannot run a `--app node` bundle, and on a
+        // host without Node a bare literal dies `spawn node ENOENT` — which is
+        // how a fully passing GJS suite was reported as a failed run.
         const child = spawn(nodeBinary(), [outfile], { stdio: 'inherit' });
         child.on('error', reject);
         child.on('exit', (code) => {

package/lib/commands/tsc.js

@@ -22,6 +22,10 @@ import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { detectNativePackages, buildNativeEnv } from '../utils/detect-native-packages.js';
+import { isOnPath } from '../utils/check-system-deps.js';
+import { existsSync } from 'node:fs';
+import { forceExit } from '../utils/force-exit.js';
+import { nodeBinary } from '../utils/run-node.js';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
 export const tscCommand = {
     command: 'tsc [tscArgs..]',
@@ -104,9 +108,12 @@ export const tscCommand = {
         if (!bundlePath && !nodeTscPath) {
             console.error('gjsify tsc: neither @gjsify/tsc (GJS bundle) nor npm `typescript` (Node) is installed.');
             console.error('  Install with: gjsify install --save-dev @gjsify/tsc   (or add `typescript`).');
-            // `return` — a bare `process.exit()` is deferred under GJS and the
-            // handler would try to spawn a compiler that is not there.
-            return process.exit(1);
+            // `return` — the handler must not fall through and try to spawn a
+            // compiler that is not there. `forceExit` and not `process.exit`
+            // because the latter is idle-scheduled under GJS, and NOTHING here
+            // armed a main loop to deliver it: the process would reach natural
+            // shutdown and report 0 while printing the message above.
+            return forceExit(1);
         }
         // Mirror `gjsify run`'s native-env composition so any future
         // typescript-the-bundle code path that reaches a native bridge
@@ -118,13 +125,54 @@ export const tscCommand = {
             ...process.env,
             ...nativeEnv,
         };
-        // Run upstream `typescript` under this Node — the Node-only fallback.
+        // Run upstream `typescript` under Node — the Node fallback.
+        //
+        // `nodeBinary()`, NEVER a bare `process.execPath`: under the GJS bundle
+        // `process.execPath` is the GJS interpreter (`/proc/self/exe` →
+        // `gjs-console`), so `spawn(process.execPath, [tsc.js])` hands
+        // TypeScript's CommonJS CLI to GJS, which dies on the first `module`
+        // reference — or, where execPath resolves to a gjsify launcher instead,
+        // re-executes the CLI with the tsc entry as an unknown argument. Both
+        // were reached from a COLD tree: `@gjsify/tsc`'s `dist/tsc.gjs.mjs` is a
+        // build output, and `build:infra` builds `@gjsify/create-app` (its first
+        // `gjsify tsc` caller) long before `@gjsify/tsc` produces it, so the
+        // fallback below is the NORMAL path there, not an edge case.
+        // `run-node.ts` owns the one correct answer; every other spawn site in
+        // this CLI already routes through it.
         const runNodeTsc = () => {
-            const child = spawn(process.execPath, [nodeTscPath, ...tscArgs], { env, stdio: 'inherit' });
-            child.on('close', (code) => process.exit(code ?? 1));
+            const nodeBin = nodeBinary();
+            // PRE-FLIGHT, deliberately NOT the spawn's `'error'` event.
+            //
+            // Under the GJS bundle that event is not delivered when the program
+            // is missing: the handler below never runs, the command returns
+            // normally, and `gjsify tsc` exits **0 in total silence** having
+            // compiled nothing. Measured in CI by `tests/e2e/tsc-node-fallback`'s
+            // "FAILS LOUDLY …" case, whose assertion printed an EMPTY captured
+            // output — no stderr at all, so nothing had reported anything.
+            //
+            // Deciding it here, synchronously, is what makes the failure
+            // reportable: the exit happens on the caller's own stack rather than
+            // in a continuation that may never be scheduled.
+            const runnable = nodeBin.includes('/') || nodeBin.includes('\\') ? existsSync(nodeBin) : isOnPath(nodeBin);
+            if (!runnable) {
+                console.error(`gjsify tsc: the @gjsify/tsc GJS bundle is unavailable and \`${nodeBin}\` cannot be run, ` +
+                    'so upstream `typescript` cannot run either.');
+                console.error('  Build the bundle with: gjsify workspace @gjsify/tsc build');
+                console.error('  …or install Node.js so the upstream `typescript` fallback can be spawned.');
+                return forceExit(1);
+            }
+            const child = spawn(nodeBin, [nodeTscPath, ...tscArgs], { env, stdio: 'inherit' });
+            child.on('close', (code) => forceExit(code ?? 1));
             child.on('error', (err) => {
-                console.error(`gjsify tsc (node typescript): ${err.message}`);
-                process.exit(1);
+                if (err.code === 'ENOENT') {
+                    console.error('gjsify tsc: the @gjsify/tsc GJS bundle is unavailable and `node` is not on PATH, ' +
+                        'so upstream `typescript` cannot run either.');
+                    console.error('  Build the bundle with: gjsify workspace @gjsify/tsc build');
+                }
+                else {
+                    console.error(`gjsify tsc (node typescript): ${err.message}`);
+                }
+                forceExit(1);
             });
         };
         // Prefer GJS — the Node-free @gjsify/tsc bundle — when it resolves. If
@@ -144,7 +192,7 @@ export const tscCommand = {
                 child.on('close', (code) => {
                     if (gjsSpawnFailed)
                         return;
-                    process.exit(code ?? 1);
+                    forceExit(code ?? 1);
                 });
                 child.on('error', (err) => {
                     gjsSpawnFailed = true;
@@ -155,11 +203,11 @@ export const tscCommand = {
                     else if (err.code === 'ENOENT') {
                         console.error('gjsify tsc: `gjs` not found on PATH and no npm `typescript` fallback.');
                         console.error('  Install GJS (e.g. `dnf install gjs`), or add `typescript` to the project.');
-                        process.exit(1);
+                        forceExit(1);
                     }
                     else {
                         console.error(`gjsify tsc: ${err.message}`);
-                        process.exit(1);
+                        forceExit(1);
                     }
                 });
                 // Never resolves naturally — process.exit() above terminates the

package/lib/commands/workspace.js

@@ -24,6 +24,7 @@ import { buildDependencyGraph, discoverWorkspaces, topologicalSort } from '@gjsi
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
 import { BuildCacheRunner, buildCacheEnabledByEnv } from '../utils/build-cache.js';
 import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { usingSelfShim } from '../utils/gjsify-shim.js';
 import { suggestClosest } from '../utils/suggest.js';
 export const workspaceCommand = {
     command: 'workspace <name> <script> [args..]',
@@ -279,6 +280,18 @@ export function detectPackageManager() {
     // orchestration work in the Flatpak sandbox.
     if (isGjs())
         return 'gjsify';
+    // Same answer for a BOOTSTRAP CLI on Node, for a reason one level deeper
+    // than it looks. `ensureGjsifyShimOnPath()` puts a working `gjsify` ahead of
+    // the tree's `node_modules/.bin` — but npm RE-PREPENDS `node_modules/.bin`
+    // for every lifecycle script it starts, so delegating to npm here restores
+    // the tree's not-yet-built shim one level down and undoes the repair.
+    // Measured on a cold tree: `run build:infra` cleared its first clause and
+    // then died inside `npm run build` with `Cannot find module
+    // …/packages/infra/cli/lib/index.js`. Running the script ourselves keeps the
+    // bootstrap CLI's identity all the way down — which is exactly what the GJS
+    // branch above already relies on, and why Linux CI never saw this.
+    if (usingSelfShim())
+        return 'gjsify';
     const ua = process.env.npm_config_user_agent ?? '';
     if (ua.startsWith('yarn/'))
         return 'yarn';

package/lib/config.js

@@ -223,8 +223,12 @@ export class Config {
         const pkg = (await this.readPackageJSON(configFilePath));
         const tsConfig = (await this.readTSConfig(configFilePath));
         tsConfig.reflection ||= cliArgs.reflection;
-        // TODO replace with `cliArgs.logLevel`
-        configData.verbose = cliArgs.verbose || false;
+        // `--verbose` and `--log-level` are two spellings of one question, and
+        // only the boolean reached here — so `--log-level debug` turned the
+        // BUNDLER's logging up (see the mapping further down, which sets
+        // `bundler.logLevel`) while the CLI's own verbose output stayed off.
+        // Either spelling now answers it; neither silences the other.
+        configData.verbose = cliArgs.verbose || cliArgs.logLevel === 'debug' || cliArgs.logLevel === 'verbose';
         configData.exclude = cliArgs.exclude || [];
         if (cliArgs.consoleShim !== undefined)
             configData.consoleShim = cliArgs.consoleShim;

package/lib/index.js

@@ -17,7 +17,24 @@ catch (err) {
     // a scary `Gjs-CRITICAL **: Module … threw an exception` that buries the
     // real, already-actionable message (e.g. "gjsify build: no usable bundler
     // engine under GJS — build the facade first or run under Node"). See #597.
-    console.error(err instanceof Error ? err.message : String(err));
+    //
+    // The `code` is printed WITH the message, not dropped. Errors in this CLI
+    // carry npm's own codes on purpose — `badPlatformError()` documents that it
+    // reproduces npm's `EBADPLATFORM` payload "so a consumer's error handling
+    // (and a human reading the message) sees what npm reports" — and npm itself
+    // prints the code (`npm ERR! code EBADPLATFORM`) rather than only the prose.
+    //
+    // It has to be explicit here because this catch became the SINGLE printer:
+    // before the `.fail()` handler in `cli-app.ts`, yargs logged the error OBJECT
+    // and the code came along for free. Printing `err.message` alone silently
+    // dropped it for every coded error, which is what turned
+    // `tests/e2e/install-optional-both-blocks` red on `main` — it asserts the
+    // code is visible, and the prose it still printed did not contain it.
+    const code = typeof err === 'object' && err !== null && typeof err.code === 'string'
+        ? err.code
+        : '';
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(code && !message.includes(code) ? `${code}: ${message}` : message);
     if (process.env.GJSIFY_DEBUG && err instanceof Error && err.stack)
         console.error(err.stack);
     // `process.exitCode` is the gentle Node idiom (streams flush). GJS has no

package/lib/templates/install.mjs.tmpl

@@ -58,8 +58,18 @@ const USER_AGENT = 'gjsify-installer/1.0';
 const CACHE_PREFIX = 'cli-';
 const CACHE_SUFFIX = '.gjs.mjs';
 
+/**
+ * Under `--fetch-only` the ONLY thing on stdout must be the bundle path, so
+ * progress goes to stderr instead. A caller does
+ * `BOOTSTRAP=$(gjs -m install.mjs --fetch-only)`, and one stray `info()` line
+ * would make that a path with a log message glued to the front — a failure that
+ * surfaces as a confusing "file not found" rather than as bad output.
+ */
+let logToStderr = false;
+
 function info(msg) {
-    print(`[gjsify] ${msg}`);
+    if (logToStderr) printerr(`[gjsify] ${msg}`);
+    else print(`[gjsify] ${msg}`);
 }
 function error(msg) {
     printerr(`[gjsify] ERROR: ${msg}`);
@@ -71,6 +81,7 @@ function parseArgs() {
     let tag = 'latest';
     let force = false;
     let help = false;
+    let fetchOnly = false;
     let bootstrapUrl = GLib.getenv('GJSIFY_INSTALL_BOOTSTRAP_URL') || DEFAULT_BOOTSTRAP_URL;
     let bootstrapSha256Url = GLib.getenv('GJSIFY_INSTALL_BOOTSTRAP_SHA256_URL');
     if (bootstrapSha256Url === null || bootstrapSha256Url === undefined) {
@@ -87,8 +98,9 @@ function parseArgs() {
         else if (a.startsWith('--tag=')) tag = a.slice('--tag='.length);
         else if (a === '--bootstrap-url') bootstrapUrl = argv[++i];
         else if (a.startsWith('--bootstrap-url=')) bootstrapUrl = a.slice('--bootstrap-url='.length);
+        else if (a === '--fetch-only') fetchOnly = true;
     }
-    return { target, tag, force, help, bootstrapUrl, bootstrapSha256Url };
+    return { target, tag, force, help, bootstrapUrl, bootstrapSha256Url, fetchOnly };
 }
 
 function printUsage() {
@@ -102,6 +114,10 @@ Options:
   --tag <tag>        npm dist-tag or version  (default: latest)
   --force, -f        Reinstall even when present.
   --bootstrap-url <url>  Override the cli.gjs.mjs download URL.
+  --fetch-only       Download + verify the bootstrap bundle, print its cached
+                     path to stdout and exit — no install. Lets a caller (CI)
+                     reuse this downloader instead of growing a second one
+                     beside it; progress goes to stderr so stdout is the path.
   --help, -h         Show this message.
 
 Env vars:
@@ -318,6 +334,9 @@ async function main() {
         printUsage();
         exit(0);
     }
+    // Set BEFORE the first `info()` — resolveBootstrap logs while downloading,
+    // and those lines would otherwise land on stdout ahead of the path.
+    logToStderr = opts.fetchOnly;
     checkGjsVersion();
 
     const session = new Soup.Session();
@@ -329,6 +348,12 @@ async function main() {
         exit(1);
     }
 
+    if (opts.fetchOnly) {
+        // The one thing on stdout. Everything above went to stderr.
+        print(bundlePath);
+        exit(0);
+    }
+
     const spec = buildSpec(opts.target, opts.tag);
     try {
         await runInstall(bundlePath, spec);

package/lib/types/command.d.ts

@@ -7,3 +7,21 @@ export interface Command<T = unknown, U = T> {
     middlewares?: MiddlewareFunction[];
     deprecated?: boolean | string;
 }
+/**
+ * A command that definitely runs something — the shape of every command except
+ * the builder-only parents.
+ *
+ * WHY IT EXISTS: `Command.handler` has to stay optional for parent commands,
+ * but that optionality then lands on every CALL site, including the ones
+ * outside `cli-app.ts`'s yargs registration where a missing handler would be a
+ * silent no-op rather than a type error. `src/affected-entry.ts` — the entry
+ * the committed `dist/affected.gjs.mjs` is built from — invoked
+ * `affectedCommand.handler(...)` through a cast that suppressed exactly that,
+ * and nothing noticed for as long as the package's tsconfig scoped the compile
+ * to the import closure of `src/index.ts`. Annotate a command that a standalone
+ * entry invokes directly with this type, and the guarantee is in the type
+ * instead of in a cast.
+ */
+export type LeafCommand<T = unknown, U = T> = Command<T, U> & {
+    handler: NonNullable<Command<T, U>['handler']>;
+};

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

@@ -61,6 +61,17 @@ export declare function buildLauncherShims(opts: {
      * path the prebuilds have to be reachable through.
      */
     prependEnv?: Readonly<Record<string, string>>;
+    /**
+     * Second interpreter + script to run when the primary interpreter is not on
+     * `PATH`. The batch/PowerShell counterpart of {@link buildShLauncher}'s
+     * `nodeFallbackAbs` — a Windows host with no `gjs` is the majority case, and
+     * the `.cmd`/`.ps1` members are the ones cmd.exe and pwsh actually reach.
+     */
+    fallback?: {
+        interpreter: string;
+        interpreterArgs?: readonly string[];
+        target: string;
+    };
 }): {
     cmd: string;
     ps1: string;
@@ -182,6 +193,26 @@ export declare function normalizeBinMap(pkgName: string, bin: string | Record<st
  *
  * `isGjsBin` lets the caller keep plain-Node packages on the plain symlink path
  * — this must not change how `lodash`'s bin is linked.
+ *
+ * WHY THE npm MAP COMES BACK TOO
+ *
+ * The reasoning above is sound and INCOMPLETE: it was written from the Node-less
+ * GJS host and is blind to the mirror case. `@gjsify/cli` declares BOTH fields,
+ * so a host with no `gjs` — macOS and Windows, the two active port targets —
+ * got `exec gjs -m <bundle>`, which is exit 127, while a working Node entry sat
+ * beside it in the same package. `cli-cross-platform.yml` recorded that on both
+ * OSes for three consecutive releases (v0.27.1, v0.28.0, v0.29.0); it is
+ * advisory, so it stayed red. The install even KNEW: its own post-install check
+ * printed `Missing required system dependencies: ✗ GJS` and then wrote a
+ * gjs-only launcher anyway.
+ *
+ * So `nodeFallback` carries the npm map alongside, and the LAUNCHER decides per
+ * invocation. Deliberately not an install-time host probe: an install-time
+ * decision is a SNAPSHOT, and this repo has already paid for that exact mistake
+ * once — `buildNativeEnvPreamble` used to bake the install-time prebuild scan,
+ * so a package installed later was invisible and v0.24.1 shipped a launcher with
+ * no preamble at all. A host probe here fails the same way in reverse: install
+ * without gjs, install gjs afterwards, shim still points at Node forever.
  */
 export declare function pickBinMap(pkgName: string, pkgJson: {
     bin?: string | Record<string, string>;
@@ -191,6 +222,7 @@ export declare function pickBinMap(pkgName: string, pkgJson: {
 }): {
     map: Map<string, string>;
     isGjsBin: boolean;
+    nodeFallback: Map<string, string> | null;
 } | null;
 /**
  * The POSIX `sh` launcher gjsify writes for a bin it owns.
@@ -205,10 +237,17 @@ export declare function pickBinMap(pkgName: string, pkgJson: {
  * because not every published bundle carries a `#!/usr/bin/env -S gjs -m` line,
  * and direct-exec'ing a shebang-less `.mjs` falls through to `/bin/sh`, which
  * then parses JavaScript as shell.
+ *
+ * `nodeFallbackAbs` makes the runtime choice per INVOCATION rather than per
+ * install — see {@link pickBinMap} for why a host probe at install time is the
+ * wrong shape. `gjs` stays first: that is today's behaviour on a host carrying
+ * both, and which runtime wins is a separate decision from making the shim
+ * runnable at all.
  */
 export declare function buildShLauncher(targetAbs: string, opts: {
     envPreamble?: string;
     isGjsBundle: boolean;
+    nodeFallbackAbs?: string;
 }): string;
 /** True when a bin target is a GJS-runnable bundle rather than a Node script. */
 export declare function isGjsBundlePath(target: string): boolean;