@gjsify/cli 0.22.0 → 0.24.1

package/lib/utils/bin-shim.js

@@ -0,0 +1,246 @@
+// SPDX-License-Identifier: ISC
+// Adapted from npm's `cmd-shim`
+// (refs/npm-cli/node_modules/bin-links/node_modules/cmd-shim/lib/index.js and
+// .../to-batch-syntax.js). Copyright (c) npm, Inc. and Contributors. ISC.
+// Modifications: rewritten as pure TypeScript string builders (no fs, no
+// `process.platform` read) so the Windows branch is unit-testable from a Linux
+// host, and split into two entry points — one for linking a package bin that
+// carries its own shebang (`buildCmdShim`, the faithful npm port) and one for
+// the *generated* launchers gjsify writes itself (`buildLauncherShims`).
+//
+// WHY THIS EXISTS
+//
+// A bin is made runnable on POSIX with a symlink into `node_modules/.bin/`;
+// the kernel reads the target's `#!` line and runs the interpreter. Windows has
+// neither of those mechanisms: `.bin/<name>` with no extension is not on
+// PATHEXT, and there is no shebang handling. npm's answer — the de-facto
+// standard every Windows Node toolchain follows — is to write three sibling
+// files:
+//
+//   `<name>`       a POSIX `sh` script (used by git-bash / MSYS / WSL / Cygwin)
+//   `<name>.cmd`   a batch file (used by cmd.exe and by `npx`/`npm run`)
+//   `<name>.ps1`   a PowerShell script (used by pwsh)
+//
+// All three re-derive the interpreter from the target's shebang, so a bin
+// declaring `#!/usr/bin/env node` and one declaring `#!/usr/bin/env -S gjs -m`
+// both work without the caller knowing which it is.
+// Matches `#!<prog> <args>` and `#!/usr/bin/env [-S] [K=V ...] <prog> <args>`.
+// Verbatim from cmd-shim's `shebangExpr`.
+const SHEBANG_RE = /^#!\s*(?:\/usr\/bin\/env\s+(?:-S\s+)?((?:[^ \t=]+=[^ \t=]+\s+)*))?([^ \t]+)(.*)$/;
+/**
+ * Parse the first line of a bin file. Returns `null` when it is not a shebang
+ * — cmd-shim then treats the target as directly executable.
+ */
+export function parseShebang(firstLine) {
+    const m = SHEBANG_RE.exec(firstLine.trim());
+    if (!m)
+        return null;
+    return { variables: m[1] ?? '', prog: m[2] ?? '', args: m[3] ?? '' };
+}
+/** `$VAR` / `${VAR}` → `%VAR%`. Port of cmd-shim's `replaceDollarWithPercentPair`. */
+function replaceDollarWithPercentPair(value) {
+    return value.replace(/\$\{?([^$@#?\- \t{}:]+)\}?/g, (_all, name) => `%${name}%`);
+}
+/** `K=V K2=V2 ` → `@SET K=V\r\n@SET K2=V2\r\n`. Port of `convertToSetCommands`. */
+function convertToSetCommands(variableString) {
+    let out = '';
+    for (const declaration of variableString.split(' ')) {
+        const eq = declaration.indexOf('=');
+        if (eq <= 0)
+            continue;
+        const key = declaration.slice(0, eq).trim();
+        const value = declaration.slice(eq + 1).trim();
+        if (key && value)
+            out += `@SET ${key}=${replaceDollarWithPercentPair(value)}\r\n`;
+    }
+    return out;
+}
+// The `:find_dp0` subroutine trick — see npm/cmd-shim#10 and npm/cli#969.
+const CMD_HEAD = '@ECHO off\r\n' +
+    'GOTO start\r\n' +
+    ':find_dp0\r\n' +
+    'SET dp0=%~dp0\r\n' +
+    'EXIT /b\r\n' +
+    ':start\r\n' +
+    'SETLOCAL\r\n' +
+    'CALL :find_dp0\r\n';
+// Resolves `$basedir` and, under git-bash/MSYS/WSL, the Windows-shaped
+// `$basedir_win` the interpreter needs for its script argument.
+const SH_BASEDIR = `basedir=$(dirname "$(echo "$0" | sed -e 's,\\\\,/,g')")\n` +
+    'basedir_win="$basedir"\n' +
+    '\n' +
+    'case `uname -a` in\n' +
+    '  *CYGWIN*|*MINGW*|*MSYS*)\n' +
+    '    if command -v cygpath > /dev/null 2>&1; then\n' +
+    '      basedir_win=`cygpath -w "$basedir"`\n' +
+    '    fi\n' +
+    '  ;;\n' +
+    '  *WSL2*)\n' +
+    '    if command -v wslpath > /dev/null 2>&1; then\n' +
+    '      basedir_win="$(wslpath -w "$basedir" 2> /dev/null)"\n' +
+    '      if [ $? -ne 0 ] || [ -z "$basedir_win" ]; then\n' +
+    '        echo "Error: wslpath failed to convert path. WSL environment may be misconfigured." >&2\n' +
+    '        exit 1\n' +
+    '      fi\n' +
+    '    fi\n' +
+    '  ;;\n' +
+    'esac\n' +
+    '\n';
+const PS1_HEAD = '#!/usr/bin/env pwsh\n' +
+    '$basedir=Split-Path $MyInvocation.MyCommand.Definition -Parent\n' +
+    '\n' +
+    '$exe=""\n' +
+    'if ($PSVersionTable.PSVersion -lt "6.0" -or $IsWindows) {\n' +
+    '  # Fix case when both the Windows and Linux builds of Node\n' +
+    '  # are installed in the same directory\n' +
+    '  $exe=".exe"\n' +
+    '}\n';
+/**
+ * Build the three Windows shim files for a package bin.
+ *
+ * @param relTargetPosix POSIX-style path from the `.bin` directory to the real
+ * bin file (i.e. `path.relative(binDir, target)` with `\` normalised to `/`).
+ * @param shebang the target's parsed `#!` line, or `null` when it has none —
+ * in which case the shims invoke the target directly, matching cmd-shim.
+ */
+export function buildCmdShim(relTargetPosix, shebang) {
+    let shTarget = relTargetPosix.split('\\').join('/');
+    let target = shTarget.split('/').join('\\');
+    let pwshTarget = shTarget;
+    let prog = shebang?.prog ?? '';
+    let args = shebang?.args ?? '';
+    const variables = shebang?.variables ?? '';
+    let shProg = prog ? prog.split('\\').join('/') : '';
+    let pwshProg = shProg ? `"${shProg}$exe"` : '';
+    let longProg = '';
+    let shLongProg = '';
+    let pwshLongProg = '';
+    if (!prog) {
+        prog = `"%dp0%\\${target}"`;
+        shProg = `"$basedir/${shTarget}"`;
+        pwshProg = shProg;
+        args = '';
+        target = '';
+        shTarget = '';
+        pwshTarget = '';
+    }
+    else {
+        longProg = `"%dp0%\\${prog}.exe"`;
+        shLongProg = `"$basedir/${prog}"`;
+        pwshLongProg = `"$basedir/${prog}$exe"`;
+        target = `"%dp0%\\${target}"`;
+        shTarget = `"$basedir_win/${shTarget}"`;
+        pwshTarget = `"$basedir/${pwshTarget}"`;
+    }
+    let cmd;
+    if (longProg) {
+        const trimmedArgs = args.trim();
+        cmd =
+            CMD_HEAD +
+                convertToSetCommands(variables) +
+                '\r\n' +
+                `IF EXIST ${longProg} (\r\n` +
+                `  SET "_prog=${longProg.replace(/(^")|("$)/g, '')}"\r\n` +
+                ') ELSE (\r\n' +
+                `  SET "_prog=${prog.replace(/(^")|("$)/g, '')}"\r\n` +
+                ')\r\n' +
+                '\r\n' +
+                // Suppresses the "Terminate Batch Job? (Y/n)" prompt — npm/cli#969.
+                'endLocal & goto #_undefined_# 2>NUL || title %COMSPEC% & ' +
+                `set PATHEXT=%PATHEXT:;.JS;=;% & "%_prog%" ${trimmedArgs} ${target} %*\r\n`;
+    }
+    else {
+        cmd = `${CMD_HEAD}${prog} ${args} ${target} %*\r\n`;
+    }
+    let sh = `#!/bin/sh\n${SH_BASEDIR}`;
+    if (shLongProg) {
+        sh +=
+            `PROG_EXE=${shLongProg.replace(/"$/, '.exe"')}\n` +
+                'if ! [ -x "$PROG_EXE" ]; then\n' +
+                `  PROG_EXE=${shLongProg}\n` +
+                '  if ! [ -x "$PROG_EXE" ]; then\n' +
+                `    PROG_EXE=${shProg}\n` +
+                '    if ! [ -x "$PROG_EXE" ]; then\n' +
+                `      PROG_EXE=${shProg}.exe\n` +
+                '    fi\n' +
+                '  fi\n' +
+                'fi\n' +
+                '\n' +
+                `exec ${variables}"$PROG_EXE" ${args} ${shTarget} "$@"\n`;
+    }
+    else {
+        sh += `exec ${shProg} ${args} ${shTarget} "$@"\n`;
+    }
+    let ps1 = PS1_HEAD;
+    if (pwshLongProg) {
+        ps1 +=
+            '$ret=0\n' +
+                `if (Test-Path ${pwshLongProg}) {\n` +
+                '  # Support pipeline input\n' +
+                '  if ($MyInvocation.ExpectingInput) {\n' +
+                `    $input | & ${pwshLongProg} ${args} ${pwshTarget} $args\n` +
+                '  } else {\n' +
+                `    & ${pwshLongProg} ${args} ${pwshTarget} $args\n` +
+                '  }\n' +
+                '  $ret=$LASTEXITCODE\n' +
+                '} else {\n' +
+                '  # Support pipeline input\n' +
+                '  if ($MyInvocation.ExpectingInput) {\n' +
+                `    $input | & ${pwshProg} ${args} ${pwshTarget} $args\n` +
+                '  } else {\n' +
+                `    & ${pwshProg} ${args} ${pwshTarget} $args\n` +
+                '  }\n' +
+                '  $ret=$LASTEXITCODE\n' +
+                '}\n' +
+                'exit $ret\n';
+    }
+    else {
+        ps1 +=
+            '# Support pipeline input\n' +
+                'if ($MyInvocation.ExpectingInput) {\n' +
+                `  $input | & ${pwshProg} ${pwshTarget} $args\n` +
+                '} else {\n' +
+                `  & ${pwshProg} ${pwshTarget} $args\n` +
+                '}\n' +
+                'exit $LASTEXITCODE\n';
+    }
+    return { sh, cmd, ps1 };
+}
+/**
+ * `.cmd` / `.ps1` companions for a launcher gjsify *generates* itself
+ * (`linkGlobalBins`, `writeWorkspaceBinShims`) rather than links.
+ *
+ * Those launchers are not a symlink to a bin with a shebang — they are a
+ * hand-written `sh` script that picks an interpreter and passes an ABSOLUTE
+ * script path. `buildCmdShim` cannot express them (it derives everything from
+ * a relative target plus a shebang), so this builds the equivalent batch /
+ * PowerShell form: optional `SET` / `$env:` assignments, then
+ * `<interpreter> [args] "<absolute target>" <argv>`.
+ *
+ * Note the interpreter is invoked by NAME (resolved through `PATH`), matching
+ * the `sh` launcher's `exec gjs`/`exec node`. A missing interpreter therefore
+ * fails the same way on every OS.
+ */
+export function buildLauncherShims(opts) {
+    const { interpreter, interpreterArgs = [], target, prependEnv = {} } = opts;
+    const winTarget = target.split('/').join('\\');
+    const argv = interpreterArgs.length > 0 ? `${interpreterArgs.join(' ')} ` : '';
+    const entries = Object.entries(prependEnv);
+    let cmd = CMD_HEAD;
+    for (const [key, value] of entries)
+        cmd += `@SET "${key}=${value};%${key}%"\r\n`;
+    cmd += `${interpreter} ${argv}"${winTarget}" %*\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';
+    return { cmd, ps1 };
+}

package/lib/utils/build-cache.d.ts

@@ -1,6 +1,12 @@
 import { type Workspace } from '@gjsify/workspace';
-/** Bump to invalidate every existing cache entry (schema/semantic changes). */
-export declare const BUILD_CACHE_LAYOUT_VERSION = "v1";
+/**
+ * Bump to invalidate every existing cache entry (schema/semantic changes).
+ *
+ * v2: output ownership moved from the whole candidate dir to per-child
+ * "output units" (`lib/esm` vs `lib/types`) — a v1 manifest recording `lib`
+ * would restore over the sibling subtree a different script owns.
+ */
+export declare const BUILD_CACHE_LAYOUT_VERSION = "v2";
 /** Conventional per-package build output directories, checked in this order. */
 export declare const OUTPUT_DIR_CANDIDATES: readonly ["lib", "dist", "dist-templates"];
 /** Keep at most this many keys per package; evict the least recently stored/used. */
@@ -46,14 +52,44 @@ export declare function hashPackageInputs(location: string): string;
  */
 export declare function hashOutputDirs(location: string, dirs: readonly string[]): string;
 /**
- * Cheap per-dir change signature (existence + file list + sizes + mtimes).
+ * The cacheable output units of a package — the granularity at which a cache
+ * entry claims ownership.
+ *
+ * A candidate dir (`lib/`) is NOT automatically one unit, because the package
+ * convention splits it between two DIFFERENT scripts: `build:gjsify` writes
+ * `lib/esm/**` (bundler output) and `build:types` writes `lib/types/**` (the
+ * `gjsify tsc` declaration emit). At whole-`lib/` granularity both scripts
+ * claim the same unit, so a cache HIT on either one does its delete-then-copy
+ * over the WHOLE tree and silently destroys the other's output — measured:
+ * `build:gjsify` hitting the cache after `build:types` ran left the package
+ * with no `lib/types/` at all, and since the script never ran, nothing
+ * regenerated them. That ships a tarball whose `types` entry point does not
+ * exist (the failure `assertTypeDeclarationsShipped` exists to catch).
+ *
+ * So: when a candidate dir contains ONLY sub-directories, each child is its
+ * own unit (`lib/esm`, `lib/types`) and the two scripts stop overlapping. A
+ * candidate holding loose files degrades to the whole dir — a build writing
+ * directly into `lib/` genuinely owns it, and the coarse unit is still
+ * correct, just less precise.
+ *
+ * The safety rule is unchanged and in fact tightened: a unit the build never
+ * modifies is never recorded, so it can never be restored over (`@gjsify/tsc`'s
+ * committed, no-build `lib/lib*.d.ts` are loose files → one `lib` unit → never
+ * touched by any build → never captured).
+ */
+export declare function outputUnits(location: string): string[];
+/**
+ * Cheap per-unit change signature (existence + file list + sizes + mtimes).
  * Taken BEFORE running the script and compared AFTER, to detect which output
- * dirs the build actually modified. Content hashing is deliberately avoided
+ * units the build actually modified. Content hashing is deliberately avoided
  * here — a build that rewrites identical bytes still bumps mtimes, and that
- * is exactly the "this dir belongs to the build" signal we want.
+ * is exactly the "this unit belongs to the build" signal we want.
+ *
+ * Units absent before the run are recorded as `null` so a freshly created
+ * `lib/esm` still reads as "modified".
  */
 export declare function snapshotOutputDirs(location: string): Record<string, string | null>;
-/** Output dirs whose signature changed (or that newly appeared) since `before`. */
+/** Output units whose signature changed (or that newly appeared) since `before`. */
 export declare function modifiedOutputDirs(location: string, before: Record<string, string | null>): string[];
 export interface ComposeCacheKeyInput {
     script: string;

package/lib/utils/build-cache.js

@@ -27,14 +27,20 @@
 //     outputs/<dir>/…        — copies of the output dirs the build MODIFIED
 //
 // Output contract: after a successful (miss) run, the candidate output dirs
-// (`lib/`, `dist/`, `dist-templates/`) are compared against a pre-run
-// snapshot and ONLY the dirs the script actually created/modified are
-// stored. On a later hit, EXACTLY those dirs are replaced (delete-then-copy
-// within the package). This is the safety rule from the v0.x CI incident
-// where a raw YAML cache restored over a package whose committed `lib/` is
-// tracked source: a dir the build never touches is never recorded, so it can
-// never be restored over. Packages that don't define the script at all are
-// filtered out by the calling command and never reach the cache.
+// (`lib/`, `dist/`, `dist-templates/`) are expanded into OUTPUT UNITS — the
+// candidate's immediate sub-directories when it holds only directories
+// (`lib/esm`, `lib/types`), else the candidate itself — compared against a
+// pre-run snapshot, and ONLY the units the script actually created/modified
+// are stored. On a later hit, EXACTLY those units are replaced
+// (delete-then-copy within the package). This is the safety rule from the
+// v0.x CI incident where a raw YAML cache restored over a package whose
+// committed `lib/` is tracked source: a unit the build never touches is never
+// recorded, so it can never be restored over. The sub-directory granularity
+// additionally keeps the two halves of the dual emit apart — `build:gjsify`
+// (→ `lib/esm`) and `build:types` (→ `lib/types`) both write under `lib/`, and
+// at whole-dir granularity a cache hit on one WIPED the other's output. See
+// `outputUnits`. Packages that don't define the script at all are filtered out
+// by the calling command and never reach the cache.
 //
 // Growth is bounded: at most MAX_KEYS_PER_PACKAGE entries per package,
 // oldest (by last store/use) evicted.
@@ -47,8 +53,14 @@ import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, readd
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { buildDependencyGraph } from '@gjsify/workspace';
-/** Bump to invalidate every existing cache entry (schema/semantic changes). */
-export const BUILD_CACHE_LAYOUT_VERSION = 'v1';
+/**
+ * Bump to invalidate every existing cache entry (schema/semantic changes).
+ *
+ * v2: output ownership moved from the whole candidate dir to per-child
+ * "output units" (`lib/esm` vs `lib/types`) — a v1 manifest recording `lib`
+ * would restore over the sibling subtree a different script owns.
+ */
+export const BUILD_CACHE_LAYOUT_VERSION = 'v2';
 /** Conventional per-package build output directories, checked in this order. */
 export const OUTPUT_DIR_CANDIDATES = ['lib', 'dist', 'dist-templates'];
 /** Keep at most this many keys per package; evict the least recently stored/used. */
@@ -223,51 +235,111 @@ export function hashOutputDirs(location, dirs) {
     return hash.digest('hex');
 }
 /**
- * Cheap per-dir change signature (existence + file list + sizes + mtimes).
- * Taken BEFORE running the script and compared AFTER, to detect which output
- * dirs the build actually modified. Content hashing is deliberately avoided
- * here — a build that rewrites identical bytes still bumps mtimes, and that
- * is exactly the "this dir belongs to the build" signal we want.
+ * The cacheable output units of a package — the granularity at which a cache
+ * entry claims ownership.
+ *
+ * A candidate dir (`lib/`) is NOT automatically one unit, because the package
+ * convention splits it between two DIFFERENT scripts: `build:gjsify` writes
+ * `lib/esm/**` (bundler output) and `build:types` writes `lib/types/**` (the
+ * `gjsify tsc` declaration emit). At whole-`lib/` granularity both scripts
+ * claim the same unit, so a cache HIT on either one does its delete-then-copy
+ * over the WHOLE tree and silently destroys the other's output — measured:
+ * `build:gjsify` hitting the cache after `build:types` ran left the package
+ * with no `lib/types/` at all, and since the script never ran, nothing
+ * regenerated them. That ships a tarball whose `types` entry point does not
+ * exist (the failure `assertTypeDeclarationsShipped` exists to catch).
+ *
+ * So: when a candidate dir contains ONLY sub-directories, each child is its
+ * own unit (`lib/esm`, `lib/types`) and the two scripts stop overlapping. A
+ * candidate holding loose files degrades to the whole dir — a build writing
+ * directly into `lib/` genuinely owns it, and the coarse unit is still
+ * correct, just less precise.
+ *
+ * The safety rule is unchanged and in fact tightened: a unit the build never
+ * modifies is never recorded, so it can never be restored over (`@gjsify/tsc`'s
+ * committed, no-build `lib/lib*.d.ts` are loose files → one `lib` unit → never
+ * touched by any build → never captured).
  */
-export function snapshotOutputDirs(location) {
-    const snapshot = {};
+export function outputUnits(location) {
+    const units = [];
     for (const dir of OUTPUT_DIR_CANDIDATES) {
         const abs = join(location, dir);
-        if (!existsSync(abs)) {
-            snapshot[dir] = null;
+        if (!existsSync(abs))
             continue;
+        let entries;
+        try {
+            entries = readdirSync(abs).filter((name) => name !== 'node_modules');
         }
-        const files = [];
-        walkFiles(abs, dir, files);
-        const hash = createHash('sha256');
-        for (const f of files) {
-            let stamp = 'link';
-            if (f.link === undefined) {
-                try {
-                    const st = lstatSync(f.abs);
-                    stamp = `${st.size}:${st.mtimeMs}`;
-                }
-                catch {
-                    stamp = 'gone';
-                }
+        catch {
+            continue;
+        }
+        // `lstatSync` rather than `withFileTypes` — the CLI also runs from the
+        // GJS bundle, where `@gjsify/fs` is the readdir implementation.
+        const allDirs = entries.every((name) => {
+            try {
+                return lstatSync(join(abs, name)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+        if (entries.length === 0 || !allDirs) {
+            units.push(dir);
+            continue;
+        }
+        for (const child of [...entries].sort())
+            units.push(`${dir}/${child}`);
+    }
+    return units;
+}
+/** Cheap change signature for ONE unit (file list + sizes + mtimes). */
+function signatureOf(location, unit) {
+    const files = [];
+    walkFiles(join(location, unit), unit, files);
+    const hash = createHash('sha256');
+    for (const f of files) {
+        let stamp = 'link';
+        if (f.link === undefined) {
+            try {
+                const st = lstatSync(f.abs);
+                stamp = `${st.size}:${st.mtimeMs}`;
+            }
+            catch {
+                stamp = 'gone';
             }
-            hash.update(`${f.rel} ${stamp}\n`);
         }
-        snapshot[dir] = hash.digest('hex');
+        hash.update(`${f.rel} ${stamp}\n`);
     }
+    return hash.digest('hex');
+}
+/**
+ * Cheap per-unit change signature (existence + file list + sizes + mtimes).
+ * Taken BEFORE running the script and compared AFTER, to detect which output
+ * units the build actually modified. Content hashing is deliberately avoided
+ * here — a build that rewrites identical bytes still bumps mtimes, and that
+ * is exactly the "this unit belongs to the build" signal we want.
+ *
+ * Units absent before the run are recorded as `null` so a freshly created
+ * `lib/esm` still reads as "modified".
+ */
+export function snapshotOutputDirs(location) {
+    const snapshot = {};
+    for (const dir of OUTPUT_DIR_CANDIDATES)
+        snapshot[dir] = null;
+    for (const unit of outputUnits(location))
+        snapshot[unit] = signatureOf(location, unit);
     return snapshot;
 }
-/** Output dirs whose signature changed (or that newly appeared) since `before`. */
+/** Output units whose signature changed (or that newly appeared) since `before`. */
 export function modifiedOutputDirs(location, before) {
-    const after = snapshotOutputDirs(location);
     const modified = [];
-    for (const dir of OUTPUT_DIR_CANDIDATES) {
-        // Newly created, deleted, or changed — all count as "the build owns
-        // this dir". A dir that is now ABSENT cannot be stored, though.
-        if (after[dir] !== before[dir] && after[dir] !== null)
-            modified.push(dir);
+    for (const unit of outputUnits(location)) {
+        // Newly created or changed — both mean "the build owns this unit".
+        // A unit that is now ABSENT cannot be stored and is simply not listed.
+        if (signatureOf(location, unit) !== (before[unit] ?? null))
+            modified.push(unit);
     }
-    return modified;
+    return modified.sort();
 }
 /** Deterministic cache key (32 hex chars) from all invalidation ingredients. */
 export function composeCacheKey(input) {

package/lib/utils/detect-native-packages.d.ts

@@ -1,9 +1,91 @@
 export interface NativePackage {
     /** npm package name, e.g. "@gjsify/webgl" */
     name: string;
-    /** Absolute path to the arch-specific prebuilds dir, e.g. "/…/@gjsify/webgl/prebuilds/linux-x86_64" */
+    /** Absolute path to the arch-specific prebuilds dir, e.g. "/…/@gjsify/webgl/prebuilds/linux-x64" */
     prebuildsDir: string;
 }
+/** The host target a resolution is performed for. Defaults to the running process. */
+export interface HostTarget {
+    /** `process.platform` value — `linux` | `darwin` | `win32` | … */
+    platform?: string;
+    /** `process.arch` value — `x64` | `arm64` | `ppc64` | `s390x` | `riscv64` | … */
+    arch?: string;
+}
+/**
+ * Environment a GJS process needs so `gi://Gjsify…` imports resolve against
+ * the detected prebuilds. `GI_TYPELIB_PATH` is universal (girepository reads
+ * it on every OS); the *library* search path is whatever the host's dynamic
+ * loader actually consults, which is a different variable per OS — see
+ * {@link buildNativeEnv}.
+ *
+ * The index signature exists for the Windows case, where the key is the host's
+ * own `PATH` spelling (`Path` on a stock Windows env block) rather than a
+ * fixed literal.
+ */
+export interface NativeEnv {
+    GI_TYPELIB_PATH: string;
+    /** ELF loader (Linux and other ELF platforms). */
+    LD_LIBRARY_PATH?: string;
+    /** Mach-O loader (macOS). `dyld` ignores `LD_LIBRARY_PATH` entirely. */
+    DYLD_LIBRARY_PATH?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * 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 declare function canonicalPlatformToken(token: string): string;
+/**
+ * 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 declare function prebuildDirCandidates(platform: string, arch: string, declaredPlatforms?: readonly string[] | undefined): string[];
+/**
+ * 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 declare function resolvePrebuildDirName(input: {
+    platform: string;
+    arch: string;
+    declaredPlatforms?: readonly string[] | undefined;
+    existingDirs: readonly string[];
+}): string | null;
 /**
  * Walk up the directory tree from `startDir` and merge native packages found
  * in every `node_modules` encountered.
@@ -16,13 +98,42 @@ export interface NativePackage {
  *
  * 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 declare function detectNativePackages(startDir: string): NativePackage[];
+export declare function detectNativePackages(startDir: string, target?: HostTarget): NativePackage[];
 /**
- * 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 declare function buildNativeEnv(packages: NativePackage[]): {
-    LD_LIBRARY_PATH: string;
-    GI_TYPELIB_PATH: string;
+export declare function libraryPathVar(platform: string): {
+    name: string;
+    separator: string;
 };
+/**
+ * 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 declare function buildNativeEnv(packages: NativePackage[], opts?: {
+    platform?: string;
+    env?: Record<string, string | undefined>;
+}): NativeEnv;