@gjsify/cli 0.31.0 → 0.32.0

package/lib/commands/self-update.d.ts

@@ -6,4 +6,31 @@ interface SelfUpdateOptions {
     skipDeps?: boolean;
 }
 export declare const selfUpdateCommand: Command<unknown, SelfUpdateOptions>;
+/** Verdict of the post-install "did this change what runs?" check. */
+export type PathVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Compare where PATH sends `binName` against the `binDir` we just linked into.
+ *
+ * Pure so the three outcomes are unit-testable off-host — the interesting two
+ * are exactly the ones a developer's own machine never produces, since a working
+ * install resolves to its own `binDir` by definition.
+ *
+ * Path comparison is case-INSENSITIVE on win32: `C:\Users\X\.local\bin` and
+ * `c:\users\x\.local\bin` are one directory there, and a case-sensitive compare
+ * would report a correct install as shadowed.
+ */
+export declare function verifyPathResolution(opts: {
+    binName: string;
+    binDir: string;
+    resolvedBin: string | null;
+    /** `null` is what `readCurrentVersion()` returns when it cannot tell. */
+    runningVersion: string | null | undefined;
+    targetVersion: string;
+    platform?: NodeJS.Platform;
+}): PathVerdict;
 export {};

package/lib/commands/self-update.js

@@ -11,12 +11,21 @@
 // `defaultGlobalLayout().prefix` (i.e. via `gjsify install -g` or via the
 // `install.mjs` bootstrap). Installs from `npm install -g @gjsify/cli` land
 // elsewhere and we don't try to chase them — we print a warning and exit.
+//
+// AND THE WARNING IS NOT ENOUGH ON ITS OWN (#1064). This command's whole job is
+// to change which binary the user's next `gjsify` runs, so success has to be
+// measured on PATH, not on the prefix it wrote. Reported from a Windows host:
+// the pre-install warning fired, the install succeeded, `Updated @gjsify/cli to
+// v0.31.0` printed — and the shell kept resolving a v0.26.0 npm-global install,
+// so the very next command re-hit the `dlx` EPERM fixed three releases earlier.
+// A silent no-op that reports success is worse than a clean failure, so the
+// post-link verification below is fatal.
 import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join, posix, resolve, win32 } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { fetchPackument } from '@gjsify/npm-registry';
 import { installPackages, makeProgressReporter } from '../utils/install-backend.js';
-import { defaultGlobalLayout, hasBundlerEngineInstalled, installGjsEnginePackages, linkGlobalBins, } from '../utils/install-global.js';
+import { defaultGlobalLayout, globalLayoutIsDefault, hasBundlerEngineInstalled, installGjsEnginePackages, linkGlobalBins, resolveBinOnPath, } from '../utils/install-global.js';
 const PACKAGE_NAME = '@gjsify/cli';
 export const selfUpdateCommand = {
     command: 'self-update',
@@ -157,6 +166,27 @@ export const selfUpdateCommand = {
                 console.log(`  • ${bin.link}  →  ${bin.target}`);
             }
         }
+        // Did the update change what `gjsify` RUNS? Everything above only proves
+        // we wrote the prefix. See the #1064 note at the top of this file.
+        //
+        // Only for the user's OWN layout: a caller that redirected the install
+        // with GJSIFY_GLOBAL_PREFIX/_BIN_DIR manages placement itself, and
+        // telling a harness that installed into a temp prefix "your PATH still
+        // points elsewhere" is true and useless.
+        if (globalLayoutIsDefault()) {
+            const verdict = verifyPathResolution({
+                binName: BIN_NAME,
+                binDir: layout.binDir,
+                resolvedBin: resolveBinOnPath(BIN_NAME),
+                runningVersion: currentVersion,
+                targetVersion: target,
+            });
+            if (!verdict.ok) {
+                console.error(`\nInstalled ${PACKAGE_NAME} v${target} at ${layout.prefix}`);
+                console.error(verdict.message);
+                return process.exit(1);
+            }
+        }
         console.log(`\nUpdated ${PACKAGE_NAME} to v${target}.`);
         if (pullDeps) {
             console.log('Runtime dependencies were resolved alongside the bundle.');
@@ -166,6 +196,51 @@ export const selfUpdateCommand = {
         }
     },
 };
