@gjsify/cli 0.35.0 → 0.37.0

package/lib/utils/install-packument-cache.js

@@ -1,13 +1,11 @@
 // On-disk packument metadata cache for `gjsify install`.
 //
 // Sibling to the content-addressable tarball cache (install-tarball-cache.ts).
-// Stores each package's abbreviated packument plus the registry `ETag` it came
-// with, so a re-resolve (lockfile miss — e.g. a dependency range changed) can
-// send a conditional `If-None-Match` and turn the unchanged majority into empty
-// `304 Not Modified` responses — a real bandwidth + parse saving on repeated /
-// dep-churn installs, on top of the ~4× gzip transfer for the changed minority
-// (packuments are fetched gzip-compressed and decoded by the fetch layer; see
-// `@gjsify/npm-registry` `fetchPackumentConditional`).
+// Stores each package's packument plus the registry `ETag` it came with, so a
+// re-resolve (lockfile miss — e.g. a dependency range changed) can send a
+// conditional `If-None-Match` and turn the unchanged majority into empty
+// `304 Not Modified` responses, on top of the ~4× gzip transfer for the changed
+// minority (see `@gjsify/npm-registry` `fetchPackumentConditional`).
 //
 // Mirrors pnpm's metadata cache + npm's make-fetch-happen HTTP-cache layer.
 //
@@ -15,32 +13,26 @@
 //
 //   $XDG_CACHE_HOME/gjsify/metadata/v3/<shard>/<shape>,<encoded-registry>,<encoded-name>.json
 //
-// The cache is keyed by (SHAPE, registry, name) — NOT name alone — so switching
-// the registry for a scope can never serve a packument from the wrong source on
-// a coincidental ETag match. `<shard>` is a 2-hex FNV-1a digest of the key, a
-// directory-fan-out step so the leaf dir never grows unbounded (same rationale
-// as the tarball cache's hex sharding). `v2` is a layout version.
+// Keyed by (SHAPE, registry, name) — NOT name alone — so switching the registry
+// for a scope can never serve a packument from the wrong source on a coincidental
+// ETag match. `<shard>` is a 2-hex FNV-1a digest of the key, directory fan-out so
+// the leaf dir never grows unbounded (as with the tarball cache's hex sharding).
 //
-// WHY THE SHAPE IS PART OF THE KEY (the v1 → v2 bump): the same packument URL
-// serves TWO different documents — the abbreviated "corgi" install document and
-// the full one — and only the full one carries a version's `libc` field (see
-// `@gjsify/npm-registry` `FetchOptions.fullMetadata`). With one key per (registry,
-// name), an escalated read would be answered by whichever shape happened to be
-// cached first: a musl-only package would come back `libc`-less, be judged
-// compatible on a glibc host, and get installed — a WRONG ANSWER that looks
-// exactly like a cache hit, with no failure until something dlopens the binary.
-// pacote prefixes its own cache key with `full:`/`corgi:` for precisely this
-// reason. The layout bump (rather than just a longer filename) makes the v1
-// entries — written before the distinction existed and therefore of unknown
-// shape — unreachable instead of ambiguous.
+// WHY THE SHAPE IS PART OF THE KEY: one packument URL serves TWO documents — the
+// abbreviated "corgi" install document and the full one — and only the full one
+// carries a version's `libc` (`@gjsify/npm-registry` `FetchOptions.fullMetadata`).
+// Keyed per (registry, name) alone, a read is answered by whichever shape was cached
+// first, so a musl-only package comes back `libc`-less, is judged compatible on a
+// glibc host, and installs — a wrong answer indistinguishable from a cache hit, with
+// no failure until something dlopens the binary. pacote prefixes its own key with
+// `full:`/`corgi:` for the same reason.
 //
 // Disabled with `GJSIFY_PACKUMENT_CACHE=0` (or `false`). Honours
 // `XDG_CACHE_HOME` like the tarball + dlx caches.
 import { join } from 'node:path';
 import { atomicWrite, gjsifyCacheRoot, readCacheFile } from './install-cache-fs.js';
-// v3, and BOTH halves of the bump matter. v2 moved the separator off the
-// Win32-reserved `|` (see `packumentCacheKey`); v3 additionally makes the
-// document SHAPE part of the key. Either change alone makes older entries
+// v2 moved the separator off the Win32-reserved `|` (see `packumentCacheKey`); v3
+// made the document SHAPE part of the key. Either change alone makes older entries
 // unreachable rather than merely stale, so a new root retires them instead of
 // leaving ambiguous orphans under the old one.
 const CACHE_LAYOUT_VERSION = 'v3';
