@socketsecurity/lib 6.0.5 → 6.0.7

package/dist/external-tools/python/asset-names.js

@@ -0,0 +1,104 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_runtime = require('../../_virtual/_rolldown/runtime.js');
+const require_constants_platform = require('../../constants/platform.js');
+const require_primordials_object = require('../../primordials/object.js');
+let node_process = require("node:process");
+node_process = require_runtime.__toESM(node_process);
+
+//#region src/external-tools/python/asset-names.ts
+/**
+* @file Python-build-standalone release asset mapping. Astral publishes
+*   per-platform CPython archives under
+*   https://github.com/astral-sh/python-build-standalone/releases/download/<tag>/.
+*   Asset name shape: `cpython-<version>+<tag>-<triple>-install_only.tar.gz`.
+*   The `install_only` flavor is a relocatable runtime (no build artifacts),
+*   extracted one directory deep (`python/bin/python3`).
+*/
+const PLATFORM_TRIPLES = require_primordials_object.ObjectFreeze({
+	__proto__: null,
+	"darwin-arm64": "aarch64-apple-darwin",
+	"darwin-x64": "x86_64-apple-darwin",
+	"linux-arm64": "aarch64-unknown-linux-gnu",
+	"linux-arm64-musl": "aarch64-unknown-linux-musl",
+	"linux-x64": "x86_64-unknown-linux-gnu",
+	"linux-x64-musl": "x86_64-unknown-linux-musl",
+	"win-arm64": "aarch64-pc-windows-msvc",
+	"win-x64": "x86_64-pc-windows-msvc"
+});
+const NODE_PLATFORM_TO_PY = require_primordials_object.ObjectFreeze({
+	__proto__: null,
+	darwin: "darwin",
+	linux: "linux",
+	win32: "win"
+});
+const NODE_ARCH_TO_PY = require_primordials_object.ObjectFreeze({
+	__proto__: null,
+	arm64: "arm64",
+	x64: "x64"
+});
+const RELEASE_BASE = "https://github.com/astral-sh/python-build-standalone/releases/download";
+/**
+* Python-build-standalone default pin — the fleet-canonical CPython build,
+* matching socket-cli's `bundle-tools.json`. Consumers that don't pass their
+* own pin resolve against this. Bump it like any dependency (soak-aware), in
+* lockstep with socket-cli (drift-watch). The `checksums` map is keyed by asset
+* filename so the download tier verifies the exact tarball per platform.
+*/
+const DEFAULT_PYTHON_PIN = require_primordials_object.ObjectFreeze({
+	__proto__: null,
+	version: "3.11.14",
+	tag: "20260203",
+	checksums: require_primordials_object.ObjectFreeze({
+		__proto__: null,
+		"cpython-3.11.14+20260203-aarch64-apple-darwin-install_only.tar.gz": "63e3352fefd3b6494f73f46f51c6581c57a7e0d98775e6e00229d14a67ec3ce9",
+		"cpython-3.11.14+20260203-aarch64-pc-windows-msvc-install_only.tar.gz": "cb7828c131a005da367f7dba3a561bed91619452de870e531ee03344b2ac346f",
+		"cpython-3.11.14+20260203-aarch64-unknown-linux-gnu-install_only.tar.gz": "7341a5a0acd65f2c7c7a228d8bafa6561d220ffed26293d6a02c15ae2ee86af5",
+		"cpython-3.11.14+20260203-aarch64-unknown-linux-musl-install_only.tar.gz": "f0e5988c108187b12eb4d53cbac33a499a8e38e1693104432e1faabbab14c664",
+		"cpython-3.11.14+20260203-x86_64-apple-darwin-install_only.tar.gz": "f3b63051a9b1ffb4f663d928ebaec4311435cb67f3bdfa5634953df93397f25e",
+		"cpython-3.11.14+20260203-x86_64-pc-windows-msvc-install_only.tar.gz": "d220beff465bdc97bf5874be8ffbf07278e5bdf9a064cab932b5d93b542e3e86",
+		"cpython-3.11.14+20260203-x86_64-unknown-linux-gnu-install_only.tar.gz": "67abde21b6e074b58c0f738f0c4802b23827a7d49707dcaf3ed4dadf572f3f37",
+		"cpython-3.11.14+20260203-x86_64-unknown-linux-musl-install_only.tar.gz": "290de5199a9647d4de4adcf13a79a7c59f060357853bf41fd6d1a69b4b5fd00c"
+	})
+});
+/**
+* Resolve the current host to a python-build-standalone `platform-arch` key (a
+* `PLATFORM_TRIPLES` key, e.g. `darwin-arm64`, `linux-x64-musl`, `win-x64`).
+* Owns the python-build-standalone vocabulary end to end: Node's `win32`
+* becomes `win`, and an Alpine host gets a `-musl` suffix so it resolves to the
+* real musl triple (upstream ships both gnu and musl Linux builds). Returns
+* `undefined` when the host platform/arch has no upstream prebuilt.
+*
+* Separate from `getJreArch` (jre/Adoptium vocabulary) and from the shared
+* `getPlatformArch` — neither matches python-build-standalone's key set.
+*/
+function getPythonArch() {
+	/* c8 ignore start - depends on process.platform/arch + libc probe. */
+	const platform = NODE_PLATFORM_TO_PY[node_process.default.platform];
+	const arch = NODE_ARCH_TO_PY[node_process.default.arch];
+	if (!platform || !arch) return;
+	const key = `${platform}-${arch}${platform === "linux" && require_constants_platform.getLibc() === "musl" ? "-musl" : ""}`;
+	return PLATFORM_TRIPLES[key] ? key : void 0;
+	/* c8 ignore stop */
+}
+/**
+* Resolve the python-build-standalone download for a version + tag + platform.
+* Returns the asset filename and URL, or `undefined` when the platform-arch has
+* no upstream prebuilt.
+*/
+function pythonAsset(opts) {
+	const { tag, version } = opts;
+	const arch = opts.arch ?? getPythonArch();
+	const triple = arch ? PLATFORM_TRIPLES[arch] : void 0;
+	if (!triple) return;
+	return {
+		assetName: `cpython-${version}+${tag}-${triple}-install_only.tar.gz`,
+		url: `${RELEASE_BASE}/${tag}/cpython-${`${version}%2B${tag}`}-${triple}-install_only.tar.gz`
+	};
+}
+
+//#endregion
+exports.DEFAULT_PYTHON_PIN = DEFAULT_PYTHON_PIN;
+exports.getPythonArch = getPythonArch;
+exports.pythonAsset = pythonAsset;

