@socketsecurity/lib 6.0.6 → 6.0.8

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

@@ -0,0 +1,75 @@
+"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_process = require("node:process");
+node_process = require_runtime.__toESM(node_process);
+let node_path = require("node:path");
+node_path = require_runtime.__toESM(node_path);
+
+//#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(options) {
+	options = {
+		__proto__: null,
+		...options
+	};
+	const { cacheDir, downloader, integrity, tag, version } = {
+		__proto__: null,
+		...options
+	};
+	const arch = options.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;

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

@@ -0,0 +1,176 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_runtime = require('../../_virtual/_rolldown/runtime.js');
+const require_integrity = require('../../integrity.js');
+const require_constants_platform = require('../../constants/platform.js');
+const require_process_spawn_child = require('../../process/spawn/child.js');
+const require_fs_safe = require('../../fs/safe.js');
+let node_fs = require("node:fs");
+let node_process = require("node:process");
+node_process = require_runtime.__toESM(node_process);
+let node_path = require("node:path");
+node_path = require_runtime.__toESM(node_path);
+let node_os = require("node:os");
+node_os = require_runtime.__toESM(node_os);
+
+//#region src/external-tools/python/pin.ts
+/**
+* @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).
+*/
+/**
+* Thrown when `pip download` produces no artifacts or a filename can't be
+* parsed into a name + version.
+*/
+var PipPackagePinError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "PipPackagePinError";
+	}
+};
+/**
+* Normalize a PEP 503 distribution name: lowercase, runs of `_ . -` collapse to
+* a single `-`. Wheel filenames use `_`; requirements/PyPI use `-`.
+*/
+function normalizeDistName(name) {
+	return name.toLowerCase().replace(/[-_.]+/g, "-");
+}
+/**
+* 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.
+*/
+function parseArtifactFilename(file) {
+	if (file.endsWith(".whl")) {
+		const parts = file.slice(0, -4).split("-");
+		if (parts.length < 2) return;
+		return {
+			name: normalizeDistName(parts[0]),
+			version: parts[1]
+		};
+	}
+	const ext = [
+		".tar.gz",
+		".tar.bz2",
+		".zip",
+		".tgz"
+	].find((e) => file.endsWith(e));
+	if (!ext) return;
+	const stem = file.slice(0, -ext.length);
+	const dashIdx = stem.lastIndexOf("-");
+	if (dashIdx <= 0) return;
+	return {
+		name: normalizeDistName(stem.slice(0, dashIdx)),
+		version: stem.slice(dashIdx + 1)
+	};
+}
+/**
+* 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.
+*/
+async function resolvePipPackagePin(options) {
+	const { pythonBin, spec } = {
+		__proto__: null,
+		...options
+	};
+	if (typeof spec !== "string" || spec.length === 0) throw new PipPackagePinError("resolvePipPackagePin requires a package spec");
+	const scratch = options.scratchDir ?? node_path.default.join(node_os.default.tmpdir(), `socket-lib-pip-pin-${node_process.default.pid}-${Date.now()}`);
+	await require_fs_safe.safeMkdir(scratch, { recursive: true });
+	try {
+		await require_process_spawn_child.spawn(pythonBin, [
+			"-m",
+			"pip",
+			"download",
+			"--no-input",
+			"--quiet",
+			"--dest",
+			scratch,
+			spec
+		], {
+			shell: require_constants_platform.WIN32,
+			stdio: "inherit"
+		});
+		const files = (await node_fs.promises.readdir(scratch)).filter((f) => f.endsWith(".whl") || f.endsWith(".tar.gz") || f.endsWith(".tar.bz2") || f.endsWith(".zip") || f.endsWith(".tgz"));
+		if (!files.length) throw new PipPackagePinError(`resolvePipPackagePin: pip download ${spec} produced no artifacts in ${scratch}`);
+		const artifacts = [];
+		const targetName = normalizeDistName(specDistName(spec));
+		let top;
+		for (const file of files.toSorted()) {
+			const hash = require_integrity.computeHashes(await node_fs.promises.readFile(node_path.default.join(scratch, file)));
+			const parsed = parseArtifactFilename(file);
+			if (!parsed) throw new PipPackagePinError(`resolvePipPackagePin: could not parse name/version from artifact ${file}`);
+			artifacts.push({
+				checksum: hash.checksum,
+				file,
+				name: parsed.name,
+				version: parsed.version
+			});
+			if (!top && parsed.name === targetName) top = {
+				hash,
+				name: parsed.name,
+				version: parsed.version
+			};
+		}
+		if (!top) {
+			const first = artifacts[0];
+			top = {
+				hash: require_integrity.computeHashes(await node_fs.promises.readFile(node_path.default.join(scratch, first.file))),
+				name: first.name,
+				version: first.version
+			};
+		}
+		const requirements = artifacts.map((a) => `${a.name}==${a.version} --hash=sha256:${a.checksum}`).join("\n") + "\n";
+		return {
+			artifacts,
+			hash: top.hash,
+			name: top.name,
+			requirements,
+			version: top.version
+		};
+	} finally {
+		try {
+			await require_fs_safe.safeDelete(scratch, { force: true });
+		} catch {}
+	}
+}
+/**
+* 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.
+*/
+function specDistName(spec) {
+	const eggIdx = spec.indexOf("#egg=");
+	if (eggIdx !== -1) return spec.slice(eggIdx + 5);
+	const match = /^([A-Za-z0-9._-]+)\s*(?:@|[=<>!~]=?)/.exec(spec);
+	return match ? match[1] : spec;
+}
+
+//#endregion
+exports.PipPackagePinError = PipPackagePinError;
+exports.normalizeDistName = normalizeDistName;
+exports.parseArtifactFilename = parseArtifactFilename;
+exports.resolvePipPackagePin = resolvePipPackagePin;
+exports.specDistName = specDistName;

