@gjsify/cli 0.22.0 → 0.24.1

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

@@ -1,6 +1,7 @@
 // Utility to find npm packages with gjsify native prebuilds.
-// Packages declare: "gjsify": { "prebuilds": "<dir>" } in their package.json.
-// The CLI uses this to auto-set LD_LIBRARY_PATH / GI_TYPELIB_PATH before running gjs.
+// Packages declare: "gjsify": { "prebuilds": "<dir>" } in their package.json,
+// and (since the OS-axis audit) the `<os>-<arch>` targets they promise in
+// "gjsify": { "platforms": [...] }.
 //
 // One algorithm — `detectNativePackages(startDir)` — walks up from `startDir`
 // and exhaustively scans every `node_modules` it finds. Used by:
@@ -10,24 +11,138 @@
 //     their full transitive prebuild set picked up automatically. The
 //     transitive walk is what makes `gjsify showcase` / `gjsify dlx` work
 //     for packages whose Vala typelibs live in *indirect* deps.
+//
+// PLATFORM RESOLUTION IS A PURE FUNCTION. Everything that depends on the host
+// OS/CPU lives in `resolvePrebuildDirName()` / `buildNativeEnv()`, both of
+// which take `platform` / `arch` as parameters instead of reading
+// `process.platform` inline. That is what makes the darwin and win32 branches
+// unit-testable from a Linux host (see `detect-native-packages.spec.ts`) —
+// the host values are only read at the outermost call site, as a default.
 import { readdirSync, existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { readPackageJson } from './pkg-json.js';
-/** Map Node.js process.arch values to the convention used in prebuilds/ directories. */
-function nodeArchToLinuxArch(arch) {
-    const map = {
-        x64: 'x86_64',
-        arm64: 'aarch64',
-        arm: 'armv7',
-        ia32: 'i686',
+/**
+ * Map a Node `process.arch` value to the uname-style spelling the Vala/meson
+ * bridges used to stage into (`prebuilds/linux-x86_64/`, the output of
+ * `uname -m` on the build host).
+ *
+ * LEGACY. Every `@gjsify/*` package now declares and stages the node spelling
+ * (`linux-x64`); this table exists only so the CLI can still load a prebuild
+ * out of a tarball published before the rename. See
+ * {@link prebuildDirCandidates}.
+ */
+const NODE_ARCH_TO_LEGACY_UNAME = {
+    x64: 'x86_64',
+    arm64: 'aarch64',
+    arm: 'armv7',
+    ia32: 'i686',
+};
+/**
+ * Arch spellings that name the same target, folded onto the NODE spelling.
+ * Mirrors `ARCH_ALIASES` in `scripts/audit-runtimes.mjs` — that script
+ * canonicalises `package.json#gjsify.platforms` the same way for the
+ * platform-support matrix, and the two MUST agree or a package could pass the
+ * audit while the CLI fails to find its artifact.
+ *
+ * The direction matters: `${process.platform}-${process.arch}` is what a
+ * running process can compute about itself, so folding *onto* it means the
+ * host identity never has to be translated in the hot path.
+ */
+const ARCH_ALIASES = {
+    x86_64: 'x64',
+    amd64: 'x64',
+    aarch64: 'arm64',
+};
+/**
+ * Canonical `<os>-<arch>` form — the node spelling — so `linux-x86_64` and
+ * `linux-x64` compare equal. Only the *arch* half is normalised; the OS half
+ * is always a `process.platform` token (`linux`/`darwin`/`win32`), which has
+ * no competing spelling.
+ */
+export function canonicalPlatformToken(token) {
+    const dash = token.indexOf('-');
+    if (dash < 0)
+        return token;
+    const os = token.slice(0, dash);
+    const arch = token.slice(dash + 1);
+    return `${os}-${ARCH_ALIASES[arch] ?? arch}`;
+}
+/**
+ * The prebuild directory names to probe for a host, most-specific first.
+ *
+ * The canonical name is `${process.platform}-${process.arch}` — `linux-x64`,
+ * `linux-arm64`, `darwin-arm64`, `win32-x64`. Every package in the release
+ * train declares it (`gjsify.platforms`), `scripts/stage-prebuild.mjs` is the
+ * only thing that creates it, and `scripts/audit-runtimes.mjs --check` rejects
+ * any other spelling, so the three can no longer drift.
+ *
+ * Two probes remain BEHIND that canonical name, and both are backward
+ * compatibility with tarballs already on npm — not a second convention:
+ *
+ *   1. **The package's own declared spelling.** A tarball published before the
+ *      rename declares (and ships) `linux-x86_64`; probing its declaration
+ *      first loads it without the CLI having to guess. This is also what makes
+ *      the rename work in the OTHER direction — an older CLI resolving a newer
+ *      package — because `canonicalPlatformToken` folds both spellings onto
+ *      one form at both ends.
+ *   2. **The legacy uname spelling.** Only reachable for a package that ships
+ *      a prebuild dir and declares NO `gjsify.platforms` at all — i.e. a
+ *      tarball predating the OS-axis audit, or a third-party package using
+ *      `gjsify.prebuilds` without the declaration. Inside this repo the audit
+ *      makes that state impossible.
+ *
+ * Both are pure array entries matched against an already-read directory
+ * listing — no extra I/O — so tolerance on the READ side costs nothing, while
+ * the single spelling is enforced everywhere a name is WRITTEN.
+ *
+ * @param platform `process.platform` value.
+ * @param arch `process.arch` value.
+ * @param declaredPlatforms `package.json#gjsify.platforms`, when present.
+ */
+export function prebuildDirCandidates(platform, arch, declaredPlatforms) {
+    const canonical = `${platform}-${arch}`;
+    const legacyArch = NODE_ARCH_TO_LEGACY_UNAME[arch] ?? arch;
+    const out = [];
+    const push = (name) => {
+        if (!out.includes(name))
+            out.push(name);
     };
-    return map[arch] ?? arch;
+    // 1. The package's own declared spelling for THIS host, if it declares one.
+    for (const declared of declaredPlatforms ?? []) {
+        if (typeof declared !== 'string')
+            continue;
+        if (canonicalPlatformToken(declared) === canonical)
+            push(declared);
+    }
+    // 2. The canonical node spelling — what everything in the train stages.
+    push(canonical);
+    // 3. The legacy uname spelling, for undeclared pre-rename tarballs.
+    push(`${platform}-${legacyArch}`);
+    return out;
+}
+/**
+ * Pick the prebuild directory a host should load, given the directories that
+ * actually exist under `<pkg>/<prebuilds>/`.
+ *
+ * Pure: no `process.*` reads, no filesystem access. This is the function the
+ * darwin and win32 branches are unit-tested through on a Linux host.
+ *
+ * @returns the chosen directory NAME (not a path), or `null` when the package
+ * ships nothing loadable on this host.
+ */
+export function resolvePrebuildDirName(input) {
+    const { platform, arch, declaredPlatforms, existingDirs } = input;
+    for (const candidate of prebuildDirCandidates(platform, arch, declaredPlatforms)) {
+        if (existingDirs.includes(candidate))
+            return candidate;
+    }
+    return null;
 }
 /**
  * Scan all packages in a node_modules directory for gjsify native prebuilds.
  * Handles scoped packages (@scope/name) as well as flat packages.
  */
-function scanNodeModules(nodeModulesDir, arch) {
+function scanNodeModules(nodeModulesDir, target) {
     const results = [];
     if (!existsSync(nodeModulesDir))
         return results;
@@ -53,14 +168,14 @@ function scanNodeModules(nodeModulesDir, arch) {
             }
             for (const scopedPkg of scopeEntries) {
                 const pkgDir = join(scopeDir, scopedPkg);
-                const native = checkPackage(pkgDir, `${entry}/${scopedPkg}`, arch);
+                const native = checkPackage(pkgDir, `${entry}/${scopedPkg}`, target);
                 if (native)
                     results.push(native);
             }
         }
         else {
             const pkgDir = join(nodeModulesDir, entry);
-            const native = checkPackage(pkgDir, entry, arch);
+            const native = checkPackage(pkgDir, entry, target);
             if (native)
                 results.push(native);
         }
@@ -68,20 +183,42 @@ function scanNodeModules(nodeModulesDir, arch) {
     return results;
 }
 /** Check a single package directory for gjsify prebuilds metadata. */
-function checkPackage(pkgDir, name, arch) {
+function checkPackage(pkgDir, name, target) {
     const pkgJson = readPackageJson(join(pkgDir, 'package.json'));
     if (!pkgJson)
         return null;
     const gjsifyMeta = pkgJson['gjsify'];
     if (!gjsifyMeta || typeof gjsifyMeta !== 'object')
         return null;
-    const prebuildsField = gjsifyMeta['prebuilds'];
+    const meta = gjsifyMeta;
+    const prebuildsField = meta['prebuilds'];
     if (typeof prebuildsField !== 'string')
         return null;
-    const prebuildsDir = join(pkgDir, prebuildsField, `linux-${arch}`);
-    if (!existsSync(prebuildsDir))
+    const declaredRaw = meta['platforms'];
+    const declaredPlatforms = Array.isArray(declaredRaw)
+        ? declaredRaw.filter((p) => typeof p === 'string')
+        : undefined;
+    const prebuildsRoot = join(pkgDir, prebuildsField);
+    let existingDirs;
+    try {
+        // A prebuild dir may legitimately be a symlink (workspace/dev layouts),
+        // so accept both real directories and links.
+        existingDirs = readdirSync(prebuildsRoot, { withFileTypes: true })
+            .filter((e) => e.isDirectory() || e.isSymbolicLink())
+            .map((e) => e.name);
+    }
+    catch {
+        return null;
+    }
+    const dirName = resolvePrebuildDirName({
+        platform: target.platform,
+        arch: target.arch,
+        declaredPlatforms,
+        existingDirs,
+    });
+    if (!dirName)
         return null;
-    return { name, prebuildsDir };
+    return { name, prebuildsDir: join(prebuildsRoot, dirName) };
 }
 /**
  * Walk up the directory tree from `startDir` and merge native packages found
@@ -95,16 +232,22 @@ function checkPackage(pkgDir, name, arch) {
  *
  * Deduplication: the first match for a given package name wins (closer
  * node_modules shadows outer ones), matching Node.js resolution semantics.
+ *
+ * @param target overrides the host platform/arch. Only tests pass this; the
+ * production call sites take the defaults.
  */
-export function detectNativePackages(startDir) {
-    const arch = nodeArchToLinuxArch(process.arch);
+export function detectNativePackages(startDir, target = {}) {
+    const resolved = {
+        platform: target.platform ?? process.platform,
+        arch: target.arch ?? process.arch,
+    };
     const merged = [];
     const seen = new Set();
     let dir = resolve(startDir);
     while (true) {
         const nodeModulesDir = join(dir, 'node_modules');
         if (existsSync(nodeModulesDir)) {
-            for (const pkg of scanNodeModules(nodeModulesDir, arch)) {
+            for (const pkg of scanNodeModules(nodeModulesDir, resolved)) {
                 if (seen.has(pkg.name))
                     continue;
                 seen.add(pkg.name);
@@ -119,14 +262,55 @@ export function detectNativePackages(startDir) {
     return merged;
 }
 /**
- * Build the LD_LIBRARY_PATH and GI_TYPELIB_PATH env var values for the detected native packages.
- * Prepends the new paths to any existing values from the environment.
+ * The environment-variable name the host's dynamic loader consults for an
+ * additional shared-library search path, plus the separator its search paths
+ * use.
+ *
+ *   * **Linux / other ELF** — `LD_LIBRARY_PATH`, `:`-separated.
+ *   * **macOS** — `DYLD_LIBRARY_PATH`. `dyld` does not read `LD_LIBRARY_PATH`
+ *     at all, which is why `.github/workflows/napi.yml` sets `DYLD_LIBRARY_PATH`
+ *     by hand on every macOS gate step.
+ *   * **Windows** — there is no dedicated variable; `LoadLibrary` searches the
+ *     process `PATH`, `;`-separated. This is the same mechanism
+ *     `@gjsify/node-gi`'s `maybePrependGtkRuntimeDllPath()` uses to make its
+ *     bundled GTK DLLs resolvable.
  */
-export function buildNativeEnv(packages) {
+export function libraryPathVar(platform) {
+    if (platform === 'darwin')
+        return { name: 'DYLD_LIBRARY_PATH', separator: ':' };
+    if (platform === 'win32')
+        return { name: 'PATH', separator: ';' };
+    return { name: 'LD_LIBRARY_PATH', separator: ':' };
+}
+/**
+ * Build the typelib + shared-library search-path environment for the detected
+ * native packages. Prepends the new paths to any existing values.
+ *
+ * Pure w.r.t. the host: `platform` and `env` are parameters, so the darwin and
+ * win32 branches are exercised by unit tests running on Linux.
+ *
+ * On Windows the `PATH` key is written back under the *host's own* spelling
+ * (a stock Windows env block uses `Path`) — Windows env names are
+ * case-insensitive, but a plain JS object is not, and `{...process.env,
+ * PATH: …}` would hand a child process two competing entries.
+ */
+export function buildNativeEnv(packages, opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const env = opts.env ?? process.env;
     const dirs = packages.map((p) => p.prebuildsDir);
-    const existing_ld = process.env['LD_LIBRARY_PATH'] ?? '';
-    const existing_gi = process.env['GI_TYPELIB_PATH'] ?? '';
-    const LD_LIBRARY_PATH = [...dirs, ...(existing_ld ? [existing_ld] : [])].join(':');
-    const GI_TYPELIB_PATH = [...dirs, ...(existing_gi ? [existing_gi] : [])].join(':');
-    return { LD_LIBRARY_PATH, GI_TYPELIB_PATH };
+    // GLib's search-path separator is `;` on Windows (G_SEARCHPATH_SEPARATOR),
+    // `:` everywhere else — the same split as the loader variable below.
+    const giSeparator = platform === 'win32' ? ';' : ':';
+    const { name: libVarName, separator: libSeparator } = libraryPathVar(platform);
+    // Windows env names are case-insensitive; reuse whatever casing the host
+    // block already uses so we replace rather than shadow it.
+    const libVarKey = platform === 'win32'
+        ? (Object.keys(env).find((k) => k.toLowerCase() === libVarName.toLowerCase()) ?? libVarName)
+        : libVarName;
+    const prepend = (value, separator) => [...dirs, ...(value ? [value] : [])].join(separator);
+    const out = {
+        GI_TYPELIB_PATH: prepend(env['GI_TYPELIB_PATH'], giSeparator),
+    };
+    out[libVarKey] = prepend(env[libVarKey], libSeparator);
+    return out;
 }

package/lib/utils/gjs-bundle-guard.d.ts

@@ -0,0 +1,32 @@
+/** The one bundler-output field this guard needs, from either engine. */
+export interface GuardedChunk {
+    /** Emitted chunk name, for the error message. */
+    fileName?: string;
+    /** External specifiers the chunk STATICALLY imports (rollup/rolldown contract). */
+    imports?: readonly string[];
+}
+/**
+ * Bare `node:` specifiers a `--app gjs` bundle may keep as static imports.
+ *
+ * Deliberately EMPTY. Every Node builtin has an `@gjsify/*` polyfill that
+ * `--app gjs` aliases to, so there is no specifier that both survives into the
+ * module graph and loads under GJS. Reading the graph instead of the text is
+ * what keeps this list empty — the entries an earlier text-scanning version
+ * needed (`node:module`, `node:process`) were quoted lookalikes, never imports.
+ *
+ * Add an entry ONLY with a comment naming why GJS can resolve it. Each one is a
+ * specifier this guard can no longer catch for real.
+ */
+export declare const GJS_ALLOWED_NODE_IMPORTS: readonly string[];
+/**
+ * The distinct bare `node:` specifiers `chunks` statically import, minus the
+ * allowlist. Sorted, so the error message and any test are stable.
+ */
+export declare function findDisallowedNodeImports(chunks: readonly GuardedChunk[], allowed?: readonly string[]): string[];
+/**
+ * Throw when a built `--app gjs` bundle statically imports Node builtins.
+ *
+ * @param chunks   the emitted chunks, as reported by the bundler
+ * @param outfile  path of the bundle, for the error message
+ */
+export declare function assertGjsBundleLoadable(chunks: readonly GuardedChunk[], outfile: string): void;

package/lib/utils/gjs-bundle-guard.js

@@ -0,0 +1,103 @@
+// Build-time guard: a `--app gjs` bundle must not keep bare `node:` imports.
+//
+// Stock GJS has NO `node:` module loader. A single surviving
+// `import … from "node:fs"` makes it abort the ENTIRE module graph before one
+// line executes:
+//
+//   Gjs-WARNING **: JS ERROR: ImportError: Unsupported URI scheme for importing: node
+//   Gjs-CRITICAL **: Failed to resolve imports for module: '…/dist/cli.gjs.mjs'
+//
+// `--app gjs` maps every Node builtin to its `@gjsify/*` polyfill, so a healthy
+// bundle has ZERO of them. But when an alias TARGET cannot be resolved — the
+// classic case being a workspace checkout whose `@gjsify/*` packages have no
+// built `lib/`, so `exports["."]` points at a file that does not exist — the
+// bundler falls back to treating the import as external and re-emits the
+// ORIGINAL `node:*` specifier. That is a WARNING, not an error: the build
+// "succeeds" and writes a bundle that cannot load anywhere. It cost three red
+// CI jobs to notice, because nothing between `gjsify build` and CI ever
+// executes the emitted GJS bundle (tsc, lint, format and the unit/e2e suites
+// all run the Node entry).
+//
+// The pre-commit hook makes it worse rather than better: it rebuilds and
+// AUTO-STAGES `dist/cli.gjs.mjs`, so a developer whose checkout cannot resolve
+// the polyfills commits a broken artifact without ever seeing it.
+//
+// So the refusal belongs at build time, in `gjsify build --app gjs` itself —
+// not in a git hook and not in one package's `build:gjs-bundle` script. The
+// invariant is a property of the ARTIFACT, and every showcase, every downstream
+// app (buchhaltung, bauplaner, Learn6502) and CI all produce it through this
+// one code path. A hook would protect only commits in this repo; a per-package
+// script would protect one package.
+//
+// ## The oracle is the module graph, NOT the emitted text
+//
+// The first cut of this guard grepped the output for `from "node:…"`. That is
+// wrong, and CI caught it: `@gjsify/process`'s own test bundle names a case
+//
+//   await it(`named-import hrtime (from "node:process") preserves .bigint`, …)
+//
+// so the phrase appears verbatim inside a STRING, in a bundle that loads and
+// runs under GJS perfectly well. The same trap sits in `@gjsify/cli`'s own
+// bundle, which embeds `giNodeShimSource()`'s `--app node` codegen template
+// (`import { createRequire } from 'node:module';`). Telling a statement from a
+// quoted lookalike needs a JS lexer — but the bundler already did that work:
+// every chunk carries the list of external specifiers it actually imports. That
+// list is exact, engine-independent (npm `rolldown` returns it directly,
+// `@gjsify/rolldown-native` forwards it through `synthRolldownOutput`), and
+// free.
+//
+// Scope is STATIC imports, which is precisely the failure mode above: they are
+// resolved when GJS links the module, so one bad specifier kills the whole
+// bundle. A dynamic `import('node:x')` throws lazily at its call site instead —
+// a real bug, but not "the artifact cannot load", and not what this gate is
+// for.
+/**
+ * Bare `node:` specifiers a `--app gjs` bundle may keep as static imports.
+ *
+ * Deliberately EMPTY. Every Node builtin has an `@gjsify/*` polyfill that
+ * `--app gjs` aliases to, so there is no specifier that both survives into the
+ * module graph and loads under GJS. Reading the graph instead of the text is
+ * what keeps this list empty — the entries an earlier text-scanning version
+ * needed (`node:module`, `node:process`) were quoted lookalikes, never imports.
+ *
+ * Add an entry ONLY with a comment naming why GJS can resolve it. Each one is a
+ * specifier this guard can no longer catch for real.
+ */
+export const GJS_ALLOWED_NODE_IMPORTS = [];
+/**
+ * The distinct bare `node:` specifiers `chunks` statically import, minus the
+ * allowlist. Sorted, so the error message and any test are stable.
+ */
+export function findDisallowedNodeImports(chunks, allowed = GJS_ALLOWED_NODE_IMPORTS) {
+    const found = new Set();
+    for (const chunk of chunks) {
+        for (const specifier of chunk.imports ?? []) {
+            if (!specifier.startsWith('node:'))
+                continue;
+            if (allowed.includes(specifier))
+                continue;
+            found.add(specifier);
+        }
+    }
+    return [...found].sort();
+}
+/**
+ * Throw when a built `--app gjs` bundle statically imports Node builtins.
+ *
+ * @param chunks   the emitted chunks, as reported by the bundler
+ * @param outfile  path of the bundle, for the error message
+ */
+export function assertGjsBundleLoadable(chunks, outfile) {
+    const offenders = findDisallowedNodeImports(chunks);
+    if (offenders.length === 0)
+        return;
+    throw new Error(`gjsify build --app gjs: ${outfile} still imports ${offenders.length} bare \`node:\` module(s), ` +
+        'which stock GJS cannot resolve — it would fail at load with ' +
+        '"ImportError: Unsupported URI scheme for importing: node".\n' +
+        offenders.map((s) => `  - ${s}`).join('\n') +
+        '\n\nThese should have been aliased to their `@gjsify/*` polyfills. The usual cause is that the ' +
+        'alias TARGET could not be resolved, so the bundler externalised the import instead (look for ' +
+        'UNRESOLVED_IMPORT warnings above): e.g. a workspace checkout whose `@gjsify/*` packages have no ' +
+        'built `lib/`. Build the workspace first (`gjsify run build:infra`), or fix the resolution, then ' +
+        'rebuild.');
+}

package/lib/utils/install-backend-native.d.ts

@@ -41,5 +41,29 @@ export declare function installPackagesNative(opts: InstallOptions): Promise<Ins
 export declare function warnMissingNativeBuilds(nodes: ResolvedNode[], prefix: string, log: Logger): void;
 export declare function parseSpec(raw: string): ParsedSpec;
 export declare function pickVersion(packument: Packument, range: string, preferred?: string): string | null;
+/**
+ * Materialise ONE `node_modules/.bin/<name>` entry for `targetAbs`.
+ *
+ * Exported (and platform-injectable) so the Windows branch is unit-tested from
+ * a Linux host — the file layout and shim contents are asserted there; only the
+ * `symlinkSync`/`CreateSymbolicLink` syscall behaviour itself is OS-bound.
+ *
+ * POSIX: a relative symlink, with a copy as the fallback (some filesystems and
+ * container overlays reject symlinks).
+ *
+ * Windows: `.bin/<name>` is not on `PATHEXT` and Windows has no shebang
+ * handling, so a symlink OR a copy of a `#!/usr/bin/env node` script is
+ * unrunnable — and a *file* symlink additionally needs elevation or Developer
+ * Mode, so the previous code reliably fell into its copy fallback and produced
+ * a dead entry. npm solves this with three sibling files (`<name>` for
+ * git-bash/MSYS/WSL, `<name>.cmd` for cmd.exe, `<name>.ps1` for pwsh); we write
+ * the same set from the same templates. See `./bin-shim.ts`.
+ */
+export declare function writeBinEntry(opts: {
+    binDir: string;
+    binName: string;
+    targetAbs: string;
+    platform?: string;
+}): void;
 type Logger = (fmt: string, ...args: unknown[]) => void;
 export {};

package/lib/utils/install-backend-native.js

@@ -24,6 +24,7 @@ import { acquireInstallLock } from './install-lock.js';
 import { getCachedTarball, getForeignCachedTarball, putCachedTarball, } from './install-tarball-cache.js';
 import { getCachedPackument, putCachedPackument } from './install-packument-cache.js';
 import { assertNativeBackendNodeVersion } from './node-version.js';
+import { buildCmdShim, parseShebang } from './bin-shim.js';
 // 16-wide download pool. Matched to the shared Soup.Session's lifted
 // `max-conns-per-host` (see @gjsify/fetch `getSharedSession`) — a higher pool
 // here only translates into real concurrency because that cap was raised from
@@ -183,9 +184,7 @@ export function warnMissingNativeBuilds(nodes, prefix, log) {
         if (!hasBinary) {
             try {
                 const releaseDir = path.join(pkgDir, 'build', 'Release');
-                hasBinary = fs
-                    .readdirSync(releaseDir)
-                    .some((f) => f.endsWith('.node') || f.endsWith('.so'));
+                hasBinary = fs.readdirSync(releaseDir).some((f) => f.endsWith('.node') || f.endsWith('.so'));
             }
             catch {
                 /* no build/Release */
@@ -984,7 +983,11 @@ async function extractOne(node, prefix, npmrc, log, signal) {
         // so a read-only HOME / out-of-disk cache volume doesn't break the install.
         putCachedTarball(node.integrity, bytes);
     }
-    fs.rmSync(dest, { recursive: true, force: true });
+    // `rmWithRetry` (not a bare rmSync): on Windows the delete of a freshly
+    // extracted tree fails with EBUSY/EPERM while any handle is still open, and
+    // stays pending afterwards — so the mkdirSync on the next line would hit
+    // EPERM/ENOTEMPTY. No-op cost on POSIX. This runs for EVERY package.
+    rmWithRetry(dest);
     fs.mkdirSync(dest, { recursive: true });
     await extractWithStallGuard(bytes, dest, node, signal);
     return false;
@@ -1116,6 +1119,73 @@ function depth(installPath) {
     // `node_modules/foo` = 1, `node_modules/foo/node_modules/bar` = 2, etc.
     return installPath.split('/node_modules/').length;
 }
+/**
+ * Read a bin file's `#!` line, if it has one. Returns `null` for an
+ * unreadable/empty file or a first line that is not a shebang — the same
+ * fallbacks npm's cmd-shim applies (it then invokes the target directly).
+ */
+function readShebang(file) {
+    let head;
+    try {
+        head = fs.readFileSync(file, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    const firstLine = head.trimStart().split(/\r*\n/, 1)[0] ?? '';
+    return parseShebang(firstLine);
+}
+/**
+ * Materialise ONE `node_modules/.bin/<name>` entry for `targetAbs`.
+ *
+ * Exported (and platform-injectable) so the Windows branch is unit-tested from
+ * a Linux host — the file layout and shim contents are asserted there; only the
+ * `symlinkSync`/`CreateSymbolicLink` syscall behaviour itself is OS-bound.
+ *
+ * POSIX: a relative symlink, with a copy as the fallback (some filesystems and
+ * container overlays reject symlinks).
+ *
+ * Windows: `.bin/<name>` is not on `PATHEXT` and Windows has no shebang
+ * handling, so a symlink OR a copy of a `#!/usr/bin/env node` script is
+ * unrunnable — and a *file* symlink additionally needs elevation or Developer
+ * Mode, so the previous code reliably fell into its copy fallback and produced
+ * a dead entry. npm solves this with three sibling files (`<name>` for
+ * git-bash/MSYS/WSL, `<name>.cmd` for cmd.exe, `<name>.ps1` for pwsh); we write
+ * the same set from the same templates. See `./bin-shim.ts`.
+ */
+export function writeBinEntry(opts) {
+    const { binDir, binName, targetAbs } = opts;
+    const platform = opts.platform ?? process.platform;
+    const linkPath = path.join(binDir, binName);
+    if (platform === 'win32') {
+        const relPosix = path.relative(binDir, targetAbs).split('\\').join('/');
+        const { sh, cmd, ps1 } = buildCmdShim(relPosix, readShebang(targetAbs));
+        for (const [file, contents] of [
+            [linkPath, sh],
+            [`${linkPath}.cmd`, cmd],
+            [`${linkPath}.ps1`, ps1],
+        ]) {
+            rmWithRetry(file);
+            fs.writeFileSync(file, contents);
+            try {
+                fs.chmodSync(file, 0o755);
+            }
+            catch {
+                /* inert on Windows; harmless under WSL/MSYS */
+            }
+        }
+        return;
+    }
+    rmWithRetry(linkPath);
+    const rel = path.relative(binDir, targetAbs);
+    try {
+        fs.symlinkSync(rel, linkPath);
+    }
+    catch {
+        fs.copyFileSync(targetAbs, linkPath);
+        fs.chmodSync(linkPath, 0o755);
+    }
+}
 async function linkBins(nodes, prefix, log) {
     // Only root-level packages publish bins into the top-level
     // `node_modules/.bin/`. Nested-package bins are addressable by their
@@ -1143,23 +1213,26 @@ async function linkBins(nodes, prefix, log) {
             catch {
                 /* best effort */
             }
-            const linkPath = path.join(binDir, binName);
-            fs.rmSync(linkPath, { force: true });
-            const rel = path.relative(binDir, targetAbs);
-            try {
-                fs.symlinkSync(rel, linkPath);
-                created++;
-            }
-            catch {
-                fs.copyFileSync(targetAbs, linkPath);
-                fs.chmodSync(linkPath, 0o755);
-                created++;
-            }
+            writeBinEntry({ binDir, binName, targetAbs });
+            created++;
         }
     }
     if (created > 0)
         log('bin: linked %d entry(ies) under .bin/', created);
 }
+/**
+ * `fs.rmSync(..., { force: true })` with the Windows retry npm/rimraf apply.
+ *
+ * On Windows a delete fails with `EBUSY`/`EPERM` while any process holds a
+ * handle (antivirus scan, an editor, a still-terminating child), and the
+ * deletion stays *pending* until the last handle closes — so an immediately
+ * following create can hit `EPERM`/`ENOTEMPTY`. Node implements the retry loop
+ * for us behind `maxRetries`; it is a no-op on POSIX, where the first attempt
+ * always succeeds.
+ */
+function rmWithRetry(target) {
+    fs.rmSync(target, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+}
 function normalizeBin(pkgName, bin) {
     const out = new Map();
     if (typeof bin === 'string') {

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

@@ -86,6 +86,22 @@ export interface LinkedBin {
  *   simplicity and so we don't need to discriminate by runtime here.
  */
 export declare function linkGlobalBins(packageNames: string[], layout: GlobalLayout): LinkedBin[];
+/**
+ * Build the POSIX-sh `export` lines that prepend the given prebuild
+ * directories to GI_TYPELIB_PATH and the host's shared-library search path.
+ * Any pre-existing value inherited from the user's environment is preserved as
+ * a suffix so user-installed typelibs/libraries still resolve.
+ *
+ * The library variable is host-dependent — `LD_LIBRARY_PATH` on Linux,
+ * `DYLD_LIBRARY_PATH` on macOS (dyld never reads the ELF one), so a launcher
+ * written on a Mac used to export a variable nothing consults, leaving every
+ * `darwin-arm64` prebuild unloadable. `platform` is a parameter so both
+ * branches are unit-testable from either host.
+ *
+ * Returns the empty string when no prebuilds were found — avoids emitting an
+ * inert assignment in the launcher.
+ */
+export declare function buildLauncherEnvPreamble(prebuildsDirs: string[], platform?: string): string;
 /** Returns `true` if `binDir` is on the user's PATH. */
 export declare function binDirOnPath(binDir: string): boolean;
 /**