@gjsify/cli 0.51.1 → 0.53.0

package/lib/utils/install-backend-native.js

@@ -45,8 +45,20 @@
 //      (v4); without it the fresh-resolve and lockfile paths disagree about one
 //      tree.
 //
-// Out of scope (still deferred): peerDependencies validation, lifecycle scripts,
-// git/file specs.
+// PEER DEPENDENCIES follow npm ≥ 7: every peer NOT marked optional in
+// `peerDependenciesMeta` is installed where the dependent resolves it — as its
+// SIBLING (queued from the dependent's parent, so the dependent and whatever
+// requires it share one instance), reusing any visible copy whose version
+// satisfies the range. Optional peers are never installed, exactly as npm skips
+// them; ADR 0020's `@gjsify/rolldown-native` depends on that. The defect this
+// closes: `wxt` declares `vite` as a required peer, `gjsify install` exited 0
+// without it, and `wxt prepare` died with "Builder not found". A peer edge is a
+// REQUIRED edge for the optionality fixpoint ({@link requiredPeerEntries}), so
+// the lockfile records the peer maps and marks a peer-aware resolve
+// (`Lockfile.peersResolved` says why that is a marker and not a version bump).
+//
+// Out of scope (still deferred): lifecycle scripts, git/file specs, and npm's
+// strict-peer-deps ERESOLVE (a conflicting peer warns, see `resolveDeps`).
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
@@ -60,6 +72,9 @@ import { getCachedPackument, putCachedPackument } from './install-packument-cach
 import { assertNativeBackendNodeVersion } from './node-version.js';
 import { buildCmdShim, buildLauncherShims, buildNativeEnvPreamble, buildShLauncher, isGjsBundlePath, parseShebang, pickBinMap, } from './bin-shim.js';
 import { detectNativePackages } from './detect-native-packages.js';
+import { findExtraneous, formatExtraneousError } from './install-extraneous.js';
+import { devLinkPath, devLinkRoot } from './dev-link.js';
+import { scanPrefix } from './prune-prefix.js';
 import { badPlatformError, checkPlatform, declaresPlatform, describePlatformTarget, readPlatformForce, resolveHostPlatform, } from './platform-check.js';
 // 16-wide download pool, matched to the shared Soup.Session's lifted
 // `max-conns-per-host` (@gjsify/fetch `getSharedSession`) — without that lift
@@ -157,10 +172,19 @@ async function installPackagesNativeLocked(opts, npmrc, log) {
         }
         log('install: --immutable, using lockfile (%d package(s))', Object.keys(existingLock.packages).length);
         nodes = lockfileToNodes(existingLock);