package/dist/external-tools/python/pip-install.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @file `downloadPipPackage()` — the Python mirror of `dlx/package.ts`'s
+ *   `downloadNpmPackage()`. Installs a pip spec into a content-addressed dlx
+ *   directory (`pip install --target <dir>`), leaving the interpreter pristine:
+ *   the package + its deps land in
+ *   `~/.socket/_dlx/<cacheKey(spec)>/site-packages`, the exact analog of how
+ *   `downloadNpmPackage` installs npm deps into
+ *   `<dlxDir>/<hash>/node_modules/`. This is the bundle-safe / SEA-VFS-safe
+ *   model:
+ *
+ *   - No venv → no symlinks, no `pyvenv.cfg` with an absolute `home=`.
+ *   - The target dir is plain files → embeddable in a SEA's VFS, relocatable at
+ *     runtime.
+ *   - One shared Python serves N isolated package dirs (true per-tool isolation
+ *     without a venv) — exactly the `node_modules`-per-cacheKey shape. Run the
+ *     installed tool with the package dir on `PYTHONPATH`: spawn(pythonBin,
+ *     ['-m', '<module>', ...args], { env: { ...process.env, PYTHONPATH:
+ *     packageDir } }) `spec` is a PyPI pin (`<pkg>==<version>`) or a git-SHA
+ *     pin (`git+https://…@<sha>`). A TOCTOU lock guards concurrent installs; an
+ *     existing non-empty package dir makes the call idempotent. Contrast
+ *     `createPipVenv` (external-tools/from-pip-venv): venv with a
+ *     `bin/<entryPoint>` — convenient but symlink + absolute-`home`-dependent,
+ *     so DLX-only and NOT bundleable.
+ */
+/**
+ * Install `spec` into a content-addressed dlx dir via `pip install --target`.
+ * Lock-guarded + idempotent. Throws on a failed pip install or if the lock
+ * can't be acquired after MAX_RETRIES. Mirrors `downloadNpmPackage`.
+ */
+export declare function downloadPipPackage(options: DownloadPipPackageOptions, retryCount?: number): Promise<DownloadPipPackageResult>;
+export declare function isAlreadyInstalled(packageDir: string): Promise<boolean>;
+export declare function isStaleLock(pid: number): boolean;
+export interface DownloadPipPackageOptions {
+    /**
+     * Optional sha256 hash (`sha256:<hex>` or bare `<hex>`) of the top-level
+     * artifact, the Python analog of `downloadNpmPackage`'s `hash`. When set, pip
+     * runs with `--require-hashes` and `--hash=sha256:<hex>`, which fails closed
+     * unless EVERY resolved artifact (the spec and its full dependency closure)
+     * carries a matching hash — so it only fits specs pip can hash-verify (a
+     * pinned `==<version>` or a direct wheel/sdist URL) with a hash-pinned
+     * closure. Omit it and rely on the immutable spec as the pin: `==<version>`
+     * (PyPI is immutable per version) or `@<full-sha>` (git is
+     * content-addressed).
+     */
+    readonly hash?: string | undefined;
+    /**
+     * Absolute path to the Python interpreter used to run pip (and later the
+     * tool). The interpreter is NOT modified — packages go to the dlx package
+     * dir. Typically from `resolvePython()`.
+     */
+    readonly pythonBin: string;
+    /**
+     * Pip install spec: `<pkg>==<version>` (PyPI exact pin) or
+     * `git+https://<url>@<sha>` (git-SHA pin).
+     */
+    readonly spec: string;
+}
+export interface DownloadPipPackageResult {
+    /**
+     * `true` when this call ran pip; `false` when an existing install was reused.
+     */
+    readonly installed: boolean;
+    /**
+     * Directory the package was installed into. Put this on `PYTHONPATH` to run
+     * the tool: `python -m <module>`. The Python analog of
+     * `DownloadNpmPackageResult.packageDir`.
+     */
+    readonly packageDir: string;
+}
+/**
+ * Content-addressed install dir for a spec:
+ * `~/.socket/_dlx/<cacheKey>/site-packages`. The Python analog of
+ * `downloadNpmPackage`'s `<hash>/node_modules`.
+ */
+export declare function pipPackageDir(spec: string): string;

