@gjsify/cli 0.29.0 → 0.31.0

package/lib/utils/dlx-cache.js

@@ -6,7 +6,7 @@
 //   - prepare into a fresh temp dir, then atomically swap a `pkg` symlink
 //   - TTL via lstat mtime + maxAgeMinutes (default 7 days)
 import { createHash } from 'node:crypto';
-import { lstatSync, mkdirSync, realpathSync, renameSync, rmSync } from 'node:fs';
+import { lstatSync, mkdirSync, readdirSync, realpathSync, renameSync, rmSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { dirLinksAreJunctions, linkDirSync } from './dir-link.js';
@@ -36,6 +36,12 @@ export function cacheDirFor(cacheKey) {
     mkdirSync(dir, { recursive: true });
     return dir;
 }
+/**
+ * The exact shape {@link makePrepareDir} produces — two lowercase-hex fields.
+ * {@link cleanupStalePrepareDirs} deletes ONLY names matching this, so the
+ * two must move together.
+ */
+const PREPARE_DIR_NAME = /^[0-9a-f]+-[0-9a-f]+$/;
 /** A fresh prepare directory under the per-key cache, named timestamp-pid. */
 export function makePrepareDir(cacheDir) {
     const name = `${Date.now().toString(16)}-${process.pid.toString(16)}`;
@@ -156,11 +162,61 @@ export function symlinkSwap(cacheDir, prepareDir, opts = {}) {
     }
     return realpathSync(linkPath);
 }
-/** Clean up `<cacheDir>/<oldPrepareDir>` siblings older than `maxAgeMinutes`. */
-export function cleanupStalePrepareDirs(cacheDir, _maxAgeMinutes = DEFAULT_TTL_MIN) {
-    // Out of scope for Phase 1 — pnpm has the same TODO. Leaving a stub so
-    // call sites already exist when we do implement it.
-    void cacheDir;
+/**
+ * Remove `<cacheDir>/<oldPrepareDir>` siblings older than `maxAgeMinutes`.
+ *
+ * Every `gjsify dlx` miss creates a fresh prepare dir and swaps the `pkg` link
+ * onto it; the previous one is then unreferenced and stayed on disk forever,
+ * because this function accepted a TTL and did nothing with it. A full npm tree
+ * per miss makes that the largest thing gjsify writes to a user's cache.
+ *
+ * Three rules keep it from deleting something it should not:
+ *
+ *   1. **Only names `makePrepareDir` could have produced** (`<hex>-<hex>`). The
+ *      cache dir also holds `pkg` and, briefly, `pkg.tmp-<ts>-<pid>` links from
+ *      a concurrent swap — and a name-shape guard is what makes "delete the
+ *      rest" safe against anything a future version puts here.
+ *   2. **Never the LIVE target**, whatever its age. A long-lived cache entry
+ *      that is still current is exactly the one worth keeping, and it ages past
+ *      any TTL while being used on every run.
+ *   3. **Never throws.** This is housekeeping on a best-effort path: a losing
+ *      race (a parallel dlx removing the same dir) or a read-only cache must not
+ *      fail the command the user actually ran.
+ */
+export function cleanupStalePrepareDirs(cacheDir, maxAgeMinutes = DEFAULT_TTL_MIN) {
+    const cutoff = Date.now() - maxAgeMinutes * ONE_MINUTE_MS;
+    // The live target, resolved once. An unreadable or absent `pkg` link simply
+    // means nothing is live yet — every prepare dir is then a candidate.
+    let live;
+    try {
+        live = realpathSync(join(cacheDir, 'pkg'));
+    }
+    catch {
+        live = undefined;
+    }
+    let entries;
+    try {
+        entries = readdirSync(cacheDir);
+    }
+    catch {
+        return;
+    }
+    for (const name of entries) {
+        if (!PREPARE_DIR_NAME.test(name))
+            continue;
+        const dir = join(cacheDir, name);
+        try {
+            if (live !== undefined && realpathSync(dir) === live)
+                continue;
+            if (lstatSync(dir).mtimeMs >= cutoff)
+                continue;
+            rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+        }
+        catch {
+            // Lost a race with another dlx, or the entry vanished between the
+            // readdir and the stat. Both mean "someone else handled it".
+        }
+    }
 }
 /** Resolve absolute path to the installed package's directory inside cache. */
 export function resolveInstalledPkgDir(cachedRoot, pkgName) {

package/lib/utils/force-exit.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 declare function forceExit(code: number): never;

package/lib/utils/force-exit.js

@@ -0,0 +1,43 @@
+// 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.
+//
+// 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
+// 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.
+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) {
+    process.exitCode = code;
+    // Under GJS this does not return — `imports.system.exit` unwinds via
+    // SpiderMonkey's uncatchable exit exception.
+    if (gjsExit(code))
+        return undefined;
+    return process.exit(code);
+}

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

@@ -0,0 +1,36 @@
+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`.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * @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".
+ */
+export declare function activateNativePrebuilds(): readonly NativePackage[];

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

@@ -0,0 +1,146 @@
+// 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:
+//
+//   neither var       "Typelib file for namespace 'GjsifyRolldown' (any
+//                      version) not found"
+//   GI_TYPELIB_PATH   "Failed to load shared library 'libgjsifyrolldown.so'
+//     only             referenced by the typelib" — reaching JS as the nameless
+//                      "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
+// proves, since girepository's own library path starts empty and no environment
+// variable seeds it.
+//
+// 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.
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+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.
+ *
+ * `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.
+ */
+function defaultRepository() {
+    const gi = globalThis.imports?.gi;
+    const repository = gi?.GIRepository?.Repository;
+    if (typeof repository?.dup_default !== 'function')
+        return null;
+    return repository.dup_default();
+}
+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`.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * @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".
+ */
+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.
+    activated = [];
+    try {
+        const repository = defaultRepository();
+        if (!repository)
+            return activated;
+        const cwdPackages = detectNativePackages(process.cwd());
+        const seen = new Set(cwdPackages.map((p) => p.name));
+        const selfPackages = detectNativePackages(dirname(fileURLToPath(import.meta.url)));
+        const packages = [...cwdPackages, ...selfPackages.filter((p) => !seen.has(p.name))];
+        for (const pkg of packages) {
+            repository.prepend_search_path(pkg.prebuildsDir);
+            repository.prepend_library_path(pkg.prebuildsDir);
+        }
+        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
+        //      `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).
+        //
+        // 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.
+    }
+    return activated;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+export declare function escapeRawNulForGjs(code: string): {
+    code: string;
+    replaced: number;
+};

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

