@socketsecurity/lib 6.0.6 → 6.0.8

package/dist/external-tools/manifest.js

@@ -2,10 +2,10 @@
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_primordials_error = require('../primordials/error.js');
-const require_primordials_string = require('../primordials/string.js');
 const require_integrity = require('../integrity.js');
-const require_primordials_array = require('../primordials/array.js');
 const require_primordials_object = require('../primordials/object.js');
+const require_primordials_string = require('../primordials/string.js');
+const require_primordials_array = require('../primordials/array.js');
 const require_fs_read_json = require('../fs/read-json.js');
 
 //#region src/external-tools/manifest.ts
@@ -20,10 +20,10 @@ const require_fs_read_json = require('../fs/read-json.js');
 *   integrity-string validation. Shape: { "<tool-name>": { "description":
 *   "human-readable summary", "version": "1.7.2", "release": "asset" |
 *   "tarball" | ..., "repository": "github:owner/repo", "notes": [...],
-*   "checksums": { "<platform-arch>": { "asset": "<asset-filename>",
+*   "platforms": { "<platform-arch>": { "asset": "<asset-filename>",
 *   "integrity": "sha256-base64=" } } } } Some tools have flavor variants (e.g.
 *   sfw's `free` / `enterprise`) that wrap the `{repository, binaryName,
-*   checksums}` triple under a flavor key. Use `getToolFlavor` for those. Some
+*   platforms}` triple under a flavor key. Use `getToolFlavor` for those. Some
 *   entries (e.g. `rust`) describe a system tool with a different shape —
 *   they're skipped by `getTool` and fully readable only via the raw
 *   `readManifest` returning unknown.
@@ -52,14 +52,14 @@ function parseChecksum(raw, toolName, platformKey) {
 	if (!isObject(raw)) throw new require_primordials_error.ErrorCtor(`external-tools.json: tool '${toolName}' checksum entry '${platformKey}' must be an object, got: ${typeof raw}`);
 	const r = raw;
 	if (typeof r.asset !== "string" || r.asset.length === 0) throw new require_primordials_error.ErrorCtor(`external-tools.json: tool '${toolName}' platform '${platformKey}' is missing a non-empty 'asset' string`);
-	if (typeof r.integrity !== "string" || !require_integrity.isIntegrityString(r.integrity)) throw new require_primordials_error.ErrorCtor(`external-tools.json: tool '${toolName}' platform '${platformKey}' has an invalid 'integrity' (expected SRI sha512 or sha256 form): ${r.integrity}`);
+	if (typeof r.integrity !== "string" || !require_integrity.isIntegrity(r.integrity)) throw new require_primordials_error.ErrorCtor(`external-tools.json: tool '${toolName}' platform '${platformKey}' has an invalid 'integrity' (expected SRI sha512 or sha256 form): ${r.integrity}`);
 	return {
 		asset: r.asset,
 		integrity: r.integrity
 	};
 }
-function parseChecksums(raw, toolName) {
-	if (!isObject(raw)) throw new require_primordials_error.ErrorCtor(`external-tools.json: tool '${toolName}' is missing a 'checksums' object`);
+function parsePlatforms(raw, toolName) {
+	if (!isObject(raw)) throw new require_primordials_error.ErrorCtor(`external-tools.json: tool '${toolName}' is missing a 'platforms' object`);
 	const out = {};
 	for (const platformKey of require_primordials_object.ObjectKeys(raw)) out[platformKey] = parseChecksum(raw[platformKey], toolName, platformKey);
 	return out;
@@ -70,7 +70,7 @@ function parseToolEntry(raw, toolName) {
 		raw
 	};
 	const r = raw;
-	if (isObject(r.checksums)) {
+	if (isObject(r.platforms)) {
 		if (typeof r.description !== "string" || typeof r.version !== "string" || typeof r.release !== "string" || typeof r.repository !== "string") return {
 			kind: "other",
 			raw
@@ -84,7 +84,7 @@ function parseToolEntry(raw, toolName) {
 				repository: r.repository,
 				binaryName: typeof r.binaryName === "string" ? r.binaryName : void 0,
 				notes: require_primordials_array.ArrayIsArray(r.notes) ? r.notes : void 0,
-				checksums: parseChecksums(r.checksums, toolName)
+				platforms: parsePlatforms(r.platforms, toolName)
 			}
 		};
 	}
@@ -105,7 +105,7 @@ function parseToolEntry(raw, toolName) {
 * callers can handle them out-of-band without blocking the manifest read.
 */
 async function readExternalToolsManifest(filepath) {
-	const raw = await /* @__PURE__ */ require_fs_read_json.readJson(filepath);
+	const raw = await require_fs_read_json.readJson(filepath);
 	if (!isObject(raw)) throw new require_primordials_error.ErrorCtor(`external-tools.json: expected top-level object, got: ${typeof raw}`);
 	const tools = {};
 	for (const toolName of require_primordials_object.ObjectKeys(raw)) {
@@ -120,12 +120,12 @@ function tryParseFlavored(raw, toolName) {
 		const value = raw[key];
 		if (!isObject(value)) continue;
 		const rf = value;
-		if (!isObject(rf.checksums)) continue;
+		if (!isObject(rf.platforms)) continue;
 		if (typeof rf.repository !== "string") continue;
 		flavors[key] = {
 			repository: rf.repository,
 			binaryName: typeof rf.binaryName === "string" ? rf.binaryName : void 0,
-			checksums: parseChecksums(rf.checksums, `${toolName}.${key}`)
+			platforms: parsePlatforms(rf.platforms, `${toolName}.${key}`)
 		};
 	}
 	if (require_primordials_object.ObjectKeys(flavors).length === 0) return;
@@ -143,7 +143,7 @@ exports.getTool = getTool;
 exports.getToolFlavor = getToolFlavor;
 exports.isObject = isObject;
 exports.parseChecksum = parseChecksum;
-exports.parseChecksums = parseChecksums;
+exports.parsePlatforms = parsePlatforms;
 exports.parseToolEntry = parseToolEntry;
 exports.readExternalToolsManifest = readExternalToolsManifest;
 exports.tryParseFlavored = tryParseFlavored;

package/dist/external-tools/opengrep/asset-names.d.ts

@@ -41,4 +41,4 @@ export interface OpengrepDownloadOptions {
  *
  * Reference: https://github.com/opengrep/opengrep/releases.
  */
-export declare function getOpengrepDownloadUrl(opts: OpengrepDownloadOptions): string | undefined;
+export declare function getOpengrepDownloadUrl(options: OpengrepDownloadOptions): string | undefined;

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

@@ -53,8 +53,11 @@ function getOpengrepAssetEntry(platformArch) {
 *
 * Reference: https://github.com/opengrep/opengrep/releases.
 */
-function getOpengrepDownloadUrl(opts) {
-	const { platformArch, version } = opts;
+function getOpengrepDownloadUrl(options) {
+	const { platformArch, version } = {
+		__proto__: null,
+		...options
+	};
 	const entry = OPENGREP_ASSET_MAP[platformArch];
 	if (!entry) return;
 	return `https://github.com/opengrep/opengrep/releases/download/v${version}/` + entry.asset;

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

@@ -14,4 +14,4 @@ export interface OpengrepFromDownloadOptions {
     cacheDir?: string | undefined;
     downloader?: BinaryDownloader | undefined;
 }
-export declare function opengrepFromDownload(opts: OpengrepFromDownloadOptions): Promise<ResolvedOpengrep | undefined>;
+export declare function opengrepFromDownload(options: OpengrepFromDownloadOptions): Promise<ResolvedOpengrep | undefined>;

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

@@ -17,8 +17,11 @@ node_path = require_runtime.__toESM(node_path);
 *   bare binaries (no extraction); Windows ships a zip. The asset-map's
 *   `isArchive` flag drives extraction vs. copy.
 */
-async function opengrepFromDownload(opts) {
-	const { cacheDir, downloader, integrity, platformArch, version } = opts;
+async function opengrepFromDownload(options) {
+	const { cacheDir, downloader, integrity, platformArch, version } = {
+		__proto__: null,
+		...options
+	};
 	const url = require_external_tools_opengrep_asset_names.getOpengrepDownloadUrl({
 		version,
 		platformArch

package/dist/external-tools/opengrep/from-vfs.js

@@ -11,7 +11,7 @@ const require_smol_vfs = require('../../smol/vfs.js');
 */
 const OPENGREP_VFS_KEY = "opengrep";
 async function opengrepFromVfs() {
-	const vfs = /* @__PURE__ */ require_smol_vfs.getSmolVfs();
+	const vfs = require_smol_vfs.getSmolVfs();
 	if (!vfs) return;
 	/* c8 ignore start - smol Node binary only. */
 	if (!vfs.has("opengrep")) return;

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

@@ -20,7 +20,7 @@ export interface ResolveOpengrepOptions {
         downloader?: BinaryDownloader | undefined;
     } | undefined;
 }
-export declare function cacheKey(opts: ResolveOpengrepOptions | undefined): string;
-export declare function doResolveOpengrep(opts?: ResolveOpengrepOptions | undefined): Promise<ResolvedOpengrep | undefined>;
+export declare function cacheKey(options: ResolveOpengrepOptions | undefined): string;
+export declare function doResolveOpengrep(options?: ResolveOpengrepOptions | undefined): Promise<ResolvedOpengrep | undefined>;
 export declare function resetOpengrepResolution(): void;
-export declare function resolveOpengrep(opts?: ResolveOpengrepOptions | undefined): Promise<ResolvedOpengrep | undefined>;
+export declare function resolveOpengrep(options?: ResolveOpengrepOptions | undefined): Promise<ResolvedOpengrep | undefined>;

package/dist/external-tools/opengrep/resolve.js

@@ -18,30 +18,38 @@ const require_external_tools_opengrep_from_vfs = require('./from-vfs.js');
 *      per option-shape.
 */
 const resolutionCache = new require_primordials_map_set.MapCtor();
-function cacheKey(opts) {
-	if (!opts?.downloadIfMissing) return "local-only";
-	const { cacheDir, integrity, platformArch, version } = opts.downloadIfMissing;
+function cacheKey(options) {
+	options = {
+		__proto__: null,
+		...options
+	};
+	if (!options?.downloadIfMissing) return "local-only";
+	const { cacheDir, integrity, platformArch, version } = options.downloadIfMissing;
 	return `dl:${version}:${platformArch}:${typeof integrity === "string" ? integrity : integrity ? `${integrity.type}:${integrity.value}` : ""}:${cacheDir ?? ""}`;
 }
-async function doResolveOpengrep(opts) {
+async function doResolveOpengrep(options) {
+	options = {
+		__proto__: null,
+		...options
+	};
 	const fromVfs = await require_external_tools_opengrep_from_vfs.opengrepFromVfs();
 	/* c8 ignore start - smol Node binary only. */
 	if (fromVfs) return fromVfs;
 	/* c8 ignore stop */
 	const fromPath = await require_external_tools_opengrep_from_path.opengrepFromPath();
 	if (fromPath) return fromPath;
-	if (opts?.downloadIfMissing) return require_external_tools_opengrep_from_download.opengrepFromDownload(opts.downloadIfMissing);
+	if (options?.downloadIfMissing) return require_external_tools_opengrep_from_download.opengrepFromDownload(options.downloadIfMissing);
 }
 /* c8 ignore start - test-only escape hatch. */
 function resetOpengrepResolution() {
 	resolutionCache.clear();
 }
 /* c8 ignore stop */
-function resolveOpengrep(opts) {
-	const key = cacheKey(opts);
+function resolveOpengrep(options) {
+	const key = cacheKey(options);
 	let cached = resolutionCache.get(key);
 	if (!cached) {
-		cached = doResolveOpengrep(opts);
+		cached = doResolveOpengrep(options);
 		resolutionCache.set(key, cached);
 	}
 	return cached;

package/dist/external-tools/opengrep/types.d.ts

@@ -20,5 +20,5 @@ export interface ResolvedOpengrep {
     /**
      * See {@link ResolvedToolIntegrity}.
      */
-    readonly integrity?: ResolvedToolIntegrity;
+    readonly integrity?: ResolvedToolIntegrity | undefined;
 }

package/dist/external-tools/python/asset-names.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @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`).
+ */
+/**
+ * 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.
+ */
+export declare const DEFAULT_PYTHON_PIN: Readonly<{
+    __proto__: null;
+    version: "3.11.14";
+    tag: "20260203";
+    checksums: Readonly<{
+        __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.
+ */
+export declare function getPythonArch(): string | undefined;
+export interface PythonAssetOptions {
+    /**
+     * CPython version, e.g. `3.11.14`.
+     */
+    readonly version: string;
+    /**
+     * Python-build-standalone release tag, e.g. `20260203`.
+     */
+    readonly tag: string;
+    /**
+     * Target `platform-arch`, e.g. `darwin-arm64`. Omit to auto-detect the
+     * current host via {@link getPythonArch}; pass an explicit value to resolve
+     * the asset for a different target (e.g. cross-platform packaging).
+     */
+    readonly arch?: string | undefined;
+}
+export interface PythonAsset {
+    /**
+     * Full asset filename:
+     * `cpython-<version>+<tag>-<triple>-install_only.tar.gz`.
+     */
+    readonly assetName: string;
+    /**
+     * Absolute download URL for the asset (with `+` percent-encoded as `%2B`).
+     */
+    readonly url: string;
+}
+/**
+ * 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.
+ */
+export declare function pythonAsset(options: PythonAssetOptions): PythonAsset | undefined;

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

@@ -0,0 +1,111 @@
+"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(options) {
+	options = {
+		__proto__: null,
+		...options
+	};
+	const { tag, version } = {
+		__proto__: null,
+		...options
+	};
+	const arch = options.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(options: 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(options: DlxPipPinOptions): Promise<PipPackagePin & {
+    pythonBin: string;
+}>;
+export declare function resolveOrThrow(options: DlxPipOptions): Promise<string>;

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

@@ -0,0 +1,98 @@
+"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(options) {
+	options = {
+		__proto__: null,
+		...options
+	};
+	const pythonBin = await resolveOrThrow(options);
+	return {
+		...await require_external_tools_python_pip_install.downloadPipPackage({
+			hash: options.hash,
+			pythonBin,
+			spec: options.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(options) {
+	options = {
+		__proto__: null,
+		...options
+	};
+	const pythonBin = await resolveOrThrow(options);
+	return {
+		...await require_external_tools_python_pin.resolvePipPackagePin({
+			pythonBin,
+			spec: options.spec
+		}),
+		pythonBin
+	};
+}
+async function resolveOrThrow(options) {
+	const { preferDownload, python } = {
+		__proto__: null,
+		...options
+	};
+	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(options: PythonFromDownloadOptions): Promise<ResolvedPython | undefined>;