@gjsify/cli 0.30.0 → 0.32.0

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-global.d.ts

@@ -29,8 +29,36 @@ export declare function defaultGlobalLayout(): GlobalLayout;
  * story already degrades on Node.
  */
 export declare const GJS_ENGINE_PACKAGES: readonly ["@gjsify/rolldown-native", "@gjsify/lightningcss-native", "@gjsify/oxfmt-native"];
-/** True when `<prefix>/node_modules/@gjsify/rolldown-native` is laid down. */
-export declare function hasBundlerEngineInstalled(prefix: string): boolean;
+/**
+ * The one engine whose absence is fatal rather than degrading: `gjsify build`
+ * has no fallback under GJS. Named separately because two different questions
+ * ("what do we install") and ("is a build possible") want different sets.
+ */
+export declare const BUNDLER_ENGINE_PACKAGE = "@gjsify/rolldown-native";
+/**
+ * True when a bundler engine `gjsify build` can actually LOAD is reachable from
+ * `dir`.
+ *
+ * This used to `existsSync` the bridge's own `package.json` and stop there. That
+ * answer was correct before ADR 0017 and is wrong after it: the bridge is now
+ * pure TypeScript (`files: ["lib", "meson.build", "src/rust", "src/vala"]`) and
+ * the binary lives in a per-target child (`@gjsify/rolldown-native-<os>-<arch>`).
+ * So "bridge present, child missing" reported `true` — which is why
+ * `self-update`'s repair gate could say "Already up to date" about a prefix whose
+ * engine cannot load. A live defect, not a hypothetical one.
+ *
+ * Asks `detectNativePackages` instead, which is the same walk-up
+ * `findRolldownNativeDir` performs at BUILD time. That matters more than the
+ * shortcut it replaces: an installer that disagrees with the builder about
+ * whether the engine is present is worse than one that is merely slow. It also
+ * makes the gjsify monorepo a no-op — the workspace symlink resolves — which is
+ * what keeps ADR 0001's non-destructive invariant safe from a registry copy
+ * landing on top of `packages/infra/rolldown-native`.
+ *
+ * `dir` is a prefix for a global install and a project root for a project one;
+ * the walk handles both.
+ */
+export declare function hasBundlerEngineInstalled(dir: string): boolean;
 /**
  * Best-effort install of the GJS-native engine packages into a global prefix.
  *
@@ -86,8 +114,57 @@ export interface LinkedBin {
  *   simplicity and so we don't need to discriminate by runtime here.
  */
 export declare function linkGlobalBins(packageNames: string[], layout: GlobalLayout): LinkedBin[];
+/**
+ * Is the global layout the user's own, or has a caller redirected it?
+ *
+ * `GJSIFY_GLOBAL_PREFIX` / `GJSIFY_GLOBAL_BIN_DIR` are the escape hatches
+ * {@link defaultGlobalLayout} documents for tests, and a caller that sets them
+ * has taken over placement — so "which `gjsify` will PATH resolve next" stops
+ * being a question about THEIR intent. `self-update` gates its fatal PATH check
+ * on this: without it, every harness installing into a temp prefix it never put
+ * on PATH is told its update did not take effect, which is true and useless.
+ * Caught by `tests/e2e/global-install-engine`.
+ *
+ * @param env injectable so both answers are testable without mutating the real
+ *   environment mid-suite.
+ */
+export declare function globalLayoutIsDefault(env?: NodeJS.ProcessEnv): boolean;
 /** Returns `true` if `binDir` is on the user's PATH. */
 export declare function binDirOnPath(binDir: string): boolean;
+/** Injection points for {@link resolveBinOnPath} — see its `platform` note. */
+export interface ResolveBinOnPathOptions {
+    /** PATH to search. Defaults to `process.env.PATH`. */
+    pathValue?: string;
+    /** PATHEXT to honour on win32. Defaults to `process.env.PATHEXT` or cmd.exe's set. */
+    pathExt?: string;
+    /** Host platform. Defaults to `process.platform`. */
+    platform?: NodeJS.Platform;
+    /** File-existence probe. Defaults to a real `fs.existsSync`. */
+    exists?: (file: string) => boolean;
+}
+/**
+ * Resolve `binName` the way the user's shell will: the FIRST hit in PATH order.
+ *
+ * WHY THIS IS NOT `binDirOnPath`. That answers "is our dir on PATH", which is
+ * necessary but not sufficient for anything that CHANGES which binary runs:
+ * `~/.local/bin` can be on PATH and still lose to an npm-global `gjsify` earlier
+ * in it. `self-update` reported "Updated to v0.31.0" on exactly that host while
+ * the shell kept resolving a v0.26.0 install five releases behind — and the user
+ * then re-hit a bug fixed three releases earlier and reported it as new (#1064).
+ * "Which one wins" is the question, so this returns the winning PATH.
+ *
+ * WINDOWS. An extension-less name is not executable there; cmd.exe and pwsh
+ * append each `PATHEXT` entry, which is how the `.cmd` shim `bin-shim.ts` writes
+ * gets found. The bare name is probed LAST so a git-bash/MSYS `sh` shim is still
+ * reported rather than missed. `platform`/`pathExt`/`exists` are injectable for
+ * the same reason `dirLinkTarget` takes `linkType`: nothing in CI resolves a bin
+ * on a Windows host, so an injected `'win32'` is the ONLY way that branch is ever
+ * EXECUTED — and an unexecutable Windows branch is exactly how the `'dir'` bug in
+ * `dir-link.ts` shipped.
+ *
+ * @returns the absolute path of the winning candidate, or `null` when PATH holds none.
+ */
+export declare function resolveBinOnPath(binName: string, opts?: ResolveBinOnPathOptions): string | null;
 /**
  * Extracts the package name from a spec like `name@1.2`, `@scope/name`,
  * or `@scope/name@latest`. Returns the unchanged string for plain names.