@@ -0,0 +1,49 @@
+// 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.
+/**
+ * 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.
+ */
+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.
+    const parts = code.split(String.fromCharCode(0));
+    return { code: parts.join('\\x00'), replaced: parts.length - 1 };
+}

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

@@ -1,6 +1,33 @@
 /**
- * Ensure a GJS-runnable `gjsify` is on `process.env.PATH` for child processes.
+ * True when nested `gjsify` calls in this process tree are being routed through
+ * 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.
+ */
+export declare function usingSelfShim(): boolean;
+/**
+ * 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.
+ *
+ * @param gjs           running under GJS (the npm bin is the Node entry there)
+ * @param selfEntry     absolute path of the CLI entry currently executing
+ * @param workspaceRoot absolute path of the workspace the command will act on
+ */
+export declare function needsSelfShim(opts: {
+    gjs: boolean;
+    selfEntry: string;
+    workspaceRoot: string;
+}): boolean;
+/**
+ * Ensure a runnable `gjsify` is on `process.env.PATH` for child processes.
  * Idempotent per process; children inherit the shim via `GJSIFY_SHIM_DIR` and
- * reuse it instead of creating their own. No-op when not running under GJS.
+ * reuse it instead of creating their own.
  */
 export declare function ensureGjsifyShimOnPath(): void;

package/lib/utils/gjsify-shim.js

@@ -1,52 +1,161 @@
-// Node-free orchestration: a GJS-runnable `gjsify` on PATH.
+// A runnable `gjsify` on PATH, for the two trees where the npm bin is not one.
 //
-// The CLI's npm `bin` (`node_modules/.bin/gjsify`) is the NODE entry — useless
-// in a node-free environment (the Flatpak sandbox has no Node). But multi-
-// package orchestration and compound package scripts resolve `gjsify` from
-// PATH and would hit that Node bin:
+// The CLI's npm bin (`node_modules/.bin/gjsify`) is a DISPATCHER written at
+// install time: it prefers `packages/infra/cli/dist/cli.gjs.mjs` on a host that
+// has `gjs`, and otherwise execs the Node entry `packages/infra/cli/lib/index.js`.
+// Multi-package orchestration and compound package scripts resolve `gjsify`
+// from PATH and go through it:
 //   - `gjsify workspace`/`foreach` spawn `<pm> run <script>` per package; under
 //     GJS the package manager is `gjsify` itself, and `spawn('gjsify', …)`
 //     searches PATH.
 //   - a compound script like `gjsify run a && gjsify run b` is executed via
-//     `/bin/sh -c …`, and the shell resolves each `gjsify` from PATH.
-// Both fail without Node (`spawn npm ENOENT`, `gjsify: not found`).
+//     `/bin/sh -c …` (or `%COMSPEC% /c …`), and the shell resolves each
+//     `gjsify` from PATH.
 //
