@gjsify/cli 0.29.0 → 0.31.0

package/lib/utils/bin-shim.js

@@ -223,26 +223,63 @@ export function buildCmdShim(relTargetPosix, shebang) {
  * fails the same way on every OS.
  */
 export function buildLauncherShims(opts) {
-    const { interpreter, interpreterArgs = [], target, prependEnv = {} } = opts;
+    const { interpreter, interpreterArgs = [], target, prependEnv = {}, fallback } = opts;
     const winTarget = target.split('/').join('\\');
     const argv = interpreterArgs.length > 0 ? `${interpreterArgs.join(' ')} ` : '';
     const entries = Object.entries(prependEnv);
+    const fbTarget = fallback === undefined ? '' : fallback.target.split('/').join('\\');
+    const fbArgv = fallback?.interpreterArgs !== undefined && fallback.interpreterArgs.length > 0
+        ? `${fallback.interpreterArgs.join(' ')} `
+        : '';
     let cmd = CMD_HEAD;
     for (const [key, value] of entries)
         cmd += `@SET "${key}=${value};%${key}%"\r\n`;
-    cmd += `${interpreter} ${argv}"${winTarget}" %*\r\n`;
+    if (fallback === undefined) {
+        cmd += `${interpreter} ${argv}"${winTarget}" %*\r\n`;
+    }
+    else {
+        // `where` is the batch equivalent of `command -v`; it writes to stdout,
+        // so both streams are silenced. ERRORLEVEL is read via IF/ELSE rather
+        // than `&&`/`||` chaining, which would swallow the child's own exit code.
+        cmd +=
+            `@where ${interpreter} >NUL 2>NUL\r\n` +
+                `@IF %ERRORLEVEL% EQU 0 (\r\n` +
+                `  ${interpreter} ${argv}"${winTarget}" %*\r\n` +
+                `) ELSE (\r\n` +
+                `  ${fallback.interpreter} ${fbArgv}"${fbTarget}" %*\r\n` +
+                `)\r\n`;
+    }
     let ps1 = '#!/usr/bin/env pwsh\n';
     for (const [key, value] of entries)
         ps1 += `$env:${key} = "${value};" + $env:${key}\n`;
     const ps1Args = interpreterArgs.map((a) => `"${a}" `).join('');
-    ps1 +=
-        '# Support pipeline input\n' +
-            'if ($MyInvocation.ExpectingInput) {\n' +
-            `  $input | & "${interpreter}" ${ps1Args}"${winTarget}" $args\n` +
-            '} else {\n' +
-            `  & "${interpreter}" ${ps1Args}"${winTarget}" $args\n` +
-            '}\n' +
-            'exit $LASTEXITCODE\n';
+    if (fallback === undefined) {
+        ps1 +=
+            '# Support pipeline input\n' +
+                'if ($MyInvocation.ExpectingInput) {\n' +
+                `  $input | & "${interpreter}" ${ps1Args}"${winTarget}" $args\n` +
+                '} else {\n' +
+                `  & "${interpreter}" ${ps1Args}"${winTarget}" $args\n` +
+                '}\n';
+    }
+    else {
+        // Bind the three parts once, then call once — the alternative (a full
+        // if/else around two near-identical invocation blocks, each of which
+        // already branches on pipeline input) is four copies of the same call.
+        const psList = (a) => a.length === 0 ? '@()' : `@(${a.map((x) => `"${x}"`).join(', ')})`;
+        ps1 +=
+            `$exe = "${interpreter}"; $exeArgs = ${psList(interpreterArgs)}; $script = "${winTarget}"\n` +
+                `if (-not (Get-Command "${interpreter}" -ErrorAction SilentlyContinue)) {\n` +
+                `  $exe = "${fallback.interpreter}"; $exeArgs = ${psList(fallback.interpreterArgs ?? [])}; $script = "${fbTarget}"\n` +
+                '}\n' +
+                '# Support pipeline input\n' +
+                'if ($MyInvocation.ExpectingInput) {\n' +
+                '  $input | & $exe @exeArgs $script $args\n' +
+                '} else {\n' +
+                '  & $exe @exeArgs $script $args\n' +
+                '}\n';
+    }
+    ps1 += 'exit $LASTEXITCODE\n';
     return { cmd, ps1 };
 }
 /** POSIX `sh` single-quoting — the one place the escape lives. */
@@ -437,14 +474,39 @@ export function normalizeBinMap(pkgName, bin) {
  *
  * `isGjsBin` lets the caller keep plain-Node packages on the plain symlink path
  * — this must not change how `lodash`'s bin is linked.
+ *
+ * WHY THE npm MAP COMES BACK TOO
+ *
+ * The reasoning above is sound and INCOMPLETE: it was written from the Node-less
+ * GJS host and is blind to the mirror case. `@gjsify/cli` declares BOTH fields,
+ * so a host with no `gjs` — macOS and Windows, the two active port targets —
+ * got `exec gjs -m <bundle>`, which is exit 127, while a working Node entry sat
+ * beside it in the same package. `cli-cross-platform.yml` recorded that on both
+ * OSes for three consecutive releases (v0.27.1, v0.28.0, v0.29.0); it is
+ * advisory, so it stayed red. The install even KNEW: its own post-install check
+ * printed `Missing required system dependencies: ✗ GJS` and then wrote a
+ * gjs-only launcher anyway.
+ *
+ * So `nodeFallback` carries the npm map alongside, and the LAUNCHER decides per
+ * invocation. Deliberately not an install-time host probe: an install-time
+ * decision is a SNAPSHOT, and this repo has already paid for that exact mistake
+ * once — `buildNativeEnvPreamble` used to bake the install-time prebuild scan,
+ * so a package installed later was invisible and v0.24.1 shipped a launcher with
+ * no preamble at all. A host probe here fails the same way in reverse: install
+ * without gjs, install gjs afterwards, shim still points at Node forever.
  */
 export function pickBinMap(pkgName, pkgJson) {
     const gjsifyBin = pkgJson.gjsify?.bin;
-    if (gjsifyBin !== undefined)
-        return { map: normalizeBinMap(pkgName, gjsifyBin), isGjsBin: true };
     const npmBin = pkgJson.bin;
+    if (gjsifyBin !== undefined) {
+        return {
+            map: normalizeBinMap(pkgName, gjsifyBin),
+            isGjsBin: true,
+            nodeFallback: npmBin === undefined ? null : normalizeBinMap(pkgName, npmBin),
+        };
+    }
     if (npmBin !== undefined)
-        return { map: normalizeBinMap(pkgName, npmBin), isGjsBin: false };
+        return { map: normalizeBinMap(pkgName, npmBin), isGjsBin: false, nodeFallback: null };
     return null;
 }
 /**
@@ -460,9 +522,23 @@ export function pickBinMap(pkgName, pkgJson) {
  * because not every published bundle carries a `#!/usr/bin/env -S gjs -m` line,
  * and direct-exec'ing a shebang-less `.mjs` falls through to `/bin/sh`, which
  * then parses JavaScript as shell.
+ *
+ * `nodeFallbackAbs` makes the runtime choice per INVOCATION rather than per
+ * install — see {@link pickBinMap} for why a host probe at install time is the
+ * wrong shape. `gjs` stays first: that is today's behaviour on a host carrying
+ * both, and which runtime wins is a separate decision from making the shim
+ * runnable at all.
  */
 export function buildShLauncher(targetAbs, opts) {
     const preamble = opts.isGjsBundle ? (opts.envPreamble ?? '') : '';
+    if (opts.isGjsBundle && opts.nodeFallbackAbs !== undefined) {
+        // The preamble only ever configures the GI search path, so it stays
+        // inside the gjs branch — exporting it around a Node exec would be
+        // inert at best and misleading to anyone reading the shim.
+        return (`#!/bin/sh\nif command -v gjs >/dev/null 2>&1; then\n${preamble}` +
+            `exec gjs -m ${shQuote(targetAbs)} "$@"\nfi\n` +
+            `exec node ${shQuote(opts.nodeFallbackAbs)} "$@"\n`);
+    }
     const exec = opts.isGjsBundle ? `exec gjs -m ${shQuote(targetAbs)} "$@"` : `exec ${shQuote(targetAbs)} "$@"`;
     return `#!/bin/sh\n${preamble}${exec}\n`;
 }

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,73 @@ 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;
+    /** Display name */
+    name: string;
+    /** pkg-config library name */
+    pkgName: string;
+}
+/** 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-
+ * available trio GLib/GObject/Gio).
+ *
+ * Used to compute the set of optional deps to check for a given project.
+ *
+ * Exported for the spec's declaration invariant: every id named here must exist in
+ * OPTIONAL_DEPS, or the dep is silently never checked.
+ */
+export declare const PACKAGE_DEPS: Record<string, string[]>;
 /**
  * Run all dependency checks. Used by `gjsify check` to show full system status.
  *
@@ -86,3 +172,4 @@ export interface TypeSkewReaders {
  * ignore the output.
  */
 export declare function checkTypeSkew(cwd: string, readers?: TypeSkewReaders): TypeSkew[];
+export {};

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,16 +115,58 @@ 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';
 }