package/dist/external-tools/python/pip-install.js

@@ -0,0 +1,142 @@
+"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_process_spawn_child = require('../../process/spawn/child.js');
+const require_paths_socket = require('../../paths/socket.js');
+const require_fs_safe = require('../../fs/safe.js');
+const require_dlx_cache = require('../../dlx/cache.js');
+let node_fs = require("node:fs");
+let node_process = require("node:process");
+node_process = require_runtime.__toESM(node_process);
+let node_path = require("node:path");
+node_path = require_runtime.__toESM(node_path);
+
+//#region src/external-tools/python/pip-install.ts
+/**
+* @file `downloadPipPackage()` — the Python mirror of `dlx/package.ts`'s
+*   `downloadNpmPackage()`. Installs a pip spec into a content-addressed dlx
+*   directory (`pip install --target <dir>`), leaving the interpreter pristine:
+*   the package + its deps land in
+*   `~/.socket/_dlx/<cacheKey(spec)>/site-packages`, the exact analog of how
+*   `downloadNpmPackage` installs npm deps into
+*   `<dlxDir>/<hash>/node_modules/`. This is the bundle-safe / SEA-VFS-safe
+*   model:
+*
+*   - No venv → no symlinks, no `pyvenv.cfg` with an absolute `home=`.
+*   - The target dir is plain files → embeddable in a SEA's VFS, relocatable at
+*     runtime.
+*   - One shared Python serves N isolated package dirs (true per-tool isolation
+*     without a venv) — exactly the `node_modules`-per-cacheKey shape. Run the
+*     installed tool with the package dir on `PYTHONPATH`: spawn(pythonBin,
+*     ['-m', '<module>', ...args], { env: { ...process.env, PYTHONPATH:
+*     packageDir } }) `spec` is a PyPI pin (`<pkg>==<version>`) or a git-SHA
+*     pin (`git+https://…@<sha>`). A TOCTOU lock guards concurrent installs; an
+*     existing non-empty package dir makes the call idempotent. Contrast
+*     `createPipVenv` (external-tools/from-pip-venv): venv with a
+*     `bin/<entryPoint>` — convenient but symlink + absolute-`home`-dependent,
+*     so DLX-only and NOT bundleable.
+*/
+const MAX_RETRIES = 3;
+const WAIT_TICKS = 30;
+/**
+* Install `spec` into a content-addressed dlx dir via `pip install --target`.
+* Lock-guarded + idempotent. Throws on a failed pip install or if the lock
+* can't be acquired after MAX_RETRIES. Mirrors `downloadNpmPackage`.
+*/
+async function downloadPipPackage(options, retryCount = 0) {
+	const { hash, pythonBin, spec } = {
+		__proto__: null,
+		...options
+	};
+	const packageDir = pipPackageDir(spec);
+	if (retryCount >= MAX_RETRIES) throw new Error(`downloadPipPackage: could not acquire install lock after ${MAX_RETRIES} retries for ${packageDir}; a peer may be stuck or the lock is stale — remove it and retry`);
+	if (await isAlreadyInstalled(packageDir)) return {
+		installed: false,
+		packageDir
+	};
+	const lockDir = node_path.default.dirname(packageDir);
+	await require_fs_safe.safeMkdir(lockDir, { recursive: true });
+	const lockFile = node_path.default.join(lockDir, ".installing");
+	try {
+		await node_fs.promises.writeFile(lockFile, node_process.default.pid.toString(), { flag: "wx" });
+	} catch (e) {
+		if (e.code !== "EEXIST") throw e;
+		let stale = false;
+		try {
+			stale = isStaleLock(Number.parseInt((await node_fs.promises.readFile(lockFile, "utf8")).trim(), 10));
+		} catch {
+			stale = true;
+		}
+		if (stale) {
+			await require_fs_safe.safeDelete(lockFile, { force: true });
+			return downloadPipPackage(options, retryCount + 1);
+		}
+		for (let i = 0; i < WAIT_TICKS; i += 1) {
+			await new Promise((resolve) => {
+				setTimeout(resolve, 1e3);
+			});
+			if (await isAlreadyInstalled(packageDir)) return {
+				installed: false,
+				packageDir
+			};
+		}
+		return downloadPipPackage(options, retryCount + 1);
+	}
+	try {
+		await require_fs_safe.safeMkdir(packageDir, { recursive: true });
+		const normalizedHash = hash ? hash.startsWith("sha256:") ? hash : `sha256:${hash}` : void 0;
+		await require_process_spawn_child.spawn(pythonBin, [
+			"-m",
+			"pip",
+			"install",
+			"--no-input",
+			"--quiet",
+			"--target",
+			packageDir,
+			...normalizedHash ? ["--require-hashes", `--hash=${normalizedHash}`] : [],
+			spec
+		], {
+			shell: require_constants_platform.WIN32,
+			stdio: "inherit"
+		});
+		if (!await isAlreadyInstalled(packageDir)) throw new Error(`downloadPipPackage: pip install --target ${packageDir} ${spec} reported success but the target is still empty`);
+		return {
+			installed: true,
+			packageDir
+		};
+	} finally {
+		await require_fs_safe.safeDelete(lockFile, { force: true });
+	}
+}
+async function isAlreadyInstalled(packageDir) {
+	try {
+		return (await node_fs.promises.readdir(packageDir)).length > 0;
+	} catch {
+		return false;
+	}
+}
+function isStaleLock(pid) {
+	if (Number.isNaN(pid) || pid <= 0) return true;
+	try {
+		node_process.default.kill(pid, 0);
+		return false;
+	} catch (e) {
+		return e.code !== "EPERM";
+	}
+}
+/**
+* Content-addressed install dir for a spec:
+* `~/.socket/_dlx/<cacheKey>/site-packages`. The Python analog of
+* `downloadNpmPackage`'s `<hash>/node_modules`.
+*/
+function pipPackageDir(spec) {
+	return node_path.default.join(require_paths_socket.getSocketDlxDir(), require_dlx_cache.generateCacheKey(spec), "site-packages");
+}
+
+//#endregion
+exports.downloadPipPackage = downloadPipPackage;
+exports.isAlreadyInstalled = isAlreadyInstalled;
+exports.isStaleLock = isStaleLock;
+exports.pipPackageDir = pipPackageDir;

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