+        // ...and the tree must hold NOTHING ELSE. The installer only adds, so without
+        // this an undescribed package survives the install and exits 0 — the CI cache
+        // poisoning of gjsify#1683 (install-extraneous.ts carries the incident).
+        // Before the download so a wrong tree costs seconds, not the extract phase,
+        // and with the FULL lockfile set: the workspace filter below removes nodes
+        // that ARE described, and judging against the smaller set would call them
+        // strangers.
+        assertNoExtraneous(opts.prefix, nodes);
     }
     else if (!opts.refreshLockfile &&
         existingLock &&
         existingLock.lockfileVersion === LOCKFILE_VERSION &&
+        existingLock.peersResolved === true &&
         lockfileMatchesRequest(existingLock, opts.specs)) {
         log('install: using lockfile (%d package(s))', Object.keys(existingLock.packages).length);
         nodes = lockfileToNodes(existingLock);
@@ -168,6 +192,9 @@ async function installPackagesNativeLocked(opts, npmrc, log) {
     else {
         // A resolve has to run (new/changed/removed dep, or no lockfile yet).
         //
+        // So does a lockfile without `peersResolved`: it may lack a required peer
+        // (Lockfile.peersResolved).
+        //
         // A pre-v4 lockfile lands here too even when it matches the request: each
         // bump added something the verdict is recomputed FROM, so a file lacking it
         // cannot be consumed verbatim — pre-v3 entries carry no platform
@@ -209,6 +236,16 @@ async function installPackagesNativeLocked(opts, npmrc, log) {
         writeLockfile(lockfilePath, opts.specs, nodes);
         log('install: wrote %s (%d entries)', LOCKFILE_NAME, nodes.length);
     }
+    // TWO NAMES FROM HERE ON, and the split is the fix for a measured defect.
+    // `nodes` stays the FULL resolved tree — what the lockfile describes and what
+    // `topLevelResolutions` answers from. `fetchable` is the subset that still has
+    // to come off the network. A package can be present without being fetched, and
+    // collapsing the two made the installer forget it existed: with a `gjsify link`
+    // active, `gjsify install is-odd` read the FILTERED array, found no `is-odd`
+    // resolution, and wrote `"is-odd": "latest"` into package.json and
+    // `is-odd@latest` into the lockfile's `requested` — over the `^3.0.1` the
+    // control run without the link produced. Never re-merge these two names.
+    let fetchable = nodes;
     // A package named after one of the monorepo's own workspaces is provided by a
     // workspace symlink (wired by `workspaceInstall`), NOT by a registry tarball —
     // even when the lockfile or a transitive edge pins a same-named published
@@ -217,26 +254,55 @@ async function installPackagesNativeLocked(opts, npmrc, log) {
     // `--immutable` robust against a committed lockfile that still carries such
     // entries, since that path never runs `resolveDeps`.
     if (opts.workspaceNames && opts.workspaceNames.size > 0) {
-        const before = nodes.length;
-        nodes = nodes.filter((n) => !opts.workspaceNames.has(n.name));
-        const dropped = before - nodes.length;
+        const before = fetchable.length;
+        fetchable = fetchable.filter((n) => !opts.workspaceNames.has(n.name));
+        const dropped = before - fetchable.length;
         if (dropped > 0) {
             log('install: %d workspace-provided package(s) symlinked, not fetched', dropped);
         }
     }
+    // Same exclusion, different reason and a different position in the pipeline: a
+    // `gjsify link` override provides these from a local checkout. It runs AFTER the
+    // lockfile write above on purpose — the consumer's committed lockfile must stay
+    // byte-identical whether or not a link is active (utils/dev-link.ts).
+    if (opts.linkedNames && opts.linkedNames.size > 0) {
+        const before = fetchable.length;
+        fetchable = fetchable.filter((n) => !opts.linkedNames.has(n.name));
+        const dropped = before - fetchable.length;
+        if (dropped > 0) {
+            log('install: %d dev-linked package(s) provided by a local checkout, not fetched', dropped);
+        }
+    }
     // os/cpu/libc: throws for an incompatible REQUIRED dep, marks incompatible
     // OPTIONAL ones inert. Runs on BOTH paths (fresh resolve and lockfile) —
     // that is what makes one committed lockfile install a per-host subset.
-    const installable = applyPlatformFilter(nodes, target, force, log);
+    const installable = applyPlatformFilter(fetchable, target, force, log);
     log('install: downloading %d tarball(s)', installable.length);
     await downloadAndExtractAll(installable, opts.prefix, npmrc, log, opts.signal, progress);
     await linkBins(installable, opts.prefix, log);
     warnMissingNativeBuilds(installable, opts.prefix, log);
     log('install: done');
     // Top-level requested packages only, so callers can write the resolved version
-    // back into package.json (`npm install --save`).
+    // back into package.json (`npm install --save`). From `nodes`, NEVER from
+    // `fetchable`: "what is installed at node_modules/<name>" is not "what was
+    // downloaded", and a provided package is installed.
     return topLevelResolutions(opts.specs, nodes);
 }
+/**
+ * `--immutable` only: refuse a `node_modules` holding packages the lockfile does not
+ * describe, naming every one of them.
+ *
+ * Deliberately NOT a prune — the reasoning, and the incident it comes from, are the
+ * header note of `install-extraneous.ts`. Scoped to the frozen path: a plain install
+ * resolves a NEW tree and may legitimately leave an older placement behind for its
+ * own prune pass to judge, so this rule would be wrong there.
+ */
+function assertNoExtraneous(prefix, nodes) {
+    const extraneous = findExtraneous({ prefix, installed: scanPrefix(prefix), expected: nodes });
+    if (extraneous.length === 0)
+        return;
+    throw new Error(formatExtraneousError(extraneous, prefix));
+}
 function errMsg(err) {
     if (err instanceof Error)
         return err.message;
@@ -483,7 +549,7 @@ optionalSpecs) {
     // `workspaceInstall` produces when two workspaces declare incompatible ranges of
     // the same external dep) all compete for the single root slot and the resolver
     // silently keeps one version for everyone. Per-workspace dedup is Phase D.8
-    // (status/open-todos.md); until it lands the conflict is surfaced loudly after
+    // (status/open-todos/README.md); until it lands the conflict is surfaced loudly after
     // the resolve (see emitTopLevelConflictWarnings).
     const topLevelRanges = new Map();
     const queue = specs.map(parseSpec).map((s) => {
@@ -551,6 +617,23 @@ optionalSpecs) {
                 // {@link computeOptionalFlags} is the only writer of the final flag.
                 continue;
             }
+            // A peer must live in ONE directory — beside its dependent. If that slot
+            // already holds a version outside the range, a private copy would give the
+            // dependent a different instance from its requester, which is the thing a
+            // peer exists to prevent. npm ≥ 7 raises ERESOLVE here in strict mode and,
+            // non-strict (`--force`, or a conflict below the root), warns "overriding
+            // peer dependency" and keeps the existing copy. We take the lenient answer:
+            // warn, keep it, install nothing.
+            if (edge.peerOf) {
+                const slot = edge.from === null ? `node_modules/${edge.name}` : `${edge.from}/node_modules/${edge.name}`;
+                const occupant = byPath.get(slot);
+                if (occupant) {
+                    console.warn(`[gjsify] warning: peer dependency conflict: ${edge.peerOf.name}@${edge.peerOf.version} ` +
+                        `wants ${edge.name}@${edge.range}, but ${occupant.version} is installed at ` +
+                        `${occupant.installPath} — keeping it (npm's non-strict behaviour).`);
+                    continue;
+                }
+            }
             // No compatible placement. Resolve a version, preferring one already
             // pinned when it satisfies the range so an add does not bump unchanged
             // deps.
@@ -579,6 +662,8 @@ optionalSpecs) {
                     installPath,
                     dependencies: v.dependencies ?? {},
                     optionalDependencies: v.optionalDependencies ?? {},
+                    peerDependencies: nonEmpty(v.peerDependencies),
+                    peerDependenciesMeta: nonEmpty(v.peerDependenciesMeta),
                     bin: v.bin,
                     // Complete as published: `fetchPkg` reads the FULL document, so all
                     // three fields come from one body — no second fetch, no heuristic.
@@ -603,6 +688,20 @@ optionalSpecs) {
                     name: `${edge.name}@${version}`,
                 });
                 if (!skipDeps) {
+                    // Required peers FIRST, so the peer claims its slot beside the
+                    // dependent before the dependent's own subtree can hoist an
+                    // incompatible copy of the same name into it. Queued from the PARENT
+                    // (`Edge.peerOf`); optional peers are never queued, npm ≥ 7 skips them.
+                    const parent = parentInstallPath(installPath);
+                    for (const [peerName, peerRange] of requiredPeerEntries(node)) {
+                        queue.push({
+                            from: parent,
+                            name: peerName,
+                            range: applyOverride(peerName, peerRange),
+                            required: !node.optional,
+                            peerOf: node,
+                        });
+                    }
                     // REQUIRED edges only — a name this package also lists in
                     // `optionalDependencies` is queued once by the loop below, as
                     // optional (header note, invariant 3). Queuing it here too would
@@ -643,7 +742,9 @@ optionalSpecs) {
                     // `assertRequiredEdgesResolved` re-judges every entry against the
                     // fixpoint flags, so a genuinely required dependency cannot go missing
                     // just because BFS reached it through an optional edge first.
-                    skippedEdges.add(edgeKey(edge.from, edge.name));
+                    // A peer edge is keyed by its DEPENDENT, not by `from`: the dependent
+                    // is the requester whose final optionality decides the verdict.
+                    skippedEdges.add(edgeKey(edge.peerOf?.installPath ?? edge.from, edge.name));
                     log('resolve: optional dep %s@%s skipped (%s)', edge.name, edge.range, errMsg(e));
                     continue;
                 }
@@ -748,6 +849,27 @@ export function requiredDepEntries(node) {
     }
     return entries;
 }
+/**
+ * A node's REQUIRED peer edges: its `peerDependencies` minus those
+ * `peerDependenciesMeta` marks `optional` (npm ≥ 7 installs the rest and skips
+ * these) and minus any name it also lists as a dependency — that edge is walked
+ * from the node itself by {@link requiredDepEntries}, or is optional because the
+ * publisher said so in `optionalDependencies`.
+ *
+ * Shared by the resolve walk and the optionality fixpoint, for the reason
+ * {@link requiredDepEntries} is: two readings of one manifest are two answers.
+ */
+export function requiredPeerEntries(node) {
+    const entries = [];
+    for (const [name, range] of Object.entries(node.peerDependencies ?? {})) {
+        if (node.peerDependenciesMeta?.[name]?.optional === true)
+            continue;
+        if (name in node.dependencies || name in node.optionalDependencies)
+            continue;
+        entries.push([name, range]);
+    }
+    return entries;
+}
 /**
  * Recompute every node's `optional` flag as a FIXPOINT over the placed graph. The
  * only writer of the final flag; whatever the nodes arrive carrying is an input
@@ -755,7 +877,8 @@ export function requiredDepEntries(node) {
  * file on the lockfile path) and is overwritten unconditionally.
  *
  * DEFINITION: a node is REQUIRED iff reachable from `requiredNames` through
- * REQUIRED edges alone ({@link requiredDepEntries}); every other node is optional.
+ * REQUIRED edges alone ({@link requiredDepEntries} plus {@link requiredPeerEntries} —
+ * a peer npm installs is as mandatory as a dependency); every other node is optional.
  * Optionality is therefore INHERITED — a plain dependency OF an optional package is
  * still optional, which is what npm's `optionalSet` computes.
  *
@@ -811,7 +934,7 @@ export function computeOptionalFlags(nodes, requiredNames, log) {
         const node = byPath.get(installPath);
         if (!node)
             continue;
-        for (const [depName] of requiredDepEntries(node)) {
+        for (const [depName] of [...requiredDepEntries(node), ...requiredPeerEntries(node)]) {
             // Resolve the edge the way the REQUESTER will at runtime — through
             // the ancestor `node_modules` chain — so a nested copy is credited
             // to the requester that nested it and the hoisted one is not
@@ -902,7 +1025,7 @@ function assertRequiredEdgesResolved(nodes, skippedEdges) {
  * (dist-tags like `latest`) cannot be compared and are skipped.
  *
  * This makes the single-root-slot behaviour honest rather than silent; the real fix
- * is a per-workspace dedup pass, Phase D.8 (status/open-todos.md).
+ * is a per-workspace dedup pass, Phase D.8 (status/open-todos/README.md).
  */
 function emitTopLevelConflictWarnings(topLevelRanges, root) {
     for (const [name, ranges] of topLevelRanges) {
@@ -1032,6 +1155,11 @@ function findVisible(requesterPath, name, byPath) {
     }
     return null;
 }
+/** The `installPath` whose `node_modules` holds this one; null for a root placement. */
+function parentInstallPath(installPath) {
+    const idx = installPath.lastIndexOf('/node_modules/');
+    return idx < 0 ? null : installPath.slice(0, idx);
+}
 /**
  * Where to install `name@version` for a request from `requesterPath`: hoist to
  * `node_modules/<name>` when the root slot is empty or already holds this version,
@@ -1092,6 +1220,8 @@ function writeLockfile(lockfilePath, specs, nodes) {
             // `computeOptionalFlags` runs on the lockfile path too and cannot recompute
             // what the file does not carry (v4, header note invariant 3).
             optionalDependencies: Object.keys(node.optionalDependencies).length > 0 ? node.optionalDependencies : undefined,
+            peerDependencies: nonEmpty(node.peerDependencies),
+            peerDependenciesMeta: nonEmpty(node.peerDependenciesMeta),
             bin: node.bin,
             // The DECLARATION, never the verdict: `inert` is per-host and deliberately
             // absent from the file, since a lockfile recording which packages the
@@ -1106,12 +1236,16 @@ function writeLockfile(lockfilePath, specs, nodes) {
         lockfileVersion: LOCKFILE_VERSION,
         requested: [...specs],
         packages,
+        peersResolved: true,
     };
     // Atomic tmp+rename so a crash mid-write, or a reader racing the writer, can never
     // observe a torn gjsify-lock.json — `--immutable` would otherwise hard-fail on the
     // corrupt file with a misleading error.
     atomicWriteStrict(lockfilePath, JSON.stringify(lockfile, null, 2) + '\n');
 }
+function nonEmpty(map) {
+    return map && Object.keys(map).length > 0 ? map : undefined;
+}
 /**
  * The lockfile-preservation oracle: `name → every version currently pinned` (a name
  * can appear at more than one path/version when the tree nested a conflicting copy).
@@ -1164,6 +1298,8 @@ function lockfileToNodes(lockfile) {
             // blocks reads as required here. `--immutable` consumes it anyway — see
             // READABLE_LOCKFILE_VERSIONS.
             optionalDependencies: entry.optionalDependencies ?? {},
+            peerDependencies: entry.peerDependencies,
+            peerDependenciesMeta: entry.peerDependenciesMeta,
             bin: entry.bin,
             // Rebuilt from the recorded declaration so `applyPlatformFilter` reaches the
             // SAME verdict here as on the fresh-resolve path, for THIS host — generally
@@ -1378,7 +1514,7 @@ async function extractOne(node, prefix, npmrc, log, signal) {
     // fail if a workspace package leaked into the fetch/extract queue (the root cause
     // fixed in `workspaceInstall`), and refusing here means a resolver regression can
     // never again `rmSync` a working-tree source dir.
-    assertNodeModulesDest(dest, node);
+    assertNodeModulesDest(dest, node, prefix);
     // Idempotent fast-path — skip the cache read + rm + re-extract for a node already
     // extracted at the resolved version. The npm/yarn/pnpm default (only added/changed
     // nodes are written) and the dominant cost on a warm re-install.
@@ -1387,14 +1523,15 @@ async function extractOne(node, prefix, npmrc, log, signal) {
         log('up-to-date: %s@%s (already extracted at %s)', node.name, node.version, node.installPath);
         return true;
     }
-    // Content-addressable cache before the network: tarballs are immutable per SRI
-    // integrity, so a hash hit is byte-identical to what the registry would return and
-    // needs no verifying re-download.
-    let bytes = getCachedTarball(node.integrity);
+    // Content-addressable cache before the network. Both readers RE-HASH the bytes
+    // against the integrity that named them, so a hit is byte-identical to what the
+    // registry would return because it was checked, not because the path says so —
+    // the store is a restorable CI artifact now, not just a local directory.
+    let bytes = await getCachedTarball(node.integrity);
     if (bytes) {
         log('cache-hit: %s@%s ← %s', node.name, node.version, node.integrity);
     }
-    else if ((bytes = getForeignCachedTarball(node.integrity))) {
+    else if ((bytes = await getForeignCachedTarball(node.integrity))) {
         // Second chance: npm's cacache content store, same SRI key — anyone who has run
         // `npm install` already has the tarball on disk. Written through to OUR store so
         // the next `gjsify install` hits first-class even if npm prunes its cache.
@@ -1514,7 +1651,7 @@ function abortError(signal) {
  *      a workspace source tree, where `rmSync(dest, { recursive: true })` deletes the
  *      link's target contents.
  */
-function assertNodeModulesDest(dest, node) {
+function assertNodeModulesDest(dest, node, prefix) {
     const segments = dest.split(path.sep);
     if (!segments.includes('node_modules')) {
         throw new Error(`gjsify install: refusing to extract ${node.name}@${node.version} into ${dest} — ` +
@@ -1533,9 +1670,36 @@ function assertNodeModulesDest(dest, node) {
     if (!realSegments.includes('node_modules')) {
         throw new Error(`gjsify install: refusing to extract ${node.name}@${node.version} — ${dest} resolves to ${real}, ` +
             `which is outside any node_modules/ directory (likely a symlink to a workspace source tree). ` +
-            `Extracting here would delete working-tree source files.`);
+            `Extracting here would delete working-tree source files.${devLinkRemedy(prefix, dest)}`);
     }
 }
+/**
+ * The extra sentence for the ONE cause this refusal has that a developer can undo
+ * with a command: a `gjsify link` development link.
+ *
+ * Measured: relinking with a narrower `--packages` left `node_modules/is-number`
+ * pointing into the checkout while the new override no longer named it, and every
+ * later `gjsify install` died on the refusal above — which spoke only of "a
+ * workspace source tree" and named no command at all. `gjsify unlink` did not
+ * rescue it either (it removed the override first, destroying the escape route),
+ * so the only way out was a hand-written `rm`. Both halves are fixed at the
+ * source; this message is what tells someone already wedged by an older CLI.
+ *
+ * The override file may be GONE by the time this fires, so its absence is not
+ * evidence: the remedy is named whenever a `node_modules` entry points outside,
+ * and it names the file only when it is actually there.
+ */
+function devLinkRemedy(prefix, dest) {
+    // Same walk the guard and the installer do, so the path this message tells
+    // someone to run `gjsify unlink` in is the one that holds the override.
+    const root = devLinkRoot(prefix);
+    const override = devLinkPath(root);
+    const active = fs.existsSync(override);
+    return (`\n  If a \`gjsify link\` development link put it there${active ? ` — ${override} is present` : ''}: ` +
+        `run \`gjsify unlink\` in ${root} to remove the links and restore the registry copies, ` +
+        `or \`gjsify link <checkout> --packages …\` to re-select. ` +
+        `If no override is left, delete ${dest} by hand and re-run.`);
+}
 function depth(installPath) {
     // `node_modules/foo` = 1, `node_modules/foo/node_modules/bar` = 2, …
     return installPath.split('/node_modules/').length;

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

@@ -0,0 +1,90 @@
+/**
+ * The half of `--immutable` that was missing: every locked package is present AND
+ * NOTHING ELSE IS.
+ *
+ * The installer only ever ADDED. Handed a `node_modules` carrying a package the
+ * lockfile never mentions, `--immutable` extracted whatever was missing, left the
+ * stranger in place and exited 0 — a green install over a tree its own lockfile does
+ * not describe.
+ *
+ * THE INCIDENT (gjsify#1683, 2026-09-15). CI caches `node_modules` keyed on
+ * `hashFiles('gjsify-lock.json')` with a prefix fallback `restore-keys:
+ * node-modules-v1-`. An earlier run of a `@girs` bump genuinely nested
+ * `node_modules/@girs/gtk-4.0/node_modules/@girs/graphene-1.0` and saved that tree.
+ * The fix push changed the lockfile → new key → miss → the FALLBACK restored the
+ * nested tree. `--immutable` added what was missing, pruned nothing, and `tsc` then
+ * saw one type under two identities: TS2883. Worse, the still-nested tree was saved
+ * under the NEW key, so no plain re-run could go green — the failure reproduced
+ * itself until the caches were deleted by hand. Nothing about the PR's code was
+ * wrong, and any lockfile-changing PR could poison itself the same way.
+ *
+ * WHY NAMING, NOT DELETING. The peers split: `npm ci` removes `node_modules` first,
+ * yarn's `--immutable` fails on a mismatch. This follows yarn, for three reasons.
+ * The flag's own name promises not to mutate, and this repo already refuses
+ * automatic deletion under it ({@link automaticPruneRefusal} returns `'--immutable'`).
+ * A verifier that deletes can delete the wrong thing — a `link`ed dep, a package
+ * some other tool put there — while a verifier that reports cannot. And the failure
+ * mode is asymmetric: a wrong deletion loses work, a wrong refusal costs one red run
+ * carrying the exact paths and the fix.
+ *
+ * That choice has a price, paid in `.github/actions/gjsify-setup/action.yml`: with
+ * this check fatal, a restored FOREIGN tree stops being silent corruption and
+ * becomes a hard failure on every lockfile-changing PR. So the `restore-keys`
+ * fallback is gone — see the comment there. The two decisions are one decision.
+ */
+import type { InstalledPackage } from './prune-prefix.js';
+/** A package directory on disk that the lockfile does not describe. */
+export interface ExtraneousPackage {
+    /**
+     * Path relative to the install prefix, always `/`-separated — the exact shape of
+     * a `gjsify-lock.json` `packages` key, so "not in the lockfile" is checkable by
+     * grepping the reported string against the file.
+     */
+    installPath: string;
+    /** From the on-disk manifest; the directory path when it was unreadable. */
+    name: string;
+    version: string;
+}
+/**
+ * Package directories under `prefix` that no entry of `expected` accounts for.
+ *
+ * Pure: it takes the scan rows ({@link scanPrefix}) and the resolved set rather than
+ * reading either, so every branch — nested placements, symlinks, subtree collapsing —
+ * is decidable without a filesystem.
+ *
+ * Three things are deliberately NOT extraneous:
+ *   - a SYMLINK, which is a workspace source tree linked in by `workspaceInstall`
+ *     and by construction absent from the lockfile (`scanPrefix` does not descend
+ *     into one either, so the user's own sources are never walked);
+ *   - a dot-entry like `.bin` or `.cache`, already dropped by the scan;
+ *   - a package the lockfile describes but the PLATFORM filter skipped on this host.
+ *     It is described, so it is not a stranger; removing the foreign-platform residue
+ *     is `prune-prefix.ts`'s separate job under a separate rule.
+ *
+ * Descendants of an extraneous directory are collapsed away: reporting the parent
+ * says everything, and the nested `@girs` tree of the incident would otherwise list
+ * its whole subtree.
+ */
+export declare function findExtraneous(opts: {
+    prefix: string;
+    installed: readonly InstalledPackage[];
+    expected: readonly {
+        installPath: string;
+    }[];
+}): ExtraneousPackage[];
+/** How many paths the message names before it starts counting. */
+export declare const EXTRANEOUS_REPORT_LIMIT = 20;
+/**
+ * The refusal, built to be actionable from the CI log alone: what is wrong, which
+ * paths, and the one thing that fixes it. Truncated past
+ * {@link EXTRANEOUS_REPORT_LIMIT} so a wholly foreign tree does not bury the advice
+ * under a thousand lines.
+ *
+ * It says DELETE, and says so as the only remedy, because that is what was measured:
+ * a plain `gjsify install` — and an explicit `--prune` — leave both a top-level and a
+ * nested stranger exactly where they were. The installer only adds, and `prune-prefix`
+ * judges one thing, npm's `os`/`cpu`/`libc`, so a package that is merely UNDESCRIBED
+ * matches no rule either owns. Sending a developer to `gjsify install` instead would
+ * hand them a command that changes nothing and a refusal that repeats verbatim.
+ */
+export declare function formatExtraneousError(entries: readonly ExtraneousPackage[], prefix: string): string;

package/lib/utils/install-extraneous.js

@@ -0,0 +1,120 @@
+/**
+ * The half of `--immutable` that was missing: every locked package is present AND
+ * NOTHING ELSE IS.
+ *
+ * The installer only ever ADDED. Handed a `node_modules` carrying a package the
+ * lockfile never mentions, `--immutable` extracted whatever was missing, left the
+ * stranger in place and exited 0 — a green install over a tree its own lockfile does
+ * not describe.
+ *
+ * THE INCIDENT (gjsify#1683, 2026-09-15). CI caches `node_modules` keyed on
+ * `hashFiles('gjsify-lock.json')` with a prefix fallback `restore-keys:
+ * node-modules-v1-`. An earlier run of a `@girs` bump genuinely nested
+ * `node_modules/@girs/gtk-4.0/node_modules/@girs/graphene-1.0` and saved that tree.
+ * The fix push changed the lockfile → new key → miss → the FALLBACK restored the
+ * nested tree. `--immutable` added what was missing, pruned nothing, and `tsc` then
+ * saw one type under two identities: TS2883. Worse, the still-nested tree was saved
+ * under the NEW key, so no plain re-run could go green — the failure reproduced
+ * itself until the caches were deleted by hand. Nothing about the PR's code was
+ * wrong, and any lockfile-changing PR could poison itself the same way.
+ *
+ * WHY NAMING, NOT DELETING. The peers split: `npm ci` removes `node_modules` first,
+ * yarn's `--immutable` fails on a mismatch. This follows yarn, for three reasons.
+ * The flag's own name promises not to mutate, and this repo already refuses
+ * automatic deletion under it ({@link automaticPruneRefusal} returns `'--immutable'`).
+ * A verifier that deletes can delete the wrong thing — a `link`ed dep, a package
+ * some other tool put there — while a verifier that reports cannot. And the failure
+ * mode is asymmetric: a wrong deletion loses work, a wrong refusal costs one red run
+ * carrying the exact paths and the fix.
+ *
+ * That choice has a price, paid in `.github/actions/gjsify-setup/action.yml`: with
+ * this check fatal, a restored FOREIGN tree stops being silent corruption and
+ * becomes a hard failure on every lockfile-changing PR. So the `restore-keys`
+ * fallback is gone — see the comment there. The two decisions are one decision.
+ */
+import { relative, sep } from 'node:path';
+/** `/`-separated, no trailing slash — lockfile key shape on every host. */
+function normalizePath(p) {
+    const slashed = sep === '/' ? p : p.split(sep).join('/');
+    return slashed.endsWith('/') ? slashed.slice(0, -1) : slashed;
+}
+/**
+ * Package directories under `prefix` that no entry of `expected` accounts for.
+ *
+ * Pure: it takes the scan rows ({@link scanPrefix}) and the resolved set rather than
+ * reading either, so every branch — nested placements, symlinks, subtree collapsing —
+ * is decidable without a filesystem.
+ *
+ * Three things are deliberately NOT extraneous:
+ *   - a SYMLINK, which is a workspace source tree linked in by `workspaceInstall`
+ *     and by construction absent from the lockfile (`scanPrefix` does not descend
+ *     into one either, so the user's own sources are never walked);
+ *   - a dot-entry like `.bin` or `.cache`, already dropped by the scan;
+ *   - a package the lockfile describes but the PLATFORM filter skipped on this host.
+ *     It is described, so it is not a stranger; removing the foreign-platform residue
+ *     is `prune-prefix.ts`'s separate job under a separate rule.
+ *
+ * Descendants of an extraneous directory are collapsed away: reporting the parent
+ * says everything, and the nested `@girs` tree of the incident would otherwise list
+ * its whole subtree.
+ */
+export function findExtraneous(opts) {
+    const described = new Set(opts.expected.map((n) => normalizePath(n.installPath)));
+    const found = [];
+    for (const pkg of opts.installed) {
+        if (pkg.linked)
+            continue;
+        const installPath = normalizePath(relative(opts.prefix, pkg.dir));
+        // Outside the prefix, or the prefix itself: not this install's to judge.
+        if (installPath === '' || installPath.startsWith('..'))
+            continue;
+        if (described.has(installPath))
+            continue;
+        found.push({ installPath, name: pkg.name, version: pkg.version });
+    }
+    found.sort((a, b) => (a.installPath < b.installPath ? -1 : a.installPath > b.installPath ? 1 : 0));
+    const roots = [];
+    for (const entry of found) {
+        const parent = roots[roots.length - 1];
+        // Sorted, so an enclosing extraneous directory is always the last one kept.
+        if (parent && entry.installPath.startsWith(`${parent.installPath}/`))
+            continue;
+        roots.push(entry);
+    }
+    return roots;
+}
+/** How many paths the message names before it starts counting. */
+export const EXTRANEOUS_REPORT_LIMIT = 20;
+/**
+ * The refusal, built to be actionable from the CI log alone: what is wrong, which
+ * paths, and the one thing that fixes it. Truncated past
+ * {@link EXTRANEOUS_REPORT_LIMIT} so a wholly foreign tree does not bury the advice
+ * under a thousand lines.
+ *
+ * It says DELETE, and says so as the only remedy, because that is what was measured:
+ * a plain `gjsify install` — and an explicit `--prune` — leave both a top-level and a
+ * nested stranger exactly where they were. The installer only adds, and `prune-prefix`
+ * judges one thing, npm's `os`/`cpu`/`libc`, so a package that is merely UNDESCRIBED
+ * matches no rule either owns. Sending a developer to `gjsify install` instead would
+ * hand them a command that changes nothing and a refusal that repeats verbatim.
+ */
+export function formatExtraneousError(entries, prefix) {
+    const shown = entries.slice(0, EXTRANEOUS_REPORT_LIMIT);
+    const lines = shown.map((e) => `  ${e.installPath}  (${e.name}@${e.version})`);
+    if (entries.length > shown.length)
+        lines.push(`  … and ${entries.length - shown.length} more`);
+    return [
+        `install: --immutable, but ${prefix}/node_modules holds ${entries.length} package(s) ` +
+            'that gjsify-lock.json does not describe.',
+        '--immutable installs the lockfile and removes nothing, so each of these would survive ' +
+            'the install and be resolved, bundled and type-checked as if it belonged ' +
+            '(gjsify#1683: a nested copy of an already-hoisted package → TS2883, one type ' +
+            'with two identities).',
+        ...lines,
+        'Fix: delete those directories — or the whole node_modules — and re-run. A plain ' +
+            '`gjsify install` does NOT clear them: it only ever adds, and its prune pass judges ' +
+            'foreign-PLATFORM packages alone (prune-prefix.ts), so an undescribed package ' +
+            'survives both. Deleting is currently the only thing that removes one. ' +
+            'In CI this usually means a cache entry was restored from a DIFFERENT lockfile.',
+    ].join('\n');
+}

package/lib/utils/install-lock.js

@@ -17,8 +17,8 @@
 // `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 Node and GJS
-//       alike; a kill(0) probe covers non-/proc Nodes), or
+//   (a) the owner pid is provably dead (`isPidAlive` in `process-table.ts`: `/proc/<pid>` where
+//       procfs exists, a signal-0 probe elsewhere), 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
@@ -31,8 +31,9 @@
 //
 // 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 { mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
+import { isPidAlive } from './process-table.js';
 const LOCK_DIR_NAME = '.gjsify-install-lock';
 const OWNER_FILE = 'owner.json';
 /** Default staleness budget — see the header comment for why 35 min. */
@@ -60,28 +61,6 @@ function lockingDisabled() {
     const trimmed = flag.trim();
     return trimmed === '0' || trimmed === 'false';
 }
-/**
- * Is `pid` a live process on this machine?
- *
- * `/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`, neither with a throw path in the GIR.
-    if (existsSync('/proc/self'))
-        return existsSync(`/proc/${pid}`);
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (err) {
-        return err.code === 'EPERM';
-    }
-}
 function mtimeMs(path) {
     try {
         return statSync(path).mtimeMs;