-/** Optional system deps keyed by their DepCheck id. */
-const OPTIONAL_DEPS = {
+/**
+ * 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' },
     gstreamer: { id: 'gstreamer', name: 'GStreamer', pkgName: 'gstreamer-1.0' },
     'gst-app': { id: 'gst-app', name: 'GStreamer App', pkgName: 'gstreamer-app-1.0' },
@@ -105,15 +183,74 @@ const OPTIONAL_DEPS = {
     // `Run-time dependency X found: NO` error mid-build.
     gnutls: { id: 'gnutls', name: 'GnuTLS', pkgName: 'gnutls' },
     nghttp2: { id: 'nghttp2', name: 'libnghttp2', pkgName: 'libnghttp2' },
+    // RUNTIME deps of the shipped prebuilds, not build-time ones — the distinction
+    // the two entries above make does not hold for these. Measured on fedora:43
+    // provisioned like a CONSUMER (gjs + libsoup3 only), `ldd` over every committed
+    // linux-x64 prebuild: three sonames do not resolve, and each makes its typelib
+    // UNLOADABLE, which surfaces as `Unsupported type void, deriving from
+    // fundamental void` at first construction — a message that names nothing.
+    //   @gjsify/rolldown-native  libjson-glib-1.0.so.0
+    //   @gjsify/webgl            libepoxy.so.0            (gdk-pixbuf already listed)
+    //   @gjsify/webrtc-native    libgstwebrtc-1.0.so.0    (gstreamer already listed)
+    // json-glib is the severe one: rolldown-native IS the GJS bundler engine, so a
+    // host without it cannot `gjsify build` at all, while `gjsify install` printed
+    // "System dependencies OK." — a check passing for the wrong reason.
+    'json-glib': { id: 'json-glib', name: 'JSON-GLib', pkgName: 'json-glib-1.0' },
+    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-
  * available trio GLib/GObject/Gio).
  *
  * Used to compute the set of optional deps to check for a given project.
+ *
+ * Exported for the spec's declaration invariant: every id named here must exist in
+ * OPTIONAL_DEPS, or the dep is silently never checked.
  */
-const PACKAGE_DEPS = {
+export const PACKAGE_DEPS = {
     '@gjsify/gamepad': ['manette'],
     '@gjsify/webaudio': ['gstreamer', 'gst-app'],
     '@gjsify/iframe': ['webkitgtk'],
@@ -124,13 +261,17 @@ const PACKAGE_DEPS = {
     // as a special-case checkNpmPackage rather than checkPkgConfig in
     // runOptionalChecks. Mapping it here so its presence in the project's
     // dep tree triggers the check.
-    '@gjsify/webgl': ['gwebgl'],
+    '@gjsify/webgl': ['gwebgl', 'gdk-pixbuf', 'epoxy'],
     // Native Vala bridges with `dependency('gnutls')` / `dependency('libnghttp2')`
     // in their meson.build. Optional because the shipped prebuild covers the
     // common-arch user path; only contributors rebuilding from source hit the
     // build-time dep.
     '@gjsify/tls-native': ['gnutls'],
     '@gjsify/http2-native': ['nghttp2'],
+    // Unlike the two above, these are LOAD-time: the prebuild is dynamically linked
+    // and GIRepository cannot open its backing library without them.
+    '@gjsify/rolldown-native': ['json-glib'],
+    '@gjsify/webrtc-native': ['gstreamer', 'gst-webrtc'],
     // @gjsify/event-bridge only needs gtk4/gdk which are already in the
     // required set, so it doesn't need an optional entry.
 };
@@ -243,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. */
@@ -367,6 +514,8 @@ const PM_PACKAGES = {
         cairo: 'libcairo2-dev',
         gnutls: 'libgnutls28-dev',
         nghttp2: 'libnghttp2-dev',
+        'json-glib': 'libjson-glib-dev',
+        epoxy: 'libepoxy-dev',
     },
     dnf: {
         gjs: 'gjs',
@@ -390,6 +539,8 @@ const PM_PACKAGES = {
         cairo: 'cairo-devel',
         gnutls: 'gnutls-devel',
         nghttp2: 'libnghttp2-devel',
+        'json-glib': 'json-glib-devel',
+        epoxy: 'libepoxy-devel',
     },
     pacman: {
         gjs: 'gjs',
@@ -413,6 +564,8 @@ const PM_PACKAGES = {
         cairo: 'cairo',
         gnutls: 'gnutls',
         nghttp2: 'libnghttp2',
+        'json-glib': 'json-glib',
+        epoxy: 'libepoxy',
     },
     zypper: {
         gjs: 'gjs',
@@ -436,6 +589,8 @@ const PM_PACKAGES = {
         cairo: 'cairo-devel',
         gnutls: 'libgnutls-devel',
         nghttp2: 'libnghttp2-devel',
+        'json-glib': 'json-glib-devel',
+        epoxy: 'libepoxy-devel',
     },
     apk: {
         gjs: 'gjs',
@@ -459,6 +614,8 @@ const PM_PACKAGES = {
         cairo: 'cairo-dev',
         gnutls: 'gnutls-dev',
         nghttp2: 'nghttp2-dev',
+        'json-glib': 'json-glib-dev',
+        epoxy: 'libepoxy-dev',
     },
     // macOS. Names verified against homebrew/core rather than inferred from the
     // Linux rows — the mapping is NOT mechanical: Homebrew ships no `-dev`/`-devel`
@@ -502,6 +659,17 @@ const PM_PACKAGES = {
         cairo: 'cairo',
         gnutls: 'gnutls',
         nghttp2: 'nghttp2',
+        '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: {},
 };
@@ -513,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 {};