package/dist/external-tools/python/dlx.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @file One-call dlx convenience wrappers for python: resolve (or download) a
+ *   CPython into the known dlx location, then run a pip primitive against it —
+ *   so callers don't thread `pythonBin` by hand. Mirrors how `dlx/package.ts`'s
+ *   `dlxPackage` wraps `downloadNpmPackage`. The dlx Python path is
+ *   deterministic given the pin (`pythonCacheDir(version, tag, arch)` →
+ *   `~/.socket/_dlx/python/...`), so the wrapper resolves to that known
+ *   location and hands the interpreter path to the pip fn itself:
+ *
+ *   - `dlxPipInstall({ python, spec })` → `resolvePython` + `downloadPipPackage`
+ *   - `dlxPipPin({ python, spec })` → `resolvePython` + `resolvePipPackagePin`
+ *     The lower-level primitives (`downloadPipPackage`, `resolvePipPackagePin`)
+ *     keep `pythonBin` required — they're the interpreter-agnostic layer. Use
+ *     them directly when you already hold an interpreter path; use these
+ *     wrappers when you have a pin and want one call.
+ */
+import type { DownloadPipPackageResult } from './pip-install';
+import type { PipPackagePin } from './pin';
+import type { PythonBuildPin } from './types';
+export interface DlxPipOptions {
+    /**
+     * Python-build-standalone pin (version + tag + optional integrity). The dlx
+     * interpreter location is derived from this — that's why no `pythonBin` is
+     * needed. Omit `arch` to auto-detect the host.
+     */
+    readonly python: PythonBuildPin & {
+        readonly arch?: string | undefined;
+    };
+    /**
+     * Prefer the downloaded dlx CPython over any PATH interpreter. Default false:
+     * a PATH `python3` wins when present, the dlx build is the fallback. Pass
+     * `true` for an exact, reproducible interpreter regardless of host Python.
+     */
+    readonly preferDownload?: boolean | undefined;
+}
+export interface DlxPipInstallOptions extends DlxPipOptions {
+    /**
+     * Optional sha256 hash of the top-level artifact, forwarded to
+     * `downloadPipPackage` (pip `--require-hashes`).
+     */
+    readonly hash?: string | undefined;
+    /**
+     * Pip install spec: `<pkg>==<version>` or `git+https://<url>@<sha>`.
+     */
+    readonly spec: string;
+}
+export interface DlxPipPinOptions extends DlxPipOptions {
+    /**
+     * Pip spec to pin: `<pkg>==<version>` or `git+https://<url>@<sha>`.
+     */
+    readonly spec: string;
+}
+/**
+ * Thrown when the python pin can't be resolved to an interpreter (no PATH
+ * Python and the download tier missed — e.g. unsupported host arch).
+ */
+export declare class DlxPythonUnavailableError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown | undefined;
+    } | undefined);
+}
+/**
+ * Resolve (or download) the dlx CPython for `python`, then pip-install `spec`
+ * into a content-addressed dlx dir. One-call form of `resolvePython` +
+ * `downloadPipPackage`. The returned result includes the interpreter path used,
+ * so callers can run the tool: `spawn(pythonBin, ['-m', '<module>'], { env: {
+ * PYTHONPATH: packageDir } })`.
+ */
+export declare function dlxPipInstall(opts: DlxPipInstallOptions): Promise<DownloadPipPackageResult & {
+    pythonBin: string;
+}>;
+/**
+ * Resolve (or download) the dlx CPython for `python`, then generate a
+ * hash-pinned closure for `spec`. One-call form of `resolvePython` +
+ * `resolvePipPackagePin`.
+ */
+export declare function dlxPipPin(opts: DlxPipPinOptions): Promise<PipPackagePin & {
+    pythonBin: string;
+}>;
+export declare function resolveOrThrow(opts: DlxPipOptions): Promise<string>;