@@ -0,0 +1,42 @@
+/**
+ * @file `resolvePython()` — CPython resolution entry point. Tries each source
+ *   in order:
+ *
+ *   1. PATH — `python3` / `python` on the system PATH.
+ *   2. download — python-build-standalone CPython into the DLX cache (only when
+ *      `downloadIfMissing` is passed). Returns `undefined` if all enabled
+ *      sources miss. Memoized per option-shape so repeated calls in one process
+ *      don't re-probe / re-download. NOTE: unlike the JRE / removed-uv
+ *      resolvers there is no VFS tier here — a CPython runtime is not embedded
+ *      in the smol Node binary. Add a `from-vfs` tier here if that changes.
+ */
+import type { BinaryDownloader } from '../from-download';
+import type { HashSpec } from '../../integrity';
+import type { ResolvedPython } from './types';
+export interface ResolvePythonOptions {
+    /**
+     * Prefer a downloaded python-build-standalone over a PATH interpreter. Use
+     * when you need an exact, reproducible CPython (the host `python3` may be the
+     * wrong version). Default false: PATH wins when present.
+     */
+    preferDownload?: boolean | undefined;
+    /**
+     * When set, fall back to downloading python-build-standalone if no PATH
+     * interpreter is found (or always, with `preferDownload`).
+     */
+    downloadIfMissing?: {
+        version: string;
+        tag: string;
+        /**
+         * Omit to auto-detect the current host via {@link getPythonArch}.
+         */
+        arch?: string | undefined;
+        integrity?: HashSpec | undefined;
+        cacheDir?: string | undefined;
+        downloader?: BinaryDownloader | undefined;
+    } | undefined;
+}
+export declare function cacheKey(options: ResolvePythonOptions | undefined): string;
+export declare function doResolvePython(options?: ResolvePythonOptions | undefined): Promise<ResolvedPython | undefined>;
+export declare function resetPythonResolution(): void;
+export declare function resolvePython(options?: ResolvePythonOptions | undefined): Promise<ResolvedPython | undefined>;