+/** The bin `@gjsify/cli` installs, and the name a user types. */
+const BIN_NAME = 'gjsify';
+/**
+ * Compare where PATH sends `binName` against the `binDir` we just linked into.
+ *
+ * Pure so the three outcomes are unit-testable off-host — the interesting two
+ * are exactly the ones a developer's own machine never produces, since a working
+ * install resolves to its own `binDir` by definition.
+ *
+ * Path comparison is case-INSENSITIVE on win32: `C:\Users\X\.local\bin` and
+ * `c:\users\x\.local\bin` are one directory there, and a case-sensitive compare
+ * would report a correct install as shadowed.
+ */
+export function verifyPathResolution(opts) {
+    const platform = opts.platform ?? process.platform;
+    // The TARGET platform's path module, never the host's — see `pathFor` in
+    // `utils/install-global.ts` for why (`resolve('C:\\x')` on posix is wrong).
+    const p = platform === 'win32' ? win32 : posix;
+    const norm = (v) => (platform === 'win32' ? p.resolve(v).toLowerCase() : p.resolve(v));
+    if (opts.resolvedBin === null) {
+        return {
+            ok: false,
+            message: `BUT nothing named \`${opts.binName}\` is on PATH, so the update cannot take effect.\n\n` +
+                `  Add the bin dir to PATH:\n    ${opts.binDir}`,
+        };
+    }
+    if (norm(p.dirname(opts.resolvedBin)) === norm(opts.binDir))
+        return { ok: true };
+    // Deliberately NOT split into "a rival install" vs "a transient runner"
+    // (npx/dlx, whose temp bin wins PATH for the length of the run). Both are the
+    // same fact — `gjsify` does not currently mean the tree we just wrote — and
+    // guessing which one it is would be a heuristic that can only be wrong. So
+    // the finding is stated and both remedies are offered.
+    const running = opts.runningVersion ? ` (v${opts.runningVersion})` : '';
+    return {
+        ok: false,
+        message: `BUT \`${opts.binName}\` on PATH resolves to\n    ${opts.resolvedBin}${running}\n` +
+            `which is NOT the install that was just updated, so the next \`${opts.binName}\`\n` +
+            `you run will not be v${opts.targetVersion}.\n\n` +
+            `  If that is another install, remove it (e.g. \`npm uninstall -g ${PACKAGE_NAME}\`)\n` +
+            `  or put ${opts.binDir} ahead of it on PATH.\n` +
+            `  If you ran this through npx/dlx, that temporary copy owns the name only for\n` +
+            `  this run — open a new shell and check \`${opts.binName} --version\`.`,
+    };
+}
 /**
  * Resolve the CLI's own `package.json#version`. Walks up from
  * `import.meta.url` (the bundle file under GJS, or `lib/index.js` under

package/lib/commands/showcase.d.ts

@@ -1,4 +1,6 @@
 import type { Command } from '../types/index.js';
+import { type Packument } from '@gjsify/npm-registry';
+import { type ExampleRuntime } from '../utils/runtimes.js';
 /**
  * Pinned invocations for the three runners that cache an unpinned bin.
  *
@@ -22,4 +24,16 @@ interface ShowcaseOptions {
     runtime?: string;
 }
 export declare const showcaseCommand: Command<unknown, ShowcaseOptions>;
+/**
+ * The pure half of {@link preflightDeclaredRuntimes}: pick the version whose
+ * declaration decides, and read it.
+ *
+ * Separate from the fetch so the fail-safe direction is unit-testable — that
+ * contract ("never fail a run that would have worked") is the only thing that
+ * makes a pre-install check safe, and it lives entirely in which branches return
+ * `undefined`.
+ *
+ * @param cliVersion the CLI's own version; `showcase` pins the showcase to it.
+ */
+export declare function declaredRuntimesFromPackument(packument: Packument, cliVersion: string | undefined): ExampleRuntime[] | null | undefined;
 export {};

package/lib/commands/showcase.js

