@gjsify/cli 0.30.0 → 0.31.0

package/lib/utils/check-system-deps.js

@@ -24,6 +24,42 @@ function tryExecFile(binary, args) {
         return null;
     }
 }
+/**
+ * True when `cmd` is on PATH. Walks `process.env.PATH` with `existsSync`
+ * instead of shelling out to `which`(1).
+ *
+ * `which` is NOT a probe you can rely on: the Fedora 43/44 minimal containers
+ * CI runs in ship without it (only the `which-2.x` rpm provides it), so a
+ * `which`-based check silently answers "missing" for EVERY command. That is
+ * exactly where this file's answer matters most — `detectPackageManager()`
+ * returning `unknown` makes `buildInstallCommand()` return null, so the
+ * distro-specific install hint for a missing system library prints nothing on
+ * the hosts that needed it. Measured twice on 2026-08-05: ts-for-gir#437 had to
+ * discover `json-glib` by hand, bauplaner#40 `libsoup3` — both in such a
+ * container, both while this file already declared the dependency.
+ *
+ * `tests/e2e/helpers.mjs`'s `hasCommand()` carries the same walk for the same
+ * reason. It stays a second copy on purpose: it is `.mjs` under `tests/` and
+ * cannot be imported from the shipped CLI.
+ */
+export function isOnPath(cmd) {
+    const pathVar = process.env.PATH;
+    if (!pathVar)
+        return false;
+    const sep = process.platform === 'win32' ? ';' : ':';
+    for (const dir of pathVar.split(sep)) {
+        if (!dir)
+            continue;
+        try {
+            if (existsSync(join(dir, cmd)))
+                return true;
+        }
+        catch {
+            // An inaccessible PATH entry is not an answer about `cmd`.
+        }
+    }
+    return false;
+}
 /** Check if a binary exists and optionally capture its version output. */
 function checkBinary(id, name, binary, versionArgs, severity, parseVersion, requiredBy) {
     const out = tryExecFile(binary, versionArgs);
@@ -79,14 +115,56 @@ function checkNpmPackage(id, name, packageName, cwd, severity, requiredBy) {
  * MacPorts or Nix host, and it is why this must never fall back to "probably brew".
  */
 export function detectPackageManager() {
+    // win32 has no `which`, so the loop below would return `unknown` by
+    // ACCIDENT rather than by construction — which was the pre-existing
+    // behaviour and produced the right answer for the wrong reason. `winget`
+    // ships with Windows 11 and is what a user actually has, and it is only
+    // ever consulted for the one dependency this platform has an entry for.
+    if (process.platform === 'win32') {
+        return tryExecFile('where', ['winget']) !== null ? 'winget' : 'unknown';
+    }
     const managers = process.platform === 'darwin' ? ['brew'] : ['apt', 'dnf', 'pacman', 'zypper', 'apk', 'brew'];
     for (const pm of managers) {
-        const result = tryExecFile('which', [pm]);
-        if (result !== null)
+        if (isOnPath(pm))
             return pm;
     }
     return 'unknown';
 }
+/**
+ * The Visual C++ runtime — an undeclared, undiagnosed win32 prerequisite (#997).
+ *
+ * `@gjsify/gtk-runtime-win32-x64` is built with gvsbuild, i.e. against the MSVC
+ * ABI, and its DLLs load into stock (also MSVC-ABI) Node. On a Windows host
+ * WITHOUT the Visual C++ redistributable that load fails — and nothing in the
+ * toolchain said so. The precedent for why that matters is PR #994: a missing
+ * load-time library made a typelib unloadable and the user-visible message was
+ * `Unsupported type void, deriving from fundamental void`, which names nothing
+ * a user could act on.
+ *
+ * Probed by FILE PRESENCE in the system directory rather than by asking a
+ * package database: the redistributable can arrive with Visual Studio, with
+ * another application's installer, or as part of a Windows image, and only one
+ * of those routes is visible to a package manager. What the loader actually
+ * needs is the DLL, so that is what is checked.
+ *
+ * `vcruntime140.dll` and `msvcp140.dll` are the C and C++ halves;
+ * `vcruntime140_1.dll` carries the x64 exception-handling machinery and is
+ * absent from pre-2019 redistributables, which is exactly the "installed, but
+ * too old" case that otherwise fails at first use rather than at load.
+ */
+export function checkMsvcRuntime() {
+    const systemRoot = process.env.SystemRoot ?? process.env.SYSTEMROOT ?? 'C:\\Windows';
+    const required = ['vcruntime140.dll', 'vcruntime140_1.dll', 'msvcp140.dll'];
+    const missing = required.filter((dll) => !existsSync(`${systemRoot}\\System32\\${dll}`));
+    return {
+        id: 'msvc-runtime',
+        name: missing.length === 0
+            ? 'Microsoft Visual C++ runtime'
+            : `Microsoft Visual C++ runtime (missing ${missing.join(', ')} — the GTK bundle's DLLs are MSVC-ABI and will not load)`,
+        found: missing.length === 0,
+        severity: 'required',
+    };
+}
 /** Optional system deps keyed by their DepCheck id. Exported for the spec's declaration invariant. */
 export const OPTIONAL_DEPS = {
     manette: { id: 'manette', name: 'libmanette', pkgName: 'manette-0.2' },
@@ -121,6 +199,47 @@ export const OPTIONAL_DEPS = {
     epoxy: { id: 'epoxy', name: 'libepoxy', pkgName: 'epoxy' },
     'gst-webrtc': { id: 'gst-webrtc', name: 'GStreamer WebRTC', pkgName: 'gstreamer-webrtc-1.0' },
 };
+/**
+ * The declared system libraries a single `@gjsify/*` package needs that are NOT
+ * present on this host.
+ *
+ * Exists so a FAILURE can answer the question this file already knows the answer
+ * to. The tables below have declared `@gjsify/rolldown-native → json-glib` since
+ * #994, complete with per-distro package names — but the only reader was
+ * `runAllChecks()`, i.e. `gjsify system-check`, a command the user has to think
+ * to run. So when the engine was installed and simply would not LOAD, the build
+ * said "@gjsify/rolldown-native is NOT INSTALLED … install it" (it was) or
+ * guessed at a bypassed launcher. Two repositories spent a CI round rediscovering
+ * a library this file could have named: ts-for-gir#437, bauplaner#40.
+ *
+ * Cannot throw, by construction rather than by a catch: `checkPkgConfig` goes
+ * through `tryExecFile`, which returns null on any failure. That matters because
+ * the caller is `diagnoseNativeEngine()`, which runs *while explaining another
+ * failure* — a probe that dies there would replace the diagnosis with its own
+ * stack.
+ *
+ * Returns `[]` for an unknown package or one with no declared deps, so a caller
+ * needs no special case for "nothing to say".
+ */
+export function missingSystemDepsFor(packageName) {
+    const ids = PACKAGE_DEPS[packageName];
+    if (!ids)
+        return [];
+    const missing = [];
+    for (const id of ids) {
+        const dep = OPTIONAL_DEPS[id];
+        // An id with no OPTIONAL_DEPS entry is not "present"; it is unanswerable
+        // here. The spec's declaration invariant is what keeps that set empty —
+        // silently reporting it as found would be the failure mode this whole
+        // function exists to end.
+        if (!dep?.pkgName)
+            continue;
+        const result = checkPkgConfig(dep.id, dep.name, dep.pkgName, 'optional', [packageName]);
+        if (!result.found)
+            missing.push(result);
+    }
+    return missing;
+}
 /**
  * Map of @gjsify/* package name → ids of OPTIONAL_DEPS this package needs.
  * Generated by walking each package's `gi://` imports (excluding the always-
@@ -265,6 +384,12 @@ export function runMinimalChecks() {
     results.push({ id: 'nodejs', name: 'Node.js', found: true, version: process.version, severity: 'required' });
     // GJS
     results.push(checkBinary('gjs', 'GJS', 'gjs', ['--version'], 'required', (out) => out.replace(/^GJS\s+/i, '').split('\n')[0] ?? out));
+    // The one win32 system dependency that is real and was undiagnosed (#997).
+    // Checked at INSTALL time, not just in `system-check`, because the failure
+    // it prevents is a bare `ERR_DLOPEN_FAILED` on a `.node` that is present —
+    // by then the user has no thread to pull.
+    if (process.platform === 'win32')
+        results.push(checkMsvcRuntime());
     return results;
 }
 /** Check gwebgl npm package (project first, CLI fallback). Optional — only needed by @gjsify/webgl users. */
@@ -537,6 +662,15 @@ const PM_PACKAGES = {
         'json-glib': 'json-glib',
         epoxy: 'libepoxy',
     },
+    // Deliberately ONE entry. Windows is not a GJS host, so `gjs`, the
+    // pkg-config toolchain and every `-devel` library above have no winget
+    // package that would help — offering one would be a wrong answer rather
+    // than a missing one, and `buildInstallCommand` already skips any id with
+    // no mapping. The Visual C++ runtime is the one win32 system dependency
+    // that IS real, installable, and currently undiagnosed (#997).
+    winget: {
+        'msvc-runtime': 'Microsoft.VCRedist.2015+.x64',
+    },
     unknown: {},
 };
 const PM_INSTALL_PREFIX = {
@@ -547,6 +681,9 @@ const PM_INSTALL_PREFIX = {
     apk: 'sudo apk add',
     // No `sudo`: Homebrew refuses to run as root and tells you so.
     brew: 'brew install',
+    // `--id` because winget's fuzzy name match is ambiguous for this package,
+    // and it is the spelling Microsoft's own docs use.
+    winget: 'winget install --id',
     unknown: '',
 };
 /**

package/lib/utils/detect-native-packages.js

@@ -642,7 +642,18 @@ export function buildNativeEnv(packages, opts = {}) {
     const systemDirs = (opts.systemGiDirs ?? systemGiLibraryDirs)({ platform, env });
     if (systemDirs.length > 0) {
         const inherited = splitSearchPath(env[DYLD_FALLBACK_VAR]);
-        out[DYLD_FALLBACK_VAR] = [...systemDirs, ...(inherited.length > 0 ? inherited : ['/usr/lib'])].join(':');
+        // Deduplicated, and not for tidiness: `systemGiLibraryDirs()` accepts a
+        // libdir stated outright through `GI_TYPELIB_PATH` on directory
+        // existence alone, so a host that names `/usr/lib/girepository-1.0`
+        // there puts `/usr/lib` in `systemDirs` — and the `/usr/lib` tail below
+        // then repeated it. A search path that lists the same directory twice
+        // asks the loader to stat it twice for every miss, and it makes the
+        // value the `$ …` echo prints read as though the CLI had composed
+        // something it did not. First occurrence wins in every loader, so
+        // dropping later repeats is behaviour-preserving.
+        out[DYLD_FALLBACK_VAR] = [
+            ...new Set([...systemDirs, ...(inherited.length > 0 ? inherited : ['/usr/lib'])]),
+        ].join(':');
     }
     return out;
 }

package/lib/utils/discover-showcases.d.ts

@@ -7,8 +7,6 @@ export interface ShowcaseInfo {
     category: string;
     /** Description for the list view */
     description: string;
-    /** Whether the showcase needs the gwebgl native prebuild. */
-    needsWebgl: boolean;
 }
 /**
  * Read the curated showcase list from `showcases.json`. Returns showcases

package/lib/utils/discover-showcases.js

@@ -43,7 +43,6 @@ export function discoverShowcases() {
         packageName: e.package,
         category: e.category,
         description: e.description ?? '',
-        needsWebgl: Boolean(e.needsWebgl),
     }));
     showcases.sort((a, b) => a.category.localeCompare(b.category) || a.name.localeCompare(b.name));
     return showcases;

package/lib/utils/dlx-cache.d.ts

@@ -54,8 +54,28 @@ export declare function getValidCachedPkg(cacheDir: string, maxAgeMinutes?: numb
 export declare function symlinkSwap(cacheDir: string, prepareDir: string, opts?: {
     junctions?: boolean;
 }): string;
-/** Clean up `<cacheDir>/<oldPrepareDir>` siblings older than `maxAgeMinutes`. */
-export declare function cleanupStalePrepareDirs(cacheDir: string, _maxAgeMinutes?: number): void;
+/**
+ * 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 declare function cleanupStalePrepareDirs(cacheDir: string, maxAgeMinutes?: number): void;
 /** Resolve absolute path to the installed package's directory inside cache. */
 export declare function resolveInstalledPkgDir(cachedRoot: string, pkgName: string): string;
 export {};

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) {
-    // TODO(open-todos: 10 small API gaps): out of scope for Phase 1 — pnpm has the same stub. Kept 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 };
+}