package/dist/external-tools/python/dlx.js

@@ -0,0 +1,87 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_external_tools_python_pip_install = require('./pip-install.js');
+const require_external_tools_python_pin = require('./pin.js');
+const require_external_tools_python_resolve = require('./resolve.js');
+
+//#region src/external-tools/python/dlx.ts
+/**
+* @file One-call dlx convenience wrappers for python: resolve (or download) a
+*   CPython into the known dlx location, then run a pip primitive against it —
+*   so callers don't thread `pythonBin` by hand. Mirrors how `dlx/package.ts`'s
+*   `dlxPackage` wraps `downloadNpmPackage`. The dlx Python path is
+*   deterministic given the pin (`pythonCacheDir(version, tag, arch)` →
+*   `~/.socket/_dlx/python/...`), so the wrapper resolves to that known
+*   location and hands the interpreter path to the pip fn itself:
+*
+*   - `dlxPipInstall({ python, spec })` → `resolvePython` + `downloadPipPackage`
+*   - `dlxPipPin({ python, spec })` → `resolvePython` + `resolvePipPackagePin`
+*     The lower-level primitives (`downloadPipPackage`, `resolvePipPackagePin`)
+*     keep `pythonBin` required — they're the interpreter-agnostic layer. Use
+*     them directly when you already hold an interpreter path; use these
+*     wrappers when you have a pin and want one call.
+*/
+/**
+* Thrown when the python pin can't be resolved to an interpreter (no PATH
+* Python and the download tier missed — e.g. unsupported host arch).
+*/
+var DlxPythonUnavailableError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "DlxPythonUnavailableError";
+	}
+};
+/**
+* Resolve (or download) the dlx CPython for `python`, then pip-install `spec`
+* into a content-addressed dlx dir. One-call form of `resolvePython` +
+* `downloadPipPackage`. The returned result includes the interpreter path used,
+* so callers can run the tool: `spawn(pythonBin, ['-m', '<module>'], { env: {
+* PYTHONPATH: packageDir } })`.
+*/
+async function dlxPipInstall(opts) {
+	const pythonBin = await resolveOrThrow(opts);
+	return {
+		...await require_external_tools_python_pip_install.downloadPipPackage({
+			hash: opts.hash,
+			pythonBin,
+			spec: opts.spec
+		}),
+		pythonBin
+	};
+}
+/**
+* Resolve (or download) the dlx CPython for `python`, then generate a
+* hash-pinned closure for `spec`. One-call form of `resolvePython` +
+* `resolvePipPackagePin`.
+*/
+async function dlxPipPin(opts) {
+	const pythonBin = await resolveOrThrow(opts);
+	return {
+		...await require_external_tools_python_pin.resolvePipPackagePin({
+			pythonBin,
+			spec: opts.spec
+		}),
+		pythonBin
+	};
+}
+async function resolveOrThrow(opts) {
+	const { preferDownload, python } = opts;
+	const resolved = await require_external_tools_python_resolve.resolvePython({
+		preferDownload,
+		downloadIfMissing: {
+			arch: python.arch,
+			integrity: python.integrity,
+			tag: python.tag,
+			version: python.version
+		}
+	});
+	if (!resolved) throw new DlxPythonUnavailableError(`dlx python: could not resolve a CPython interpreter for ${python.version}+${python.tag} — no host python3 and the python-build-standalone download tier missed (unsupported host arch?)`);
+	return resolved.path;
+}
+
+//#endregion
+exports.DlxPythonUnavailableError = DlxPythonUnavailableError;
+exports.dlxPipInstall = dlxPipInstall;
+exports.dlxPipPin = dlxPipPin;
+exports.resolveOrThrow = resolveOrThrow;

