@gjsify/cli 0.26.0 → 0.27.0

package/lib/commands/upgrade.js

@@ -448,10 +448,7 @@ function printTable(candidates) {
         'kind' +
         ANSI.reset;
     console.log(head);
-    console.log(' '.repeat(idxW + 2) +
-        ANSI.dim +
-        '─'.repeat(nameW + fanW + curW + newW + 16) +
-        ANSI.reset);
+    console.log(' '.repeat(idxW + 2) + ANSI.dim + '─'.repeat(nameW + fanW + curW + newW + 16) + ANSI.reset);
     for (let i = 0; i < candidates.length; i++) {
         const c = candidates[i];
         const idx = `${i + 1}.`.padEnd(idxW);

package/lib/templates/install.mjs.tmpl

@@ -26,8 +26,11 @@
  * Test hooks (set by tests/e2e/install-script/run.mjs):
  *   GJSIFY_INSTALL_BOOTSTRAP_URL  override the cli.gjs.mjs download origin
  *                                 (accepts file:// for offline tests)
- *   GJSIFY_INSTALL_BOOTSTRAP_SHA256_URL  override the .sha256 companion URL
- *                                 (set to empty string to skip SHA-256)
+ *   GJSIFY_INSTALL_BOOTSTRAP_SHA256_URL  override the .sha256 companion URL.
+ *                                 An EMPTY string is the only way to install
+ *                                 without verification, and it warns loudly; a
+ *                                 digest URL that is set but unreachable is a
+ *                                 hard failure, never a silent downgrade.
  *   GJSIFY_GLOBAL_PREFIX          override install prefix (forwarded to cli)
  *   GJSIFY_GLOBAL_BIN_DIR         override bin dir (forwarded to cli)
  *   GJSIFY_INSTALL_REGISTRY       override npm registry (forwarded as npm_config_registry)
@@ -50,6 +53,11 @@ const DEFAULT_BOOTSTRAP_SHA256_URL = `${DEFAULT_BOOTSTRAP_URL}.sha256`;
 
 const USER_AGENT = 'gjsify-installer/1.0';
 
+// The bootstrap cache is CONTENT-ADDRESSED: `cli-<sha256>.gjs.mjs`. See
+// `resolveBootstrap()` for why the digest, not a fixed name, keys it.
+const CACHE_PREFIX = 'cli-';
+const CACHE_SUFFIX = '.gjs.mjs';
+
 function info(msg) {
     print(`[gjsify] ${msg}`);
 }
@@ -168,35 +176,118 @@ function writeBytes(path, bytes) {
     Gio.File.new_for_path(path).replace_contents(bytes, null, false, Gio.FileCreateFlags.REPLACE_DESTINATION, null);
 }
 
-async function downloadBootstrap(session, bootstrapUrl, sha256Url) {
-    info(`Downloading bootstrap from ${bootstrapUrl} ...`);
-    const bundleBytes = await fetchBytes(session, bootstrapUrl);
-    if (sha256Url && sha256Url !== '') {
-        info('Verifying SHA-256 ...');
-        let sumExpected;
+function readBytesOrNull(path) {
+    try {
+        const [, bytes] = Gio.File.new_for_path(path).load_contents(null);
+        return bytes;
+    } catch {
+        // An absent — or unreadable, e.g. truncated by a killed earlier run —
+        // cache entry is a MISS, not an error. `load_contents` is a real
+        // `throws="1"` GIR call, so this catch has a genuine throw path.
+        return null;
+    }
+}
+
+/**
+ * Drop every other cached bootstrap so the content-addressed cache stays
+ * bounded. Each entry is a ~6.6 MB bundle and the digest changes with every
+ * release — without this, keying the cache by content would trade "the cache
+ * can never be warm" for "the cache grows forever".
+ */
+function pruneCache(dir, keepBasename) {
+    const children = Gio.File.new_for_path(dir).enumerate_children('standard::name', Gio.FileQueryInfoFlags.NONE, null);
+    for (;;) {
+        const info_ = children.next_file(null);
+        if (info_ === null) break;
+        const name = info_.get_name();
+        if (name === keepBasename || !name.startsWith(CACHE_PREFIX) || !name.endsWith(CACHE_SUFFIX)) continue;
+        Gio.File.new_for_path(GLib.build_filenamev([dir, name])).delete(null);
+    }
+}
+
+/**
+ * Resolve a VERIFIED bootstrap bundle and return its path.
+ *
+ * The digest is fetched BEFORE the bundle, and the cache is keyed by it. That
+ * ordering is the mechanism, not an optimisation — it fixes two independent
+ * defects that both came from doing it the other way round:
+ *
+ *   1. Verification was skippable by anyone who could break ONE request. The
+ *      bundle was downloaded first and verified after, and a failed `.sha256`
+ *      fetch merely logged "skipping verification" and carried on — so a proxy,
+ *      a 404, or a captive portal silently downgraded the install to no
+ *      verification at all. Fetching the digest first makes that impossible:
+ *      no digest, no install.
+ *   2. The cache could never be warm. It wrote a fixed `cli.gjs.mjs` and never
+ *      read it back, so every run re-downloaded ~6.6 MB. A content-addressed
+ *      name lets a matching entry short-circuit the download entirely.
+ *
+ * Skipping verification is still possible, but only as an EXPLICIT act
+ * (`GJSIFY_INSTALL_BOOTSTRAP_SHA256_URL=''`), and it says so on stderr.
+ */
+async function resolveBootstrap(session, bootstrapUrl, sha256Url) {
+    let expected = null;
+    if (sha256Url) {
+        info(`Fetching published SHA-256 from ${sha256Url} ...`);
+        let sumBytes;
         try {
-            const sumBytes = await fetchBytes(session, sha256Url);
-            sumExpected = new TextDecoder().decode(sumBytes).trim().split(/\s+/)[0];
+            sumBytes = await fetchBytes(session, sha256Url);
         } catch (err) {
-            error(`Could not fetch ${sha256Url} — skipping verification: ${err.message}`);
+            error(`Could not fetch ${sha256Url}: ${err.message}`);
+            error('Refusing to install an UNVERIFIED bootstrap bundle.');
+            error("To bootstrap without verification, set GJSIFY_INSTALL_BOOTSTRAP_SHA256_URL='' explicitly.");
+            exit(1);
         }
-        if (sumExpected) {
-            const sumActual = sha256Hex(bundleBytes);
-            if (sumExpected.toLowerCase() !== sumActual.toLowerCase()) {
-                error(`SHA-256 mismatch: expected ${sumExpected}, got ${sumActual}`);
-                exit(1);
-            }
+        expected = (new TextDecoder().decode(sumBytes).trim().split(/\s+/)[0] ?? '').toLowerCase();
+        if (!/^[0-9a-f]{64}$/.test(expected)) {
+            error(`${sha256Url} did not contain a SHA-256 digest (read ${JSON.stringify(expected.slice(0, 80))}).`);
+            exit(1);
         }
+    } else {
+        error("SHA-256 verification is DISABLED (GJSIFY_INSTALL_BOOTSTRAP_SHA256_URL='') — the bundle is unverified.");
     }
+
     const dir = cacheDir();
+    const basename = expected
+        ? `${CACHE_PREFIX}${expected}${CACHE_SUFFIX}`
+        : `${CACHE_PREFIX}unverified${CACHE_SUFFIX}`;
+    const bundlePath = GLib.build_filenamev([dir, basename]);
+
+    if (expected) {
+        // Re-hash rather than trusting the filename: the name is only a CLAIM
+        // about the contents, and a truncated entry keeps its name.
+        const cached = readBytesOrNull(bundlePath);
+        if (cached && sha256Hex(cached).toLowerCase() === expected) {
+            info(`Reusing verified bootstrap ${bundlePath} (${cached.length} bytes)`);
+            return bundlePath;
+        }
+    }
+
+    info(`Downloading bootstrap from ${bootstrapUrl} ...`);
+    const bundleBytes = await fetchBytes(session, bootstrapUrl);
+    if (expected) {
+        const actual = sha256Hex(bundleBytes).toLowerCase();
+        if (actual !== expected) {
+            error(`SHA-256 mismatch: expected ${expected}, got ${actual}`);
+            exit(1);
+        }
+        info('SHA-256 verified.');
+    }
+
     try {
         ensureDir(dir);
     } catch {
         /* exists */
     }
-    const bundlePath = GLib.build_filenamev([dir, 'cli.gjs.mjs']);
     writeBytes(bundlePath, bundleBytes);
     info(`Bootstrap cached at ${bundlePath} (${bundleBytes.length} bytes)`);
+    try {
+        pruneCache(dir, basename);
+    } catch (err) {
+        // Housekeeping only: a read-only or concurrently-modified cache dir
+        // must never fail an install.
+        info(`Could not prune the bootstrap cache: ${err.message}`);
+    }
     return bundlePath;
 }
 
@@ -232,7 +323,7 @@ async function main() {
     const session = new Soup.Session();
     let bundlePath;
     try {
-        bundlePath = await downloadBootstrap(session, opts.bootstrapUrl, opts.bootstrapSha256Url);
+        bundlePath = await resolveBootstrap(session, opts.bootstrapUrl, opts.bootstrapSha256Url);
     } catch (err) {
         error(`Bootstrap download failed: ${err.message}`);
         exit(1);

package/lib/utils/bin-shim.d.ts

@@ -1,3 +1,4 @@
+import { type HostLibc } from './detect-native-packages.js';
 /** The three sibling files a Windows bin entry consists of. */
 export interface WindowsShimFiles {
     /** POSIX `sh` script — the extension-less `<name>` file. */
@@ -104,6 +105,20 @@ export declare function buildLauncherShims(opts: {
  * {@link buildLauncherShims} from the same baked list, and `PATH` doubles as the
  * DLL search path with `;` separators. It keeps the snapshot behaviour.
  *
+ * MACOS CAVEAT — the `${DYLD_LIBRARY_PATH:+…}` half of the export can never
+ * fire, and the export itself does not survive a script boundary. System
+ * Integrity Protection strips every `DYLD_*` variable from the environment
+ * whenever a PROTECTED binary is exec'd, and `/bin/sh` is protected — so by the
+ * time this preamble runs, an inherited `DYLD_LIBRARY_PATH` is already gone
+ * (measured: `DYLD_LIBRARY_PATH=x /bin/sh -c 'echo $DYLD_LIBRARY_PATH'` prints
+ * nothing, while the same through Homebrew's unprotected `node` prints `x`).
+ * The value this preamble exports is likewise dropped again at the next
+ * `/bin/sh -c` hop, which is how every package script runs. Do NOT "simplify"
+ * the preservation away as dead code — it is load-bearing on Linux. And do not
+ * rely on `DYLD_LIBRARY_PATH` alone to make a darwin prebuild loadable across a
+ * script chain: the self-relative `@loader_path` rpath that
+ * `check-prebuild-loader-path.mjs` enforces is what actually has to carry it.
+ *
  * @param scanRoot Directory whose `node_modules` is globbed at launch time.
  * @param bakedDirs Prebuild dirs found at write time; entries outside `scanRoot`
  *   are embedded (entries inside it are dropped — the scan finds them).
@@ -112,4 +127,62 @@ export declare function buildLauncherShims(opts: {
 export declare function buildNativeEnvPreamble(scanRoot: string, bakedDirs?: readonly string[], target?: {
     platform?: string;
     arch?: string;
+    libc?: HostLibc | null;
+}): string;
+/** POSIX `sh` single-quoting for a launcher's target path. */
+export declare function shQuoteArg(s: string): string;
+/**
+ * Expand a `bin` / `gjsify.bin` declaration into `binName → relative target`.
+ *
+ * The string form is npm's shorthand for `{ <package-name-without-scope>: <path> }`.
+ */
+export declare function normalizeBinMap(pkgName: string, bin: string | Record<string, string>): Map<string, string>;
+/**
+ * Which bin map a package wants installed, and whether it is the GJS-runnable one.
+ *
+ * `gjsify.bin` WINS over npm `bin` when declared. The npm field can only ever
+ * name the Node entry — npm has no way to express "and this other file is the
+ * one to run when the host has `gjs` but no `node`" — so a package that ships
+ * both declares the GJS bundle here. Honouring it is what makes a Node-LESS GJS
+ * host work at all: on such a host the npm bin's `#!/usr/bin/env node` shebang
+ * fails with `env: can't execute 'node'`, and because the launcher is also the
+ * only thing that can export `GI_TYPELIB_PATH` before the GJS runtime starts,
+ * that failure takes `gjsify build` down with it (the typelib lookup happens
+ * before the bundle's first line — the CLI cannot repair it from the inside).
+ *
+ * Measured on a postmarketOS/aarch64 phone with gjs 1.88 and no node: install
+ * and prebuild loading both worked, and only the `#!/usr/bin/env node` shim in
+ * `node_modules/.bin/` stood between that host and a working `gjsify build`.
+ *
+ * `isGjsBin` lets the caller keep plain-Node packages on the plain symlink path
+ * — this must not change how `lodash`'s bin is linked.
+ */
+export declare function pickBinMap(pkgName: string, pkgJson: {
+    bin?: string | Record<string, string>;
+    gjsify?: {
+        bin?: string | Record<string, string>;
+    };
+}): {
+    map: Map<string, string>;
+    isGjsBin: boolean;
+} | null;
+/**
+ * The POSIX `sh` launcher gjsify writes for a bin it owns.
+ *
+ * Why a launcher and not a symlink: when a GJS bundle is reached through a
+ * symlink, the kernel resolves it to find the executable but hands the ORIGINAL
+ * path to it, so `gjs -m <symlink>` makes `import.meta.url` point at the link's
+ * directory and every asset read relative to it looks in the wrong place. An
+ * explicit `exec` with the real path avoids that.
+ *
+ * `.gjs.mjs`/`.mjs` targets are wrapped in `gjs -m` rather than exec'd directly
+ * because not every published bundle carries a `#!/usr/bin/env -S gjs -m` line,
+ * and direct-exec'ing a shebang-less `.mjs` falls through to `/bin/sh`, which
+ * then parses JavaScript as shell.
+ */
+export declare function buildShLauncher(targetAbs: string, opts: {
+    envPreamble?: string;
+    isGjsBundle: boolean;
 }): string;
+/** True when a bin target is a GJS-runnable bundle rather than a Node script. */
+export declare function isGjsBundlePath(target: string): boolean;

package/lib/utils/bin-shim.js

@@ -24,7 +24,7 @@
 // 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.
-import { libraryPathVar, prebuildDirCandidates } from './detect-native-packages.js';
+import { detectHostLibc, libraryPathVar, prebuildDirCandidates } from './detect-native-packages.js';
 // 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]+)(.*)$/;
@@ -289,6 +289,20 @@ function shQuote(s) {
  * {@link buildLauncherShims} from the same baked list, and `PATH` doubles as the
  * DLL search path with `;` separators. It keeps the snapshot behaviour.
  *
+ * MACOS CAVEAT — the `${DYLD_LIBRARY_PATH:+…}` half of the export can never
+ * fire, and the export itself does not survive a script boundary. System
+ * Integrity Protection strips every `DYLD_*` variable from the environment
+ * whenever a PROTECTED binary is exec'd, and `/bin/sh` is protected — so by the
+ * time this preamble runs, an inherited `DYLD_LIBRARY_PATH` is already gone
+ * (measured: `DYLD_LIBRARY_PATH=x /bin/sh -c 'echo $DYLD_LIBRARY_PATH'` prints
+ * nothing, while the same through Homebrew's unprotected `node` prints `x`).
+ * The value this preamble exports is likewise dropped again at the next
+ * `/bin/sh -c` hop, which is how every package script runs. Do NOT "simplify"
+ * the preservation away as dead code — it is load-bearing on Linux. And do not
+ * rely on `DYLD_LIBRARY_PATH` alone to make a darwin prebuild loadable across a
+ * script chain: the self-relative `@loader_path` rpath that
+ * `check-prebuild-loader-path.mjs` enforces is what actually has to carry it.
+ *
  * @param scanRoot Directory whose `node_modules` is globbed at launch time.
  * @param bakedDirs Prebuild dirs found at write time; entries outside `scanRoot`
  *   are embedded (entries inside it are dropped — the scan finds them).
@@ -297,6 +311,15 @@ function shQuote(s) {
 export function buildNativeEnvPreamble(scanRoot, bakedDirs = [], target = {}) {
     const platform = target.platform ?? process.platform;
     const arch = target.arch ?? process.arch;
+    // The libc is a HOST fact, so it belongs in the glob just as much as the
+    // arch does. Omitting it made the launcher probe only `linux-<arch>` on a
+    // musl host — survivable while every prebuild sat in the depending
+    // package's own tree, but ADR 0017 moved each binary into a per-target
+    // package (`<name>-linux-arm64-musl`, shipping `prebuilds/linux-arm64-musl/`),
+    // so the directory the launcher must find is now the one it did not name.
+    // `detectNativePackages` has always been libc-aware; this is the same
+    // question asked in the shell, and the two must not answer it differently.
+    const libc = target.libc !== undefined ? target.libc : detectHostLibc(platform);
     const { name: libVar, separator } = libraryPathVar(platform);
     if (platform === 'win32') {
         if (bakedDirs.length === 0)
@@ -317,7 +340,7 @@ export function buildNativeEnvPreamble(scanRoot, bakedDirs = [], target = {}) {
     // platforms is correct here — the shell cannot read a package.json, and a
     // package declaring ONLY a non-canonical spelling of this host has not
     // existed since the audit made that state impossible.
-    const candidates = prebuildDirCandidates(platform, arch);
+    const candidates = prebuildDirCandidates(platform, arch, undefined, libc);
     const patterns = [];
     for (const candidate of candidates) {
         // Scoped (`@gjsify/x`) and unscoped packages, matching `scanNodeModules`.
@@ -349,3 +372,75 @@ export function buildNativeEnvPreamble(scanRoot, bakedDirs = [], target = {}) {
         `fi\n` +
         `unset gjsify_np gjsify_d gjsify_t\n`);
 }
+/** POSIX `sh` single-quoting for a launcher's target path. */
+export function shQuoteArg(s) {
+    return shQuote(s);
+}
+/**
+ * Expand a `bin` / `gjsify.bin` declaration into `binName → relative target`.
+ *
+ * The string form is npm's shorthand for `{ <package-name-without-scope>: <path> }`.
+ */
+export function normalizeBinMap(pkgName, bin) {
+    const out = new Map();
+    if (typeof bin === 'string') {
+        const baseName = pkgName.startsWith('@') ? pkgName.slice(pkgName.indexOf('/') + 1) : pkgName;
+        out.set(baseName, bin);
+        return out;
+    }
+    for (const [k, v] of Object.entries(bin))
+        out.set(k, v);
+    return out;
+}
+/**
+ * Which bin map a package wants installed, and whether it is the GJS-runnable one.
+ *
+ * `gjsify.bin` WINS over npm `bin` when declared. The npm field can only ever
+ * name the Node entry — npm has no way to express "and this other file is the
+ * one to run when the host has `gjs` but no `node`" — so a package that ships
+ * both declares the GJS bundle here. Honouring it is what makes a Node-LESS GJS
+ * host work at all: on such a host the npm bin's `#!/usr/bin/env node` shebang
+ * fails with `env: can't execute 'node'`, and because the launcher is also the
+ * only thing that can export `GI_TYPELIB_PATH` before the GJS runtime starts,
+ * that failure takes `gjsify build` down with it (the typelib lookup happens
+ * before the bundle's first line — the CLI cannot repair it from the inside).
+ *
+ * Measured on a postmarketOS/aarch64 phone with gjs 1.88 and no node: install
+ * and prebuild loading both worked, and only the `#!/usr/bin/env node` shim in
+ * `node_modules/.bin/` stood between that host and a working `gjsify build`.
+ *
+ * `isGjsBin` lets the caller keep plain-Node packages on the plain symlink path
+ * — this must not change how `lodash`'s bin is linked.
+ */
+export function pickBinMap(pkgName, pkgJson) {
+    const gjsifyBin = pkgJson.gjsify?.bin;
+    if (gjsifyBin !== undefined)
+        return { map: normalizeBinMap(pkgName, gjsifyBin), isGjsBin: true };
+    const npmBin = pkgJson.bin;
+    if (npmBin !== undefined)
+        return { map: normalizeBinMap(pkgName, npmBin), isGjsBin: false };
+    return null;
+}
+/**
+ * The POSIX `sh` launcher gjsify writes for a bin it owns.
+ *
+ * Why a launcher and not a symlink: when a GJS bundle is reached through a
+ * symlink, the kernel resolves it to find the executable but hands the ORIGINAL
+ * path to it, so `gjs -m <symlink>` makes `import.meta.url` point at the link's
+ * directory and every asset read relative to it looks in the wrong place. An
+ * explicit `exec` with the real path avoids that.
+ *
+ * `.gjs.mjs`/`.mjs` targets are wrapped in `gjs -m` rather than exec'd directly
+ * because not every published bundle carries a `#!/usr/bin/env -S gjs -m` line,
+ * and direct-exec'ing a shebang-less `.mjs` falls through to `/bin/sh`, which
+ * then parses JavaScript as shell.
+ */
+export function buildShLauncher(targetAbs, opts) {
+    const preamble = opts.isGjsBundle ? (opts.envPreamble ?? '') : '';
+    const exec = opts.isGjsBundle ? `exec gjs -m ${shQuote(targetAbs)} "$@"` : `exec ${shQuote(targetAbs)} "$@"`;
+    return `#!/bin/sh\n${preamble}${exec}\n`;
+}
+/** True when a bin target is a GJS-runnable bundle rather than a Node script. */
+export function isGjsBundlePath(target) {
+    return target.endsWith('.gjs.mjs') || target.endsWith('.mjs');
+}

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

@@ -5,8 +5,14 @@ import { type Workspace } from '@gjsify/workspace';
  * 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.
+ *
+ * v3: a `.tsbuildinfo` inside a candidate dir no longer counts as a loose file
+ * (see {@link outputUnits}). The six packages that emit one into `lib/` were
+ * still on v2's whole-dir ownership and could restore over a sibling unit; a v2
+ * manifest for them records `lib`, so it must not be replayed against the
+ * per-child units this version stores.
  */
-export declare const BUILD_CACHE_LAYOUT_VERSION = "v2";
+export declare const BUILD_CACHE_LAYOUT_VERSION = "v3";
 /** 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. */
@@ -51,32 +57,6 @@ export declare function hashPackageInputs(location: string): string;
  * as an integrity stamp of what was stored.
  */
 export declare function hashOutputDirs(location: string, dirs: readonly string[]): string;
-/**
- * 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).

package/lib/utils/build-cache.js

@@ -49,18 +49,25 @@
 // or a permission error degrade to "run the script uncached" — a cache
 // hiccup must never break a build.
 import { createHash } from 'node:crypto';
-import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readlinkSync, readSync, renameSync, rmSync, symlinkSync, copyFileSync, writeFileSync, } from 'node:fs';
+import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readlinkSync, readSync, renameSync, rmSync, copyFileSync, writeFileSync, } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { buildDependencyGraph } from '@gjsify/workspace';
+import { replicateLinkSync } from './dir-link.js';
 /**
  * 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.
+ *
+ * v3: a `.tsbuildinfo` inside a candidate dir no longer counts as a loose file
+ * (see {@link outputUnits}). The six packages that emit one into `lib/` were
+ * still on v2's whole-dir ownership and could restore over a sibling unit; a v2
+ * manifest for them records `lib`, so it must not be replayed against the
+ * per-child units this version stores.
  */
-export const BUILD_CACHE_LAYOUT_VERSION = 'v2';
+export const BUILD_CACHE_LAYOUT_VERSION = 'v3';
 /** 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. */
@@ -259,7 +266,26 @@ export function hashOutputDirs(location, dirs) {
  * 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).
+ *
+ * A `.tsbuildinfo` does NOT count as a loose file, and that exemption is
+ * load-bearing rather than cosmetic. It is incremental-compiler STATE, not a
+ * build output — nothing ships it — yet six packages point `tsBuildInfoFile`
+ * inside their emit dir, and its mere presence flipped `lib/` back to whole-dir
+ * ownership, re-creating for those packages exactly the clobber the per-child
+ * split above was introduced to fix. Measured on `@gjsify/semver`: `lib/`
+ * held `esm/`, `types/` and `tsconfig.build.tsbuildinfo`, so a `build:types`
+ * cache hit restored the whole `lib` and DELETED the `lib/esm` a previous step
+ * had just produced — leaving the Node CLI entry unloadable
+ * (`ERR_MODULE_NOT_FOUND: @gjsify/semver/lib/esm/index.js`) on a cold macOS
+ * tree, where that entry is the only usable one.
+ *
+ * Excluding it also keeps it OUT of every stored unit, which is the right
+ * outcome independently: a restored `.tsbuildinfo` describes an emit that did
+ * not happen in this tree, and tsc then treats the project as up to date,
+ * writes nothing and exits 0 — the silent no-op `verify-package-outputs.mjs`
+ * exists to catch.
  */
+const isBuildInfo = (name) => name.endsWith('.tsbuildinfo');
 export function outputUnits(location) {
     const units = [];
     for (const dir of OUTPUT_DIR_CANDIDATES) {
@@ -268,7 +294,7 @@ export function outputUnits(location) {
             continue;
         let entries;
         try {
-            entries = readdirSync(abs).filter((name) => name !== 'node_modules');
+            entries = readdirSync(abs).filter((name) => name !== 'node_modules' && !isBuildInfo(name));
         }
         catch {
             continue;
@@ -417,7 +443,11 @@ function copyDirRecursive(from, to) {
         const dst = join(to, entry);
         const st = lstatSync(src);
         if (st.isSymbolicLink()) {
-            symlinkSync(readlinkSync(src), dst);
+            // Not `symlinkSync(readlinkSync(src), dst)`: replicating a link to a
+            // DIRECTORY verbatim needs a junction on Windows, and the target has
+            // to be resolved for it. See `dir-link.ts` — the one definition of
+            // that rule, added after the same mistake shipped in `dlx-cache.ts`.
+            replicateLinkSync(src, dst);
         }
         else if (st.isDirectory()) {
             copyDirRecursive(src, dst);

package/lib/utils/check-system-deps.d.ts

@@ -12,7 +12,21 @@ export interface DepCheck {
     /** For optional deps: which @gjsify/* packages need this lib */
     requiredBy?: string[];
 }
-export type PackageManager = 'apt' | 'dnf' | 'pacman' | 'zypper' | 'apk' | 'unknown';
+export type PackageManager = 'apt' | 'dnf' | 'pacman' | 'zypper' | 'apk' | 'brew' | 'unknown';
+/**
+ * The package manager whose install command we may suggest.
+ *
+ * Probe order is PLATFORM-FIRST, not a single global list. On macOS the Linux
+ * managers are absent, so a flat list ending in `brew` would work by accident —
+ * but Homebrew also runs on Linux, where it is the LAST resort rather than the
+ * first (a Fedora host with linuxbrew installed wants `sudo dnf install`, whose
+ * packages carry the distro's own GI typelibs). Keying the order on
+ * `process.platform` states that intent instead of leaving it to list position.
+ *
+ * Returning `unknown` is a supported answer, not a failure: `buildInstallCommand`
+ * then prints no command rather than a wrong one. That is the honest result on a
+ * MacPorts or Nix host, and it is why this must never fall back to "probably brew".
+ */
 export declare function detectPackageManager(): PackageManager;
 /**
  * Run all dependency checks. Used by `gjsify check` to show full system status.