-// Fix: under GJS, write a tiny wrapper that re-invokes the running GJS bundle
-// under `gjs -m`, and prepend its directory to `process.env.PATH` so every
-// child process (and grandchild, via the inherited `GJSIFY_SHIM_DIR` marker)
-// resolves `gjsify` to a GJS-runnable executable. No-op on Node.
+// Fix: write a tiny wrapper that re-invokes the RUNNING CLI, and prepend its
+// directory to `process.env.PATH` so every child process (and grandchild, via
+// the inherited `GJSIFY_SHIM_DIR` marker) resolves `gjsify` to a CLI that
+// actually exists.
+//
+// TWO HOSTS NEED IT, FOR TWO DIFFERENT REASONS
+//
+// GJS — always. The npm bin is the NODE entry and is useless in a node-free
+// environment (the Flatpak sandbox has no Node): without the shim the failures
+// are `spawn npm ENOENT` and `gjsify: not found`.
+//
+// Node — only when the running CLI came from OUTSIDE the workspace, which is
+// exactly the cold-tree bootstrap (`npx @gjsify/cli@latest …`, or a global
+// install). ADR 0002 untracked BOTH bundles, so on a tree that is installed but
+// not yet built, `node_modules/.bin/gjsify` exists and everything it dispatches
+// to is missing. The bin shim is then a live landmine: it resolves, and then
+// dies with `Cannot find module …/packages/infra/cli/lib/index.js` on the FIRST
+// nested `gjsify` — which for `gjsify run build:infra` is its first clause,
+// `gjsify workspace @gjsify/vite-plugin-blueprint build`.
+//
+// THE INCIDENT, because a rule without it gets simplified back into the bug.
+//
+// `windows-suites.yml` (added #1021) and `macos-suites.yml` (#1022) both landed
+// during the 2026-08-06 GitHub Actions degradation with NO checks reported on
+// their PRs, and neither leg had ever been green. Both ordered the cold-tree
+// bootstrap as `run build:infra` BEFORE `install`, which cannot work either:
+// `@gjsify/vite-plugin-blueprint` declares `"types": ["node"]`, so with no
+// `node_modules` its `gjsify tsc` fails `TS2688: Cannot find type definition
+// file for 'node'`. Correcting the order to install-then-build then exposed
+// THIS gap, one step later.
+//
+// Reproduced on Linux at de7f5525 in a cold worktree — nothing about it is
+// Windows-specific:
+//
+//   npx --yes @gjsify/cli@latest install --immutable   # ok
+//   npx --yes @gjsify/cli@latest run build:infra       # Cannot find module …
+//
+// Linux CI never saw it because its bootstrap runs `gjs -m <published bundle>
+// run build:infra` (`.github/actions/gjsify-setup`), which takes the GJS branch
+// above. Windows is simply the only leg with no `gjs` to fall back on, so it is
+// where the gap became load-bearing.
+//
+// Scoped to an outside-the-workspace CLI ON PURPOSE: when the invocation
+// already came through the workspace's own `node_modules/.bin/gjsify`, that
+// shim IS the CLI the tree wants, and today's dispatch (GJS bundle first on a
+// host with `gjs`) stays byte-for-byte unchanged. Widening this to every Node
+// invocation would silently move in-repo nested builds off the GJS bundle.
 import { mkdtempSync, writeFileSync, chmodSync, existsSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join, delimiter } from 'node:path';