package/dist/external-tools/python/from-download.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @file `pythonFromDownload()` — fetches a python-build-standalone CPython into
+ *   the DLX cache and returns a `ResolvedPython` pointing at the interpreter.
+ *   The `install_only` tarball extracts to a `python/` subdirectory, so the
+ *   interpreter lands at `<extractedDir>/python/bin/python3` (or
+ *   `python/python.exe` on Windows) — no strip.
+ */
+import type { BinaryDownloader } from '../from-download';
+import type { HashSpec } from '../../integrity';
+import type { ResolvedPython } from './types';
+export interface PythonFromDownloadOptions {
+    /**
+     * CPython version, e.g. `3.11.14`.
+     */
+    version: string;
+    /**
+     * Python-build-standalone release tag, e.g. `20260203`.
+     */
+    tag: string;
+    /**
+     * Target `platform-arch`, e.g. `darwin-arm64`. Omit to auto-detect the
+     * current host via {@link getPythonArch}.
+     */
+    arch?: string | undefined;
+    /**
+     * Optional pinned integrity (hex SHA-256 or SRI) for the tarball.
+     */
+    integrity?: HashSpec | undefined;
+    /**
+     * Override the extraction directory. Defaults to
+     * `~/.socket/_dlx/python/<version>-<tag>-<arch>`.
+     */
+    cacheDir?: string | undefined;
+    /**
+     * Inject a custom downloader (tests / alternate cache). Defaults to dlx.
+     */
+    downloader?: BinaryDownloader | undefined;
+}
+/**
+ * Return the absolute path to the interpreter inside an extracted
+ * python-build-standalone tree. The layout follows the TARGET arch, not the
+ * host: a Windows target nests the interpreter at `python/python.exe`, every
+ * other target at `python/bin/python3`. Keying off `process.platform` would be
+ * wrong when cross-resolving (e.g. a Windows host downloading a linux-x64
+ * build). `arch` is a platform-arch key like `win-x64` / `linux-x64`; omit it
+ * to fall back to the host platform.
+ */
+export declare function pythonBinPath(extractedDir: string, arch?: string | undefined): string;
+/**
+ * Default DLX cache directory for a python build pin.
+ */
+export declare function pythonCacheDir(version: string, tag: string, arch: string): string;
+export declare function pythonFromDownload(opts: PythonFromDownloadOptions): Promise<ResolvedPython | undefined>;

package/dist/external-tools/python/from-download.js

