@gjsify/cli 0.21.0 → 0.23.0

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,126 @@
 //     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 used by the
+ * Vala/meson bridges, which stage into `prebuilds/linux-x86_64/` (the output
+ * of `uname -m` on the build host).
+ */
+const NODE_ARCH_TO_UNAME = {
+    x64: 'x86_64',
+    arm64: 'aarch64',
+    arm: 'armv7',
+    ia32: 'i686',
+};
+/**
+ * Arch spellings that name the same target. 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.
+ */
+const ARCH_ALIASES = {
+    x64: 'x86_64',
+    amd64: 'x86_64',
+    arm64: 'aarch64',
+};
+/**
+ * Canonical `<os>-<arch>` form so `linux-x64` and `linux-x86_64` — or
+ * `darwin-arm64` and `darwin-aarch64` — 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.
+ *
+ * There are two live spellings in this repo and neither can be declared the
+ * winner:
+ *
+ *   * the Vala/meson bridges stage `prebuilds/linux-x86_64/` — uname-style,
+ *     because the meson jobs name the directory after `uname -m`;
+ *   * `@gjsify/node-gi` (and `@gjsify/napi`'s prebuild staging) use
+ *     `prebuilds/${process.platform}-${process.arch}/` — node-style
+ *     (`linux-x64`, `darwin-arm64`, `win32-x64`).
+ *
+ * So we probe both, and — when the package declares `gjsify.platforms` — we
+ * probe the package's OWN spelling first. That is strictly better than
+ * guessing: a package that declares `darwin-arm64` tells us the exact
+ * directory name it stages, whatever convention it picked.
+ *
+ * Ordering of the generic fallbacks is per-OS rather than fixed, so the first
+ * probe is the spelling that platform's toolchain actually produces:
+ * uname-style on Linux (`linux-x86_64`), node-style on macOS/Windows
+ * (`darwin-arm64`, `win32-x64` — on Apple silicon `uname -m` also reports
+ * `arm64`, so there node-style *is* the native spelling).
+ *
+ * @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 unameArch = NODE_ARCH_TO_UNAME[arch] ?? arch;
+    const preferred = platform === 'linux' ? unameArch : arch;
+    const alternate = platform === 'linux' ? arch : unameArch;
+    const generic = [`${platform}-${preferred}`, `${platform}-${alternate}`];
+    const hostCanonical = canonicalPlatformToken(generic[0]);
+    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) === hostCanonical)
+            push(declared);
+    }
+    // 2. The two generic spellings.
+    for (const name of generic)
+        push(name);
+    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 +156,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 +171,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 +220,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 +250,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/install-backend-native.d.ts

@@ -4,11 +4,66 @@ interface ParsedSpec {
     name: string;
     range: string;
 }
+interface ResolvedNode {
+    /** Package name (e.g. `@gjsify/cli`, `lodash`). */
+    name: string;
+    version: string;
+    tarballUrl: string;
+    integrity?: string;
+    /** Where this node lives relative to the install prefix. Always
+     *  starts with `node_modules/`; nested entries look like
+     *  `node_modules/<parent>/node_modules/<dep>`. */
+    installPath: string;
+    /** `dependencies` field from the packument (range strings keyed by name). */
+    dependencies: Record<string, string>;
+    /** `optionalDependencies` field from the packument. */
+    optionalDependencies: Record<string, string>;
+    bin?: string | Record<string, string>;
+}
 export interface InstalledTopLevel {
     name: string;
     version: string;
 }
 export declare function installPackagesNative(opts: InstallOptions): Promise<InstalledTopLevel[]>;
