@gjsify/cli 0.30.0 → 0.32.0

package/lib/config.js

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

package/lib/index.js

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

package/lib/templates/install.mjs.tmpl

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

package/lib/types/command.d.ts

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

package/lib/utils/check-system-deps.d.ts

@@ -12,7 +12,26 @@ export interface DepCheck {
     /** For optional deps: which @gjsify/* packages need this lib */
     requiredBy?: string[];
 }
-export type PackageManager = 'apt' | 'dnf' | 'pacman' | 'zypper' | 'apk' | 'brew' | 'unknown';
+export type PackageManager = 'apt' | 'dnf' | 'pacman' | 'zypper' | 'apk' | 'brew' | 'winget' | 'unknown';
+/**
+ * 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 declare function isOnPath(cmd: string): boolean;
 /**
  * The package manager whose install command we may suggest.
  *
@@ -28,6 +47,29 @@ export type PackageManager = 'apt' | 'dnf' | 'pacman' | 'zypper' | 'apk' | 'brew
  * MacPorts or Nix host, and it is why this must never fall back to "probably brew".
  */
 export declare function detectPackageManager(): PackageManager;
+/**
+ * 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 declare function checkMsvcRuntime(): DepCheck;
 interface OptionalDep {
     /** DepCheck id */
     id: string;
@@ -38,6 +80,29 @@ interface OptionalDep {
 }
 /** Optional system deps keyed by their DepCheck id. Exported for the spec's declaration invariant. */
 export declare const OPTIONAL_DEPS: Record<string, OptionalDep>;
+/**
+ * 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 declare function missingSystemDepsFor(packageName: string): DepCheck[];
 /**
  * Map of @gjsify/* package name → ids of OPTIONAL_DEPS this package needs.
  * Generated by walking each package's `gi://` imports (excluding the always-

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);
+}