@@ -0,0 +1,68 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_runtime = require('../../_virtual/_rolldown/runtime.js');
+const require_paths_socket = require('../../paths/socket.js');
+const require_external_tools_from_download = require('../from-download.js');
+const require_external_tools_python_asset_names = require('./asset-names.js');
+let node_path = require("node:path");
+node_path = require_runtime.__toESM(node_path);
+let node_process = require("node:process");
+node_process = require_runtime.__toESM(node_process);
+
+//#region src/external-tools/python/from-download.ts
+/**
+* @file `pythonFromDownload()` — fetches a python-build-standalone CPython into
+*   the DLX cache and returns a `ResolvedPython` pointing at the interpreter.
+*   The `install_only` tarball extracts to a `python/` subdirectory, so the
+*   interpreter lands at `<extractedDir>/python/bin/python3` (or
+*   `python/python.exe` on Windows) — no strip.
+*/
+/**
+* Return the absolute path to the interpreter inside an extracted
+* python-build-standalone tree. The layout follows the TARGET arch, not the
+* host: a Windows target nests the interpreter at `python/python.exe`, every
+* other target at `python/bin/python3`. Keying off `process.platform` would be
+* wrong when cross-resolving (e.g. a Windows host downloading a linux-x64
+* build). `arch` is a platform-arch key like `win-x64` / `linux-x64`; omit it
+* to fall back to the host platform.
+*/
+function pythonBinPath(extractedDir, arch) {
+	if (arch ? arch.startsWith("win-") : node_process.default.platform === "win32") return node_path.default.join(extractedDir, "python", "python.exe");
+	return node_path.default.join(extractedDir, "python", "bin", "python3");
+}
+/**
+* Default DLX cache directory for a python build pin.
+*/
+function pythonCacheDir(version, tag, arch) {
+	return node_path.default.join(require_paths_socket.getSocketDlxDir(), "python", `${version}-${tag}-${arch}`);
+}
+async function pythonFromDownload(opts) {
+	const { cacheDir, downloader, integrity, tag, version } = opts;
+	const arch = opts.arch ?? require_external_tools_python_asset_names.getPythonArch();
+	if (!arch) return;
+	const asset = require_external_tools_python_asset_names.pythonAsset({
+		version,
+		tag,
+		arch
+	});
+	if (!asset) return;
+	const extractedDir = cacheDir ?? pythonCacheDir(version, tag, arch);
+	const archive = await require_external_tools_from_download.downloadAndExtractTool({
+		url: asset.url,
+		name: `python-${version}-${tag}-${arch}.tar.gz`,
+		integrity,
+		extractedDir,
+		downloader
+	});
+	return {
+		path: pythonBinPath(extractedDir, arch),
+		source: "download",
+		integrity: archive.integrity
+	};
+}
+
+//#endregion
+exports.pythonBinPath = pythonBinPath;
+exports.pythonCacheDir = pythonCacheDir;
+exports.pythonFromDownload = pythonFromDownload;

package/dist/external-tools/python/from-path.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @file `pythonFromPath()` — looks for a CPython interpreter on the system
+ *   PATH. Tries `python3` first (the POSIX convention), then `python` (the
+ *   Windows convention / some minimal images). Returns the first hit.
+ */
+import type { ResolvedPython } from './types';
+export declare function pythonFromPath(): Promise<ResolvedPython | undefined>;

package/dist/external-tools/python/from-path.js

@@ -0,0 +1,23 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_bin_which = require('../../bin/which.js');
+
+//#region src/external-tools/python/from-path.ts
+/**
+* @file `pythonFromPath()` — looks for a CPython interpreter on the system
+*   PATH. Tries `python3` first (the POSIX convention), then `python` (the
+*   Windows convention / some minimal images). Returns the first hit.
+*/
+async function pythonFromPath() {
+	for (const bin of ["python3", "python"]) {
+		const onPath = await require_bin_which.which(bin, { nothrow: true });
+		if (typeof onPath === "string") return {
+			path: onPath,
+			source: "path"
+		};
+	}
+}
+
+//#endregion
+exports.pythonFromPath = pythonFromPath;

package/dist/external-tools/python/pin.d.ts