+import { join, delimiter, relative, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { buildLauncherShims } from './bin-shim.js';
+import { findWorkspaceRoot } from './workspace-root.js';
 let _ensured = false;
+let _selfShimActive = false;
 /**
- * Ensure a GJS-runnable `gjsify` is on `process.env.PATH` for child processes.
+ * True when nested `gjsify` calls in this process tree are being routed through
+ * 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.
+ */
+export function usingSelfShim() {
+    return _selfShimActive;
+}
+/**
+ * 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.
+ *
+ * @param gjs           running under GJS (the npm bin is the Node entry there)
+ * @param selfEntry     absolute path of the CLI entry currently executing
+ * @param workspaceRoot absolute path of the workspace the command will act on
+ */
+export function needsSelfShim(opts) {
+    if (opts.gjs)
+        return true;
+    // Outside the workspace ⇒ a bootstrap CLI (npx / global install), so the
+    // tree's own `.bin/gjsify` may well point at build outputs that do not
+    // exist yet. Inside ⇒ the tree's CLI is the one running; leave PATH alone.
+    const rel = relative(opts.workspaceRoot, opts.selfEntry);
+    return rel === '' || rel.startsWith('..') || isAbsolute(rel);
+}
+/**
+ * Ensure a runnable `gjsify` is on `process.env.PATH` for child processes.
  * Idempotent per process; children inherit the shim via `GJSIFY_SHIM_DIR` and
- * reuse it instead of creating their own. No-op when not running under GJS.
+ * reuse it instead of creating their own.
  */
 export function ensureGjsifyShimOnPath() {
-    if (_ensured || !isGjs())
+    if (_ensured)
         return;
     _ensured = true;
-    // A parent gjsify (also under GJS) already created the shim — reuse it so
-    // nested orchestration doesn't pile up temp dirs / PATH entries.
+    // A parent gjsify already created the shim — reuse it so nested
+    // orchestration doesn't pile up temp dirs / PATH entries. The
+    // extension-less member is written on every host, so it stays the probe.
     const inherited = process.env.GJSIFY_SHIM_DIR;
     if (inherited && existsSync(join(inherited, 'gjsify'))) {
+        _selfShimActive = true;
         if (!(process.env.PATH ?? '').split(delimiter).includes(inherited)) {
             process.env.PATH = inherited + delimiter + (process.env.PATH ?? '');
         }
         return;
     }
-    // `import.meta.url` resolves to the running GJS bundle (cli.gjs.mjs) — the
-    // whole CLI collapses into that single file, so this module's URL is it.
-    const selfBundle = fileURLToPath(import.meta.url);
-    const gjs = process.env.GJS_CONSOLE || 'gjs';
+    const gjs = isGjs();
+    // Under GJS `import.meta.url` IS the entry — the whole CLI collapses into
+    // the single `cli.gjs.mjs` bundle, so this module's URL is it. Under Node
+    // this module is `lib/utils/gjsify-shim.js` and the npm bin is
+    // `lib/index.js` (package.json `bin`), one hop up.
+    const selfEntry = gjs ? fileURLToPath(import.meta.url) : fileURLToPath(new URL('../index.js', import.meta.url));
+    const workspaceRoot = findWorkspaceRoot(process.cwd()) ?? process.cwd();
+    if (!needsSelfShim({ gjs, selfEntry, workspaceRoot }))
+        return;
     const dir = mkdtempSync(join(tmpdir(), 'gjsify-shim-'));
     const shim = join(dir, 'gjsify');
-    writeFileSync(shim, `#!/bin/sh\nexec "${gjs}" -m "${selfBundle}" "$@"\n`, { mode: 0o755 });
+    // The interpreter is named, not pathed, on every member — matching
+    // `buildShLauncher`'s `exec gjs` / `exec node` and `buildLauncherShims`'
+    // documented contract, so a missing interpreter fails the same way on every
+    // OS. `process.execPath` is deliberately NOT used: the batch member cannot
+    // quote an interpreter argument (`<interpreter> "<target>" %*`), so a path
+    // like `C:\Program Files\nodejs\node.exe` would split, and a trio whose
+    // members disagree about which interpreter they re-enter is worse than one
+    // name resolved consistently.
+    const interpreter = gjs ? process.env.GJS_CONSOLE || 'gjs' : 'node';
+    const interpreterArgs = gjs ? ['-m'] : [];
+    const argv = interpreterArgs.length > 0 ? `${interpreterArgs.join(' ')} ` : '';
+    writeFileSync(shim, `#!/bin/sh\nexec "${interpreter}" ${argv}"${selfEntry}" "$@"\n`, { mode: 0o755 });
     chmodSync(shim, 0o755);
+    // cmd.exe and pwsh cannot run the extension-less member: it is not on
+    // PATHEXT and Windows has no shebang handling. npm's three-sibling answer
+    // is the de-facto standard, and `buildLauncherShims` is this repo's
+    // reviewed port of it — including the IF/ELSE ERRORLEVEL handling that
+    // `&&`/`||` chaining gets wrong.
+    if (!gjs && process.platform === 'win32') {
+        const { cmd, ps1 } = buildLauncherShims({ interpreter, interpreterArgs, target: selfEntry });
+        writeFileSync(`${shim}.cmd`, cmd);
+        writeFileSync(`${shim}.ps1`, ps1);
+    }
+    _selfShimActive = true;
     process.env.GJSIFY_SHIM_DIR = dir;
     process.env.PATH = dir + delimiter + (process.env.PATH ?? '');
 }

package/lib/utils/install-backend-native.d.ts

@@ -250,6 +250,14 @@ export declare function writeBinEntry(opts: {
         envPreamble: string;
         prebuildDirs: readonly string[];
     };
+    /**
+     * The package's npm `bin` target, when it declares one ALONGSIDE
+     * `gjsify.bin`. The launcher then picks a runtime per invocation instead of
+     * hard-coding `gjs` — see {@link pickBinMap}. Absent for a package that
+     * declares only one of the two, which is every package but `@gjsify/cli`
+     * today.
+     */
+    nodeFallbackAbs?: string;
 }): void;
 type Logger = (fmt: string, ...args: unknown[]) => void;
 export {};