@pnpm/exe 12.0.0-rc.4 → 12.0.0-rc.6

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,42 @@
+# Third-Party Notices
+
+This product includes software derived from third-party sources. The
+components below, and their license terms, are listed here in satisfaction
+of those terms.
+
+## Yarn (`@yarnpkg/nm`, `@yarnpkg/extensions`)
+
+- Source: <https://github.com/yarnpkg/berry>
+- License: BSD 2-Clause
+
+The `nodeLinker: hoisted` layout is produced by a Rust port of the hoisting
+algorithm in `@yarnpkg/nm`, and the built-in package-compatibility database
+is a copy of the one in `@yarnpkg/extensions`.
+
+```text
+BSD 2-Clause License
+
+Copyright (c) 2016-present, Yarn Contributors.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+```

package/bin/pnpm.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+// Corepack's entry point into pnpm. Corepack hardcodes `./bin/pnpm.mjs` and
+// `./bin/pnpx.mjs` for every pnpm >=11 (see its `config.json`) and loads them
+// into its own Node.js process, which a native executable cannot be loaded into.
+//
+// Nothing else runs this file: `package.json#bin` still points at the native
+// binary, so an ordinary `npm install -g pnpm` never pays for a Node.js startup.
+//
+// Corepack installs no dependencies and runs no lifecycle scripts, so the
+// `@pnpm/exe.<target>` package that carries the binary is absent and
+// `install.js` never ran. The binary is therefore downloaded on first use and
+// kept next to this wrapper — where the native binary also finds the `dist/`
+// payload it ships node-gyp in.
+//
+// The download itself is `get-pnpm`, the package behind https://get.pnpm.io,
+// which already knows how to verify one; it travels in that same `dist/`
+// payload. What is left here is Corepack's environment, which it does not know:
+// where to download from, what credentials to use, and whose signature to trust.
+import { Buffer } from 'node:buffer'
+import { spawnSync } from 'node:child_process'
+import console from 'node:console'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import process from 'node:process'
+import { URL } from 'node:url'
+import { readWrapperManifest, resolveInstalledBinary, wrapperDir } from '../native-binary.mjs'
+
+// Deliberately not the `pnpm` placeholder that `install.js` overwrites: a name
+// of its own is what tells a downloaded binary apart from the placeholder.
+const DOWNLOADED_BINARY = path.join(
+  wrapperDir,
+  process.platform === 'win32' ? 'pnpm-native.exe' : 'pnpm-native'
+)
+const GET_PNPM = new URL('../dist/node_modules/get-pnpm/lib/index.js', import.meta.url)
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org'
+
+run(await nativeBinary())
+
+function run (binary) {
+  // Ctrl-C reaches the whole foreground process group, so the binary gets its
+  // own SIGINT; exiting here first would hand the terminal back while it is
+  // still shutting down.
+  process.on('SIGINT', () => {})
+
+  const result = spawnSync(binary, process.argv.slice(2), { stdio: 'inherit' })
+  if (result.error != null) {
+    fail(`Could not run the pnpm binary at ${binary}: ${result.error.message}`)
+  }
+  process.exitCode = result.signal == null
+    ? result.status ?? 1
+    : 128 + (os.constants.signals[result.signal] ?? 0)
+}
+
+async function nativeBinary () {
+  const installed = resolveInstalledBinary()
+  if (installed != null) {
+    return installed
+  }
+  // A plain file, not merely something at that path: what a previous run left
+  // is a file, and a directory there would be spawned as if it were a binary.
+  if (fs.lstatSync(DOWNLOADED_BINARY, { throwIfNoEntry: false })?.isFile() === true) {
+    return DOWNLOADED_BINARY
+  }
+
+  if (process.env.COREPACK_ENABLE_NETWORK === '0') {
+    fail('Network access is disabled by the environment, so the pnpm binary cannot be downloaded.')
+  }
+
+  const { version } = readWrapperManifest()
+  console.error(`Downloading the pnpm ${version} binary for ${process.platform}-${process.arch}...`)
+  const { downloadPnpmExecutable } = await import(GET_PNPM).catch((err) => {
+    fail(`This copy of the pnpm package is missing the downloader it needs: ${err.message}`)
+  })
+  try {
+    await downloadPnpmExecutable({
+      version,
+      registry: process.env.COREPACK_NPM_REGISTRY || DEFAULT_REGISTRY,
+      destPath: DOWNLOADED_BINARY,
+      headers: registryHeaders(),
+      ...signaturePolicy(),
+    })
+  } catch (err) {
+    fail(`Could not download the pnpm ${version} binary: ${err.message}`)
+  }
+  return DOWNLOADED_BINARY
+}
+
+/**
+ * Credentials for the registry, read the way Corepack reads its own. `get-pnpm`
+ * keeps them on that registry's origin, so a download host it names never
+ * receives them.
+ */
+function registryHeaders () {
+  const { COREPACK_NPM_TOKEN, COREPACK_NPM_USERNAME, COREPACK_NPM_PASSWORD } = process.env
+  if (COREPACK_NPM_TOKEN) {
+    return { authorization: `Bearer ${COREPACK_NPM_TOKEN}` }
+  }
+  if (COREPACK_NPM_USERNAME && COREPACK_NPM_PASSWORD) {
+    const credentials = Buffer.from(`${COREPACK_NPM_USERNAME}:${COREPACK_NPM_PASSWORD}`, 'utf8')
+    return { authorization: `Basic ${credentials.toString('base64')}` }
+  }
+  return undefined
+}
+
+/**
+ * Whose signature over the download to trust, following `COREPACK_INTEGRITY_KEYS`
+ * exactly as Corepack does: npm's own keys when it is unset, the keys it names
+ * when it holds a key set, and no signature check at all when it is `0` or
+ * empty — which is the state a registry that re-publishes packages, and
+ * therefore carries no npm signatures, already has to be in for Corepack to
+ * have installed this wrapper from it.
+ */
+function signaturePolicy () {
+  const configured = process.env.COREPACK_INTEGRITY_KEYS
+  if (configured == null) {
+    return {}
+  }
+  if (configured === '' || configured === '0') {
+    return { verifySignature: false }
+  }
+  let keys
+  try {
+    keys = JSON.parse(configured).npm
+  } catch (err) {
+    fail(`COREPACK_INTEGRITY_KEYS is not readable as JSON: ${err.message}`)
+  }
+  // An absent or malformed `npm` entry would otherwise be passed on as no keys
+  // at all, which falls back to npm's own — the opposite of what setting the
+  // variable asked for. An empty set is left alone: it names no key to trust,
+  // and Corepack reads it the same way, so every download is refused.
+  if (!Array.isArray(keys)) {
+    fail('COREPACK_INTEGRITY_KEYS holds no "npm" key set to verify the pnpm binary against.')
+  }
+  return { keys }
+}
+
+function fail (message) {
+  console.error(message)
+  process.exit(1)
+}