@@ -4,6 +4,8 @@ import { createRequire } from 'node:module';
 import { dirname } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { ensurePkgDir } from './dlx.js';
+import { fetchPackument } from '@gjsify/npm-registry';
+import { loadNpmrc } from '../utils/load-npmrc.js';
 import { parseSpec } from '../utils/parse-spec.js';
 import { resolveNodeEntry } from '../utils/resolve-gjs-entry.js';
 import { runRuntimeBundle } from '../utils/run-node.js';
@@ -212,15 +214,9 @@ export const showcaseCommand = {
  */
 async function resolveShowcaseDir(showcase, cliVersion, extraSpecs = []) {
     // Local-first: a workspace showcase resolves via its own package name.
-    try {
-        const req = createRequire(import.meta.url);
-        const localPkgJson = req.resolve(`${showcase.packageName}/package.json`);
-        if (existsSync(localPkgJson))
-            return dirname(localPkgJson);
-    }
-    catch {
-        // Not resolvable locally — fall through to dlx install.
-    }
+    const local = resolveLocalShowcaseDir(showcase);
+    if (local)
+        return local;
     const spec = cliVersion ? `${showcase.packageName}@${cliVersion}` : showcase.packageName;
     const { pkgDir } = await ensurePkgDir(parseSpec(spec), {
         verbose: false,
@@ -230,6 +226,117 @@ async function resolveShowcaseDir(showcase, cliVersion, extraSpecs = []) {
     });
     return pkgDir;
 }
+/**
+ * The LOCAL (workspace / node_modules) directory of a showcase, or `null`.
+ *
+ * Factored out because two callers need the same question answered: the resolver
+ * below, and the pre-flight, which must know whether an install is even going to
+ * happen before deciding to spend a registry request avoiding it.
+ */
+function resolveLocalShowcaseDir(showcase) {
+    try {
+        const req = createRequire(import.meta.url);
+        const localPkgJson = req.resolve(`${showcase.packageName}/package.json`);
+        if (existsSync(localPkgJson))
+            return dirname(localPkgJson);
+    }
+    catch {
+        // Not resolvable locally — the caller falls back to a dlx install.
+    }
+    return null;
+}
+/**
+ * The batteries-included GTK runtime to add to a showcase's dlx tree, if any.
+ *
+ * WHY THE LAUNCHER AND NOT THE PACKAGE. `@gjsify/node-gi` deliberately declares
+ * no bundle: making one its dependency is #910, where a from-source addon met a
+ * foreign GTK and produced wrong method entries and a 29-minute timeout. The rule
+ * that replaced it is "whoever SHIPS an app declares the bundle" — and for a
+ * showcase, the shipper is this command, which assembles the dlx tree. Same
+ * reasoning, same place, as the `@gjsify/node-gi` spec beside it.
+ *
+ * Only where a system GTK is not a given, which is exactly where a bundle is
+ * built: Windows has none at all (#1063 — every `gi://` showcase died in
+ * `ERR_DLOPEN_FAILED` on a clean host), and macOS has Homebrew's, which is
+ * measurably not findable. On Linux the distribution's GTK is the tested
+ * combination and node-gi's own policy prefers it, so pulling ~80 MB nobody would
+ * use would be waste.
+ *
+ * The tree only ever holds the PUBLISHED PREBUILD, never a from-source build, so
+ * the mismatch #910 hit cannot arise here by construction.
+ */
+function gtkRuntimeSpecs(cliVersion) {
+    const target = `${process.platform}-${process.arch}`;
+    const shipped = ['win32-x64', 'darwin-arm64', 'darwin-x64'];
+    if (!shipped.includes(target))
+        return [];
+    const name = `@gjsify/gtk-runtime-${target}`;
+    return [cliVersion ? `${name}@${cliVersion}` : name];
+}
+/**
+ * Read a showcase's declared runtimes from the REGISTRY, with no install (#1069).
+ *
+ * WHY. `--runtime node` on a gjs-only showcase used to resolve and download the
+ * whole dlx tree — plus the pinned native `@gjsify/node-gi` bridge, added
+ * BECAUSE `--runtime node` was requested — and only then read the declaration
+ * that rejects the run. Measured for `adwaita-storybook`: a 310 KB showcase with
+ * no runtime deps, and 3.77 MB of `node-gi` fetched to support a runtime the
+ * package was about to refuse. The full packument carries
+ * `gjsify.example.runtimes` verbatim, so one metadata GET answers it.
+ *
+ * NOT solved by putting `runtimes` in `showcases.json`: that is a second copy of
+ * a declaration the package already owns, maintained by hand. See the
+ * `needsWebgl` post-mortem in `utils/discover-showcases.ts` — "a field nobody
+ * reads is a field nobody maintains", proven by a showcase that shipped
+ * `"needsWebgl": false` while its engine was WebGL2-only.
+ *
+ * FAIL-SAFE DIRECTION, and it is the whole contract: this may only ever turn a
+ * run that WOULD have failed into a faster failure. It must never fail a run
+ * that would have worked, so every uncertain branch — offline, unpublished
+ * version, missing field, malformed document — returns `undefined` and lets the
+ * install proceed to the authoritative on-disk check.
+ *
+ * @returns the declared list, `null` for a package that declares none
+ *   (unconstrained), or `undefined` when the question could not be answered.
+ */
+async function preflightDeclaredRuntimes(showcase, cliVersion) {
+    try {
+        // `fullMetadata` is REQUIRED: the abbreviated (corgi) document omits
+        // custom fields, so `gjsify.example` is simply absent there — the same
+        // shape as the `libc` note in `@gjsify/npm-registry`'s PackumentVersion.
+        const packument = await fetchPackument(showcase.packageName, {
+            npmrc: await loadNpmrc(process.cwd()),
+            fullMetadata: true,
+        });
+        return declaredRuntimesFromPackument(packument, cliVersion);
+    }
+    catch {
+        // Offline, private registry, auth failure, 404 — all "cannot say".
+        return undefined;
+    }
+}
+/**
+ * The pure half of {@link preflightDeclaredRuntimes}: pick the version whose
+ * declaration decides, and read it.
+ *
+ * Separate from the fetch so the fail-safe direction is unit-testable — that
+ * contract ("never fail a run that would have worked") is the only thing that
+ * makes a pre-install check safe, and it lives entirely in which branches return
+ * `undefined`.
+ *
+ * @param cliVersion the CLI's own version; `showcase` pins the showcase to it.
+ */
+export function declaredRuntimesFromPackument(packument, cliVersion) {
+    // A pinned version that is NOT published is "cannot say", never "ask latest":
+    // a different version's declaration is a different answer, and a wrong
+    // "unsupported" is precisely the failure this must not introduce. (A dev or
+    // pre-release CLI is the normal way to reach this.)
+    const version = cliVersion ?? packument['dist-tags']?.latest;
+    const entry = version ? packument.versions?.[version] : undefined;
+    if (!entry)
+        return undefined;
+    return readDeclaredRuntimes(entry);
+}
 /**
  * Run a showcase on a non-gjs runtime (node/bun/deno). Resolves the package,
  * validates it against the showcase's `gjsify.example.runtimes` declaration
@@ -237,6 +344,19 @@ async function resolveShowcaseDir(showcase, cliVersion, extraSpecs = []) {
  * node), resolves its `--app node` bundle and launches it via the shared runner.
  */
 async function runShowcaseOnRuntime(showcase, runtime, cliVersion) {
+    // PRE-FLIGHT, before anything is downloaded. Only for the dlx path: a local
+    // showcase resolves with no network and no install, so there is nothing to
+    // pre-empt there and the on-disk check below is already free.
+    if (resolveLocalShowcaseDir(showcase) === null) {
+        const preflight = await preflightDeclaredRuntimes(showcase, cliVersion);
+        if (preflight !== undefined) {
+            const support = checkRuntimeSupported(runtime, preflight, showcase.name);
+            if (!support.ok) {
+                console.error(support.message);
+                return process.exit(1);
+            }
+        }
+    }
     let pkgDir;
     try {
         // `@gjsify/node-gi` is the `gi://` bridge the `--app node` bundle
@@ -248,7 +368,7 @@ async function runShowcaseOnRuntime(showcase, runtime, cliVersion) {
         // it supplies the bridge. Pinned to the CLI's version like the showcase
         // itself, so the bridge and the bundle move together.
         const nodeGiSpec = cliVersion ? `@gjsify/node-gi@${cliVersion}` : '@gjsify/node-gi';
-        pkgDir = await resolveShowcaseDir(showcase, cliVersion, [nodeGiSpec]);
+        pkgDir = await resolveShowcaseDir(showcase, cliVersion, [nodeGiSpec, ...gtkRuntimeSpecs(cliVersion)]);
     }
     catch (err) {
         console.error(`Could not resolve showcase "${showcase.name}": ${err.message}`);

package/lib/utils/install-global.d.ts

@@ -114,8 +114,57 @@ export interface LinkedBin {
  *   simplicity and so we don't need to discriminate by runtime here.
  */
 export declare function linkGlobalBins(packageNames: string[], layout: GlobalLayout): LinkedBin[];
+/**
+ * Is the global layout the user's own, or has a caller redirected it?
+ *
+ * `GJSIFY_GLOBAL_PREFIX` / `GJSIFY_GLOBAL_BIN_DIR` are the escape hatches
+ * {@link defaultGlobalLayout} documents for tests, and a caller that sets them
+ * has taken over placement — so "which `gjsify` will PATH resolve next" stops
+ * being a question about THEIR intent. `self-update` gates its fatal PATH check
+ * on this: without it, every harness installing into a temp prefix it never put
+ * on PATH is told its update did not take effect, which is true and useless.
+ * Caught by `tests/e2e/global-install-engine`.
+ *
+ * @param env injectable so both answers are testable without mutating the real
+ *   environment mid-suite.
+ */
+export declare function globalLayoutIsDefault(env?: NodeJS.ProcessEnv): boolean;
 /** Returns `true` if `binDir` is on the user's PATH. */
 export declare function binDirOnPath(binDir: string): boolean;
+/** Injection points for {@link resolveBinOnPath} — see its `platform` note. */
+export interface ResolveBinOnPathOptions {
+    /** PATH to search. Defaults to `process.env.PATH`. */
+    pathValue?: string;
+    /** PATHEXT to honour on win32. Defaults to `process.env.PATHEXT` or cmd.exe's set. */
+    pathExt?: string;
+    /** Host platform. Defaults to `process.platform`. */
+    platform?: NodeJS.Platform;
+    /** File-existence probe. Defaults to a real `fs.existsSync`. */
+    exists?: (file: string) => boolean;
+}
+/**
+ * Resolve `binName` the way the user's shell will: the FIRST hit in PATH order.
+ *
+ * WHY THIS IS NOT `binDirOnPath`. That answers "is our dir on PATH", which is
+ * necessary but not sufficient for anything that CHANGES which binary runs:
+ * `~/.local/bin` can be on PATH and still lose to an npm-global `gjsify` earlier
+ * in it. `self-update` reported "Updated to v0.31.0" on exactly that host while
+ * the shell kept resolving a v0.26.0 install five releases behind — and the user
+ * then re-hit a bug fixed three releases earlier and reported it as new (#1064).
+ * "Which one wins" is the question, so this returns the winning PATH.
+ *
+ * WINDOWS. An extension-less name is not executable there; cmd.exe and pwsh
+ * append each `PATHEXT` entry, which is how the `.cmd` shim `bin-shim.ts` writes
+ * gets found. The bare name is probed LAST so a git-bash/MSYS `sh` shim is still
+ * reported rather than missed. `platform`/`pathExt`/`exists` are injectable for
+ * the same reason `dirLinkTarget` takes `linkType`: nothing in CI resolves a bin
+ * on a Windows host, so an injected `'win32'` is the ONLY way that branch is ever
+ * EXECUTED — and an unexecutable Windows branch is exactly how the `'dir'` bug in
+ * `dir-link.ts` shipped.
+ *
+ * @returns the absolute path of the winning candidate, or `null` when PATH holds none.
+ */
+export declare function resolveBinOnPath(binName: string, opts?: ResolveBinOnPathOptions): string | null;
 /**
  * Extracts the package name from a spec like `name@1.2`, `@scope/name`,
  * or `@scope/name@latest`. Returns the unchanged string for plain names.

package/lib/utils/install-global.js

@@ -297,12 +297,100 @@ function readShebangOf(file) {
 function readJson(file) {
     return JSON.parse(fs.readFileSync(file, 'utf-8'));
 }
+/**
+ * Is the global layout the user's own, or has a caller redirected it?
+ *
+ * `GJSIFY_GLOBAL_PREFIX` / `GJSIFY_GLOBAL_BIN_DIR` are the escape hatches
+ * {@link defaultGlobalLayout} documents for tests, and a caller that sets them
+ * has taken over placement — so "which `gjsify` will PATH resolve next" stops
+ * being a question about THEIR intent. `self-update` gates its fatal PATH check
+ * on this: without it, every harness installing into a temp prefix it never put
+ * on PATH is told its update did not take effect, which is true and useless.
+ * Caught by `tests/e2e/global-install-engine`.
+ *
+ * @param env injectable so both answers are testable without mutating the real
+ *   environment mid-suite.
+ */
+export function globalLayoutIsDefault(env = process.env) {
+    return !env.GJSIFY_GLOBAL_PREFIX && !env.GJSIFY_GLOBAL_BIN_DIR;
+}
+/**
+ * The path module for a TARGET platform, not for the host.
+ *
+ * Load-bearing for every function below that takes a `platform`. `path.resolve`
+ * is host-bound: on Linux `path.resolve('C:\\tools')` returns
+ * `<cwd>/C:\tools`, because posix has no notion of a drive letter. So a function
+ * that accepts `platform` and then calls the host's `path` is only pretending to
+ * be portable — it silently mangles Windows input everywhere except Windows,
+ * which is exactly the class of bug an injected platform is supposed to expose.
+ * Caught by `resolve-bin-on-path.spec.ts`, which asserts real `C:\…` semantics
+ * from Linux.
+ */
+function pathFor(platform) {
+    return platform === 'win32' ? path.win32 : path.posix;
+}
+/** PATH split into resolved directory entries, in search order. */
+function searchPathEntries(pathValue, platform) {
+    const p = pathFor(platform);
+    const sep = platform === 'win32' ? ';' : ':';
+    return pathValue
+        .split(sep)
+        .filter(Boolean)
+        .map((entry) => p.resolve(entry));
+}
 /** Returns `true` if `binDir` is on the user's PATH. */
 export function binDirOnPath(binDir) {
-    const PATH = process.env.PATH ?? '';
-    const sep = process.platform === 'win32' ? ';' : ':';
-    const want = path.resolve(binDir);
-    return PATH.split(sep).some((entry) => entry && path.resolve(entry) === want);
+    const want = pathFor(process.platform).resolve(binDir);
+    return searchPathEntries(process.env.PATH ?? '', process.platform).includes(want);
+}
+/** cmd.exe's default when PATHEXT is unset. `.CMD` is the one npm-style shims need. */
+const DEFAULT_PATHEXT = '.COM;.EXE;.BAT;.CMD;.VBS;.JS;.WS;.MSC';
+/**
+ * Resolve `binName` the way the user's shell will: the FIRST hit in PATH order.
+ *
+ * WHY THIS IS NOT `binDirOnPath`. That answers "is our dir on PATH", which is
+ * necessary but not sufficient for anything that CHANGES which binary runs:
+ * `~/.local/bin` can be on PATH and still lose to an npm-global `gjsify` earlier
+ * in it. `self-update` reported "Updated to v0.31.0" on exactly that host while
+ * the shell kept resolving a v0.26.0 install five releases behind — and the user
+ * then re-hit a bug fixed three releases earlier and reported it as new (#1064).
+ * "Which one wins" is the question, so this returns the winning PATH.
+ *
+ * WINDOWS. An extension-less name is not executable there; cmd.exe and pwsh
+ * append each `PATHEXT` entry, which is how the `.cmd` shim `bin-shim.ts` writes
+ * gets found. The bare name is probed LAST so a git-bash/MSYS `sh` shim is still
+ * reported rather than missed. `platform`/`pathExt`/`exists` are injectable for
+ * the same reason `dirLinkTarget` takes `linkType`: nothing in CI resolves a bin
+ * on a Windows host, so an injected `'win32'` is the ONLY way that branch is ever
+ * EXECUTED — and an unexecutable Windows branch is exactly how the `'dir'` bug in
+ * `dir-link.ts` shipped.
+ *
+ * @returns the absolute path of the winning candidate, or `null` when PATH holds none.
+ */
+export function resolveBinOnPath(binName, opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const pathValue = opts.pathValue ?? process.env.PATH ?? '';
+    const exists = opts.exists ?? fs.existsSync;
+    // On win32 the extensions come FIRST (what cmd.exe/pwsh actually launch) and
+    // the bare name last (git-bash). Elsewhere there is only the bare name.
+    const suffixes = platform === 'win32'
+        ? [
+            ...(opts.pathExt ?? process.env.PATHEXT ?? DEFAULT_PATHEXT)
+                .split(';')
+                .filter(Boolean)
+                .map((ext) => (ext.startsWith('.') ? ext : `.${ext}`)),
+            '',
+        ]
+        : [''];
+    const p = pathFor(platform);
+    for (const dir of searchPathEntries(pathValue, platform)) {
+        for (const suffix of suffixes) {
+            const candidate = p.join(dir, `${binName}${suffix}`);
+            if (exists(candidate))
+                return candidate;
+        }
+    }
+    return null;
 }
 /**
  * Extracts the package name from a spec like `name@1.2`, `@scope/name`,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/cli",
-    "version": "0.31.0",
+    "version": "0.32.0",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -134,19 +134,19 @@
         "cli"
     ],
     "dependencies": {
-        "@gjsify/buffer": "^0.31.0",
-        "@gjsify/create-app": "^0.31.0",
-        "@gjsify/node-globals": "^0.31.0",
-        "@gjsify/node-polyfills": "^0.31.0",
-        "@gjsify/npm-registry": "^0.31.0",
-        "@gjsify/resolve-npm": "^0.31.0",
-        "@gjsify/rolldown-plugin-gjsify": "^0.31.0",
-        "@gjsify/rolldown-plugin-pnp": "^0.31.0",
-        "@gjsify/semver": "^0.31.0",
-        "@gjsify/tar": "^0.31.0",
-        "@gjsify/tsc": "^0.31.0",
-        "@gjsify/web-polyfills": "^0.31.0",
-        "@gjsify/workspace": "^0.31.0",
+        "@gjsify/buffer": "^0.32.0",
+        "@gjsify/create-app": "^0.32.0",
+        "@gjsify/node-globals": "^0.32.0",
+        "@gjsify/node-polyfills": "^0.32.0",
+        "@gjsify/npm-registry": "^0.32.0",
+        "@gjsify/resolve-npm": "^0.32.0",
+        "@gjsify/rolldown-plugin-gjsify": "^0.32.0",
+        "@gjsify/rolldown-plugin-pnp": "^0.32.0",
+        "@gjsify/semver": "^0.32.0",
+        "@gjsify/tar": "^0.32.0",
+        "@gjsify/tsc": "^0.32.0",
+        "@gjsify/web-polyfills": "^0.32.0",
+        "@gjsify/workspace": "^0.32.0",
         "cosmiconfig": "^9.0.2",
         "get-tsconfig": "^4.14.0",
         "pkg-types": "^2.3.1",
@@ -154,13 +154,13 @@
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@gjsify/unit": "^0.31.0",
+        "@gjsify/unit": "^0.32.0",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/oxfmt-native": "^0.31.0",
-        "@gjsify/rolldown-native": "^0.31.0"
+        "@gjsify/oxfmt-native": "^0.32.0",
+        "@gjsify/rolldown-native": "^0.32.0"
     },
     "peerDependenciesMeta": {
         "@gjsify/oxfmt-native": {