@gjsify/cli 0.36.0 → 0.38.0

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

@@ -19,86 +19,71 @@ export interface InstallOptions {
     /** Use `<prefix>/gjsify-lock.json` as the source of truth — fail if missing. */
     frozen?: boolean;
     /**
-     * Native backend only: force a fresh re-resolution that bumps every spec to
-     * the newest version satisfying its range, rewriting the lockfile — the
-     * pre-0.7.x behaviour. By default (this flag off) a resolve that has to run
-     * (a new/changed/removed dep) PRESERVES the versions already pinned in the
-     * existing lockfile and only resolves the genuinely new/changed deps, the
-     * way `npm install` / `yarn install` / `pnpm install` do. Set this to
-     * intentionally pick up in-range updates (≈ `yarn install
-     * --mode=update-lockfile` / `npm update` / `pnpm update`).
+     * Native backend only: force a fresh re-resolution that bumps every spec to the
+     * newest version satisfying its range, rewriting the lockfile. Off, a resolve
+     * that has to run PRESERVES the versions already pinned and only resolves the
+     * genuinely new/changed deps, as `npm`/`yarn`/`pnpm install` do. Set it to
+     * intentionally pick up in-range updates (≈ `npm update`).
      */
     refreshLockfile?: boolean;
     /**
-     * Per-package version overrides — `<name> → <range>`. Applied to every
-     * edge during dependency resolution, irrespective of the requester.
-     * Mirrors npm's top-level `overrides` field and yarn's `resolutions`
-     * (the simple, name-only flavour; pattern keys like `typescript@*` are
-     * normalised to bare `typescript` by the caller before passing in).
-     *
-     * Lets a workspace root pin a transitive dep version when the
-     * deduplicated tree would otherwise pick a different one — e.g. for
-     * forcing `typescript@~5.9` across every `typescript@*` devDep.
+     * Per-package version overrides — `<name> → <range>`, applied to every edge
+     * during resolution irrespective of the requester. Mirrors npm's top-level
+     * `overrides` and yarn's `resolutions` (name-only flavour; pattern keys like
+     * `typescript@*` are normalised to bare `typescript` by the caller). Lets a
+     * workspace root pin a transitive dep the deduplicated tree would otherwise
+     * resolve differently.
      */
     overrides?: Record<string, string>;
     /**
-     * Native backend only: skip transitive dependency resolution and only
-     * install the top-level requested packages. Use this when the packages
-     * are self-contained bundles whose declared `dependencies` are either
-     * bundled into the artifact (e.g. `@gjsify/cli`'s GJS bundle) or
-     * workspace-only packages not published to npm separately. Setting this
-     * avoids spurious packument fetches for workspace-internal packages.
+     * Native backend only: install only the top-level requested packages, skipping
+     * transitive resolution. For self-contained bundles whose declared
+     * `dependencies` are either bundled into the artifact (e.g. `@gjsify/cli`'s GJS
+     * bundle) or workspace-only and never published, where resolution would only
+     * produce spurious packument fetches.
      *
-     * Has no effect when `frozen: true` (the lockfile already contains the
-     * full resolved tree and is used verbatim) or when `GJSIFY_INSTALL_BACKEND=npm`
-     * (npm does its own resolution and does not consult this flag).
+     * No effect under `frozen: true` (the lockfile holds the full resolved tree and
+     * is used verbatim) or `GJSIFY_INSTALL_BACKEND=npm` (npm resolves for itself).
      */
     skipDeps?: boolean;
     /**
-     * Native backend only: overall wall-clock budget for the install. When
-     * fired, in-flight packument + tarball fetches are aborted via their
-     * AbortSignals (the resolver/extractor surface the abort as a normal
-     * AbortError), so the user gets a clean failure instead of a silent
-     * hang. Zero or undefined disables the overall budget — per-request
-     * timeouts in @gjsify/npm-registry still apply.
+     * Native backend only: overall wall-clock budget. On firing, in-flight packument
+     * + tarball fetches abort via their AbortSignals (surfaced as a normal
+     * AbortError), so a stall fails cleanly instead of hanging. Zero/undefined
+     * disables the overall budget; per-request timeouts in @gjsify/npm-registry
+     * still apply.
      */
     signal?: AbortSignal;
     /**
-     * Native backend only: progress reporter for resolve / download / extract /
-     * link phases. The CLI auto-creates a TTY-aware reporter by default; pass
-     * a custom reporter (or the `NOOP` from `makeProgressReporter({enabled:false})`)
-     * to override.
+     * Native backend only: progress reporter for the resolve / download / extract /
+     * link phases. Defaults to a TTY-aware reporter; pass a custom one (or the
+     * `NOOP` from `makeProgressReporter({enabled:false})`) to override.
      */
     progress?: ProgressReporter;
     /**
-     * Native backend only: the names of the monorepo's own workspace packages.
-     * A package whose name is in this set is materialised as a symlink to its
-     * workspace source by `workspaceInstall`, never fetched from the registry —
-     * even when the lockfile or a transitive edge references a same-named
-     * published version (e.g. a `types-dev/<lib>` workspace that ALSO exists on
-     * npm). The native backend drops such names from `resolveDeps` AND from the
-     * fetch/extract set, so `extractOne` never tries to `rm` + overwrite a
-     * workspace source symlink (its data-loss guard would otherwise abort the
-     * whole install). The `npm` backend ignores this — npm resolves workspaces
-     * itself.
+     * Native backend only: the monorepo's own workspace package names. A name in
+     * this set is materialised as a symlink to its workspace source by
+     * `workspaceInstall` and never fetched, even when the lockfile or a transitive
+     * edge references a same-named PUBLISHED version (e.g. a `types-dev/<lib>`
+     * workspace that also exists on npm). Such names are dropped from `resolveDeps`
+     * AND from the fetch/extract set, so `extractOne` never tries to `rm` +
+     * overwrite a workspace source symlink — its data-loss guard would abort the
+     * whole install. The `npm` backend ignores this and resolves workspaces itself.
      */
     workspaceNames?: Set<string>;
     /**
-     * Native backend only: requester labels for top-level specs, keyed by the
-     * exact `"<name>@<range>"` spec string. `workspaceInstall` records which
-     * workspace(s) declared each aggregated external spec so the resolver's
-     * version-conflict warning can name BOTH sides of a conflict ("^1 requested
-     * by @scope/a, ^2 requested by @scope/b"). Optional — flows without
-     * per-requester attribution (single-project installs, dlx) omit it and the
-     * warning falls back to the bare ranges.
+     * Native backend only: requester labels for top-level specs, keyed by the exact
+     * `"<name>@<range>"` string, so the resolver's version-conflict warning can name
+     * BOTH sides ("^1 requested by @scope/a, ^2 requested by @scope/b"). Optional —
+     * flows without per-requester attribution (single-project installs, dlx) omit it
+     * and the warning falls back to bare ranges.
      */
     specOrigins?: Map<string, string[]>;
 }
 export interface InstallResult {
-    /** Top-level packages that were requested, with the version each
-     *  resolved to. Empty for the npm backend (parsing npm's stdout would
-     *  be unreliable; callers that need this should set
-     *  GJSIFY_INSTALL_BACKEND=native). */
+    /** Requested top-level packages with the version each resolved to. Empty for
+     *  the npm backend — parsing npm's stdout would be unreliable, so a caller that
+     *  needs this must use the native backend. */
     installed: Array<{
         name: string;
         version: string;

package/lib/utils/install-backend.js

@@ -1,17 +1,15 @@
 // Install backend abstraction.
 //
-// Default: native backend (resolves packuments via @gjsify/npm-registry,
-// extracts tarballs via @gjsify/tar — no Node, no npm required at runtime).
-// Fallback: `npm install --no-package-lock --no-audit --no-fund --prefix <dir> <specs...>`,
-// for parity with the legacy code path. Switched via
-// `GJSIFY_INSTALL_BACKEND=native|npm`.
+// Default: native backend (resolves packuments via @gjsify/npm-registry, extracts
+// tarballs via @gjsify/tar — no Node, no npm required at runtime). Fallback:
+// `npm install`. Switched via `GJSIFY_INSTALL_BACKEND=native|npm`.
 //
 // `gjsify dlx` uses this seam — installing under a cache prefix, with no
-// package.json update to the user's project. The native backend matches that
-// workflow without ever shelling out to Node.
+// package.json update to the user's project.
 //
-// `--no-package-lock` keeps the cache prepare dir hermetic; the cache key
-// already covers reproducibility. `--no-audit --no-fund` cuts ~5s off cold runs.
+// On the npm path, `--no-package-lock` keeps the cache prepare dir hermetic (the
+// cache key already covers reproducibility) and `--no-audit --no-fund` cuts ~5s
+// off cold runs.
 import { writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { spawnToCompletion } from './spawn.js';
@@ -30,8 +28,8 @@ async function installViaNpm({ prefix, specs, verbose, registry }) {
     if (specs.length === 0) {
         throw new Error('installPackages: empty specs list');
     }
-    // Seed an empty package.json so npm doesn't walk up from prefix and pick
-    // up the user's project metadata. Cosmetic name/version only.
+    // Seed an empty package.json so npm doesn't walk up from prefix and pick up the
+    // user's project metadata. Cosmetic name/version only.
     writeFileSync(join(prefix, 'package.json'), JSON.stringify({ name: 'gjsify-dlx-cache', version: '0.0.0', private: true }, null, 2));
     if (registry) {
         writeFileSync(join(prefix, '.npmrc'), `registry=${registry}\n`);
@@ -46,17 +44,14 @@ async function installViaNpm({ prefix, specs, verbose, registry }) {
         ...(verbose ? ['--loglevel', 'verbose'] : ['--loglevel', 'warn']),
         ...specs,
     ];
-    // Through `spawnToCompletion` so `npm` is resolved the way every other
-    // spawn in the CLI resolves it. A bare `spawn('npm', …)` is ENOENT on
-    // Windows — `CreateProcess` appends only `.exe` and npm ships a `.cmd`
-    // shim (see utils/win32-command.ts). That made this backend unusable
-    // there, and the ENOENT hint below actively misdiagnosed it: npm IS on
-    // PATH on such a host, and it told the user to select the backend that
-    // was already the default while calling it unsupported.
+    // Through `spawnToCompletion` because a bare `spawn('npm', …)` is ENOENT on
+    // Windows — `CreateProcess` appends only `.exe` and npm ships a `.cmd` shim
+    // (see utils/win32-command.ts). That made this backend unusable there while the
+    // ENOENT hint below misdiagnosed it as npm being absent from PATH.
     //
-    // `completion: 'return'` — `installPackages` resolves a promise to its
-    // caller instead of exiting, so under GJS this must not leave a main loop
-    // armed. (Moot in practice: this backend needs npm, hence Node.)
+    // `completion: 'return'` — this resolves a promise to its caller instead of
+    // exiting, so under GJS it must not leave a main loop armed. (Moot in practice:
+    // this backend needs npm, hence Node.)
     const { code } = await spawnToCompletion('npm', args, {
         completion: 'return',
         notFound: (err) => new Error(`npm not found on PATH — install Node.js, or unset GJSIFY_INSTALL_BACKEND to use the default native backend (${err.message})`),

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

@@ -6,26 +6,21 @@
  */
 export declare function gjsifyCacheRoot(kind: string, layoutVersion: string): string;
 /**
- * Write `bytes` to `path` atomically: write a `<path>.tmp.<pid>` sibling, then
- * `rename` it into place, so a concurrent reader never observes a half-written
- * file. Creates the parent directory. Best-effort — any failure (read-only /
- * out-of-disk cache volume) is swallowed so a cache hiccup never breaks the
- * install; the caller proceeds with its in-memory copy.
+ * Write `bytes` to `path` atomically via a `<path>.tmp.<pid>` sibling + `rename`. Best-effort:
+ * any failure (read-only / out-of-disk cache volume) is swallowed so a cache hiccup never
+ * breaks the install — the caller proceeds with its in-memory copy.
  */
 export declare function atomicWrite(path: string, bytes: Uint8Array | string): void;
 /**
- * Strict sibling of {@link atomicWrite}: identical tmp+`rename` pattern, but
- * failures PROPAGATE to the caller. Use for files whose corruption/loss must
- * abort the operation (the `gjsify-lock.json` writer) rather than degrade
- * silently like a cache entry. `rename` over the destination is atomic on
- * POSIX, so a concurrent reader (or a crash mid-write) sees either the old
- * complete file or the new complete file — never a torn one.
+ * Strict sibling of {@link atomicWrite}: same tmp+`rename` pattern, but failures PROPAGATE.
+ * Use for files whose loss must abort the operation (the `gjsify-lock.json` writer) rather
+ * than degrade silently like a cache entry. `rename` over the destination is atomic on POSIX,
+ * so a concurrent reader — or a crash mid-write — sees the old or the new file, never a torn one.
  */
 export declare function atomicWriteStrict(path: string, bytes: Uint8Array | string): void;
 /**
- * Read a cache file, returning its bytes on a HIT or `null` on a MISS. A
- * missing file, a zero-byte file (an interrupted previous write), or any read
- * error are all treated as a MISS — the file is left untouched so a follow-up
- * writer's atomic rename isn't disturbed.
+ * Read a cache file: bytes on a HIT, `null` on a MISS. Missing, zero-byte (an interrupted
+ * previous write) and unreadable all count as a MISS, and the file is left untouched so a
+ * follow-up writer's atomic rename isn't disturbed.
  */
 export declare function readCacheFile(path: string): Buffer | null;

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

@@ -2,18 +2,15 @@
 // Shared filesystem primitives for `gjsify install`'s on-disk caches and its
 // lockfile writer.
 //
-// Both the content-addressable tarball cache (install-tarball-cache.ts) and the
-// packument metadata cache (install-packument-cache.ts) need the same three
-// things: an `XDG_CACHE_HOME`-honouring cache root, an atomic write (so a
-// concurrent install never observes a half-written entry), and a read that
-// treats a missing / zero-byte / unreadable file as a MISS. Centralising them
-// here keeps the two caches byte-for-byte consistent. The lockfile writer
-// (`gjsify-lock.json`) shares the same tmp+rename pattern via the strict
-// variant so an interrupted install can never leave a torn lockfile behind.
+// The tarball cache (install-tarball-cache.ts) and the packument metadata cache
+// (install-packument-cache.ts) need the same three things: an `XDG_CACHE_HOME`-honouring
+// root, an atomic write (so a concurrent install never observes a half-written entry), and a
+// read treating missing / zero-byte / unreadable as a MISS. The `gjsify-lock.json` writer
+// shares the tmp+rename pattern via the strict variant, so an interrupted install cannot
+// leave a torn lockfile.
 //
-// Out of scope: the dlx cache (`dlx-cache.ts`) has a different layout
-// (`gjsify/dlx`, sha256 + symlink-swap) and its own TTL/prepare-dir concerns —
-// it is a precedent for the XDG helper, not a reuse target.
+// Out of scope: the dlx cache (`dlx-cache.ts`) has a different layout (`gjsify/dlx`, sha256 +
+// symlink-swap) and its own TTL concerns — a precedent for the XDG helper, not a reuse target.
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -29,11 +26,9 @@ export function gjsifyCacheRoot(kind, layoutVersion) {
     return join(base, 'gjsify', kind, layoutVersion);
 }
 /**
- * Write `bytes` to `path` atomically: write a `<path>.tmp.<pid>` sibling, then
- * `rename` it into place, so a concurrent reader never observes a half-written
- * file. Creates the parent directory. Best-effort — any failure (read-only /
- * out-of-disk cache volume) is swallowed so a cache hiccup never breaks the
- * install; the caller proceeds with its in-memory copy.
+ * Write `bytes` to `path` atomically via a `<path>.tmp.<pid>` sibling + `rename`. Best-effort:
+ * any failure (read-only / out-of-disk cache volume) is swallowed so a cache hiccup never
+ * breaks the install — the caller proceeds with its in-memory copy.
  */
 export function atomicWrite(path, bytes) {
     try {
@@ -44,12 +39,10 @@ export function atomicWrite(path, bytes) {
     }
 }
 /**
- * Strict sibling of {@link atomicWrite}: identical tmp+`rename` pattern, but
- * failures PROPAGATE to the caller. Use for files whose corruption/loss must
- * abort the operation (the `gjsify-lock.json` writer) rather than degrade
- * silently like a cache entry. `rename` over the destination is atomic on
- * POSIX, so a concurrent reader (or a crash mid-write) sees either the old
- * complete file or the new complete file — never a torn one.
+ * Strict sibling of {@link atomicWrite}: same tmp+`rename` pattern, but failures PROPAGATE.
+ * Use for files whose loss must abort the operation (the `gjsify-lock.json` writer) rather
+ * than degrade silently like a cache entry. `rename` over the destination is atomic on POSIX,
+ * so a concurrent reader — or a crash mid-write — sees the old or the new file, never a torn one.
  */
 export function atomicWriteStrict(path, bytes) {
     mkdirSync(join(path, '..'), { recursive: true });
@@ -58,10 +51,9 @@ export function atomicWriteStrict(path, bytes) {
     renameSync(tmp, path);
 }
 /**
- * Read a cache file, returning its bytes on a HIT or `null` on a MISS. A
- * missing file, a zero-byte file (an interrupted previous write), or any read
- * error are all treated as a MISS — the file is left untouched so a follow-up
- * writer's atomic rename isn't disturbed.
+ * Read a cache file: bytes on a HIT, `null` on a MISS. Missing, zero-byte (an interrupted
+ * previous write) and unreadable all count as a MISS, and the file is left untouched so a
+ * follow-up writer's atomic rename isn't disturbed.
  */
 export function readCacheFile(path) {
     if (!existsSync(path))

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

@@ -3,12 +3,11 @@ export interface InstallLockHandle {
     release(): void;
 }
 /**
- * Acquire the cross-process install lock for `prefix`. Resolves once this
- * process may mutate `<prefix>/node_modules` + `<prefix>/gjsify-lock.json`;
- * the caller MUST `release()` in a `finally`. Waits (with backoff) while a
- * live concurrent install holds the lock; steals provably-stale locks (dead
- * owner pid / exceeded staleness budget). `signal` aborts the wait — wired
- * to the overall install budget so a waiter never outlives its own timeout.
+ * Acquire the cross-process install lock for `prefix`, resolving once this process may mutate
+ * `<prefix>/node_modules` + `<prefix>/gjsify-lock.json`. The caller MUST `release()` in a
+ * `finally`. Waits with backoff while a live install holds the lock, and steals provably-stale
+ * ones. `signal` aborts the wait — wired to the install budget so a waiter never outlives its
+ * own timeout.
  */
 export declare function acquireInstallLock(prefix: string, opts?: {
     signal?: AbortSignal;

package/lib/utils/install-lock.js

@@ -1,48 +1,36 @@
 // SPDX-License-Identifier: MIT
 // Cross-process install lock for `gjsify install` (ADR 0001, step 2).
 //
-// WHAT is locked: mutation of ONE install prefix — its `node_modules/` tree,
-// its `gjsify-lock.json`, and (through the same code path) the user-global
-// prefix that `gjsify install -g` extracts into. Two processes installing
-// into the SAME prefix used to interleave `rmSync` + extract on the same
-// destination directories (corrupt trees, spurious ENOENT mid-extract) and
-// tear the lockfile. The lock serializes them. Installs into DIFFERENT
-// prefixes stay fully concurrent.
+// LOCKED: mutation of ONE install prefix — its `node_modules/` tree, its `gjsify-lock.json`, and
+// the user-global prefix `gjsify install -g` extracts into. Two processes installing into the
+// SAME prefix interleaved `rmSync` + extract on the same destinations (corrupt trees, spurious
+// ENOENT mid-extract) and tore the lockfile. Different prefixes stay fully concurrent.
 //
-// WHAT is deliberately NOT locked: the shared XDG caches
-// (`$XDG_CACHE_HOME/gjsify/{tarballs,metadata}`). Those are content-addressed
-// and written via atomic tmp+`rename` (`install-cache-fs.ts`), so concurrent
-// writers are already safe lock-free — identical-content last-rename-wins.
+// NOT LOCKED: the shared XDG caches (`$XDG_CACHE_HOME/gjsify/{tarballs,metadata}`) — they are
+// content-addressed and written via atomic tmp+`rename` (`install-cache-fs.ts`), so concurrent
+// writers are already safe lock-free.
 //
-// Mechanism: `mkdir` of `<prefix>/node_modules/.gjsify-install-lock` is the
-// atomic acquire. mkdir has exclusive-create semantics on every runtime we
-// target: Node's `mkdirSync` throws EEXIST, and the GJS fs polyfill maps
-// Gio's G_IO_ERROR_EXISTS to the same code. (A lock FILE with `flag: 'wx'`
-// would NOT work — the GJS `writeFileSync` polyfill ignores open flags and
-// happily overwrites.) An `owner.json` inside the dir records pid + start
-// time for staleness checks and diagnostics.
+// Mechanism: `mkdir` of `<prefix>/node_modules/.gjsify-install-lock` is the atomic acquire, with
+// exclusive-create semantics on every runtime targeted (Node's `mkdirSync` throws EEXIST; the
+// GJS fs polyfill maps Gio's G_IO_ERROR_EXISTS to the same code). A lock FILE with `flag: 'wx'`
+// would NOT work — the GJS `writeFileSync` polyfill ignores open flags and overwrites. An
+// `owner.json` inside records pid + start time for staleness checks.
 //
-// Staleness: a crashed install cannot release its lock, so contenders steal
-// when
-//   (a) the owner pid is provably dead (`/proc/<pid>` on Linux — readable
-//       under both Node and GJS; a kill(0) probe covers non-/proc Nodes), or
-//   (b) the lock outlives GJSIFY_INSTALL_LOCK_STALE_MS (default 35 min —
-//       just above the 30-min overall install budget, so a budget-bound
-//       install always times out and exits before its lock can be stolen
-//       out from under it), or
-//   (c) `mkdir` succeeded but `owner.json` never appeared within a short
-//       grace period (the owner died between the two steps).
-// The steal itself is race-free: the stale dir is claimed via an atomic
-// `rename` to a unique sibling name — exactly one contender's rename
-// succeeds; losers see ENOENT and simply retry the acquire loop.
+// Staleness — a crashed install cannot release its lock, so contenders steal when
+//   (a) the owner pid is provably dead (`/proc/<pid>` on Linux, readable under Node and GJS
+//       alike; a kill(0) probe covers non-/proc Nodes), or
+//   (b) the lock outlives GJSIFY_INSTALL_LOCK_STALE_MS (default 35 min — just above the 30-min
+//       install budget, so a budget-bound install always exits before its lock can be stolen out
+//       from under it), or
+//   (c) `mkdir` succeeded but `owner.json` never appeared within a short grace period.
+// The steal is race-free: the stale dir is claimed by an atomic `rename` to a unique sibling, so
+// exactly one contender wins and losers see ENOENT and retry the acquire loop.
 //
-// Re-entrant per process: `workspaceInstall` holds the root-prefix lock for
-// the whole workspace flow while the inner `installPackagesNative` calls
-// re-acquire the same prefix — those just bump a refcount.
+// Re-entrant per process: `workspaceInstall` holds the root-prefix lock for the whole workspace
+// flow while inner `installPackagesNative` calls re-acquire the same prefix and just refcount.
 //
-// Escape hatch: GJSIFY_INSTALL_LOCK=0 disables locking entirely (e.g. for a
-// network filesystem with broken rename/mkdir atomicity, or an outer tool
-// that already serializes installs).
+// GJSIFY_INSTALL_LOCK=0 disables locking entirely — for a network filesystem with broken
+// rename/mkdir atomicity, or an outer tool that already serializes installs.
 import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 const LOCK_DIR_NAME = '.gjsify-install-lock';
@@ -75,18 +63,15 @@ function lockingDisabled() {
 /**
  * Is `pid` a live process on this machine?
  *
- * `/proc/<pid>` is the reliable cross-runtime probe on Linux (the primary
- * target): it works identically under Node and GJS. Elsewhere fall back to a
- * signal-0 probe — ESRCH means dead, EPERM means alive-but-foreign. The GJS
- * `process.kill` polyfill shells out and cannot report ESRCH, but GJS only
- * runs on /proc platforms in practice, so the fallback branch is Node's.
- * Unknown outcomes are treated as ALIVE (conservative — never steal a lock
- * we cannot prove abandoned; the mtime staleness budget still applies).
+ * `/proc/<pid>` is the reliable cross-runtime probe on Linux, identical under Node and GJS;
+ * elsewhere a signal-0 probe (ESRCH dead, EPERM alive-but-foreign). The GJS `process.kill`
+ * polyfill shells out and cannot report ESRCH, but GJS only runs on /proc platforms in practice,
+ * so the fallback branch is Node's. Unknown outcomes count as ALIVE — never steal a lock that
+ * cannot be proven abandoned; the mtime staleness budget still applies.
  */
 function isPidAlive(pid) {
-    // `existsSync` never throws by contract: Node returns false on any error,
-    // and the GJS shim is a typeof guard + Gio `query_exists` (both without a
-    // throw path in the GIR). Off Linux the `if` is simply false.
+    // `existsSync` never throws by contract: Node returns false on any error, and the GJS shim is
+    // a typeof guard + Gio `query_exists`, neither with a throw path in the GIR.
     if (existsSync('/proc/self'))
         return existsSync(`/proc/${pid}`);
     try {
@@ -122,9 +107,8 @@ function assessLock(lockDir) {
         }
         const started = typeof owner.startedAt === 'number' ? owner.startedAt : mtimeMs(ownerPath);
         if (started !== null && now - started > staleMs()) {
-            // Alive but far beyond any plausible install duration — the
-            // observed 0%-CPU hung-install shape. Steal so one wedged
-            // process can't block every future install of this prefix.
+            // Alive but far beyond any plausible install duration — the observed 0%-CPU
+            // hung-install shape. Steal, so one wedged process cannot block this prefix forever.
             return {
                 stale: true,
                 reason: `owner pid ${owner.pid} exceeded the ${staleMs()}ms staleness budget`,
@@ -133,8 +117,8 @@ function assessLock(lockDir) {
         }
         return { stale: false, ownerPid: owner.pid };
     }
-    // No readable owner.json: the winner may be between mkdir and the owner
-    // write — give it a grace period, then treat the dir as abandoned.
+    // No readable owner.json: the winner may be between mkdir and the owner write, so allow a
+    // grace period before treating the dir as abandoned.
     const dirMtime = mtimeMs(lockDir);
     if (dirMtime === null)
         return { stale: false }; // vanished — retry mkdir
@@ -144,9 +128,8 @@ function assessLock(lockDir) {
     return { stale: false };
 }
 /**
- * Atomically claim + remove a stale lock dir. Returns `true` when THIS
- * process won the claim (the rename succeeded), `false` when another
- * contender got there first — the caller just retries its acquire loop.
+ * Atomically claim + remove a stale lock dir. `true` when THIS process won the claim, `false`
+ * when another contender got there first — the caller just retries its acquire loop.
  */
 function stealStaleLock(lockDir) {
     const claimed = `${lockDir}.stale-${process.pid}-${++stealCounter}`;
@@ -206,8 +189,8 @@ function makeHandle(lockDir) {
             if (entry.count > 0)
                 return;
             held.delete(lockDir);
-            // Only remove the on-disk dir when it is still OURS — a staleness
-            // steal could have handed the path to another process meanwhile.
+            // Only remove the on-disk dir when it is still OURS — a staleness steal could have
+            // handed the path to another process meanwhile.
             try {
                 const owner = JSON.parse(readFileSync(join(lockDir, OWNER_FILE), 'utf-8'));
                 if (owner.nonce !== undefined && owner.nonce !== entry.nonce)
@@ -226,12 +209,11 @@ function makeHandle(lockDir) {
     };
 }
 /**
- * Acquire the cross-process install lock for `prefix`. Resolves once this
- * process may mutate `<prefix>/node_modules` + `<prefix>/gjsify-lock.json`;
- * the caller MUST `release()` in a `finally`. Waits (with backoff) while a
- * live concurrent install holds the lock; steals provably-stale locks (dead
- * owner pid / exceeded staleness budget). `signal` aborts the wait — wired
- * to the overall install budget so a waiter never outlives its own timeout.
+ * Acquire the cross-process install lock for `prefix`, resolving once this process may mutate
+ * `<prefix>/node_modules` + `<prefix>/gjsify-lock.json`. The caller MUST `release()` in a
+ * `finally`. Waits with backoff while a live install holds the lock, and steals provably-stale
+ * ones. `signal` aborts the wait — wired to the install budget so a waiter never outlives its
+ * own timeout.
  */
 export async function acquireInstallLock(prefix, opts = {}) {
     if (lockingDisabled()) {
@@ -241,8 +223,7 @@ export async function acquireInstallLock(prefix, opts = {}) {
             },
         };
     }
-    // Canonicalize so two spellings of the same prefix (symlink, relative
-    // path) share one re-entrancy slot.
+    // Canonicalize so two spellings of one prefix (symlink, relative path) share a re-entrancy slot.
     let canonicalPrefix;
     try {
         canonicalPrefix = realpathSync(prefix);

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

@@ -1,9 +1,8 @@
 import type { Packument } from '@gjsify/npm-registry';
 /**
  * Which document shape an entry holds. `'corgi'` = the abbreviated
- * `application/vnd.npm.install-v1+json` install document (the default for every
- * resolve); `'full'` = `application/json`. Same names pacote uses, so the two
- * caches are describable in one sentence.
+ * `application/vnd.npm.install-v1+json` install document; `'full'` =
+ * `application/json`, the only one carrying `libc`. Same names pacote uses.
  */
 export type PackumentShape = 'corgi' | 'full';
 export interface CachedPackument {
@@ -14,47 +13,42 @@ export interface CachedPackument {
  * 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 declare function packumentCacheKey(registry: string, name: string, shape: PackumentShape): string;
 /**
- * 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 declare function getCachedPackument(registry: string, name: string, shape?: PackumentShape): CachedPackument | null;
 /**
  * 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 declare function putCachedPackument(registry: string, name: string, etag: string, packument: Packument, shape?: PackumentShape): void;