pnpm 12.15.0 → 12.16.0

package/dist/node_modules/get-pnpm/lib/registry.js

@@ -1,12 +1,18 @@
 import { createHash } from 'node:crypto';
 import { createWriteStream } from 'node:fs';
 import http from 'node:http';
+import net from 'node:net';
 import { pipeline } from 'node:stream/promises';
+import tls from 'node:tls';
 const ABBREVIATED_PACKUMENT = 'application/vnd.npm.install-v1+json';
 export const DEFAULT_REGISTRY = 'https://registry.npmjs.org/';
-/** The registry npx/npm is configured with, so a mirror stays a mirror. */
-export function registryFromEnv() {
-    return normalizeRegistry(process.env.npm_config_registry ?? process.env.NPM_CONFIG_REGISTRY ?? DEFAULT_REGISTRY);
+/** Whether credentials may be sent to `url`: over HTTPS, or to the local machine. */
+export function isUrlSecureForCredentials(url) {
+    return url.protocol === 'https:' || (url.protocol === 'http:' && isLoopback(url.hostname));
+}
+function isLoopback(hostname) {
+    return hostname === 'localhost' || hostname === '[::1]' ||
+        (net.isIPv4(hostname) && hostname.startsWith('127.'));
 }
 /**
  * A registry URL that can be used as a base for a relative path.
@@ -20,8 +26,9 @@ export function normalizeRegistry(registry) {
 const PROXY_VARS = ['https_proxy', 'HTTPS_PROXY', 'http_proxy', 'HTTP_PROXY'];
 /**
  * Routes every request made until the returned function is called through the
- * proxy the environment names in `HTTPS_PROXY`/`HTTP_PROXY`, honouring
- * `NO_PROXY`. A no-op when the environment names none.
+ * proxy `proxyEnv` names in `HTTPS_PROXY`/`HTTP_PROXY`, honouring `NO_PROXY`.
+ * A no-op when it names none, which leaves a proxy Node.js applied at startup
+ * in place.
  *
  * `fetch` reads those variables only when Node was started with
  * `NODE_USE_ENV_PROXY=1`, which nothing that embeds this package controls:
@@ -35,10 +42,11 @@ const PROXY_VARS = ['https_proxy', 'HTTPS_PROXY', 'http_proxy', 'HTTP_PROXY'];
  *
  * The setting is process-global, so overlapping downloads share one
  * activation: the first call applies the proxy and the last of the returned
- * functions to run puts the agents back, never one in the middle.
+ * functions to run puts the agents back, never one in the middle. The proxy of
+ * that first call is the one they share.
  */
-export function useProxyFromEnv() {
-    if (!PROXY_VARS.some((name) => process.env[name]))
+export function useProxyFromEnv(proxyEnv = process.env) {
+    if (!PROXY_VARS.some((name) => proxyEnv[name]))
         return () => { };
     const { setGlobalProxyFromEnv } = http;
     if (setGlobalProxyFromEnv == null)
@@ -46,7 +54,7 @@ export function useProxyFromEnv() {
     // Counted only once the activation took: a call that threw on a malformed
     // proxy URL holds nothing to release, and a retry after a fix has to activate.
     if (proxyUsers === 0)
-        restoreProxy = setGlobalProxyFromEnv(process.env);
+        restoreProxy = setGlobalProxyFromEnv(proxyEnv);
     proxyUsers++;
     let released = false;
     return () => {
@@ -59,17 +67,84 @@ export function useProxyFromEnv() {
 }
 let proxyUsers = 0;
 let restoreProxy = () => { };
+/**
+ * Adds `ca`, PEM certificates, to the CAs every TLS connection trusts until
+ * the returned function is called. Node.js's own CAs stay trusted, so a
+ * download host the registry names stays reachable.
+ *
+ * `fetch` takes no CA of its own, so this is process-global, like the proxy:
+ * overlapping calls each add theirs, and the defaults come back once the last
+ * returned function has run. A connection or TLS session opened while the CAs
+ * were trusted can still be reused after that.
+ *
+ * Node.js before 22.19 and 24.5 cannot add a CA after startup, so there it only
+ * says to use `NODE_EXTRA_CA_CERTS`.
+ */
+export function useCertificateAuthorities(ca = []) {
+    if (ca.length === 0)
+        return () => { };
+    if (typeof tls.setDefaultCACertificates !== 'function') {
+        console.warn(`Node.js ${process.version} cannot trust the CA certificates of the npm config after startup. Set NODE_EXTRA_CA_CERTS to a file holding them instead.`);
+        return () => { };
+    }
+    const added = [...ca];
+    const builtIn = defaultCertificates ?? tls.getCACertificates('default');
+    try {
+        tls.setDefaultCACertificates([...builtIn, ...[...addedCertificates, added].flat()]);
+    }
+    catch (err) {
+        throw new Error(`Could not trust the CA certificates of the npm config: ${err.message}`, { cause: err });
+    }
+    defaultCertificates = builtIn;
+    addedCertificates.add(added);
+    return () => {
+        if (!addedCertificates.delete(added))
+            return;
+        tls.setDefaultCACertificates([...builtIn, ...[...addedCertificates].flat()]);
+        if (addedCertificates.size === 0)
+            defaultCertificates = undefined;
+    };
+}
+/** What `tls` trusted before the first active {@link useCertificateAuthorities} call. */
+let defaultCertificates;
+const addedCertificates = new Set();
 // Node's fetch applies no timeout of its own: a registry that accepts the
 // connection and then stalls would hang the install with no output. Metadata is
 // small and quick; the tarball budget has to survive a slow connection carrying
 // a ~150 MB download.
 const METADATA_TIMEOUT_MS = 30_000;
 const TARBALL_TIMEOUT_MS = 15 * 60_000;
-export async function fetchPackument(registry, pkgName, headers) {
-    return fetchJson(new URL(pkgName, registry), ABBREVIATED_PACKUMENT, headers);
+// The tarball budget is too long to wait out a connection that stopped sending
+// partway through. Going this long without a byte abandons the attempt so it
+// can be retried, while a slow download that keeps making progress is left be.
+const TARBALL_STALL_TIMEOUT_MS = 30_000;
+// A reset connection or a 502 from a load balancer in front of the registry is
+// transient, and should not fail the whole install. `fetch` retries none of
+// this on its own, so it is done here.
+const MAX_ATTEMPTS = 3;
+const RETRY_DELAY_MS = 500;
+export async function fetchPackument(registry, pkgName, headers, headersPath) {
+    return fetchJson(new URL(pkgName, registry), ABBREVIATED_PACKUMENT, { registry, headers, headersPath });
+}
+export async function fetchVersionMeta(registry, pkgName, version, headers, headersPath) {
+    return fetchJson(new URL(`${pkgName}/${version}`, registry), 'application/json', { registry, headers, headersPath });
 }
-export async function fetchVersionMeta(registry, pkgName, version, headers) {
-    return fetchJson(new URL(`${pkgName}/${version}`, registry), 'application/json', headers);
+/**
+ * The registry signatures of `pkgName@version`.
+ *
+ * Some registry proxies, JFrog Artifactory among them, strip `dist.signatures`
+ * from the version document but keep them in the package document, so that is
+ * where they are looked up when `meta` carries none. Only the signatures are
+ * taken from it: they cover `<name>@<version>:<integrity>`, so they still have
+ * to verify against the checksum in `meta`, which the tarball is checked
+ * against.
+ */
+export async function fetchSignatures(meta, opts) {
+    if (meta.dist.signatures?.length)
+        return meta.dist.signatures;
+    // Escaped the way npm requests a scoped package, which every registry serves.
+    const packument = await fetchJson(new URL(opts.pkgName.replaceAll('/', '%2f'), opts.registry), ABBREVIATED_PACKUMENT, { registry: opts.registry, headers: opts.headers, headersPath: opts.headersPath });
+    return packument.versions?.[opts.version]?.dist?.signatures;
 }
 /**
  * Streams `meta.dist.tarball` to `dest`, verifying the checksum the registry
@@ -82,21 +157,34 @@ export async function fetchVersionMeta(registry, pkgName, version, headers) {
  */
 export async function downloadTarball(meta, dest, opts = {}) {
     const url = tarballUrl(meta, opts.registry);
-    const response = await request(url, undefined, TARBALL_TIMEOUT_MS, headersFor(url, opts));
     const [algorithm, expected] = checksum(meta);
-    const hash = createHash(algorithm);
-    const body = response.body;
-    await pipeline(async function* () {
-        for await (const chunk of body) {
-            hash.update(chunk);
-            yield chunk;
-        }
-    }, createWriteStream(dest));
-    const actual = hash.digest('base64');
+    // The whole download is retried, not just the request: a connection reset
+    // halfway through a ~150 MB body is the likeliest blip of all. Each attempt
+    // rewrites `dest` from the start.
+    const actual = await withRetries(() => downloadAttempt(url, dest, algorithm, opts));
     if (actual !== expected) {
         throw new Error(`The download from ${url.href} does not match the checksum the npm registry published for it. Refusing to install.`);
     }
 }
+/** One attempt of `downloadTarball`. @returns the digest of what was written. */
+async function downloadAttempt(url, dest, algorithm, opts) {
+    const stall = stallWatchdog(opts.stallTimeoutMs ?? TARBALL_STALL_TIMEOUT_MS);
+    try {
+        const response = await request(url, undefined, TARBALL_TIMEOUT_MS, opts, stall.signal);
+        const hash = createHash(algorithm);
+        await pipeline(readBody(response, url, TARBALL_TIMEOUT_MS), async function* (body) {
+            for await (const chunk of body) {
+                stall.reset();
+                hash.update(chunk);
+                yield chunk;
+            }
+        }, createWriteStream(dest));
+        return hash.digest('base64');
+    }
+    finally {
+        stall.clear();
+    }
+}
 /**
  * Where to download `meta`'s tarball from.
  *
@@ -114,7 +202,13 @@ export function tarballUrl(meta, registry) {
 function headersFor(url, opts) {
     if (opts.headers == null || opts.registry == null)
         return undefined;
-    return url.origin === new URL(opts.registry).origin ? opts.headers : undefined;
+    const registry = new URL(normalizeRegistry(opts.registry));
+    if (url.origin !== registry.origin)
+        return undefined;
+    if (opts.headersPath == null)
+        return opts.headers;
+    const scope = opts.headersPath.endsWith('/') ? opts.headersPath : `${opts.headersPath}/`;
+    return url.pathname.startsWith(scope) ? opts.headers : undefined;
 }
 /**
  * The algorithm and digest to check a tarball against.
@@ -135,29 +229,159 @@ function checksum(meta) {
     }
     return [entry.slice(0, separator), entry.slice(separator + 1)];
 }
-async function fetchJson(url, accept, headers) {
-    const response = await request(url, accept, METADATA_TIMEOUT_MS, headers);
-    return await response.json();
+async function fetchJson(url, accept, opts = {}) {
+    return withRetries(async () => {
+        const response = await request(url, accept, METADATA_TIMEOUT_MS, opts);
+        const chunks = [];
+        for await (const chunk of readBody(response, url, METADATA_TIMEOUT_MS))
+            chunks.push(chunk);
+        // Malformed JSON is what the server sent, and would be sent again, so a
+        // parse failure is not retried.
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    });
+}
+/** A request failure, marked so `withRetries` knows whether retrying it can help. */
+class RequestFailure extends Error {
+    retryable;
+    constructor(message, opts) {
+        super(message, { cause: opts.cause });
+        this.retryable = opts.retryable;
+    }
+}
+async function withRetries(attempt) {
+    for (let attemptNo = 1;; attemptNo++) {
+        try {
+            // eslint-disable-next-line no-await-in-loop -- each attempt waits for the previous one to fail
+            return await attempt();
+        }
+        catch (err) {
+            if (attemptNo >= MAX_ATTEMPTS || !(err instanceof RequestFailure) || !err.retryable)
+                throw err;
+            // eslint-disable-next-line no-await-in-loop -- the delay is what spaces the attempts out
+            await delay(RETRY_DELAY_MS * attemptNo);
+        }
+    }
+}
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+const MAX_REDIRECTS = 20;
+/**
+ * Follows redirects by hand, so each hop gets only the credentials
+ * `headersFor` allows it: `fetch` would carry them to any path on the same
+ * origin, outside the scope the token was configured for.
+ */
+async function request(url, accept, timeoutMs, opts = {}, stallSignal) {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const signal = stallSignal == null ? timeout : AbortSignal.any([timeout, stallSignal]);
+    let currentUrl = url;
+    for (let redirects = 0;; redirects++) {
+        // eslint-disable-next-line no-await-in-loop -- each hop is known only once the previous one answers
+        const response = await fetchHop(currentUrl, { accept, signal, timeoutMs, opts });
+        if (!REDIRECT_STATUSES.has(response.status) && response.ok)
+            return response;
+        // Left unread, the body would hold the connection until it is collected.
+        // eslint-disable-next-line no-await-in-loop -- the connection is released before the next hop opens one
+        await response.body?.cancel().catch(() => { });
+        const target = redirectTarget(response, currentUrl);
+        if (redirects >= MAX_REDIRECTS) {
+            throw new RequestFailure(`Could not download ${url.href}: too many redirects`, { retryable: false });
+        }
+        currentUrl = target;
+    }
 }
-async function request(url, accept, timeoutMs, headers) {
-    let response;
+async function fetchHop(url, { accept, signal, timeoutMs, opts }) {
     try {
-        response = await fetch(url, {
-            signal: AbortSignal.timeout(timeoutMs),
-            headers: { ...headers, ...(accept ? { accept } : {}) },
+        return await fetch(url, {
+            redirect: 'manual',
+            signal,
+            headers: { ...headersFor(url, opts), ...(accept ? { accept } : {}) },
         });
     }
     catch (err) {
-        const reason = err.name === 'TimeoutError'
-            ? `timed out after ${Math.round(timeoutMs / 1000)}s`
-            : err.message;
-        throw new Error(`Could not reach ${url.href}: ${reason}`, { cause: err });
+        throw new RequestFailure(`Could not reach ${url.href}: ${reasonFor(err, timeoutMs)}`, { cause: err, retryable: isRetryableError(err, timeoutMs) });
     }
-    if (!response.ok) {
-        throw new Error(`Could not download ${url.href}: ${response.status} ${response.statusText}`);
+}
+/** Where the redirect `response` points; throws for a response that is not one. */
+function redirectTarget(response, url) {
+    if (!REDIRECT_STATUSES.has(response.status)) {
+        throw new RequestFailure(`Could not download ${url.href}: ${response.status} ${response.statusText}`, { retryable: isRetryableStatus(response.status) });
+    }
+    const location = response.headers.get('location');
+    if (location == null) {
+        throw new RequestFailure(`Could not download ${url.href}: ${response.status} redirect without a Location header`, { retryable: false });
+    }
+    return new URL(location, url);
+}
+/**
+ * `response`'s body, with a connection lost partway through, or a body that
+ * never came, marked as worth retrying. A 200 with nothing in it is a proxy or
+ * CDN hiccup, not an answer.
+ */
+async function* readBody(response, url, timeoutMs) {
+    let received = 0;
+    if (response.body != null) {
+        try {
+            for await (const chunk of response.body) {
+                received += chunk.byteLength;
+                yield chunk;
+            }
+        }
+        catch (err) {
+            throw interrupted(url, err, timeoutMs);
+        }
     }
-    if (response.body == null) {
-        throw new Error(`Empty response from ${url.href}`);
+    if (received === 0) {
+        throw new RequestFailure(`Empty response from ${url.href}`, { retryable: true });
     }
-    return response;
+}
+/**
+ * A signal that aborts once `timeoutMs` passes without a call to `reset`.
+ *
+ * It aborts with a plain `Error` rather than a `TimeoutError`, so the failure
+ * reads as an interrupted connection and is retried like one.
+ */
+function stallWatchdog(timeoutMs) {
+    const controller = new AbortController();
+    let timer;
+    const clear = () => {
+        clearTimeout(timer);
+    };
+    const reset = () => {
+        clear();
+        timer = setTimeout(() => {
+            controller.abort(new Error(`no data received for ${Math.round(timeoutMs / 1000)}s`));
+        }, timeoutMs);
+    };
+    reset();
+    return { signal: controller.signal, reset, clear };
+}
+function interrupted(url, err, timeoutMs) {
+    return new RequestFailure(`The download from ${url.href} was interrupted: ${reasonFor(err, timeoutMs)}`, { cause: err, retryable: isRetryableError(err, timeoutMs) });
+}
+function reasonFor(err, timeoutMs) {
+    return err.name === 'TimeoutError'
+        ? `timed out after ${Math.round(timeoutMs / 1000)}s`
+        : err.message;
+}
+/**
+ * A connection that could not be made, or was reset, is exactly the kind of
+ * blip retrying is for. So is a metadata request that stalled. A tarball that
+ * ran out its whole budget is not: that budget is already sized for a slow
+ * connection, and each retry would hang the install for as long again.
+ */
+function isRetryableError(err, timeoutMs) {
+    return err.name !== 'TimeoutError' || timeoutMs < TARBALL_TIMEOUT_MS;
+}
+/**
+ * A 4xx means the request itself is wrong (a missing package, a bad
+ * credential) — retrying would just ask the same wrong question again. The
+ * exceptions are a request timeout and rate limiting, which say "not now"
+ * rather than "no". A 5xx is the server's problem, and often a transient one.
+ */
+function isRetryableStatus(status) {
+    return status === 408 || status === 429 || status >= 500;
+}
+async function delay(ms) {
+    await new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
 }

package/dist/node_modules/get-pnpm/lib/resolveVersion.js

@@ -1,9 +1,11 @@
+import semver from 'semver';
 /**
  * Turns what the user asked for into a concrete pnpm version.
  *
  * `spec` may be a dist-tag (`latest`, `next-12`), an exact version (`11.20.0`,
- * with an optional leading `v`), or a bare major (`12`), which picks that
- * major's stable release and falls back to its prerelease lane.
+ * with an optional leading `v`), a bare major (`12`), which picks that major's
+ * stable release and falls back to its prerelease lane, or a semver range
+ * (`^12.1.0`, `>=11 <13`).
  *
  * Dist-tags win over exact versions, matching `install.ps1`.
  *
@@ -21,8 +23,23 @@ export function resolveVersion(packument, spec) {
         if (majorTag)
             return majorTag;
     }
+    const inRange = semver.validRange(spec) == null ? undefined : versionInRange(packument, spec);
+    if (inRange != null)
+        return inRange;
     throw new Error(`Sorry! pnpm version "${spec}" could not be found. Available tags: ${Object.keys(distTags).sort().join(', ')}`);
 }
+/**
+ * The version npm would install for `range`: the `latest` release when it is
+ * in range, otherwise the highest that is. A prerelease is picked only by a
+ * range that names one, as in npm and in pnpm's switch to a project's pinned
+ * version.
+ */
+function versionInRange(packument, range) {
+    const latest = packument['dist-tags'].latest;
+    if (latest != null && semver.satisfies(latest, range))
+        return latest;
+    return semver.maxSatisfying(Object.keys(packument.versions), range) ?? undefined;
+}
 /** The major of an exact version, as the package layout depends on it. */
 export function majorVersion(version) {
     const field = version.split('.')[0] ?? '';

package/dist/node_modules/get-pnpm/lib/sameFileContents.js

@@ -6,40 +6,44 @@ const CHUNK_SIZE = 64 * 1024;
  * Compared rather than hashed: the answer is usually "no" at the first
  * differing byte, and there is nothing to gain from reading further.
  *
- * `b` is the untrusted side — a path something else may hold — so anything
- * other than a readable regular file of the same size is simply not the same
- * file, rather than an error.
+ * `candidate` is the untrusted side — a path something else may hold — so
+ * anything other than a readable regular file of the same size is not
+ * the same file, rather than an error.
  */
-export function sameFileContents(a, b) {
-    const sizeA = fs.statSync(a).size;
-    const statB = fs.lstatSync(b, { throwIfNoEntry: false });
-    if (statB?.isFile() !== true || statB.size !== sizeA)
+export function sameFileContents(file, candidate) {
+    const size = fs.statSync(file).size;
+    const candidateStat = fs.lstatSync(candidate, { throwIfNoEntry: false });
+    if (candidateStat?.isFile() !== true || candidateStat.size !== size)
         return false;
-    let fdA;
-    let fdB;
+    let fileFd;
+    let candidateFd;
     try {
-        fdA = fs.openSync(a, 'r');
-        fdB = fs.openSync(b, 'r');
-        const bufferA = Buffer.alloc(CHUNK_SIZE);
-        const bufferB = Buffer.alloc(CHUNK_SIZE);
-        while (true) {
-            const readA = fs.readSync(fdA, bufferA, 0, CHUNK_SIZE, null);
-            const readB = fs.readSync(fdB, bufferB, 0, CHUNK_SIZE, null);
-            if (readA !== readB)
-                return false;
-            if (readA === 0)
-                return true;
-            if (!bufferA.subarray(0, readA).equals(bufferB.subarray(0, readB)))
-                return false;
-        }
+        fileFd = fs.openSync(file, 'r');
+        candidateFd = fs.openSync(candidate, 'r');
+        return sameBytes(fileFd, candidateFd);
     }
     catch {
         return false;
     }
     finally {
-        if (fdA !== undefined)
-            fs.closeSync(fdA);
-        if (fdB !== undefined)
-            fs.closeSync(fdB);
+        if (fileFd !== undefined)
+            fs.closeSync(fileFd);
+        if (candidateFd !== undefined)
+            fs.closeSync(candidateFd);
+    }
+}
+/** Whether the rest of two open files is the same, read chunk by chunk. */
+function sameBytes(fdA, fdB) {
+    const bufferA = Buffer.alloc(CHUNK_SIZE);
+    const bufferB = Buffer.alloc(CHUNK_SIZE);
+    while (true) {
+        const readA = fs.readSync(fdA, bufferA, 0, CHUNK_SIZE, null);
+        const readB = fs.readSync(fdB, bufferB, 0, CHUNK_SIZE, null);
+        if (readA !== readB)
+            return false;
+        if (readA === 0)
+            return true;
+        if (!bufferA.subarray(0, readA).equals(bufferB.subarray(0, readB)))
+            return false;
     }
 }

package/dist/node_modules/get-pnpm/lib/shadowingPnpm.js

@@ -0,0 +1,174 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/**
+ * Shim scripts (npm's `.cmd` files, Corepack's) name their target inside;
+ * anything larger than this is a real executable, not a script.
+ */
+const SHIM_SCRIPT_MAX_SIZE = 64 * 1024;
+const REMOVAL_COMMANDS = {
+    npm: 'npm uninstall -g pnpm',
+    homebrew: 'brew uninstall pnpm',
+    corepack: 'corepack disable pnpm',
+    volta: 'volta uninstall pnpm',
+    scoop: 'scoop uninstall pnpm',
+    unknown: undefined,
+};
+const ORIGIN_DESCRIPTIONS = {
+    npm: 'installed with npm',
+    homebrew: 'installed with Homebrew',
+    corepack: 'a Corepack shim',
+    volta: 'installed with Volta',
+    scoop: 'installed with Scoop',
+    unknown: 'not installed by pnpm',
+};
+/**
+ * Where `pnpm setup` installs: `PNPM_HOME`, or pnpm's default for the
+ * platform, resolved the way pnpm resolves it.
+ */
+export function pnpmHomeDir(env = process.env, platform = process.platform) {
+    if (env.PNPM_HOME)
+        return env.PNPM_HOME;
+    if (env.XDG_DATA_HOME)
+        return path.join(env.XDG_DATA_HOME, 'pnpm');
+    switch (platform) {
+        case 'darwin': return path.join(os.homedir(), 'Library', 'pnpm');
+        case 'win32': return env.LOCALAPPDATA ? path.join(env.LOCALAPPDATA, 'pnpm') : path.join(os.homedir(), '.pnpm');
+        default: return path.join(os.homedir(), '.local', 'share', 'pnpm');
+    }
+}
+/**
+ * The `pnpm` that a lookup through `pathEnv` finds ahead of the one `pnpm
+ * setup` installed under `pnpmHome`, if any.
+ *
+ * A `pnpm` from another installer (npm, Homebrew, Corepack, Volta, Scoop)
+ * that sits ahead of `$PNPM_HOME/bin` on PATH keeps running after the
+ * installer reports success, so every version it installs looks like it
+ * never took.
+ *
+ * A `pnpm` in `$PNPM_HOME/bin`, in `$PNPM_HOME` itself (which the v10 layout
+ * linked into directly), or a symlink resolving into either, is pnpm's own
+ * and never shadows.
+ */
+export function findShadowingPnpm(pnpmHome, opts) {
+    if (opts.pathEnv == null)
+        return undefined;
+    const platform = opts.platform ?? process.platform;
+    const [executable, ...others] = lookUpAll(opts.pathEnv, platform, opts.pathExt);
+    if (executable == null || isOwnPnpm(executable, pnpmHome))
+        return undefined;
+    return {
+        executable,
+        origin: detectInstallOrigin(executable),
+        binOnPath: others.some((candidate) => isOwnPnpm(candidate, pnpmHome)),
+    };
+}
+/**
+ * The warning to print once `pnpm setup` installed under `pnpmHome` and
+ * `shadowing` still answers to `pnpm`.
+ */
+export function renderShadowingPnpmWarning(shadowing, pnpmHome) {
+    const bin = path.join(pnpmHome, 'bin');
+    const origin = ORIGIN_DESCRIPTIONS[shadowing.origin];
+    const reorder = `move ${bin} ahead of ${path.dirname(shadowing.executable)} in PATH`;
+    const removal = REMOVAL_COMMANDS[shadowing.origin];
+    const fix = removal != null ? `run "${removal}" or ${reorder}` : reorder;
+    if (shadowing.binOnPath) {
+        return `Warning: "pnpm" on PATH is ${shadowing.executable} (${origin}), which comes before ${bin}.\n` +
+            `Your shell keeps running that pnpm, not the one pnpm installed to ${bin}.\n` +
+            `To finish switching, ${fix}.`;
+    }
+    return `Warning: "pnpm" on PATH is ${shadowing.executable} (${origin}), and ${bin} is not on PATH yet.\n` +
+        `Once a new shell adds it, it has to come first: ${fix}.`;
+}
+export function detectInstallOrigin(executable) {
+    return originFromPath(realpathOrSelf(executable)) ??
+        originFromPath(executable) ??
+        originFromShimScript(executable) ??
+        'unknown';
+}
+/** Every `pnpm` on `pathEnv`, in lookup order, the way the shell would find them. */
+function lookUpAll(pathEnv, platform, pathExt) {
+    const names = platform === 'win32'
+        ? (pathExt ?? process.env.PATHEXT ?? '.EXE;.CMD;.BAT;.COM').split(';').filter(Boolean).map((ext) => `pnpm${ext}`)
+        : ['pnpm'];
+    return pathEnv.split(platform === 'win32' ? ';' : ':').flatMap((dir) => {
+        const base = dir === '' ? '.' : dir;
+        const spellings = platform === 'win32' ? spellingsOnDisk(base) : undefined;
+        return names
+            .map((name) => path.join(base, spellings?.get(name.toLowerCase()) ?? name))
+            .filter((candidate) => isExecutableFile(candidate, platform));
+    });
+}
+/**
+ * The names in `dir` keyed by their lower case form. Windows matches
+ * `pnpm.CMD` from PATHEXT to `pnpm.cmd` on disk, and the warning should name
+ * the file as it is spelled there.
+ */
+function spellingsOnDisk(dir) {
+    try {
+        return new Map(fs.readdirSync(dir).map((entry) => [entry.toLowerCase(), entry]));
+    }
+    catch {
+        return new Map();
+    }
+}
+function isExecutableFile(file, platform) {
+    try {
+        if (!fs.statSync(file).isFile())
+            return false;
+        if (platform !== 'win32')
+            fs.accessSync(file, fs.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function originFromPath(executable) {
+    const components = executable.split(/[\\/]/).map((component) => component.toLowerCase());
+    const follows = (first, second) => components.some((component, index) => component === first && components[index + 1] === second);
+    if (follows('cellar', 'pnpm'))
+        return 'homebrew';
+    if (components.includes('corepack'))
+        return 'corepack';
+    if (components.includes('.volta'))
+        return 'volta';
+    if (components.includes('scoop'))
+        return 'scoop';
+    if (follows('node_modules', 'pnpm'))
+        return 'npm';
+    return undefined;
+}
+function originFromShimScript(executable) {
+    let script;
+    try {
+        if (fs.statSync(executable).size > SHIM_SCRIPT_MAX_SIZE)
+            return undefined;
+        script = fs.readFileSync(executable, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    if (script.includes('corepack'))
+        return 'corepack';
+    if (script.includes('node_modules/pnpm/') || script.includes('node_modules\\pnpm\\'))
+        return 'npm';
+    return undefined;
+}
+function isOwnPnpm(executable, pnpmHome) {
+    const ownDirs = [path.join(pnpmHome, 'bin'), pnpmHome];
+    const dirs = [path.dirname(executable), path.dirname(realpathOrSelf(executable))];
+    return dirs.some((dir) => ownDirs.some((own) => sameDir(dir, own)));
+}
+function sameDir(left, right) {
+    return path.relative(left, right) === '' || path.relative(realpathOrSelf(left), realpathOrSelf(right)) === '';
+}
+function realpathOrSelf(file) {
+    try {
+        return fs.realpathSync(file);
+    }
+    catch {
+        return file;
+    }
+}