package/bin/pnpx.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// Corepack's `pnpx` entry point; see ./pnpm.mjs. The native binary infers the
+// `dlx` subcommand from the name it was launched under, which does not survive
+// being spawned from here, so inject it the way the `pnpx` shell script does.
+import process from 'node:process'
+
+process.argv = [...process.argv.slice(0, 2), 'dlx', ...process.argv.slice(2)]
+
+await import('./pnpm.mjs')

package/dist/node_modules/.bin/get-pnpm

@@ -0,0 +1,50 @@
+#!/bin/sh
+# Resolve $0 through symlinks so basedir is the shim's real directory.
+# Cap hops at the kernel's ELOOP limit so a cycle cannot hang the shim.
+link="$0"
+hops=0
+while [ -L "$link" ] && [ "$hops" -lt 40 ]; do
+  hops=$((hops+1))
+  target=$(readlink "$link")
+  case "$target" in
+    /*) link="$target" ;;
+    *)  link="$(dirname "$link")/$target" ;;
+  esac
+done
+basedir=$(dirname "$(echo "$link" | sed -e 's,\\,/,g')")
+basedir_win="$basedir"
+exe=""
+msys=""
+
+case `uname -a` in
+  *CYGWIN*|*MINGW*|*MSYS*)
+    if command -v cygpath > /dev/null 2>&1; then
+      basedir_win=`cygpath -w "$basedir"`
+    fi
+    exe=".exe"
+    msys="true"
+  ;;
+  *WSL2*)
+    if command -v wslpath > /dev/null 2>&1; then
+      basedir_win="$(wslpath -w "$basedir" 2> /dev/null)"
+      if [ $? -ne 0 ] || [ -z "$basedir_win" ]; then
+        basedir_win="$basedir"
+      else
+        exe=".exe"
+      fi
+    fi
+  ;;
+esac
+
+if [ -n "$exe" ] && [ -x "$basedir/node.exe" ]; then
+  exec "$basedir/node.exe"  "$basedir_win/../get-pnpm/bin/get-pnpm.js" "$@"
+elif [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../get-pnpm/bin/get-pnpm.js" "$@"
+elif command -v node >/dev/null 2>&1; then
+  exec node  "$basedir/../get-pnpm/bin/get-pnpm.js" "$@"
+elif [ -n "$exe" ] && command -v node.exe >/dev/null 2>&1; then
+  exec node.exe  "$basedir_win/../get-pnpm/bin/get-pnpm.js" "$@"
+else
+  exec node  "$basedir/../get-pnpm/bin/get-pnpm.js" "$@"
+fi
+# cmd-shim-target=/home/runner/_work/pnpm/pnpm/pnpm/npm/pnpm/temp-deploy/node_modules/get-pnpm/bin/get-pnpm.js

package/dist/node_modules/.package-map.json

@@ -1 +1 @@
-{"packages":{".":{"url":"..","dependencies":{"node-gyp":"node-gyp","pacquet":"."}},"@isaacs/fs-minipass":{"url":"./@isaacs/fs-minipass","dependencies":{"@isaacs/fs-minipass":"@isaacs/fs-minipass","minipass":"minipass"}},"abbrev":{"url":"./abbrev","dependencies":{"abbrev":"abbrev"}},"chownr":{"url":"./chownr","dependencies":{"chownr":"chownr"}},"env-paths":{"url":"./env-paths","dependencies":{"env-paths":"env-paths"}},"exponential-backoff":{"url":"./exponential-backoff","dependencies":{"exponential-backoff":"exponential-backoff"}},"fdir":{"url":"./fdir","dependencies":{"fdir":"fdir","picomatch":"picomatch"}},"graceful-fs":{"url":"./graceful-fs","dependencies":{"graceful-fs":"graceful-fs"}},"isexe":{"url":"./isexe","dependencies":{"isexe":"isexe"}},"minipass":{"url":"./minipass","dependencies":{"minipass":"minipass"}},"minizlib":{"url":"./minizlib","dependencies":{"minipass":"minipass","minizlib":"minizlib"}},"node-gyp":{"url":"./node-gyp","dependencies":{"env-paths":"env-paths","exponential-backoff":"exponential-backoff","graceful-fs":"graceful-fs","node-gyp":"node-gyp","nopt":"nopt","proc-log":"proc-log","semver":"semver","tar":"tar","tinyglobby":"tinyglobby","undici":"undici","which":"which"}},"nopt":{"url":"./nopt","dependencies":{"abbrev":"abbrev","nopt":"nopt"}},"picomatch":{"url":"./picomatch","dependencies":{"picomatch":"picomatch"}},"proc-log":{"url":"./proc-log","dependencies":{"proc-log":"proc-log"}},"semver":{"url":"./semver","dependencies":{"semver":"semver"}},"tar":{"url":"./tar","dependencies":{"@isaacs/fs-minipass":"@isaacs/fs-minipass","chownr":"chownr","minipass":"minipass","minizlib":"minizlib","tar":"tar","yallist":"yallist"}},"tinyglobby":{"url":"./tinyglobby","dependencies":{"fdir":"fdir","picomatch":"picomatch","tinyglobby":"tinyglobby"}},"undici":{"url":"./undici","dependencies":{"undici":"undici"}},"which":{"url":"./which","dependencies":{"isexe":"isexe","which":"which"}},"yallist":{"url":"./yallist","dependencies":{"yallist":"yallist"}}}}
+{"packages":{".":{"url":"..","dependencies":{"get-pnpm":"get-pnpm","node-gyp":"node-gyp","pacquet":"."}},"@isaacs/fs-minipass":{"url":"./@isaacs/fs-minipass","dependencies":{"@isaacs/fs-minipass":"@isaacs/fs-minipass","minipass":"minipass"}},"abbrev":{"url":"./abbrev","dependencies":{"abbrev":"abbrev"}},"chownr":{"url":"./chownr","dependencies":{"chownr":"chownr"}},"env-paths":{"url":"./env-paths","dependencies":{"env-paths":"env-paths"}},"exponential-backoff":{"url":"./exponential-backoff","dependencies":{"exponential-backoff":"exponential-backoff"}},"fdir":{"url":"./fdir","dependencies":{"fdir":"fdir","picomatch":"picomatch"}},"get-pnpm":{"url":"./get-pnpm","dependencies":{"get-pnpm":"get-pnpm"}},"graceful-fs":{"url":"./graceful-fs","dependencies":{"graceful-fs":"graceful-fs"}},"isexe":{"url":"./isexe","dependencies":{"isexe":"isexe"}},"minipass":{"url":"./minipass","dependencies":{"minipass":"minipass"}},"minizlib":{"url":"./minizlib","dependencies":{"minipass":"minipass","minizlib":"minizlib"}},"node-gyp":{"url":"./node-gyp","dependencies":{"env-paths":"env-paths","exponential-backoff":"exponential-backoff","graceful-fs":"graceful-fs","node-gyp":"node-gyp","nopt":"nopt","proc-log":"proc-log","semver":"semver","tar":"tar","tinyglobby":"tinyglobby","undici":"undici","which":"which"}},"nopt":{"url":"./nopt","dependencies":{"abbrev":"abbrev","nopt":"nopt"}},"picomatch":{"url":"./picomatch","dependencies":{"picomatch":"picomatch"}},"proc-log":{"url":"./proc-log","dependencies":{"proc-log":"proc-log"}},"semver":{"url":"./semver","dependencies":{"semver":"semver"}},"tar":{"url":"./tar","dependencies":{"@isaacs/fs-minipass":"@isaacs/fs-minipass","chownr":"chownr","minipass":"minipass","minizlib":"minizlib","tar":"tar","yallist":"yallist"}},"tinyglobby":{"url":"./tinyglobby","dependencies":{"fdir":"fdir","picomatch":"picomatch","tinyglobby":"tinyglobby"}},"undici":{"url":"./undici","dependencies":{"undici":"undici"}},"which":{"url":"./which","dependencies":{"isexe":"isexe","which":"which"}},"yallist":{"url":"./yallist","dependencies":{"yallist":"yallist"}}}}

package/dist/node_modules/.pnpm-workspace-state-v1.json

@@ -1,9 +1,9 @@
 {
-  "lastValidatedTimestamp": 1786544175645,
+  "lastValidatedTimestamp": 1786812811685,
   "projects": {
     "/home/runner/_work/pnpm/pnpm/pnpm/npm/pnpm/temp-deploy": {
       "name": "pacquet",
-      "version": "12.0.0-rc.4"
+      "version": "12.0.0-rc.6"
     }
   },
   "pnpmfiles": [],
@@ -131,7 +131,7 @@
         "escape-string-regexp": "^5.0.0",
         "eslint": "^10.8.1",
         "eslint-plugin-import-x": "^4.17.1",
-        "eslint-plugin-jest": "^29.16.0",
+        "eslint-plugin-jest": "^29.16.1",
         "eslint-plugin-n": "^18.3.0",
         "eslint-plugin-promise": "^7.3.0",
         "eslint-plugin-regexp": "^3.1.1",
@@ -142,6 +142,7 @@
         "fast-glob": "^3.3.3",
         "fs-extra": "^11.4.0",
         "fuse-native": "^2.2.6",
+        "get-pnpm": "^0.0.3",
         "get-port": "^7.2.0",
         "ghooks": "2.0.4",
         "graceful-fs": "^4.2.11",
@@ -248,7 +249,7 @@
         "ts-jest-resolver": "2.0.1",
         "typescript": "6.0.3",
         "typescript-eslint": "^8.67.0",
-        "undici": "^7.27.2",
+        "undici": "^7.29.0",
         "unified": "^11.0.5",
         "validate-npm-package-name": "7.0.2",
         "version-selector-type": "^3.0.0",

package/dist/node_modules/get-pnpm/bin/get-pnpm.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { runCli } from '../lib/index.js'
+
+try {
+  process.exitCode = await runCli(process.argv.slice(2))
+} catch (err) {
+  // Anything can be thrown, and reading `.message` off a non-Error would either
+  // print `undefined` or throw again, burying the reason under a stack trace.
+  console.error(err instanceof Error ? err.message : String(err))
+  process.exitCode = 1
+}

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

@@ -0,0 +1,99 @@
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { extractTarballMember } from './extractTarballMember.js';
+import { isMusl, platformPackageName } from './platformPackageName.js';
+import { downloadTarball, fetchVersionMeta, normalizeRegistry } from './registry.js';
+import { majorVersion } from './resolveVersion.js';
+import { sameFileContents } from './sameFileContents.js';
+import { verifyRegistrySignature } from './verifySignature.js';
+/** Name the executable is published under inside its platform package. */
+function executableName() {
+    return process.platform === 'win32' ? 'pnpm.exe' : 'pnpm';
+}
+/**
+ * Places the pnpm executable for this host at `destPath`, and nothing else.
+ *
+ * The narrow half of {@link downloadPnpm}, for a caller that already knows the
+ * exact version and already has whatever else it needs: no dist-tag lookup (so
+ * no packument download), no `dist/` tree, no directory to assemble. Corepack
+ * is the case it exists for — it unpacks the `pnpm` package itself but installs
+ * none of its dependencies, so the executable has to arrive separately.
+ *
+ * The download is checked against the checksum the registry published for it,
+ * and that checksum against npm's signature, exactly as {@link downloadPnpm}
+ * does; nothing is written to `destPath` until both pass. See
+ * {@link DownloadExecutableOptions.verifySignature} for the one waiver.
+ *
+ * Placement is atomic and tolerates losing a race: a concurrent call that got
+ * there first keeps its copy, since both placed the same verified bytes.
+ *
+ * @returns the package the executable came from.
+ */
+export async function downloadPnpmExecutable(opts) {
+    const { version, destPath } = opts;
+    const registry = normalizeRegistry(opts.registry);
+    const packageName = platformPackageName({
+        major: majorVersion(version),
+        platform: process.platform,
+        arch: process.arch,
+        musl: isMusl(),
+    });
+    const meta = await fetchVersionMeta(registry, packageName, version, opts.headers);
+    if (!meta.dist.integrity) {
+        throw new Error(`The npm registry published no checksum for ${packageName}@${version}, so it cannot be verified.`);
+    }
+    if (opts.verifySignature !== false) {
+        verifyRegistrySignature({
+            name: packageName,
+            version,
+            integrity: meta.dist.integrity,
+            signatures: meta.dist.signatures,
+            keys: opts.keys,
+        });
+    }
+    const scratch = `${destPath}.${randomBytes(6).toString('hex')}`;
+    const tarball = `${scratch}.tgz`;
+    const staged = `${scratch}.tmp`;
+    fs.mkdirSync(path.dirname(destPath), { recursive: true });
+    try {
+        await downloadTarball(meta, tarball, { registry, headers: opts.headers });
+        const member = `package/${executableName()}`;
+        if (!await extractTarballMember(tarball, member, staged, 0o755)) {
+            throw new Error(`The ${packageName}@${version} tarball contains no ${member}.`);
+        }
+        place(staged, destPath);
+    }
+    finally {
+        fs.rmSync(tarball, { force: true });
+        fs.rmSync(staged, { force: true });
+    }
+    return { packageName };
+}
+/**
+ * The codes Windows fails a rename with when the destination is held open —
+ * which is what a concurrent call executing the copy it just placed looks like.
+ * POSIX replaces the destination instead, so a failure there is a real one.
+ */
+const DESTINATION_IN_USE = new Set(['EPERM', 'EACCES', 'EBUSY']);
+/**
+ * Moves the verified executable into place, keeping the copy a concurrent call
+ * placed if that is what stops the rename.
+ *
+ * A lost race is not assumed from the failure alone: the copy already there has
+ * to hold the same bytes as the one just verified, or this call has no idea
+ * what it would be reporting success for. Anything else — no permission on the
+ * directory, a directory or an unrelated file at `destPath` — is a failure.
+ */
+function place(staged, destPath) {
+    try {
+        fs.renameSync(staged, destPath);
+    }
+    catch (err) {
+        const code = err.code ?? '';
+        if (!DESTINATION_IN_USE.has(code))
+            throw err;
+        if (!sameFileContents(staged, destPath))
+            throw err;
+    }
+}

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