@@ -0,0 +1,121 @@
+/**
+ * @file `resolvePipPackagePin()` — the Python mirror of
+ *   `resolveNpmPackagePin()` (dlx/lockfile). Resolves a pip spec and its full
+ *   dependency closure WITHOUT installing into the interpreter, then returns
+ *   everything needed to pin a reproducible, hash-verified install:
+ *
+ *   - the resolved top-level name + version,
+ *   - the top-level artifact's hashes (sha512 SRI + sha256 hex), and
+ *   - a fully-hashed `requirements.txt` body (`name==version --hash=sha256:<hex>`
+ *     for every artifact in the closure) ready to feed back to
+ *     `downloadPipPackage` / `pip install --require-hashes`. Engine: `pip
+ *     download --dest <scratch> <spec>` downloads the spec + its resolved
+ *     closure as wheels/sdists into a scratch dir (no install, no venv), each
+ *     file is hashed, then the scratch dir is torn down. This is pip's own
+ *     recipe for producing hashed requirements — `pip-tools` is NOT required.
+ *     Contrast `resolveNpmPackagePin` (dlx/lockfile): same contract, npm engine
+ *     (Arborist lockfile-only + pacote), emits a `package-lock.json`. The pip
+ *     side emits a hashed `requirements.txt` because that — not a lockfile — is
+ *     what `pip install --require-hashes` consumes. NOTE on the soak window:
+ *     `resolveNpmPackagePin` applies a min-release-age cutoff via Arborist's
+ *     `before` date. pip has no native release-age gate, so this generator does
+ *     NOT enforce one — callers that need a soak must vet the resolved versions
+ *     out of band. The spec itself remains the primary pin: `==<version>` (PyPI
+ *     is immutable per version) or `@<full-sha>` (git is content-addressed).
+ */
+import type { ComputedHashes } from '../../integrity';
+export interface ResolvePipPackagePinOptions {
+    /**
+     * Absolute path to the Python interpreter used to run `pip download`,
+     * typically from `resolvePython()`. The interpreter is NOT modified.
+     */
+    readonly pythonBin: string;
+    /**
+     * Directory `pip download` resolves the closure into. Defaults to a unique
+     * scratch dir under the OS temp dir, removed before returning.
+     */
+    readonly scratchDir?: string | undefined;
+    /**
+     * Pip spec to pin: `<pkg>==<version>` (PyPI exact pin) or
+     * `git+https://<url>@<sha>` (git-SHA pin).
+     */
+    readonly spec: string;
+}
+export interface PipArtifactPin {
+    /**
+     * Sha256 hex of the artifact, the `--hash=sha256:<hex>` value pip expects.
+     */
+    readonly checksum: string;
+    /**
+     * Downloaded artifact filename, e.g. `is_odd-3.0.1-py3-none-any.whl`.
+     */
+    readonly file: string;
+    /**
+     * Distribution name parsed from the filename, e.g. `is-odd`.
+     */
+    readonly name: string;
+    /**
+     * Distribution version parsed from the filename, e.g. `3.0.1`.
+     */
+    readonly version: string;
+}
+export interface PipPackagePin {
+    /**
+     * Per-artifact pins for the full resolved closure (top-level + transitive).
+     */
+    readonly artifacts: readonly PipArtifactPin[];
+    /**
+     * Hashes of the top-level artifact (sha512 SRI + sha256 hex). The Python
+     * analog of `NpmPackagePin.hash`.
+     */
+    readonly hash: ComputedHashes;
+    /**
+     * Resolved top-level distribution name.
+     */
+    readonly name: string;
+    /**
+     * Fully-hashed `requirements.txt` content, ready to write to disk and feed to
+     * `pip install --require-hashes -r <file>`. The Python analog of
+     * `NpmPackagePin.lockfile`.
+     */
+    readonly requirements: string;
+    /**
+     * Resolved top-level distribution version.
+     */
+    readonly version: string;
+}
+/**
+ * Thrown when `pip download` produces no artifacts or a filename can't be
+ * parsed into a name + version.
+ */
+export declare class PipPackagePinError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown | undefined;
+    } | undefined);
+}
+/**
+ * Normalize a PEP 503 distribution name: lowercase, runs of `_ . -` collapse to
+ * a single `-`. Wheel filenames use `_`; requirements/PyPI use `-`.
+ */
+export declare function normalizeDistName(name: string): string;
+/**
+ * Parse `<name>-<version>` out of a wheel (`name-ver-...whl`) or sdist
+ * (`name-ver.tar.gz` / `name-ver.zip`) filename. Returns undefined when the
+ * shape isn't recognized.
+ */
+export declare function parseArtifactFilename(file: string): {
+    name: string;
+    version: string;
+} | undefined;
+/**
+ * Generate a vendorable, hash-pinned closure for a pip spec without installing
+ * it. Mirrors `resolveNpmPackagePin`. Throws `PipPackagePinError` on an empty
+ * download or an unparseable artifact filename.
+ */
+export declare function resolvePipPackagePin(options: ResolvePipPackagePinOptions): Promise<PipPackagePin>;
+/**
+ * Best-effort distribution name from a pip spec for matching the top-level
+ * artifact: strips a `==`/`>=`/etc. version and a `git+...#egg=<name>`
+ * fragment. Falls back to the raw spec when neither is present.
+ */
+export declare function specDistName(spec: string): string;