+/**
+ * Warn about a native package that installed WITHOUT a usable binary.
+ *
+ * gjsify install is node-free (it runs under GJS) and does NOT run a package's
+ * `install`/`postinstall` lifecycle script — running e.g. `node-gyp rebuild` would
+ * need Node + a C++ toolchain, breaking that property (see the header's "out of
+ * scope"). Such a package works only if it SHIPS a prebuild for the platform (the
+ * sanctioned path — `prebuilds/<platform>-<arch>/…`) or is later built by hand. When
+ * neither is present the package silently loads no binary (the `@gjsify/node-gi
+ * 0.21.0` case: installed, but `node_gi.node` absent → the consumer hit a runtime
+ * failure with no hint). Surface it at install time with an actionable line. Pure
+ * detection — no script is run, so node-free-ness is preserved.
+ */
+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
@@ -121,6 +122,7 @@ async function installPackagesNativeLocked(opts, npmrc, log) {
     log('install: downloading %d tarball(s)', nodes.length);
     await downloadAndExtractAll(nodes, opts.prefix, npmrc, log, opts.signal, progress);
     await linkBins(nodes, opts.prefix, log);
+    warnMissingNativeBuilds(nodes, opts.prefix, log);
     log('install: done');
     // Surface the top-level requested packages so callers can update
     // package.json with the resolved version (mirrors `npm install --save`
@@ -132,6 +134,69 @@ function errMsg(err) {
         return err.message;
     return String(err);
 }
+/**
+ * Warn about a native package that installed WITHOUT a usable binary.
+ *
+ * gjsify install is node-free (it runs under GJS) and does NOT run a package's
+ * `install`/`postinstall` lifecycle script — running e.g. `node-gyp rebuild` would
+ * need Node + a C++ toolchain, breaking that property (see the header's "out of
+ * scope"). Such a package works only if it SHIPS a prebuild for the platform (the
+ * sanctioned path — `prebuilds/<platform>-<arch>/…`) or is later built by hand. When
+ * neither is present the package silently loads no binary (the `@gjsify/node-gi
+ * 0.21.0` case: installed, but `node_gi.node` absent → the consumer hit a runtime
+ * failure with no hint). Surface it at install time with an actionable line. Pure
+ * detection — no script is run, so node-free-ness is preserved.
+ */
+export function warnMissingNativeBuilds(nodes, prefix, log) {
+    const plat = process.platform;
+    const arch = process.arch;
+    const buildScriptKeys = ['preinstall', 'install', 'postinstall'];
+    for (const n of nodes) {
+        const pkgDir = path.join(prefix, n.installPath);
+        let scripts;
+        try {
+            const manifest = JSON.parse(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf8'));
+            scripts = manifest?.scripts;
+        }
+        catch {
+            continue; // no/unreadable manifest — nothing to assess
+        }
+        if (!scripts || typeof scripts !== 'object')
+            continue;
+        const scriptKey = buildScriptKeys.find((k) => typeof scripts[k] === 'string');
+        if (scriptKey === undefined)
+            continue; // no native build lifecycle script
+        // Does it ship a prebuild for THIS platform (any prebuilds/<plat>-…/ with a
+        // file), or carry a locally-built build/Release binary?
+        let hasBinary = false;
+        try {
+            const prebuildsDir = path.join(pkgDir, 'prebuilds');
+            for (const entry of fs.readdirSync(prebuildsDir)) {
+                if (entry.startsWith(`${plat}-`) && fs.readdirSync(path.join(prebuildsDir, entry)).length > 0) {
+                    hasBinary = true;
+                    break;
+                }
+            }
+        }
+        catch {
+            /* no prebuilds dir */
+        }
+        if (!hasBinary) {
+            try {
+                const releaseDir = path.join(pkgDir, 'build', 'Release');
+                hasBinary = fs.readdirSync(releaseDir).some((f) => f.endsWith('.node') || f.endsWith('.so'));
+            }
+            catch {
+                /* no build/Release */
+            }
+        }
+        if (!hasBinary) {
+            log('install: WARNING — %s declares a native `%s` build script but ships no %s-%s prebuild, ' +
+                'and gjsify install does not run build scripts (node-free). It will not load until built: ' +
+                'run `node-gyp rebuild` in %s, or use a version that ships a %s-%s prebuild.', n.name, scriptKey, plat, arch, n.installPath, plat, arch);
+        }
+    }
+}
 function topLevelResolutions(specs, nodes) {
     // Top-level installs live at `node_modules/<name>` (no nesting). Build
     // a name → root-node lookup limited to the top-level set.
@@ -918,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;
@@ -1050,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
@@ -1077,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;
 /**