@@ -0,0 +1,23 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+/**
+ * Unpacks a package tarball into `dest`, leaving its `package/` root in place.
+ *
+ * Shells out to `tar`, which every supported host has: macOS and Linux ship it,
+ * and Windows has had bsdtar since Windows 10 1803. Member selection and
+ * `--strip-components` are avoided because busybox tar and bsdtar disagree
+ * about them.
+ */
+export function extractTarball(tarball, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    const { error, status, stderr } = spawnSync('tar', ['-xzf', tarball, '-C', dest], { encoding: 'utf8' });
+    if (error != null) {
+        if (error.code === 'ENOENT') {
+            throw new Error('This installer needs the `tar` command, which was not found on your PATH.');
+        }
+        throw error;
+    }
+    if (status !== 0) {
+        throw new Error(`Could not extract ${tarball}: ${stderr.trim()}`);
+    }
+}

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

@@ -0,0 +1,128 @@
+import { createReadStream, createWriteStream } from 'node:fs';
+import { pipeline } from 'node:stream/promises';
+import { createGunzip } from 'node:zlib';
+const BLOCK_SIZE = 512;
+/** Regular file, in both the old (`\0`) and the ustar (`0`) spelling. */
+const FILE_TYPES = new Set(['0', '\0']);
+/**
+ * Writes one file out of a package tarball to `dest`, and nothing else.
+ *
+ * Reads the archive in-process rather than shelling out to `tar` the way
+ * {@link extractTarball} does: a caller that wants a single executable, in an
+ * environment it does not control (a Corepack cache in a minimal image), should
+ * not need a `tar` on the PATH for it. Only regular files are considered, which
+ * is all an npm tarball holds beyond directories, and the parse stays streaming
+ * so the archive never lands in memory.
+ *
+ * `dest` is created exclusively — an existing file, or a symlink planted at
+ * that path, fails the write rather than being followed.
+ *
+ * @param tarball Path to the gzipped archive.
+ * @param memberPath Path of the wanted file inside it, e.g. `package/pnpm`.
+ * @param dest Path to write it to.
+ * @param mode Permissions for `dest`.
+ * @returns whether the member was there.
+ */
+export async function extractTarballMember(tarball, memberPath, dest, mode = 0o644) {
+    let found = false;
+    await pipeline(createReadStream(tarball), createGunzip(), async function (source) {
+        const reader = new BlockReader(source);
+        while (true) {
+            const header = await reader.read(BLOCK_SIZE);
+            // The archive ends with zero-filled blocks; one is enough to stop.
+            if (header == null || header[0] === 0)
+                return;
+            const entry = parseHeader(header);
+            if (FILE_TYPES.has(entry.type) && entry.path === memberPath) {
+                const written = await reader.pipe(entry.size, createWriteStream(dest, { flags: 'wx', mode }));
+                if (written !== entry.size) {
+                    throw new Error(`${tarball} ends after ${written} of the ${entry.size} bytes it declares for ${memberPath}.`);
+                }
+                found = true;
+                // The rest of the archive holds nothing this caller asked for, and
+                // the checksum that vouches for it was checked before any of it was
+                // read.
+                return;
+            }
+            await reader.skip(Math.ceil(entry.size / BLOCK_SIZE) * BLOCK_SIZE);
+        }
+    });
+    return found;
+}
+function parseHeader(header) {
+    const name = readString(header, 0, 100);
+    const prefix = readString(header, 345, 155);
+    return {
+        path: prefix === '' ? name : `${prefix}/${name}`,
+        size: parseInt(readString(header, 124, 12).trim() || '0', 8),
+        type: String.fromCharCode(header[156]),
+    };
+}
+function readString(header, start, length) {
+    const field = header.subarray(start, start + length);
+    const end = field.indexOf(0);
+    return field.toString('utf8', 0, end === -1 ? field.length : end);
+}
+class BlockReader {
+    #iterator;
+    #buffered = [];
+    #buffedBytes = 0;
+    #done = false;
+    constructor(source) {
+        this.#iterator = source[Symbol.asyncIterator]();
+    }
+    /** The next `size` bytes, or `null` once the stream ends. */
+    async read(size) {
+        if (!await this.#fill(size))
+            return null;
+        return this.#take(size);
+    }
+    async skip(size) {
+        let left = size;
+        while (left > 0) {
+            if (!await this.#fill(1))
+                return;
+            left -= this.#take(Math.min(left, this.#buffedBytes)).length;
+        }
+    }
+    /**
+     * Hands the next `size` bytes to `destination`, without collecting them.
+     *
+     * @returns how many bytes there were, which is fewer than `size` only when
+     * the stream ended early.
+     */
+    async pipe(size, destination) {
+        const self = this;
+        let left = size;
+        await pipeline(async function* () {
+            while (left > 0) {
+                if (!await self.#fill(1))
+                    return;
+                const chunk = self.#take(Math.min(left, self.#buffedBytes));
+                left -= chunk.length;
+                yield chunk;
+            }
+        }, destination);
+        return size - left;
+    }
+    /** Reads until at least `size` bytes are buffered, or the stream ends. */
+    async #fill(size) {
+        while (this.#buffedBytes < size && !this.#done) {
+            const { value, done } = await this.#iterator.next();
+            if (done === true) {
+                this.#done = true;
+            }
+            else {
+                this.#buffered.push(value);
+                this.#buffedBytes += value.length;
+            }
+        }
+        return this.#buffedBytes >= size;
+    }
+    #take(size) {
+        const joined = this.#buffered.length === 1 ? this.#buffered[0] : Buffer.concat(this.#buffered);
+        this.#buffered = joined.length > size ? [joined.subarray(size)] : [];
+        this.#buffedBytes = joined.length - size;
+        return joined.subarray(0, size);
+    }
+}