@@ -80,25 +72,21 @@ function encodePart(part) {
  * The cache key for a (shape, registry, name) triple — exported so the filename
  * rule below is a PROPERTY a test can assert, not a claim in a comment.
  *
- * THE SEPARATOR IS NOT COSMETIC. It used to be `|`, producing names like
- * `corgi|https%3A%2F%2Fregistry.npmjs.org%2F|%40gjsify%2Fnode-gi.json` — and `|`
- * is a Win32 RESERVED filename character, so every write failed with `EINVAL`.
- * Nothing reported it: `atomicWrite` is best-effort on purpose (a read-only
- * cache volume must not break an install) and `readCacheFile` reads an
- * unreadable path as a MISS. So on Windows this cache was never broken loudly —
- * it was silently DEAD, and the `If-None-Match` → `304` revalidation that is the
- * entire reason this file exists never engaged once.
+ * THE SEPARATOR IS NOT COSMETIC. `|` is a Win32 RESERVED filename character, so
+ * while it was the separator every write there failed with `EINVAL` and nothing
+ * reported it: `atomicWrite` is best-effort on purpose (a read-only cache volume
+ * must not break an install) and `readCacheFile` treats an unreadable path as a
+ * MISS. The cache was not broken loudly on Windows, it was silently DEAD, and the
+ * `If-None-Match` → `304` revalidation this file exists for never engaged once.
  *
- * `,` is legal on Win32 AND escaped by `encodeURIComponent`, which is what keeps
- * a flat three-part name injective: an encoded part cannot contain the
- * separator, so exactly one triple maps to any given filename. The shape needs
- * no encoding — it is one of two literals, neither containing the separator —
- * and it LEADS so that listing a shard groups by shape.
+ * `,` is legal on Win32 AND escaped by `encodeURIComponent`, which keeps a flat
+ * three-part name injective: an encoded part cannot contain the separator, so
+ * exactly one triple maps to any filename. The shape needs no encoding — one of two
+ * literals — and LEADS so listing a shard groups by shape.
  *
- * The shard key and the filename are derived from the SAME encoded parts. They
- * used to disagree — the key hashed the raw values while the name used the
- * encoded ones — which is how a reserved character in the name survived review
- * of a function whose other half looked correct.
+ * The shard key and the filename must derive from the SAME encoded parts; hashing
+ * the raw values while naming with the encoded ones is how a reserved character
+ * survived review of a function whose other half looked correct.
  */
 export function packumentCacheKey(registry, name, shape) {
     return `${shape},${encodePart(registry)},${encodePart(name)}`;
@@ -111,15 +99,15 @@ function pathFor(registry, name, shape) {
     return join(cacheRoot(), shardFor(key), `${key}.json`);
 }
 /**
- * Read a cached packument + its ETag for `(registry, name)` in the given
- * document `shape`. Returns `null` on a miss, when the cache is disabled, or
- * when the entry is unreadable/corrupt (treated as a miss — the caller just
- * re-fetches).
+ * Read a cached packument + its ETag for `(registry, name)` in the given document
+ * `shape`. Returns `null` on a miss, when the cache is disabled, or when the entry
+ * is unreadable/corrupt (treated as a miss — the caller re-fetches).
  *
- * `shape` defaults to `'corgi'` because that is what a resolve fetches and what
- * every caller predating the full-document escalation meant. A caller that
- * escalated MUST pass `'full'` — reading the corgi entry would return a body
- * with no `libc`, i.e. the exact wrong answer the shape key exists to prevent.
+ * The `shape` must be the one the body was fetched under: the two documents are
+ * different bodies with independently-versioned ETags behind ONE URL, so reading
+ * across shapes returns a `libc`-less body that looks exactly like a hit. The
+ * install backend resolves with `'full'`; the `'corgi'` default serves callers that
+ * do not escalate.
  */
 export function getCachedPackument(registry, name, shape = 'corgi') {
     const path = pathFor(registry, name, shape);
@@ -143,12 +131,11 @@ export function getCachedPackument(registry, name, shape = 'corgi') {
 /**
  * Persist a packument + ETag for `(registry, name)` under its document `shape`.
  * Writes to a `<path>.tmp.<pid>` sibling then atomically renames so a concurrent
- * reader never sees a partial write. No-op when the cache is disabled, the ETag
- * is empty, or the write fails (read-only / out-of-disk cache volume must not
- * break the install).
+ * reader never sees a partial write. No-op when the cache is disabled, the ETag is
+ * empty, or the write fails (a read-only / out-of-disk cache volume must not break
+ * the install).
  *
- * `shape` is last and defaults to `'corgi'` to keep the pre-escalation call
- * shape valid; it must match the `accept` header the body was fetched with.
+ * `shape` must match the `accept` header the body was fetched with.
  */
 export function putCachedPackument(registry, name, etag, packument, shape = 'corgi') {
     if (!etag)

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

@@ -7,19 +7,12 @@ export interface ProgressEvent {
     name?: string;
 }
 export interface ProgressReporter {
-    /** Called for each step within a phase. */
     update(event: ProgressEvent): void;
-    /** Called once when a phase begins; lets the reporter print a header line. */
     beginPhase(phase: ProgressPhase, total: number): void;
-    /** Called once when a phase completes; clears the inline progress bar. */
+    /** Clears the inline bar and replaces it with a completion line. */
     endPhase(phase: ProgressPhase): void;
 }
-/**
- * Make a progress reporter that auto-targets `process.stderr`.
- * - `enabled=false` → silent.
- * - stderr is not a TTY → fall back to one line per phase (begin + end).
- * - stderr is a TTY → live single-line progress bar (\r-updated, 30fps).
- */
+/** Pick the reporter for `process.stderr` (or `opts.stream`): silent, plain, or TTY bar. */
 export declare function makeProgressReporter(opts?: {
     enabled?: boolean;
     stream?: NodeJS.WriteStream;

package/lib/utils/install-progress.js

@@ -1,16 +1,7 @@
-// Progress reporter for `gjsify install` + `gjsify dlx`.
-//
-// Auto-enables on TTY stderr. Renders a single-line progress bar that gets
-// overwritten via `\r`, mirroring what `yarn install` / `pnpm install` show:
-//
-//     resolving [████████░░░░░░░░] 234/500 typescript@^6.0.3
-//
-// Falls back to a chatty mode (one line per completed step) when stderr is
-// not a TTY, e.g. when piped into a log file or running on CI.
-//
-// Caller plumbing — the install backend calls `report({phase, current, total,
-// name})` after every resolve/download/extract step; the renderer rate-limits
-// to ~30fps so a tight inner loop doesn't drown the terminal.
+// Progress reporter for `gjsify install` + `gjsify dlx`. The backend reports every
+// resolve/download/extract/link step; on TTY stderr this renders one `\r`-overwritten
+// bar, rate-limited to ~30fps so a tight inner loop cannot drown the terminal, and
+// on a non-TTY it degrades to the heartbeat mode described below.
 const PHASE_LABEL = {
     resolve: 'resolving',
     download: 'downloading',
@@ -22,12 +13,7 @@ const NOOP_REPORTER = {
     beginPhase() { },
     endPhase() { },
 };
-/**
- * Make a progress reporter that auto-targets `process.stderr`.
- * - `enabled=false` → silent.
- * - stderr is not a TTY → fall back to one line per phase (begin + end).
- * - stderr is a TTY → live single-line progress bar (\r-updated, 30fps).
- */
+/** Pick the reporter for `process.stderr` (or `opts.stream`): silent, plain, or TTY bar. */
 export function makeProgressReporter(opts = {}) {
     if (opts.enabled === false)
         return NOOP_REPORTER;
@@ -38,7 +24,6 @@ export function makeProgressReporter(opts = {}) {
         return NOOP_REPORTER;
     return isTty ? makeTtyReporter(stream) : makePlainReporter(stream);
 }
-// ──── TTY reporter — single-line, \r-updated, 30fps rate-limit ────────────
 function makeTtyReporter(stream) {
     let lastRender = 0;
     let lastLine = '';
@@ -49,7 +34,7 @@ function makeTtyReporter(stream) {
             return;
         lastRender = now;
         lastLine = line;
-        // Clear current line, write new content. \x1b[2K = erase entire line.
+        // `\x1b[2K` = erase entire line.
         stream.write('\r\x1b[2K' + line);
     }
     function clearLine() {
@@ -58,33 +43,26 @@ function makeTtyReporter(stream) {
     }
     return {
         beginPhase(phase, total) {
-            // First frame so the user sees immediate feedback.
+            // Forced, so the first frame is not eaten by the rate limit.
             render(formatBar(phase, 0, total, undefined, stream.columns ?? 80), true);
         },
         update(ev) {
             render(formatBar(ev.phase, ev.current, ev.total, ev.name, stream.columns ?? 80));
         },
         endPhase(phase) {
-            // Replace the live bar with a completion line so the user sees
-            // a definitive "done" after the spinner stops.
+            // A definitive "done" line, or the stopped bar reads as a stall.
             const label = PHASE_LABEL[phase];
             clearLine();
             stream.write(`gjsify install: ${label} done\n`);
         },
     };
 }
-// ──── Plain reporter — phase begin/end + periodic heartbeat (non-TTY) ──────
-//
-// On a non-TTY (piped to a log file, CI, or captured output) the bar can't
-// `\r`-overwrite, so per-package lines are suppressed to avoid flooding the
-// log. But emitting NOTHING between `beginPhase` and `endPhase` makes a long
-// download/extract phase look frozen — the exact "no further output for 25+
-// minutes" symptom of a slow install. So we emit a low-frequency heartbeat:
-// at most one line per HEARTBEAT_MS, AND only after at least a few packages of
-// real progress, so a fast warm install (most nodes skipped) stays quiet while
-// a genuinely long phase reports `… N/M (X%)` every few seconds. This mirrors
-// what npm (`--loglevel http`) and pnpm log on non-TTY: progress you can watch
-// without it being one line per file.
+// Non-TTY heartbeat. Per-package lines would flood a log file, but emitting
+// NOTHING between `beginPhase` and `endPhase` makes a long download/extract look
+// frozen — the exact "no further output for 25+ minutes" symptom of a slow install.
+// So: at most one line per HEARTBEAT_MS, and only once `current` has actually
+// advanced, which keeps a fast warm install (most nodes skipped) silent while a
+// genuinely long phase reports `… N/M (X%)` every few seconds.
 const HEARTBEAT_MS = 5_000;
 function makePlainReporter(stream) {
     let lastHeartbeat = 0;
@@ -111,12 +89,10 @@ function makePlainReporter(stream) {
         },
     };
 }
-// ──── Bar formatter ────────────────────────────────────────────────────────
 function formatBar(phase, current, total, name, columns) {
     const label = PHASE_LABEL[phase];
     const ratio = total > 0 ? Math.min(1, current / total) : 0;
     const pct = `${current}/${total}`;
-    // Reserve: "gjsify install: " (16) + label (max ~12) + " [" (2) + "] " (2) + pct (~8) + " " + name
     const prefix = `gjsify install: ${label} `;
     const suffix = ` ${pct}` + (name ? ` ${name}` : '');
     const barWidth = Math.max(8, Math.min(40, columns - prefix.length - suffix.length - 4));
@@ -124,7 +100,6 @@ function formatBar(phase, current, total, name, columns) {
     const bar = '█'.repeat(filled) + '░'.repeat(barWidth - filled);
     let line = `${prefix}[${bar}]${suffix}`;
     if (line.length > columns) {
-        // Truncate name if the terminal is narrow.
         const overflow = line.length - columns + 1;
         const truncatedName = name && name.length > overflow ? name.slice(0, name.length - overflow - 1) + '…' : '';
         line = `${prefix}[${bar}] ${pct}${truncatedName ? ' ' + truncatedName : ''}`;

package/lib/utils/install-tarball-cache.d.ts

@@ -1,31 +1,25 @@
 /**
- * Read a cached tarball by SRI integrity. Returns the raw tarball bytes if
- * the cache has a HIT, `null` otherwise. A read failure (e.g. partial
- * write from an interrupted previous run) is treated as a MISS — the file
- * is left untouched so we don't trip a follow-up writer's atomic rename.
+ * Read a cached tarball by SRI integrity — raw bytes on a HIT, `null` otherwise. A
+ * read failure (e.g. a partial write from an interrupted run) is a MISS, and the
+ * file is left untouched so a follow-up writer's atomic rename is not tripped.
  */
 export declare function getCachedTarball(integrity: string | undefined): Uint8Array | null;
 /**
- * Persist a tarball to the cache. Writes to a `<path>.tmp.<pid>` sibling
- * then atomically renames into place so concurrent installs can never
- * observe a half-written entry. No-op when:
- *   - `integrity` is missing / malformed (no cache key)
- *   - the destination already exists (idempotent — content-addressed)
- *   - the write fails (e.g. cache root is read-only) — silently degrade
- *     so a cache-volume issue doesn't break the install itself.
+ * Persist a tarball to the cache, via a `<path>.tmp.<pid>` sibling and an atomic
+ * rename so concurrent installs never observe a half-written entry. No-op when
+ * `integrity` is missing/malformed, when the destination already exists
+ * (content-addressed, so immutable), or when the write fails — a read-only cache
+ * volume must not break the install itself.
  */
 export declare function putCachedTarball(integrity: string | undefined, bytes: Uint8Array): void;
-/**
- * Best-effort cache stats for diagnostics. Returns `null` when the cache
- * root doesn't exist yet (first run).
- */
+/** The cache root, for diagnostics. Not probed — the directory may not exist yet. */
 export declare function cacheRootForLogging(): string;
 export declare function isCacheHit(integrity: string | undefined): boolean;
 /**
- * Read a tarball from npm's cacache content store by SRI integrity. Returns
- * the raw `.tgz` bytes on a HIT, `null` on a MISS / disabled interop / read
- * failure. Like {@link getCachedTarball}, this trusts the content-addressed
- * path rather than re-hashing — the extractor surfaces any genuinely corrupt
- * tarball loudly, and cacache verified the bytes on write.
+ * Read a tarball from npm's cacache content store by SRI integrity — raw `.tgz`
+ * bytes on a HIT, `null` on a MISS, disabled interop or read failure. Like
+ * {@link getCachedTarball} it trusts the content-addressed path rather than
+ * re-hashing: cacache verified the bytes on write, and the extractor surfaces a
+ * genuinely corrupt tarball loudly.
  */
 export declare function getForeignCachedTarball(integrity: string | undefined): Uint8Array | null;

package/lib/utils/install-tarball-cache.js

@@ -1,35 +1,29 @@
 // Content-addressable tarball cache for `gjsify install`.
 //
-// Mirrors pnpm / yarn-berry's store layout: each tarball is stored once on
-// disk keyed by its SRI integrity hash (`sha512-…`). When the resolver hits
-// a node whose integrity is already cached, `fetchTarball` is skipped and
-// we read the bytes off the local filesystem instead.
+// Mirrors pnpm / yarn-berry's store layout: each tarball is stored once on disk
+// keyed by its SRI integrity hash (`sha512-…`), so a node whose integrity is
+// already cached skips `fetchTarball` and reads the bytes off local disk.
 //
-// Why this matters: a cold install on this monorepo (200+ workspaces,
-// 600+ transitive deps) spends ~20 minutes at 80% CPU. Most of that time is
-// re-downloading + re-extracting the SAME tarballs that just came down in
-// the previous run because there is no cache between runs. With this cache,
-// the second `gjsify install` on the same repo skips every tarball fetch
-// and just goes straight to extract → drops well below 1 minute in practice.
+// Measured on this monorepo (200+ workspaces, 600+ transitive deps): a cold
+// install spends ~20 minutes at 80% CPU, most of it re-downloading tarballs the
+// previous run had already fetched. With the cache the second `gjsify install`
+// goes straight to extract and drops well under a minute.
 //
-// Layout (matches the pnpm pattern so we stay forward-compatible with
-// `~/.cache/gjsify/store` if we eventually share a store across projects):
+// Layout, following the pnpm pattern:
 //
 //   $XDG_CACHE_HOME/gjsify/tarballs/v1/<hex-prefix-2>/<full-hex>.tgz
 //
-// The 2-byte prefix is a directory-sharding step so the leaf directory
-// never gets pathologically large — same pattern git's loose objects use.
-// `v1` is a layout version so we can change the file shape (e.g. add a
-// manifest sidecar) without invalidating the world.
+// The 2-byte prefix shards the directory so the leaf never gets pathologically
+// large (git's loose-object pattern). `v1` is a layout version, so the file shape
+// can change without invalidating the world.
 //
-// SRI integrity input → cache key:
+// SRI integrity → cache key, by hex-encoding the base64 digest:
 //
 //   "sha512-AbCd…=="   →  ("sha512", "ab/cdefg….tgz")
 //
-// We hex-encode the base64 SRI digest. Two integrities that produce the
-// same hex bytes share the same cache entry; that is the invariant pnpm
-// relies on too. Tarballs without an integrity hash (older registries)
-// fall through to a no-op cache and download every time.
+// Two integrities with the same hex bytes share an entry, the invariant pnpm relies
+// on too. Tarballs without an integrity hash (older registries) fall through to a
+// no-op cache and download every time.
 import { Buffer } from 'node:buffer';
 import { existsSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -41,10 +35,9 @@ function cacheRoot() {
     return gjsifyCacheRoot('tarballs', CACHE_LAYOUT_VERSION);
 }
 /**
- * Parse an SRI integrity string (`sha512-AbCd…=`) into its algorithm + hex
- * digest, or `null` for a missing / malformed value (caller falls back to a
- * fresh download). Shared by both the gjsify-store and npm-cacache path
- * derivations below — the base64→hex decode used to be inlined in each.
+ * Parse an SRI integrity string (`sha512-AbCd…=`) into its algorithm + hex digest,
+ * or `null` for a missing / malformed value (the caller falls back to a fresh
+ * download). Shared by the gjsify-store and npm-cacache path derivations below.
  */
 function parseSri(integrity) {
     if (!integrity)
@@ -75,10 +68,9 @@ function pathFor(integrity) {
     return join(cacheRoot(), sri.algorithm, shard, `${sri.hex}.tgz`);
 }
 /**
- * Read a cached tarball by SRI integrity. Returns the raw tarball bytes if
- * the cache has a HIT, `null` otherwise. A read failure (e.g. partial
- * write from an interrupted previous run) is treated as a MISS — the file
- * is left untouched so we don't trip a follow-up writer's atomic rename.
+ * Read a cached tarball by SRI integrity — raw bytes on a HIT, `null` otherwise. A
+ * read failure (e.g. a partial write from an interrupted run) is a MISS, and the
+ * file is left untouched so a follow-up writer's atomic rename is not tripped.
  */
 export function getCachedTarball(integrity) {
     const path = pathFor(integrity);
@@ -87,13 +79,11 @@ export function getCachedTarball(integrity) {
     return readCacheFile(path);
 }
 /**
- * Persist a tarball to the cache. Writes to a `<path>.tmp.<pid>` sibling
- * then atomically renames into place so concurrent installs can never
- * observe a half-written entry. No-op when:
- *   - `integrity` is missing / malformed (no cache key)
- *   - the destination already exists (idempotent — content-addressed)
- *   - the write fails (e.g. cache root is read-only) — silently degrade
- *     so a cache-volume issue doesn't break the install itself.
+ * Persist a tarball to the cache, via a `<path>.tmp.<pid>` sibling and an atomic
+ * rename so concurrent installs never observe a half-written entry. No-op when
+ * `integrity` is missing/malformed, when the destination already exists
+ * (content-addressed, so immutable), or when the write fails — a read-only cache
+ * volume must not break the install itself.
  */
 export function putCachedTarball(integrity, bytes) {
     const path = pathFor(integrity);
@@ -104,10 +94,7 @@ export function putCachedTarball(integrity, bytes) {
         return;
     atomicWrite(path, bytes);
 }
-/**
- * Best-effort cache stats for diagnostics. Returns `null` when the cache
- * root doesn't exist yet (first run).
- */
+/** The cache root, for diagnostics. Not probed — the directory may not exist yet. */
 export function cacheRootForLogging() {
     return cacheRoot();
 }
@@ -123,26 +110,21 @@ export function isCacheHit(integrity) {
         return false;
     }
 }
-// ---------------------------------------------------------------------------
 // Foreign cache interop — read npm's cacache content store.
 //
-// npm stores downloaded tarballs in a content-addressable store
-// (`cacache`) keyed by the SAME SRI integrity we key our own store on, and
-// holds the raw `.tgz` bytes verbatim. Layout (cacache `content-v2`):
+// npm keys its content-addressable store on the SAME SRI integrity as ours and
+// holds the raw `.tgz` bytes verbatim, so anyone who has run `npm install` already
+// has these tarballs on disk and reading them turns a cold `gjsify install` into a
+// near-warm one with no network round-trip. Layout (cacache `content-v2`):
 //
 //   <npm-cache>/_cacache/content-v2/<algo>/<hex[0:2]>/<hex[2:4]>/<hex[4:]>
 //
-// `<algo>` is the SRI algorithm (`sha512`), `<hex>` the hex-encoded digest —
-// identical derivation to our own `pathFor`, just a different root and no
-// `.tgz` extension. So anyone who has run `npm install` before already has
-// these tarballs on disk; reading them turns a cold `gjsify install` into a
-// near-warm one without a single network round-trip.
+// Identical derivation to our own `pathFor`, with a different root and no `.tgz`
+// extension.
 //
-// pnpm/yarn/bun stores are deliberately NOT read here: pnpm/bun store
-// *unpacked* per-file content (no tarball to hand to the extractor) and yarn
-// berry stores zip archives under its own (non-SRI) cache key — none map to a
-// tarball-by-integrity lookup the way npm's cacache does.
-// ---------------------------------------------------------------------------
+// pnpm/yarn/bun stores are deliberately NOT read: pnpm and bun store *unpacked*
+// per-file content (no tarball to hand the extractor) and yarn berry stores zips
+// under its own non-SRI key, so none map to a tarball-by-integrity lookup.
 /**
  * Resolve npm's `content-v2` directory, honouring `GJSIFY_NPM_CACHE`
  * (full path to a `_cacache` dir; `0`/`false`/empty disables the interop),
@@ -175,11 +157,11 @@ function npmCachePathFor(integrity) {
     return join(contentDir, sri.algorithm, sri.hex.slice(0, 2), sri.hex.slice(2, 4), sri.hex.slice(4));
 }
 /**
- * Read a tarball from npm's cacache content store by SRI integrity. Returns
- * the raw `.tgz` bytes on a HIT, `null` on a MISS / disabled interop / read
- * failure. Like {@link getCachedTarball}, this trusts the content-addressed
- * path rather than re-hashing — the extractor surfaces any genuinely corrupt
- * tarball loudly, and cacache verified the bytes on write.
+ * Read a tarball from npm's cacache content store by SRI integrity — raw `.tgz`
+ * bytes on a HIT, `null` on a MISS, disabled interop or read failure. Like
+ * {@link getCachedTarball} it trusts the content-addressed path rather than
+ * re-hashing: cacache verified the bytes on write, and the extractor surfaces a
+ * genuinely corrupt tarball loudly.
  */
 export function getForeignCachedTarball(integrity) {
     const path = npmCachePathFor(integrity);

package/lib/utils/library-output.d.ts

@@ -1,30 +1,17 @@
 /**
- * The literal (non-glob) base directories the build's input source files live
- * in, derived from the bundler `input` patterns. A file entry maps to its
- * containing dir, a glob is reduced to the literal prefix before the first
- * wildcard:
- *   - `src/index.ts`   → `<cwd>/src`
- *   - `src/**` + `/*.ts` → `<cwd>/src`
- *   - `src`            → `<cwd>/src`
+ * The literal (non-glob) base directories the input source files live in, derived from the
+ * bundler `input` patterns: a file entry maps to its containing dir, a glob is reduced to the
+ * literal prefix before the first wildcard (`src/index.ts`, `src` and `src/**` + `/*.ts` all
+ * give `<cwd>/src`).
  *
- * The project root itself is intentionally excluded — a flat library that
- * keeps its source at the project root and emits there is an explicit layout,
- * not the `src/`-subdir footgun this guard targets.
+ * The project root is intentionally excluded — a flat library keeping its source at the root and
+ * emitting there is an explicit layout, not the `src/`-subdir footgun this guard targets.
  */
 export declare function inputSourceDirs(input: unknown, cwd: string): string[];
 /**
- * `true` when writing library output to `outdir` would land build artifacts
- * inside (or directly on top of) the input source tree. Unsafe iff `outdir`
- * equals, or is nested under, any input source directory.
- *
- *   isOutdirInsideSource('src',      ['<cwd>/src'])       → true   (leak)
- *   isOutdirInsideSource('src/nest', ['<cwd>/src'])       → true   (leak)
- *   isOutdirInsideSource('dist/esm', ['<cwd>/src'])       → false  (safe)
- *   isOutdirInsideSource('lib',      ['<cwd>/src'])       → false  (safe)
+ * `true` when library output written to `outdir` would land inside (or on top of) the input
+ * source tree — i.e. `outdir` equals, or is nested under, any input source directory.
  */
 export declare function isOutdirInsideSource(outdir: string, sourceDirs: readonly string[], cwd: string): boolean;
-/**
- * The error thrown when a `--library` build would emit into its own source
- * tree. Names both remedies so the fix is actionable at the point of failure.
- */
+/** The error thrown when a `--library` build would emit into its own source tree. */
 export declare function libraryOutputLeakError(outdir: string): Error;