pyfig 0.3.1 → 0.5.0

package/dist/cjs/index.js

@@ -66,19 +66,12 @@ var __export = (target, all) => {
 var exports_src = {};
 __export(exports_src, {
   DEFAULT_MANAGED_PYTHON: () => DEFAULT_MANAGED_PYTHON,
-  DEFAULT_PIP_RANGE: () => DEFAULT_PIP_RANGE,
-  DEFAULT_PYTHON_RANGE: () => DEFAULT_PYTHON_RANGE,
+  DEFAULT_REQUIRES_PYTHON: () => DEFAULT_REQUIRES_PYTHON,
   DEFAULT_UV_RANGE: () => DEFAULT_UV_RANGE,
   DEFAULT_UV_VERSION: () => DEFAULT_UV_VERSION,
-  clearPyfigCaches: () => clearPyfigCaches,
   createPyfig: () => createPyfig,
   ensureEnvironment: () => ensureEnvironment,
   ensureUv: () => ensureUv,
-  ensureVirtualEnvironment: () => ensureVirtualEnvironment,
-  pipSpawn: () => pipSpawn,
-  pipSpawnSync: () => pipSpawnSync,
-  pythonSpawn: () => pythonSpawn,
-  pythonSpawnSync: () => pythonSpawnSync,
   resolveProjectRoot: () => resolveProjectRoot,
   uvSpawn: () => uvSpawn,
   uvSpawnSync: () => uvSpawnSync
@@ -86,7 +79,6 @@ __export(exports_src, {
 module.exports = __toCommonJS(exports_src);
 
 // src/config.ts
-var import_node_crypto = require("node:crypto");
 var import_node_path2 = __toESM(require("node:path"), 1);
 var envPaths = __toESM(require("env-paths"), 1);
 var import_semver = __toESM(require("semver"), 1);
@@ -94,69 +86,13 @@ var import_semver = __toESM(require("semver"), 1);
 // src/project-root.ts
 var import_node_fs = __toESM(require("node:fs"), 1);
 var import_node_path = __toESM(require("node:path"), 1);
-var import_pacwich = require("pacwich");
-var PACKAGE_MANAGER_LOCKFILES = [
-  "bun.lock",
-  "bun.lockb",
-  "npm-shrinkwrap.json",
-  "package-lock.json",
-  "pnpm-lock.yaml",
-  "yarn.lock"
-];
-var PYTHON_PROJECT_MARKERS = [
-  "pyproject.toml",
-  "uv.lock"
-];
 function resolveProjectRoot(startDirectory = process.cwd()) {
   const start = import_node_path.default.resolve(startDirectory);
-  const workspaceRoot = findWorkspaceProjectRoot(start);
-  if (workspaceRoot) {
-    try {
-      return import_node_path.default.resolve(import_pacwich.createFileSystemProject({
-        rootDirectory: start,
-        disableExecutableConfigs: true
-      }).rootDirectory);
-    } catch {
-      return workspaceRoot;
-    }
-  }
-  return findConventionalProjectRoot(start);
-}
-function findWorkspaceProjectRoot(startDirectory) {
-  for (const directory of ancestors(startDirectory)) {
-    const packageJson = import_node_path.default.join(directory, "package.json");
-    if (!import_node_fs.default.existsSync(packageJson))
-      continue;
-    if (import_node_fs.default.existsSync(import_node_path.default.join(directory, "pnpm-workspace.yaml")))
-      return directory;
-    try {
-      const manifest = JSON.parse(import_node_fs.default.readFileSync(packageJson, "utf8"));
-      if (hasWorkspaceDeclaration(manifest.workspaces))
-        return directory;
-    } catch {}
-  }
-  return null;
-}
-function findConventionalProjectRoot(startDirectory) {
-  let nearestPackageDirectory = null;
-  let nearestPythonDirectory = null;
-  for (const directory of ancestors(startDirectory)) {
-    const hasPackage = import_node_fs.default.existsSync(import_node_path.default.join(directory, "package.json"));
-    if (hasPackage && !nearestPackageDirectory)
-      nearestPackageDirectory = directory;
-    if (!nearestPythonDirectory && PYTHON_PROJECT_MARKERS.some((file) => import_node_fs.default.existsSync(import_node_path.default.join(directory, file)))) {
-      nearestPythonDirectory = directory;
-    }
-    if (hasPackage && PACKAGE_MANAGER_LOCKFILES.some((file) => import_node_fs.default.existsSync(import_node_path.default.join(directory, file)))) {
-      return directory;
-    }
+  for (const directory of ancestors(start)) {
     if (import_node_fs.default.existsSync(import_node_path.default.join(directory, ".git")))
       return directory;
   }
-  return nearestPackageDirectory ?? nearestPythonDirectory ?? startDirectory;
-}
-function hasWorkspaceDeclaration(value) {
-  return Array.isArray(value) || value !== null && typeof value === "object";
+  return start;
 }
 function* ancestors(startDirectory) {
   let directory = startDirectory;
@@ -169,16 +105,26 @@ function* ancestors(startDirectory) {
   }
 }
 
+// src/python-version.ts
+var import_pep440 = require("@renovatebot/pep440");
+function isValidPythonSpecifier(specifier) {
+  return import_pep440.validRange(specifier);
+}
+function isValidPythonVersion(version) {
+  return import_pep440.valid(version) !== null;
+}
+function pythonVersionSatisfies(version, specifier) {
+  return import_pep440.filter([version], specifier).length === 1;
+}
+
 // src/config.ts
-var DEFAULT_PYTHON_RANGE = ">=3.10.0 <4.0.0";
-var DEFAULT_PIP_RANGE = ">=20.3.0";
+var DEFAULT_REQUIRES_PYTHON = ">=3.10,<4";
 var DEFAULT_MANAGED_PYTHON = "3.12";
 var DEFAULT_UV_VERSION = "0.13.6";
-var DEFAULT_UV_RANGE = `>=${DEFAULT_UV_VERSION} <1.0.0`;
+var DEFAULT_UV_RANGE = ">=0.10.0 <1.0.0";
 var DEFAULT_PROBE_TIMEOUT_MS = 1e4;
 var DEFAULT_INSTALL_TIMEOUT_MS = 10 * 60000;
 var DEFAULT_DOWNLOAD_TIMEOUT_MS = 5 * 60000;
-var DEFAULT_CACHE_TTL_MS = 30000;
 var envPathsFunction = (() => {
   const imported = envPaths.default;
   const implementation = typeof imported === "function" ? imported : imported.default;
@@ -188,30 +134,26 @@ var envPathsFunction = (() => {
 })();
 function resolveOptions(options = {}) {
   const env = { ...options.env ?? process.env };
-  const pythonRange = options.pythonRange ?? env["PYFIG_PYTHON_RANGE"] ?? DEFAULT_PYTHON_RANGE;
-  const pipRange = options.pipRange ?? env["PYFIG_PIP_RANGE"] ?? DEFAULT_PIP_RANGE;
+  const requiresPython = options.requiresPython ?? env["PYFIG_REQUIRES_PYTHON"] ?? DEFAULT_REQUIRES_PYTHON;
   const uvRange = options.uvRange ?? env["PYFIG_UV_RANGE"] ?? DEFAULT_UV_RANGE;
-  assertRange("Python", pythonRange);
-  assertRange("pip", pipRange);
+  assertPythonSpecifier(requiresPython);
   assertRange("uv", uvRange);
   const managedPython = options.managedPython ?? env["PYFIG_MANAGED_PYTHON"] ?? DEFAULT_MANAGED_PYTHON;
   const uvVersion = options.uvVersion ?? env["PYFIG_UV_VERSION"] ?? DEFAULT_UV_VERSION;
-  assertManagedPythonRequest(managedPython, pythonRange);
+  assertManagedPythonRequest(managedPython, requiresPython);
   assertUvVersion(uvVersion, uvRange);
   const probeTimeoutMs = resolveDuration("probeTimeoutMs", options.probeTimeoutMs, env["PYFIG_PROBE_TIMEOUT_MS"], DEFAULT_PROBE_TIMEOUT_MS);
   const installTimeoutMs = resolveDuration("installTimeoutMs", options.installTimeoutMs, env["PYFIG_INSTALL_TIMEOUT_MS"], DEFAULT_INSTALL_TIMEOUT_MS);
   const downloadTimeoutMs = resolveDuration("downloadTimeoutMs", options.downloadTimeoutMs, env["PYFIG_DOWNLOAD_TIMEOUT_MS"], DEFAULT_DOWNLOAD_TIMEOUT_MS);
   const coordinationTimeoutMs = resolveDuration("coordinationTimeoutMs", options.coordinationTimeoutMs, env["PYFIG_COORDINATION_TIMEOUT_MS"], installTimeoutMs + downloadTimeoutMs + 60000);
-  const cacheTtlMs = resolveDuration("cacheTtlMs", options.cacheTtlMs, env["PYFIG_CACHE_TTL_MS"], DEFAULT_CACHE_TTL_MS, true);
   const configuredHome = options.cacheDir ?? env["PYFIG_HOME"];
   const cacheDir = configuredHome ? import_node_path2.default.resolve(configuredHome) : envPathsFunction("pyfig", { suffix: "" }).cache;
   const configuredProjectRoot = options.projectRoot ?? env["PYFIG_PROJECT_ROOT"];
-  const projectRoot = configuredProjectRoot ? import_node_path2.default.resolve(configuredProjectRoot) : resolveProjectRoot();
+  const projectRoot = configuredProjectRoot ? import_node_path2.default.resolve(configuredProjectRoot) : resolveProjectRoot(env["INIT_CWD"] ?? process.cwd());
   const autoInstall = options.autoInstall ?? parseBoolean(env["PYFIG_AUTO_INSTALL"], true);
   return {
     python: options.python ?? env["PYFIG_PYTHON"] ?? "",
-    pythonRange,
-    pipRange,
+    requiresPython,
     managedPython,
     uvVersion,
     uvRange,
@@ -227,40 +169,16 @@ function resolveOptions(options = {}) {
     installTimeoutMs,
     downloadTimeoutMs,
     coordinationTimeoutMs,
-    cacheTtlMs,
     env
   };
 }
-function configurationFingerprint(options) {
-  const policy = [
-    normalizedPath(options.projectRoot),
-    normalizedPath(options.cacheDir),
-    options.python,
-    options.pythonRange,
-    options.pipRange,
-    options.managedPython,
-    options.uvVersion,
-    options.uvRange,
-    options.requireEmbedding,
-    options.requireGil,
-    options.autoInstall,
-    options.installPython,
-    options.installUv,
-    options.createVirtualEnvironment,
-    options.probeTimeoutMs,
-    options.installTimeoutMs,
-    options.downloadTimeoutMs,
-    options.coordinationTimeoutMs,
-    options.cacheTtlMs,
-    environmentFingerprint(options.env)
-  ];
-  return import_node_crypto.createHash("sha256").update(JSON.stringify(policy)).digest("hex");
-}
 function uvEnvironment(options) {
   return {
     ...options.env,
     UV_PYTHON_INSTALL_DIR: import_node_path2.default.join(options.cacheDir, "python"),
-    UV_CACHE_DIR: import_node_path2.default.join(options.cacheDir, "uv-cache")
+    UV_CACHE_DIR: import_node_path2.default.join(options.cacheDir, "uv-cache"),
+    UV_PYTHON_PREFERENCE: "system",
+    UV_NO_CONFIG: "1"
   };
 }
 function assertRange(tool, range) {
@@ -276,14 +194,19 @@ function assertUvVersion(version, range) {
     throw new TypeError(`Pinned uv ${version} does not satisfy supported range ${range}.`);
   }
 }
-function assertManagedPythonRequest(request, pythonRange) {
+function assertPythonSpecifier(specifier) {
+  if (!isValidPythonSpecifier(specifier)) {
+    throw new TypeError(`Invalid requires-python PEP 440 specifier: ${specifier}`);
+  }
+}
+function assertManagedPythonRequest(request, requiresPython) {
   if (!request || /[\\/\0\r\n]/u.test(request) || request.includes("..")) {
     throw new TypeError(`Invalid managed Python request: ${request}`);
   }
   if (/^\d+\.\d+(?:\.\d+)?$/u.test(request)) {
     const normalized = request.split(".").length === 2 ? `${request}.0` : request;
-    if (!import_semver.default.satisfies(normalized, pythonRange)) {
-      throw new TypeError(`Managed Python ${request} cannot satisfy configured range ${pythonRange}.`);
+    if (!pythonVersionSatisfies(normalized, requiresPython)) {
+      throw new TypeError(`Managed Python ${request} cannot satisfy requires-python ${requiresPython}.`);
     }
   }
 }
@@ -304,46 +227,176 @@ function parseBoolean(value, fallback) {
     return false;
   throw new TypeError(`Invalid boolean value: ${value}`);
 }
-function environmentFingerprint(env) {
-  const entries = Object.entries(env).filter((entry) => entry[1] !== undefined).map(([key, value]) => [
-    process.platform === "win32" ? key.toUpperCase() : key,
-    value
-  ]).sort(([left], [right]) => left.localeCompare(right));
-  return import_node_crypto.createHash("sha256").update(JSON.stringify(entries)).digest("hex");
-}
-function normalizedPath(value) {
-  const resolved = import_node_path2.default.resolve(value);
-  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
-}
+// src/client.ts
+var import_loqkit2 = require("loqkit");
+
 // src/provision.ts
-var import_node_crypto3 = require("node:crypto");
+var import_node_crypto = require("node:crypto");
 var import_node_fs3 = require("node:fs");
-var import_promises2 = require("node:fs/promises");
+var import_promises = require("node:fs/promises");
 var import_node_fs4 = __toESM(require("node:fs"), 1);
 var import_node_os = __toESM(require("node:os"), 1);
-var import_node_path7 = __toESM(require("node:path"), 1);
+var import_node_path5 = __toESM(require("node:path"), 1);
 var import_node_stream = require("node:stream");
-var import_promises3 = require("node:stream/promises");
-var import_extract_zip = __toESM(require("extract-zip"), 1);
+var import_promises2 = require("node:stream/promises");
+var import_fflate = require("fflate");
 var tar = __toESM(require("tar"), 1);
 var import_undici = require("undici");
 
-// src/coordination.ts
-var import_node_crypto2 = require("node:crypto");
-var import_node_child_process2 = require("node:child_process");
-var import_promises = require("node:fs/promises");
-var import_node_path4 = __toESM(require("node:path"), 1);
-var workerThreads = __toESM(require("node:worker_threads"), 1);
-var import_proper_lockfile = __toESM(require("proper-lockfile"), 1);
+// src/provision-lock.ts
+var import_loqkit = require("loqkit");
+async function withProvisioningLock(options) {
+  let existing;
+  const result = await import_loqkit.withLock({ resource: options.key }, options.mutate, {
+    key: options.key,
+    name: "Pyfig provisioning",
+    namespace: "pyfig",
+    timeout: options.timeoutMs,
+    predicate: async () => {
+      const value = await options.check();
+      if (value === null)
+        return true;
+      existing = { value };
+      return false;
+    }
+  });
+  if (result.context.state === "executed")
+    return result.value;
+  if (existing)
+    return existing.value;
+  throw new Error(`Provisioning check for ${options.key} did not produce a resource.`);
+}
+
+// src/virtual-environment.ts
+var import_node_fs2 = __toESM(require("node:fs"), 1);
+var import_node_path3 = __toESM(require("node:path"), 1);
+var VIRTUAL_ENV_DIRECTORY_NAME = import_node_path3.default.join("node_modules", ".pyfig", "venv");
+function virtualEnvironmentDirectory(projectRoot) {
+  return import_node_path3.default.join(projectRoot, VIRTUAL_ENV_DIRECTORY_NAME);
+}
+function externalVirtualEnvironmentDirectories(projectRoot, env) {
+  const candidates = [env["VIRTUAL_ENV"], import_node_path3.default.join(projectRoot, ".venv")].filter((value) => Boolean(value)).map((value) => import_node_path3.default.resolve(value));
+  return [...new Map(candidates.map((value) => [canonicalPath(value), value])).values()];
+}
+function virtualEnvironmentPythonExecutable(virtualEnvironment) {
+  return import_node_path3.default.join(virtualEnvironment, process.platform === "win32" ? "Scripts" : "bin", process.platform === "win32" ? "python.exe" : "python");
+}
+function activateVirtualEnvironment(env, virtualEnvironment, pythonExecutable) {
+  const activated = { ...env };
+  const pathEntry = Object.keys(activated).find((key) => key.toUpperCase() === "PATH");
+  const existingPath = pathEntry ? activated[pathEntry] : undefined;
+  for (const key of Object.keys(activated)) {
+    const normalized = key.toUpperCase();
+    if (normalized === "PATH" || normalized === "PYTHONHOME" || normalized === "VIRTUAL_ENV") {
+      delete activated[key];
+    }
+  }
+  activated["PATH"] = [import_node_path3.default.dirname(pythonExecutable), existingPath].filter((value) => Boolean(value)).join(import_node_path3.default.delimiter);
+  activated["VIRTUAL_ENV"] = virtualEnvironment;
+  return activated;
+}
+function pathsEqual(left, right) {
+  return canonicalPath(left) === canonicalPath(right);
+}
+function canonicalPath(value) {
+  const resolved = import_node_path3.default.resolve(value);
+  let canonical = resolved;
+  try {
+    canonical = import_node_fs2.default.realpathSync.native(resolved);
+  } catch {}
+  return process.platform === "win32" ? canonical.toLowerCase() : canonical;
+}
+
+// src/package-target.ts
+var TARGET_OPTIONS = new Set([
+  "--active",
+  "--config-file",
+  "--directory",
+  "--isolated",
+  "--prefix",
+  "--project",
+  "--python",
+  "--root",
+  "--system",
+  "--target",
+  "--user"
+]);
+var TARGET_ENVIRONMENT_VARIABLES = new Set([
+  "CONDA_PREFIX",
+  "PIP_PREFIX",
+  "PIP_PYTHON",
+  "PIP_ROOT",
+  "PIP_TARGET",
+  "PIP_USER",
+  "PYTHONHOME",
+  "PYTHONUSERBASE",
+  "UV_CONFIG_FILE",
+  "UV_PROJECT",
+  "UV_PROJECT_ENVIRONMENT",
+  "UV_PYTHON",
+  "UV_PREFIX",
+  "UV_ROOT",
+  "UV_SYSTEM_PYTHON",
+  "UV_TARGET"
+]);
+function uvCommandNeedsEnvironment(args) {
+  return args[0] === "pip" || args[0] === "run";
+}
+function targetUvArguments(args, python) {
+  if (!python.virtualEnvironment) {
+    throw new Error("Targeted uv commands require a virtual environment.");
+  }
+  assertNoTargetOverride(args);
+  if (args[0] === "run") {
+    return ["run", "--no-project", "--python", python.executable, ...args.slice(1)];
+  }
+  if (args[0] === "pip" && args[1]) {
+    return ["pip", args[1], "--python", python.executable, ...args.slice(2)];
+  }
+  return [...args];
+}
+function uvCommandEnvironment(env, python) {
+  const sanitized = sanitizeUvEnvironment(env);
+  if (!python?.virtualEnvironment)
+    return sanitized;
+  return {
+    ...activateVirtualEnvironment(sanitized, python.virtualEnvironment, python.executable),
+    UV_PYTHON: python.executable
+  };
+}
+function sanitizeUvEnvironment(env) {
+  const sanitized = { ...env };
+  for (const key of Object.keys(sanitized)) {
+    if (TARGET_ENVIRONMENT_VARIABLES.has(key.toUpperCase()))
+      delete sanitized[key];
+  }
+  return sanitized;
+}
+function assertNoTargetOverride(args) {
+  for (const argument of args.slice(1)) {
+    if (argument === "--")
+      return;
+    const [name] = argument.split("=", 1);
+    if (name && TARGET_OPTIONS.has(name)) {
+      throw new Error(`${name} cannot override the environment selected by Pyfig.`);
+    }
+    if (argument === "-p" || argument.startsWith("-p=") || /^-p[^-]/u.test(argument)) {
+      throw new Error("-p cannot override the environment selected by Pyfig.");
+    }
+  }
+}
+
+// src/probes.ts
+var import_semver2 = __toESM(require("semver"), 1);
 
 // src/process.ts
 var import_node_child_process = require("node:child_process");
-var import_node_path3 = __toESM(require("node:path"), 1);
+var import_node_path4 = __toESM(require("node:path"), 1);
 var import_which = __toESM(require("which"), 1);
 async function resolveExecutable(value, env) {
   if (!value)
     return null;
-  if (import_node_path3.default.isAbsolute(value)) {
+  if (import_node_path4.default.isAbsolute(value)) {
     return await import_which.default(value, { nothrow: true, path: env["PATH"], pathExt: env["PATHEXT"] });
   }
   if (!/^[A-Za-z0-9_.-]+$/u.test(value))
@@ -360,14 +413,15 @@ function run(executable, args, env, timeoutMs) {
   });
   if (result.status !== 0 || result.error) {
     const detail = result.stderr?.trim() || result.error?.message || `exit ${result.status}`;
-    throw new Error(`${import_node_path3.default.basename(executable)} ${args.slice(0, 3).join(" ")} failed: ${detail}`);
+    throw new Error(`${import_node_path4.default.basename(executable)} ${args.slice(0, 3).join(" ")} failed: ${detail}`);
   }
   return { stdout: result.stdout, stderr: result.stderr };
 }
-async function runAsync(executable, args, env, timeoutMs, signal) {
+async function runAsync(executable, args, env, timeoutMs, signal, cwd) {
   return new Promise((resolve, reject) => {
     const child = import_node_child_process.spawn(executable, args, {
       env,
+      cwd,
       stdio: ["ignore", "pipe", "pipe"],
       windowsHide: true
     });
@@ -388,11 +442,11 @@ async function runAsync(executable, args, env, timeoutMs, signal) {
     const abort = () => {
       child.kill();
       const reason = signal?.reason;
-      finish(reason instanceof Error ? reason : new Error(`${import_node_path3.default.basename(executable)} was aborted.`));
+      finish(reason instanceof Error ? reason : new Error(`${import_node_path4.default.basename(executable)} was aborted.`));
     };
     const timer = setTimeout(() => {
       child.kill();
-      finish(new Error(`${import_node_path3.default.basename(executable)} timed out after ${timeoutMs}ms.`));
+      finish(new Error(`${import_node_path4.default.basename(executable)} timed out after ${timeoutMs}ms.`));
     }, timeoutMs);
     child.stdout.setEncoding("utf8");
     child.stderr.setEncoding("utf8");
@@ -400,21 +454,21 @@ async function runAsync(executable, args, env, timeoutMs, signal) {
       stdout += chunk;
       if (stdout.length > 4 * 1024 * 1024) {
         child.kill();
-        finish(new Error(`${import_node_path3.default.basename(executable)} exceeded the output limit.`));
+        finish(new Error(`${import_node_path4.default.basename(executable)} exceeded the output limit.`));
       }
     });
     child.stderr.on("data", (chunk) => {
       stderr += chunk;
       if (stderr.length > 4 * 1024 * 1024) {
         child.kill();
-        finish(new Error(`${import_node_path3.default.basename(executable)} exceeded the error-output limit.`));
+        finish(new Error(`${import_node_path4.default.basename(executable)} exceeded the error-output limit.`));
       }
     });
     child.once("error", (error) => finish(error));
     child.once("close", (code, childSignal) => {
       if (code !== 0) {
         const detail = stderr.trim() || (childSignal ? `signal ${childSignal}` : `exit ${code}`);
-        finish(new Error(`${import_node_path3.default.basename(executable)} ${args.slice(0, 3).join(" ")} failed: ${detail}`));
+        finish(new Error(`${import_node_path4.default.basename(executable)} ${args.slice(0, 3).join(" ")} failed: ${detail}`));
         return;
       }
       finish(undefined, { stdout, stderr });
@@ -426,213 +480,6 @@ async function runAsync(executable, args, env, timeoutMs, signal) {
   });
 }
 
-// src/coordination.ts
-var realmMutexTails = new Map;
-var flockLookups = new Map;
-var FLOCK_READY = "PYFIG_FLOCK_READY";
-var FLOCK_HOLDER = [
-  `process.stdout.write('${FLOCK_READY}\\n')`,
-  "process.stdin.resume()",
-  'process.stdin.once("end",()=>process.exit(0))'
-].join(";");
-async function withProvisioningLock(options) {
-  const existing = await options.check();
-  if (existing !== null)
-    return existing;
-  return withResourceLock(options, async (signal) => {
-    const rechecked = await options.check();
-    return rechecked ?? options.mutate(signal);
-  });
-}
-async function withResourceLock(options, operation) {
-  await import_promises.mkdir(options.target, { recursive: true });
-  return withRealmMutex(options.key, () => withWorkerLock(options, () => withNativeFlock(options, () => withPortableLease(options, operation))));
-}
-async function withRealmMutex(key, operation) {
-  const previous = realmMutexTails.get(key) ?? Promise.resolve();
-  let releaseGate;
-  const gate = new Promise((resolve) => {
-    releaseGate = resolve;
-  });
-  const tail = previous.catch(() => {
-    return;
-  }).then(() => gate);
-  realmMutexTails.set(key, tail);
-  await previous.catch(() => {
-    return;
-  });
-  try {
-    return await operation();
-  } finally {
-    releaseGate();
-    if (realmMutexTails.get(key) === tail)
-      realmMutexTails.delete(key);
-  }
-}
-async function withWorkerLock(options, operation) {
-  const manager = workerThreads.locks;
-  if (!manager?.request)
-    return operation();
-  const controller = new AbortController;
-  const timeout = setTimeout(() => controller.abort(new Error(`Timed out waiting for worker lock ${options.key}.`)), options.timeoutMs);
-  let entered = false;
-  try {
-    return await manager.request(workerLockName(options.key), { mode: "exclusive", signal: controller.signal }, async () => {
-      entered = true;
-      return operation();
-    });
-  } catch (error) {
-    if (entered)
-      throw error;
-    return operation();
-  } finally {
-    clearTimeout(timeout);
-  }
-}
-async function withNativeFlock(options, operation) {
-  if (process.platform === "win32")
-    return operation();
-  const executable = await findFlock(process.env);
-  if (!executable)
-    return operation();
-  const child = await acquireFlock(executable, `${options.target}.flock`, options.timeoutMs);
-  if (!child)
-    return operation();
-  try {
-    return await operation();
-  } finally {
-    await releaseFlock(child);
-  }
-}
-async function findFlock(env) {
-  const lookupKey = `${env["PATH"] ?? ""}\x00${env["PATHEXT"] ?? ""}`;
-  let lookup = flockLookups.get(lookupKey);
-  if (!lookup) {
-    lookup = resolveExecutable("flock", env);
-    flockLookups.set(lookupKey, lookup);
-  }
-  return lookup;
-}
-async function acquireFlock(executable, lockPath, timeoutMs) {
-  const waitSeconds = Math.max(1, Math.ceil(Math.min(timeoutMs, 30000) / 1000));
-  const child = import_node_child_process2.spawn(executable, ["-x", "-w", String(waitSeconds), lockPath, process.execPath, "-e", FLOCK_HOLDER], { stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
-  child.stderr.resume();
-  let output = "";
-  const acquired = await new Promise((resolve) => {
-    let settled = false;
-    const finish = (value) => {
-      if (settled)
-        return;
-      settled = true;
-      clearTimeout(timer);
-      resolve(value);
-    };
-    const timer = setTimeout(() => finish(false), Math.min(timeoutMs, 30000) + 5000);
-    child.once("error", () => finish(false));
-    child.once("exit", () => finish(false));
-    child.stdout.setEncoding("utf8");
-    child.stdout.on("data", (chunk) => {
-      output += chunk;
-      if (output.includes(FLOCK_READY))
-        finish(true);
-    });
-  });
-  if (acquired)
-    return child;
-  child.kill();
-  return null;
-}
-async function releaseFlock(child) {
-  if (child.exitCode !== null)
-    return;
-  child.stdin.end();
-  await new Promise((resolve) => {
-    const timer = setTimeout(() => {
-      child.kill();
-      resolve();
-    }, 5000);
-    child.once("exit", () => {
-      clearTimeout(timer);
-      resolve();
-    });
-  });
-}
-async function withPortableLease(options, operation) {
-  const controller = new AbortController;
-  let compromised = null;
-  const retryIntervalMs = 500;
-  const release = await import_proper_lockfile.default.lock(options.target, {
-    realpath: true,
-    stale: 120000,
-    update: 15000,
-    retries: {
-      retries: Math.ceil(options.timeoutMs / retryIntervalMs),
-      factor: 1,
-      minTimeout: retryIntervalMs,
-      maxTimeout: retryIntervalMs
-    },
-    onCompromised: (error) => {
-      compromised = error;
-      controller.abort(error);
-    }
-  });
-  try {
-    const result = await operation(controller.signal);
-    if (compromised)
-      throw compromised;
-    return result;
-  } finally {
-    controller.abort();
-    await release();
-  }
-}
-function workerLockName(key) {
-  return `pyfig:${import_node_crypto2.createHash("sha256").update(key).digest("hex")}`;
-}
-function cacheLockTarget(cacheDirectory, name) {
-  return import_node_path4.default.join(cacheDirectory, "locks", name);
-}
-
-// src/probes.ts
-var import_node_path6 = __toESM(require("node:path"), 1);
-var import_semver2 = __toESM(require("semver"), 1);
-
-// src/virtual-environment.ts
-var import_node_fs2 = __toESM(require("node:fs"), 1);
-var import_node_path5 = __toESM(require("node:path"), 1);
-var VIRTUAL_ENV_DIRECTORY_NAME = ".venv";
-function virtualEnvironmentDirectory(projectRoot) {
-  return import_node_path5.default.join(projectRoot, VIRTUAL_ENV_DIRECTORY_NAME);
-}
-function virtualEnvironmentPythonExecutable(virtualEnvironment) {
-  return import_node_path5.default.join(virtualEnvironment, process.platform === "win32" ? "Scripts" : "bin", process.platform === "win32" ? "python.exe" : "python");
-}
-function activateVirtualEnvironment(env, virtualEnvironment, pythonExecutable) {
-  const activated = { ...env };
-  const pathEntry = Object.keys(activated).find((key) => key.toUpperCase() === "PATH");
-  const existingPath = pathEntry ? activated[pathEntry] : undefined;
-  for (const key of Object.keys(activated)) {
-    const normalized = key.toUpperCase();
-    if (normalized === "PATH" || normalized === "PYTHONHOME" || normalized === "VIRTUAL_ENV") {
-      delete activated[key];
-    }
-  }
-  activated["PATH"] = [import_node_path5.default.dirname(pythonExecutable), existingPath].filter((value) => Boolean(value)).join(import_node_path5.default.delimiter);
-  activated["VIRTUAL_ENV"] = virtualEnvironment;
-  return activated;
-}
-function pathsEqual(left, right) {
-  return canonicalPath(left) === canonicalPath(right);
-}
-function canonicalPath(value) {
-  const resolved = import_node_path5.default.resolve(value);
-  let canonical = resolved;
-  try {
-    canonical = import_node_fs2.default.realpathSync.native(resolved);
-  } catch {}
-  return process.platform === "win32" ? canonical.toLowerCase() : canonical;
-}
-
 // src/probes.ts
 var PYTHON_PROBE = `
 import json
@@ -682,7 +529,15 @@ if os.path.isfile(header_path) and library_path:
     }
 
 release_level = sys.version_info.releaselevel
-release_suffix = "" if release_level == "final" else f"-{release_level}.{sys.version_info.serial}"
+release_suffixes = {
+    "alpha": "a",
+    "beta": "b",
+    "candidate": "rc",
+    "final": "",
+}
+release_suffix = release_suffixes[release_level]
+if release_suffix:
+    release_suffix += str(sys.version_info.serial)
 
 print(json.dumps({
     "executable": sys.executable,
@@ -702,24 +557,8 @@ print(json.dumps({
     "embedding": embedding,
 }))
 `;
-async function findPython(options) {
-  const candidates = [];
-  if (options.python)
-    candidates.push({ executable: options.python, args: [] });
-  if (process.platform === "win32") {
-    candidates.push({ executable: "python", args: [] }, { executable: "python3", args: [] }, { executable: "py", args: ["-3"] });
-  } else {
-    candidates.push(...["python3.15", "python3.14", "python3.13", "python3.12", "python3.11", "python3.10"].map((executable) => ({ executable, args: [] })), { executable: "python3", args: [] }, { executable: "python", args: [] });
-  }
-  for (const candidate of candidates) {
-    const info = await probePython(candidate, options);
-    if (info && pythonSatisfiesRequirements(info, options))
-      return info;
-  }
-  return null;
-}
-function pythonSatisfiesRequirements(python, options) {
-  return import_semver2.default.satisfies(python.version, options.pythonRange) && (!options.requireEmbedding || python.implementation === "cpython" && python.embedding !== null && pythonArchitectureMatchesRuntime(python)) && (!options.requireGil || !python.gilDisabled);
+function pythonSatisfiesPolicy(python, options) {
+  return pythonVersionSatisfies(python.version, options.requiresPython) && (!options.requireEmbedding || python.implementation === "cpython" && python.embedding !== null && pythonArchitectureMatchesRuntime(python)) && (!options.requireGil || !python.gilDisabled);
 }
 async function probePython(candidate, options) {
   const executable = await resolveExecutable(candidate.executable, options.env);
@@ -728,55 +567,11 @@ async function probePython(candidate, options) {
   try {
     const { stdout } = run(executable, [...candidate.args, "-c", PYTHON_PROBE], options.env, options.probeTimeoutMs);
     const info = JSON.parse(stdout.trim());
-    return import_semver2.default.valid(info.version) ? info : null;
+    return isValidPythonVersion(info.version) ? info : null;
   } catch {
     return null;
   }
 }
-async function findPip(python, options) {
-  if (!python.virtualEnvironment) {
-    throw new Error("pip discovery requires a virtual-environment Python interpreter.");
-  }
-  const activeEnv = activateVirtualEnvironment(options.env, python.virtualEnvironment, python.executable);
-  try {
-    const { stdout } = run(python.executable, ["-m", "pip", "--version"], activeEnv, options.probeTimeoutMs);
-    const details = parsePipVersionOutput(stdout);
-    const version = normalizeVersion(details?.version);
-    if (!version || !import_semver2.default.satisfies(version, options.pipRange))
-      return null;
-    if (!details || !pipBelongsToPython(details, python))
-      return null;
-    return {
-      kind: "pip",
-      executable: python.executable,
-      prefixArgs: ["-m", "pip"],
-      version,
-      pythonExecutable: python.executable,
-      virtualEnvironment: python.virtualEnvironment
-    };
-  } catch {
-    return null;
-  }
-}
-function parsePipVersionOutput(output) {
-  const match = output.trim().match(/^pip\s+(\S+)\s+from\s+(.+?)\s+\(python\s+(\d+)\.(\d+)(?:\.\d+)?\)$/iu);
-  if (!match?.[1] || !match[2] || !match[3] || !match[4])
-    return null;
-  return {
-    version: match[1],
-    location: match[2],
-    pythonMajor: Number.parseInt(match[3], 10),
-    pythonMinor: Number.parseInt(match[4], 10)
-  };
-}
-function pipBelongsToPython(pip, python) {
-  if (pip.pythonMajor !== python.major || pip.pythonMinor !== python.minor)
-    return false;
-  const prefix = normalizePathForComparison(import_node_path6.default.resolve(python.prefix));
-  const location = normalizePathForComparison(import_node_path6.default.resolve(pip.location));
-  const relative = import_node_path6.default.relative(prefix, location);
-  return relative === "" || relative !== ".." && !relative.startsWith(`..${import_node_path6.default.sep}`) && !import_node_path6.default.isAbsolute(relative);
-}
 async function findUv(options) {
   const configured = options.env["PYFIG_UV"] ?? "uv";
   const executable = await resolveExecutable(configured, options.env);
@@ -797,9 +592,6 @@ function normalizeVersion(value) {
     return null;
   return import_semver2.default.valid(value) ?? import_semver2.default.coerce(value)?.version ?? null;
 }
-function normalizePathForComparison(value) {
-  return process.platform === "win32" ? value.toLowerCase() : value;
-}
 function pythonArchitectureMatchesRuntime(python) {
   const architecture = python.architecture.toLowerCase();
   if (python.pointerBits !== (process.arch === "ia32" ? 32 : 64))
@@ -814,228 +606,223 @@ function pythonArchitectureMatchesRuntime(python) {
   return architecture === process.arch;
 }
 
-// src/state.ts
-var completed = new Map;
-var inFlight = new Map;
-var cacheGeneration = 0;
-async function memoizeAsync(namespace, key, ttlMs, validate, load) {
-  const cacheKey = `${namespace}\x00${key}`;
-  const cached = completed.get(cacheKey);
-  if (cached && cached.expiresAt >= Date.now()) {
-    try {
-      if (await validate(cached.value))
-        return cached.value;
-    } catch {}
-    completed.delete(cacheKey);
-  }
-  const pending = inFlight.get(cacheKey);
-  if (pending)
-    return pending;
-  const generation = cacheGeneration;
-  const loading = load().then((value) => {
-    if (ttlMs > 0 && generation === cacheGeneration) {
-      completed.set(cacheKey, { expiresAt: Date.now() + ttlMs, value });
-    }
-    return value;
-  }).finally(() => {
-    if (inFlight.get(cacheKey) === loading)
-      inFlight.delete(cacheKey);
-  });
-  inFlight.set(cacheKey, loading);
-  return loading;
-}
-function memoizeSync(namespace, key, ttlMs, validate, load) {
-  const cacheKey = `${namespace}\x00${key}`;
-  const cached = completed.get(cacheKey);
-  if (cached && cached.expiresAt >= Date.now()) {
-    try {
-      if (validate(cached.value))
-        return cached.value;
-    } catch {}
-    completed.delete(cacheKey);
-  }
-  const value = load();
-  if (ttlMs > 0)
-    completed.set(cacheKey, { expiresAt: Date.now() + ttlMs, value });
-  return value;
-}
-function clearPyfigCaches() {
-  cacheGeneration += 1;
-  completed.clear();
-  inFlight.clear();
-}
-
 // src/provision.ts
-async function ensurePython(options = {}) {
-  const resolved = resolveOptions(options);
-  return memoizeAsync("python", configurationFingerprint(resolved), resolved.cacheTtlMs, pythonIsPresent, () => ensurePythonResolved(resolved));
-}
-async function ensureVirtualEnvironment(options = {}) {
-  const resolved = resolveOptions(options);
-  return memoizeAsync("venv", configurationFingerprint(resolved), resolved.cacheTtlMs, (python) => pythonIsPresent(python) && Boolean(python.virtualEnvironment) && pathsEqual(python.virtualEnvironment, virtualEnvironmentDirectory(resolved.projectRoot)), () => ensureVirtualEnvironmentResolved(resolved));
-}
 async function ensureUv(options = {}) {
-  const resolved = resolveOptions(options);
-  return memoizeAsync("uv", configurationFingerprint(resolved), resolved.cacheTtlMs, (uv) => import_node_fs4.default.existsSync(uv.executable), () => ensureUvResolved(resolved));
+  return ensureUvResolved(resolveOptions(options));
 }
-async function ensureEnvironment(options = {}) {
+async function ensureEnvironment(options = {}, dependencies = [], dependencyOptions = {}) {
   const resolved = resolveOptions(options);
-  return memoizeAsync("environment", configurationFingerprint(resolved), resolved.cacheTtlMs, environmentIsPresent, async () => {
-    const python = await ensureVirtualEnvironmentResolved(resolved);
-    const packageManager = await ensurePipResolved(python, resolved);
-    return { python, packageManager };
-  });
+  const normalized = normalizeDependencies(dependencies);
+  const selections = normalizeDependencyOptions(dependencyOptions);
+  const uv = await ensureUvResolved(resolved);
+  const python = await ensureVirtualEnvironmentResolved(resolved, uv);
+  if (normalized.length > 0 || selections.extras.length > 0 || selections.groups.length > 0 || selections.allExtras) {
+    await installRuntimeDependencies(uv, python, normalized, selections, resolved);
+  }
+  return {
+    python,
+    uv,
+    managed: isManagedEnvironment(python, resolved)
+  };
 }
-async function ensureVirtualEnvironmentResolved(options) {
+async function ensureVirtualEnvironmentResolved(options, uv) {
+  const existing = await findReusableEnvironment(options);
+  if (existing)
+    return existing;
   const directory = virtualEnvironmentDirectory(options.projectRoot);
   const check = async () => {
-    const existing = await inspectVirtualEnvironment(directory, options);
-    if (!existing)
-      return null;
-    if (pythonSatisfiesRequirements(existing, options) && await virtualEnvironmentMatchesConfiguredPython(existing, options)) {
-      return existing;
-    }
-    throw incompatibleVirtualEnvironmentError(directory, existing, options);
+    const candidate = await inspectVirtualEnvironment(directory, options);
+    return candidate && pythonSatisfiesPolicy(candidate, options) && await virtualEnvironmentMatchesConfiguredPython(candidate, options) ? candidate : null;
   };
-  const existing = await check();
-  if (existing)
-    return existing;
   if (!options.createVirtualEnvironment) {
-    throw new Error(`No virtual environment at ${directory} satisfies the Python requirements; ` + "virtual-environment creation is disabled.");
+    throw new Error(`No compatible environment is available and creation is disabled. ` + `Pyfig would create ${directory}.`);
   }
-  const basePython = await ensurePythonResolved(options);
-  const preferredUv = await findAvailableUv(options) ?? (options.installUv ? await ensureUvResolved(options) : null);
+  const basePython = await ensureBasePythonResolved(uv, options);
   return withProvisioningLock({
     key: `venv:${canonicalPath(directory)}`,
-    target: directory,
     timeoutMs: options.coordinationTimeoutMs,
-    env: options.env,
     check,
-    mutate: async (signal) => {
-      const entries = await import_promises2.readdir(directory);
-      const hasVenvConfiguration = import_node_fs4.default.existsSync(import_node_path7.default.join(directory, "pyvenv.cfg"));
-      if (entries.length > 0 && !hasVenvConfiguration) {
-        throw new Error(`Refusing to replace non-virtual-environment contents at ${directory}.`);
-      }
-      await createVirtualEnvironment(directory, basePython, preferredUv, options, signal);
-      const installed = await inspectVirtualEnvironment(directory, options);
-      if (!installed || !pythonSatisfiesRequirements(installed, options)) {
-        throw new Error(`Python created ${directory}, but it does not satisfy the requested runtime capabilities.`);
+    mutate: async () => {
+      await import_promises.rm(directory, { recursive: true, force: true });
+      await import_promises.mkdir(import_node_path5.default.dirname(directory), { recursive: true });
+      await runAsync(uv.executable, [
+        "venv",
+        "--no-project",
+        "--no-config",
+        "--no-python-downloads",
+        "--python",
+        basePython.executable,
+        directory
+      ], isolatedUvEnvironment(options), options.installTimeoutMs);
+      const installed = await check();
+      if (!installed) {
+        throw new Error(`uv created ${directory}, but its Python does not satisfy the requested capabilities.`);
       }
       return installed;
     }
   });
 }
-async function createVirtualEnvironment(directory, basePython, preferredUv, options, signal) {
-  if (preferredUv) {
-    try {
-      await createVirtualEnvironmentWithUv(preferredUv, directory, basePython, options, signal);
-      return;
-    } catch {}
+async function findReusableEnvironment(options) {
+  if (options.python) {
+    const configured = await probePython({ executable: options.python, args: [] }, options);
+    if (!configured || !pythonSatisfiesPolicy(configured, options)) {
+      throw incompatibleConfiguredPython(options);
+    }
+    if (configured.virtualEnvironment)
+      return configured;
   }
-  try {
-    await runAsync(basePython.executable, ["-m", "venv", directory], withoutActiveVirtualEnvironment(options.env), options.installTimeoutMs, signal);
-    return;
-  } catch (systemVenvError) {
-    if (preferredUv || !options.installUv)
-      throw systemVenvError;
+  for (const directory of [
+    ...externalVirtualEnvironmentDirectories(options.projectRoot, options.env),
+    virtualEnvironmentDirectory(options.projectRoot)
+  ]) {
+    const info = await inspectVirtualEnvironment(directory, options);
+    if (info && pythonSatisfiesPolicy(info, options) && await virtualEnvironmentMatchesConfiguredPython(info, options)) {
+      return info;
+    }
   }
-  throw new Error("Python could not create a virtual environment and uv installation is disabled.");
-}
-async function createVirtualEnvironmentWithUv(uv, directory, basePython, options, signal) {
-  await runAsync(uv.executable, [
-    "venv",
-    "--no-project",
-    "--no-config",
-    "--no-python-downloads",
-    "--allow-existing",
-    "--python",
-    basePython.executable,
-    directory
-  ], uvEnvironment(options), options.installTimeoutMs, signal);
-}
-async function inspectVirtualEnvironment(directory, options) {
-  const executable = virtualEnvironmentPythonExecutable(directory);
-  const info = await probePython({ executable, args: [] }, options);
-  return info?.virtualEnvironment && pathsEqual(info.virtualEnvironment, directory) ? info : null;
+  return null;
 }
-async function ensurePythonResolved(options) {
-  const existing = await discoverPython(options);
-  if (existing)
-    return existing;
+async function ensureBasePythonResolved(uv, options) {
+  if (options.python) {
+    const configured = await probePython({ executable: options.python, args: [] }, options);
+    if (!configured || !pythonSatisfiesPolicy(configured, options)) {
+      throw incompatibleConfiguredPython(options);
+    }
+    if (!configured.virtualEnvironment)
+      return configured;
+    const base = await probePython({ executable: configured.baseExecutable, args: [] }, options);
+    if (base && pythonSatisfiesPolicy(base, options))
+      return base;
+    throw incompatibleConfiguredPython(options);
+  }
+  const system = await findPythonWithUv(uv, options, "system");
+  if (system)
+    return system;
+  const cachedManaged = await findPythonWithUv(uv, options, "managed");
+  if (cachedManaged)
+    return cachedManaged;
   if (!options.installPython) {
-    const capability = options.requireEmbedding ? " with compatible CPython development headers, architecture, and a linkable library" : "";
-    throw new Error(`No Python interpreter satisfies ${options.pythonRange}${capability}; ` + "managed Python installation is disabled.");
+    throw new Error(missingPythonMessage(options, "managed Python installation is disabled"));
   }
-  const lockTarget = cacheLockTarget(options.cacheDir, "python");
   return withProvisioningLock({
-    key: `python:${canonicalPath(lockTarget)}`,
-    target: lockTarget,
+    key: `python:${canonicalPath(import_node_path5.default.join(options.cacheDir, "python"))}`,
     timeoutMs: options.coordinationTimeoutMs,
-    env: options.env,
-    check: () => discoverPython(options),
-    mutate: async (signal) => {
-      const uv = await ensureUvResolved(options);
-      const uvEnv = uvEnvironment(options);
-      await runAsync(uv.executable, ["python", "install", "--no-config", options.managedPython], uvEnv, options.installTimeoutMs, signal);
-      const installed = await findPythonWithUv(uv, options, signal);
+    check: () => findPythonWithUv(uv, options, "managed"),
+    mutate: async () => {
+      await runAsync(uv.executable, ["python", "install", "--no-config", options.managedPython], isolatedUvEnvironment(options), options.installTimeoutMs);
+      const installed = await findPythonWithUv(uv, options, "managed");
       if (!installed) {
-        throw new Error(`uv installed Python ${options.managedPython}, but it does not satisfy the requested ` + "runtime capabilities.");
+        throw new Error(missingPythonMessage(options, `uv installed ${options.managedPython}, but it remains incompatible`));
       }
       return installed;
     }
   });
 }
-async function discoverPython(options) {
-  if (options.python) {
-    const configured = await probePython({ executable: options.python, args: [] }, options);
-    if (configured && pythonSatisfiesRequirements(configured, options))
-      return configured;
-    throw new Error(`Configured Python ${options.python} is unavailable or does not satisfy ${options.pythonRange}.`);
-  }
-  const existingUv = await findAvailableUv(options);
-  if (existingUv) {
-    const uvPython = await findPythonWithUv(existingUv, options);
-    if (uvPython)
-      return uvPython;
-  }
-  return findPython({ ...options, python: "" });
-}
-async function findPythonWithUv(uv, options, signal) {
-  const requests = [undefined, options.managedPython];
-  for (const requestedPython of requests) {
+async function findPythonWithUv(uv, options, source) {
+  for (const request of ["", options.managedPython]) {
     const args = [
       "python",
       "find",
       "--no-project",
       "--no-config",
-      "--managed-python",
-      "--no-python-downloads"
+      "--no-python-downloads",
+      source === "system" ? "--system" : "--managed-python"
     ];
-    if (requestedPython)
-      args.push(requestedPython);
+    if (request)
+      args.push(request);
     try {
-      const { stdout } = await runAsync(uv.executable, args, uvEnvironment(options), options.probeTimeoutMs, signal);
+      const { stdout } = await runAsync(uv.executable, args, explicitPythonSourceEnvironment(options), options.probeTimeoutMs);
       const info = await probePython({ executable: stdout.trim(), args: [] }, options);
-      if (info && pythonSatisfiesRequirements(info, options))
+      if (info && pythonSatisfiesPolicy(info, options))
         return info;
-    } catch (error) {
-      if (signal?.aborted)
-        throw signal.reason ?? error;
-    }
+    } catch {}
   }
+  try {
+    const { stdout } = await runAsync(uv.executable, [
+      "python",
+      "list",
+      "--no-config",
+      "--no-python-downloads",
+      "--only-installed",
+      "--output-format",
+      "json",
+      source === "system" ? "--no-managed-python" : "--managed-python"
+    ], explicitPythonSourceEnvironment(options), options.probeTimeoutMs);
+    const candidates = installedPythonPaths(stdout);
+    for (const executable of candidates) {
+      const info = await probePython({ executable, args: [] }, options);
+      if (info && !info.virtualEnvironment && pythonSatisfiesPolicy(info, options)) {
+        return info;
+      }
+    }
+  } catch {}
   return null;
 }
-async function ensurePipResolved(python, options) {
-  const existingUv = await findAvailableUv(options);
-  if (existingUv)
-    return uvPackageManager(existingUv, python);
-  if (options.installUv)
-    return uvPackageManager(await ensureUvResolved(options), python);
-  const existingPip = await findPip(python, options);
-  if (existingPip)
-    return existingPip;
-  throw new Error(`The virtual environment's python -m pip does not satisfy ${options.pipRange}; ` + "uv installation is disabled.");
+function installedPythonPaths(output) {
+  const parsed = JSON.parse(output);
+  if (!Array.isArray(parsed))
+    return [];
+  const paths = parsed.flatMap((entry) => {
+    if (!entry || typeof entry !== "object" || !("path" in entry))
+      return [];
+    const candidate = entry.path;
+    return typeof candidate === "string" && candidate ? [candidate] : [];
+  });
+  return [...new Map(paths.map((candidate) => [canonicalPath(candidate), candidate])).values()];
+}
+async function inspectVirtualEnvironment(directory, options) {
+  const executable = virtualEnvironmentPythonExecutable(directory);
+  const info = await probePython({ executable, args: [] }, options);
+  return info?.virtualEnvironment && pathsEqual(info.virtualEnvironment, directory) ? info : null;
+}
+async function installRuntimeDependencies(uv, python, dependencies, dependencyOptions, options) {
+  if (!python.virtualEnvironment) {
+    throw new Error("Runtime dependency installation requires a virtual environment.");
+  }
+  await withProvisioningLock({
+    key: `dependencies:${canonicalPath(python.virtualEnvironment)}`,
+    timeoutMs: options.coordinationTimeoutMs,
+    check: async () => null,
+    mutate: async () => {
+      const temporary = await import_promises.mkdtemp(import_node_path5.default.join(import_node_os.default.tmpdir(), "pyfig-dependencies-"));
+      try {
+        const additions = import_node_path5.default.join(temporary, "runtime-dependencies.txt");
+        const resolved = import_node_path5.default.join(temporary, "resolved-dependencies.txt");
+        const pyproject = import_node_path5.default.join(options.projectRoot, "pyproject.toml");
+        const hasPyproject = import_node_fs4.default.existsSync(pyproject);
+        if (!hasPyproject && (dependencyOptions.extras.length > 0 || dependencyOptions.groups.length > 0 || dependencyOptions.allExtras)) {
+          throw new Error("Runtime extras and groups require an existing pyproject.toml.");
+        }
+        const sources = hasPyproject ? [pyproject] : [];
+        if (dependencies.length > 0) {
+          await import_promises.writeFile(additions, `${dependencies.join(`
+`)}
+`, "utf8");
+          sources.push(additions);
+        }
+        const selectionArgs = [
+          ...dependencyOptions.extras.flatMap((extra) => ["--extra", extra]),
+          ...dependencyOptions.groups.flatMap((group) => ["--group", group]),
+          ...dependencyOptions.allExtras ? ["--all-extras"] : []
+        ];
+        await runAsync(uv.executable, [
+          "pip",
+          "compile",
+          "--no-config",
+          "--python",
+          python.executable,
+          ...selectionArgs,
+          ...sources,
+          "--output-file",
+          resolved
+        ], targetUvEnvironment(options, python), options.installTimeoutMs, undefined, options.projectRoot);
+        await runAsync(uv.executable, ["pip", "install", "--no-config", "--python", python.executable, "-r", resolved], targetUvEnvironment(options, python), options.installTimeoutMs, undefined, options.projectRoot);
+      } finally {
+        await import_promises.rm(temporary, { recursive: true, force: true });
+      }
+      return true;
+    }
+  });
 }
 async function ensureUvResolved(options) {
   const existing = await findAvailableUv(options);
@@ -1046,15 +833,12 @@ async function ensureUvResolved(options) {
   }
   const installDir = uvInstallDirectory(options);
   const executable = uvExecutable(options);
-  const lockTarget = cacheLockTarget(options.cacheDir, "uv");
   return withProvisioningLock({
-    key: `uv:${canonicalPath(lockTarget)}`,
-    target: lockTarget,
+    key: `uv:${canonicalPath(installDir)}`,
     timeoutMs: options.coordinationTimeoutMs,
-    env: options.env,
     check: () => findAvailableUv(options),
-    mutate: async (signal) => {
-      await installUv(installDir, options, signal);
+    mutate: async () => {
+      await installUv(installDir, options);
       const result = probeUv(executable, options);
       if (!result || result.version !== options.uvVersion) {
         throw new Error(`Expected managed uv ${options.uvVersion}, but the installed executable did not match.`);
@@ -1064,88 +848,134 @@ async function ensureUvResolved(options) {
   });
 }
 async function findAvailableUv(options) {
-  const system = await findUv(options);
-  if (system)
-    return system;
+  const external = await findUv(options);
+  if (external)
+    return external;
   const managed = probeUv(uvExecutable(options), options);
   return managed?.version === options.uvVersion ? managed : null;
 }
-function uvInstallDirectory(options) {
-  return import_node_path7.default.join(options.cacheDir, "tools", "uv", options.uvVersion);
-}
-function uvExecutable(options) {
-  return import_node_path7.default.join(uvInstallDirectory(options), process.platform === "win32" ? "uv.exe" : "uv");
+function normalizeDependencies(dependencies) {
+  const normalized = dependencies.map((dependency) => dependency.trim());
+  for (const dependency of normalized) {
+    if (!dependency || /[\0\r\n]/u.test(dependency)) {
+      throw new TypeError(`Invalid runtime dependency: ${JSON.stringify(dependency)}`);
+    }
+  }
+  return [...new Set(normalized)];
 }
-function uvPackageManager(uv, python) {
-  if (!python.virtualEnvironment) {
-    throw new Error("uv pip commands require a virtual-environment Python interpreter.");
+function normalizeDependencyOptions(options) {
+  const extras = normalizeNames("extra", options.extras ?? []);
+  const groups = normalizeNames("dependency group", options.groups ?? []);
+  if (options.allExtras && extras.length > 0) {
+    throw new TypeError("allExtras cannot be combined with explicit extras.");
   }
-  return {
-    kind: "uv",
-    executable: uv.executable,
-    prefixArgs: ["pip"],
-    version: uv.version,
-    pythonExecutable: python.executable,
-    virtualEnvironment: python.virtualEnvironment
-  };
+  return { extras, groups, allExtras: options.allExtras ?? false };
 }
-function withoutActiveVirtualEnvironment(env) {
-  const result = { ...env };
-  for (const key of Object.keys(result)) {
-    const normalized = key.toUpperCase();
-    if (normalized === "CONDA_PREFIX" || normalized === "VIRTUAL_ENV" || normalized === "PYTHONHOME") {
-      delete result[key];
+function normalizeNames(kind, names) {
+  const normalized = names.map((name) => name.trim());
+  for (const name of normalized) {
+    if (!name || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(name)) {
+      throw new TypeError(`Invalid ${kind}: ${JSON.stringify(name)}`);
     }
   }
-  return result;
+  return [...new Set(normalized)];
+}
+function isManagedEnvironment(python, options) {
+  return Boolean(python.virtualEnvironment) && pathsEqual(python.virtualEnvironment, virtualEnvironmentDirectory(options.projectRoot));
+}
+function isolatedUvEnvironment(options) {
+  return sanitizeUvEnvironment(uvEnvironment(options));
 }
-async function installUv(installDir, options, signal) {
+function explicitPythonSourceEnvironment(options) {
+  const env = isolatedUvEnvironment(options);
+  delete env["UV_PYTHON_PREFERENCE"];
+  return env;
+}
+function targetUvEnvironment(options, python) {
+  return uvCommandEnvironment(uvEnvironment(options), python);
+}
+function incompatibleConfiguredPython(options) {
+  return new Error(`Configured Python ${options.python} is unavailable or does not satisfy ` + `requires-python ${options.requiresPython}` + `${options.requireEmbedding ? " with CPython embedding files" : ""}.`);
+}
+function missingPythonMessage(options, reason) {
+  const embedding = options.requireEmbedding ? " with compatible CPython headers, library, architecture, and GIL ABI" : "";
+  return `No Python satisfies requires-python ${options.requiresPython}${embedding}; ${reason}.`;
+}
+async function virtualEnvironmentMatchesConfiguredPython(virtualEnvironment, options) {
+  if (!options.python)
+    return true;
+  const configured = await probePython({ executable: options.python, args: [] }, options);
+  if (!configured || !pythonSatisfiesPolicy(configured, options))
+    return false;
+  if (configured.virtualEnvironment && pathsEqual(configured.executable, virtualEnvironment.executable)) {
+    return true;
+  }
+  const configuredBase = configured.virtualEnvironment ? configured.baseExecutable : configured.executable;
+  return pathsEqual(configuredBase, virtualEnvironment.baseExecutable);
+}
+function uvInstallDirectory(options) {
+  return import_node_path5.default.join(options.cacheDir, "tools", "uv", options.uvVersion);
+}
+function uvExecutable(options) {
+  return import_node_path5.default.join(uvInstallDirectory(options), process.platform === "win32" ? "uv.exe" : "uv");
+}
+async function installUv(installDir, options) {
   const asset = uvAsset();
   const baseUrl = `https://github.com/astral-sh/uv/releases/download/${options.uvVersion}`;
-  const temporary = await import_promises2.mkdtemp(import_node_path7.default.join(import_node_os.default.tmpdir(), "pyfig-uv-"));
+  const temporary = await import_promises.mkdtemp(import_node_path5.default.join(import_node_os.default.tmpdir(), "pyfig-uv-"));
   const dispatcher = proxyDispatcher(options.env);
   try {
-    const archive = import_node_path7.default.join(temporary, asset);
-    await download(`${baseUrl}/${asset}`, archive, options.downloadTimeoutMs, signal, dispatcher);
-    const expected = (await downloadText(`${baseUrl}/${asset}.sha256`, options.downloadTimeoutMs, signal, dispatcher)).trim().split(/\s+/u)[0];
+    const archive = import_node_path5.default.join(temporary, asset);
+    await download(`${baseUrl}/${asset}`, archive, options.downloadTimeoutMs, dispatcher);
+    const expected = (await downloadText(`${baseUrl}/${asset}.sha256`, options.downloadTimeoutMs, dispatcher)).trim().split(/\s+/u)[0];
     const actual = await sha256File(archive);
     if (!expected || expected.toLowerCase() !== actual.toLowerCase()) {
       throw new Error(`uv archive checksum mismatch for ${asset}`);
     }
-    const extracted = import_node_path7.default.join(temporary, "extracted");
-    await import_promises2.mkdir(extracted, { recursive: true });
-    signal.throwIfAborted();
-    if (asset.endsWith(".zip"))
-      await import_extract_zip.default(archive, { dir: extracted });
-    else
-      await tar.x({ file: archive, cwd: extracted, strict: true });
-    signal.throwIfAborted();
-    const source = await findFile(extracted, process.platform === "win32" ? "uv.exe" : "uv");
+    const extracted = import_node_path5.default.join(temporary, "extracted");
+    await import_promises.mkdir(extracted, { recursive: true });
+    const source = await extractUvExecutable(archive, asset, extracted);
     if (!source)
       throw new Error(`uv archive did not contain the expected executable: ${asset}`);
     await publishUvAtomically(source, installDir, options);
   } finally {
     await dispatcher?.close();
-    await import_promises2.rm(temporary, { recursive: true, force: true });
+    await import_promises.rm(temporary, { recursive: true, force: true });
+  }
+}
+async function extractUvExecutable(archive, asset, destination) {
+  const executableName = process.platform === "win32" ? "uv.exe" : "uv";
+  if (!asset.endsWith(".zip")) {
+    await tar.x({ file: archive, cwd: destination, strict: true });
+    return findFile(destination, executableName);
   }
+  const entries = import_fflate.unzipSync(await import_promises.readFile(archive), {
+    filter: ({ name }) => import_node_path5.default.posix.basename(name.replaceAll("\\", "/")) === executableName
+  });
+  const matches = Object.entries(entries).filter(([name]) => import_node_path5.default.posix.basename(name.replaceAll("\\", "/")) === executableName);
+  if (matches.length !== 1 || !matches[0])
+    return null;
+  const source = import_node_path5.default.join(destination, executableName);
+  await import_promises.writeFile(source, matches[0][1], { flag: "wx" });
+  return source;
 }
 async function publishUvAtomically(source, installDir, options) {
-  await import_promises2.mkdir(installDir, { recursive: true });
+  await import_promises.mkdir(installDir, { recursive: true });
   const executable = uvExecutable(options);
-  const staged = import_node_path7.default.join(installDir, `.${import_node_path7.default.basename(executable)}.${process.pid}.${import_node_crypto3.randomUUID()}.tmp`);
+  const staged = import_node_path5.default.join(installDir, `.${import_node_path5.default.basename(executable)}.${process.pid}.${import_node_crypto.randomUUID()}.tmp`);
   try {
-    await import_promises2.copyFile(source, staged);
+    await import_promises.copyFile(source, staged);
     if (process.platform !== "win32")
-      await import_promises2.chmod(staged, 493);
+      await import_promises.chmod(staged, 493);
     const stagedUv = probeUv(staged, options);
     if (!stagedUv || stagedUv.version !== options.uvVersion) {
       throw new Error(`Downloaded uv executable is not version ${options.uvVersion}.`);
     }
     if (process.platform === "win32")
-      await import_promises2.rm(executable, { force: true });
-    await import_promises2.rename(staged, executable);
+      await import_promises.rm(executable, { force: true });
+    await import_promises.rename(staged, executable);
   } finally {
-    await import_promises2.rm(staged, { force: true });
+    await import_promises.rm(staged, { force: true });
   }
 }
 function uvAsset() {
@@ -1160,23 +990,23 @@ function uvAsset() {
     return `uv-${architecture}-unknown-linux-musl.tar.gz`;
   throw new Error(`uv bootstrap does not support platform ${process.platform}.`);
 }
-async function download(url, destination, timeoutMs, externalSignal, dispatcher) {
+async function download(url, destination, timeoutMs, dispatcher) {
   const response = await import_undici.fetch(url, {
     dispatcher,
     redirect: "follow",
-    signal: combinedSignal(timeoutMs, externalSignal)
+    signal: AbortSignal.timeout(timeoutMs)
   });
   if (!response.ok || !response.body) {
     await response.body?.cancel();
     throw new Error(`Could not download ${url}: HTTP ${response.status}`);
   }
-  await import_promises3.pipeline(import_node_stream.Readable.fromWeb(response.body), import_node_fs3.createWriteStream(destination, { flags: "wx" }));
+  await import_promises2.pipeline(import_node_stream.Readable.fromWeb(response.body), import_node_fs3.createWriteStream(destination, { flags: "wx" }));
 }
-async function downloadText(url, timeoutMs, externalSignal, dispatcher) {
+async function downloadText(url, timeoutMs, dispatcher) {
   const response = await import_undici.fetch(url, {
     dispatcher,
     redirect: "follow",
-    signal: combinedSignal(timeoutMs, externalSignal)
+    signal: AbortSignal.timeout(timeoutMs)
   });
   if (!response.ok) {
     await response.body?.cancel();
@@ -1198,18 +1028,15 @@ function proxyDispatcher(env) {
 function environmentValue(env, lowercase, uppercase) {
   return env[lowercase] ?? env[uppercase];
 }
-function combinedSignal(timeoutMs, externalSignal) {
-  return AbortSignal.any([externalSignal, AbortSignal.timeout(timeoutMs)]);
-}
 async function sha256File(file) {
-  const hash = import_node_crypto3.createHash("sha256");
+  const hash = import_node_crypto.createHash("sha256");
   for await (const chunk of import_node_fs3.createReadStream(file))
     hash.update(chunk);
   return hash.digest("hex");
 }
 async function findFile(directory, name) {
-  for (const entry of await import_promises2.readdir(directory, { withFileTypes: true })) {
-    const target = import_node_path7.default.join(directory, entry.name);
+  for (const entry of await import_promises.readdir(directory, { withFileTypes: true })) {
+    const target = import_node_path5.default.join(directory, entry.name);
     if (entry.isFile() && entry.name === name)
       return target;
     if (entry.isDirectory()) {
@@ -1220,176 +1047,27 @@ async function findFile(directory, name) {
   }
   return null;
 }
-function incompatibleVirtualEnvironmentError(directory, python, options) {
-  const capabilities = options.requireEmbedding ? " or lacks compatible CPython embedding headers, library, or architecture" : "";
-  return new Error(`The existing virtual environment at ${directory} uses Python ${python.version}, ` + `which does not satisfy ${options.pythonRange}${capabilities}.`);
-}
-async function virtualEnvironmentMatchesConfiguredPython(virtualEnvironment, options) {
-  if (!options.python)
-    return true;
-  const configured = await probePython({ executable: options.python, args: [] }, options);
-  if (!configured || !pythonSatisfiesRequirements(configured, options))
-    return false;
-  if (configured.virtualEnvironment && pathsEqual(configured.executable, virtualEnvironment.executable)) {
-    return true;
-  }
-  const configuredBase = configured.virtualEnvironment ? configured.baseExecutable : configured.executable;
-  return pathsEqual(configuredBase, virtualEnvironment.baseExecutable);
-}
-function pythonIsPresent(python) {
-  return import_node_fs4.default.existsSync(python.executable);
-}
-function environmentIsPresent(environment) {
-  return pythonIsPresent(environment.python) && import_node_fs4.default.existsSync(environment.packageManager.executable);
-}
 
 // src/runners.ts
-var import_node_child_process3 = require("node:child_process");
-var import_node_fs6 = __toESM(require("node:fs"), 1);
-
-// src/package-target.ts
-var import_node_os2 = __toESM(require("node:os"), 1);
-var TARGET_CHANGING_OPTIONS = new Set([
-  "--config-file",
-  "--prefix",
-  "--python",
-  "--root",
-  "--system",
-  "--target",
-  "--user"
-]);
-var TARGET_CHANGING_SHORT_OPTIONS = new Set(["-p", "-t"]);
-var TARGET_ENVIRONMENT_VARIABLES = new Set([
-  "CONDA_PREFIX",
-  "PIP_CONFIG_FILE",
-  "PIP_PREFIX",
-  "PIP_PYTHON",
-  "PIP_ROOT",
-  "PIP_TARGET",
-  "PIP_USER",
-  "PYTHONHOME",
-  "PYTHONUSERBASE",
-  "UV_CONFIG_FILE",
-  "UV_PROJECT_ENVIRONMENT",
-  "UV_PREFIX",
-  "UV_PYTHON",
-  "UV_ROOT",
-  "UV_SYSTEM_PYTHON",
-  "UV_TARGET"
-]);
-function assertSafePackageArguments(args) {
-  for (const argument of args) {
-    if (argument === "--")
-      break;
-    const [name] = argument.split("=", 1);
-    if (name && TARGET_CHANGING_OPTIONS.has(name)) {
-      throw new Error(`${name} is not allowed because Pyfig package commands are pinned to the repository .venv.`);
-    }
-    const shortName = argument.slice(0, 2);
-    if (TARGET_CHANGING_SHORT_OPTIONS.has(shortName)) {
-      throw new Error(`${shortName} is not allowed because Pyfig package commands are pinned to the repository .venv.`);
-    }
-  }
-}
-function packageManagerEnvironment(env, packageManager) {
-  const active = sanitizedTargetEnvironment(env);
-  const activated = activateVirtualEnvironment(active, packageManager.virtualEnvironment, packageManager.pythonExecutable);
-  return packageManager.kind === "uv" ? {
-    ...activated,
-    UV_NO_CONFIG: "1",
-    UV_PYTHON: packageManager.pythonExecutable
-  } : {
-    ...activated,
-    PIP_CONFIG_FILE: import_node_os2.default.devNull,
-    PIP_REQUIRE_VIRTUALENV: "1",
-    PYTHONNOUSERSITE: "1"
-  };
-}
-function uvPipEnvironment(env, python) {
-  if (!python.virtualEnvironment) {
-    throw new Error("uv pip commands require the repository virtual environment.");
-  }
-  return {
-    ...activateVirtualEnvironment(sanitizedTargetEnvironment(env), python.virtualEnvironment, python.executable),
-    UV_NO_CONFIG: "1",
-    UV_PYTHON: python.executable
-  };
-}
-function assertMutationUsesUv(packageManager, args) {
-  if (packageManager.kind === "pip" && isPackageMutation(args)) {
-    throw new Error("Package mutation requires uv so the repository environment is locked across processes. " + "Enable uv installation or use a read-only pip command.");
-  }
-}
-function isPackageMutation(args) {
-  return args.some((argument) => argument === "install" || argument === "sync" || argument === "uninstall");
-}
-function isUvPipCommand(args) {
-  const separator = args.indexOf("--");
-  const commandArguments = separator === -1 ? args : args.slice(0, separator);
-  return commandArguments.includes("pip");
-}
-function sanitizedTargetEnvironment(env) {
-  const sanitized = { ...env };
-  for (const key of Object.keys(sanitized)) {
-    if (TARGET_ENVIRONMENT_VARIABLES.has(key.toUpperCase()))
-      delete sanitized[key];
-  }
-  return sanitized;
-}
+var import_node_child_process2 = require("node:child_process");
 
 // src/runtime-files.ts
 var import_node_fs5 = __toESM(require("node:fs"), 1);
-var import_node_path8 = __toESM(require("node:path"), 1);
+var import_node_path6 = __toESM(require("node:path"), 1);
 function runtimeFile(name) {
   const moduleDirectory = __dirname;
-  const compiled = import_node_path8.default.join(moduleDirectory, `${name}.js`);
-  return import_node_fs5.default.existsSync(compiled) ? compiled : import_node_path8.default.join(moduleDirectory, `${name}.ts`);
+  const compiled = import_node_path6.default.join(moduleDirectory, `${name}.js`);
+  return import_node_fs5.default.existsSync(compiled) ? compiled : import_node_path6.default.join(moduleDirectory, `${name}.ts`);
 }
 
 // src/runners.ts
-async function pythonSpawn(args = [], spawnOptions = {}, pyfigOptions = {}) {
-  const options = optionsForInvocation(pyfigOptions, spawnOptions.env);
-  const python = await ensureVirtualEnvironment(options);
-  const command = buildPythonCommand(python, args, resolveOptions(options).env);
-  return import_node_child_process3.spawn(command.executable, command.args, {
-    ...spawnOptions,
-    env: command.env
-  });
-}
-function pythonSpawnSync(args = [], spawnOptions = {}, pyfigOptions = {}) {
-  const options = optionsForInvocation(pyfigOptions, spawnOptions.env);
-  const python = resolveSynchronously("venv", options);
-  const command = buildPythonCommand(python, args, resolveOptions(options).env);
-  return import_node_child_process3.spawnSync(command.executable, command.args, {
-    ...spawnOptions,
-    env: command.env
-  });
-}
-async function pipSpawn(args = [], spawnOptions = {}, pyfigOptions = {}) {
-  const options = optionsForInvocation(pyfigOptions, spawnOptions.env);
-  const environment = await ensureEnvironment(options);
-  const command = buildPipCommand(environment.packageManager, args, resolveOptions(options).env);
-  return import_node_child_process3.spawn(command.executable, command.args, {
-    ...spawnOptions,
-    env: command.env
-  });
-}
-function pipSpawnSync(args = [], spawnOptions = {}, pyfigOptions = {}) {
-  const options = optionsForInvocation(pyfigOptions, spawnOptions.env);
-  const environment = resolveSynchronously("environment", options);
-  const command = buildPipCommand(environment.packageManager, args, resolveOptions(options).env);
-  return import_node_child_process3.spawnSync(command.executable, command.args, {
-    ...spawnOptions,
-    env: command.env
-  });
-}
 async function uvSpawn(args = [], spawnOptions = {}, pyfigOptions = {}) {
   const options = optionsForInvocation(pyfigOptions, spawnOptions.env);
   const resolved = resolveOptions(options);
-  const uv = await ensureUv(resolved);
-  const python = isUvPipCommand(args) ? await ensureVirtualEnvironment(resolved) : undefined;
-  const command = buildUvCommand(uv, args, resolved, python);
-  return import_node_child_process3.spawn(command.executable, command.args, {
+  const environment = uvCommandNeedsEnvironment(args) ? await ensureEnvironment(resolved) : undefined;
+  const uv = environment?.uv ?? await ensureUv(resolved);
+  const command = buildUvCommand(uv, args, resolved, environment?.python);
+  return import_node_child_process2.spawn(command.executable, command.args, {
     ...spawnOptions,
     env: command.env
   });
@@ -1397,45 +1075,19 @@ async function uvSpawn(args = [], spawnOptions = {}, pyfigOptions = {}) {
 function uvSpawnSync(args = [], spawnOptions = {}, pyfigOptions = {}) {
   const options = optionsForInvocation(pyfigOptions, spawnOptions.env);
   const resolved = resolveOptions(options);
-  const resolution = isUvPipCommand(args) ? resolveSynchronously("uv-pip", resolved) : { uv: resolveSynchronously("uv", resolved), python: undefined };
-  const command = buildUvCommand(resolution.uv, args, resolved, resolution.python);
-  return import_node_child_process3.spawnSync(command.executable, command.args, {
+  const environment = uvCommandNeedsEnvironment(args) ? resolveSynchronously("environment", resolved) : undefined;
+  const uv = environment?.uv ?? resolveSynchronously("uv", resolved);
+  const command = buildUvCommand(uv, args, resolved, environment?.python);
+  return import_node_child_process2.spawnSync(command.executable, command.args, {
     ...spawnOptions,
     env: command.env
   });
 }
-function buildPythonCommand(python, args, env) {
-  const commandEnv = python.virtualEnvironment ? activateVirtualEnvironment(env, python.virtualEnvironment, python.executable) : env;
-  return {
-    executable: python.executable,
-    args: [...args],
-    env: commandEnv
-  };
-}
-function buildPipCommand(packageManager, args, env) {
-  if (!packageManager.virtualEnvironment) {
-    throw new Error("pip commands require an active virtual environment.");
-  }
-  assertSafePackageArguments(args);
-  assertMutationUsesUv(packageManager, args);
-  return {
-    executable: packageManager.executable,
-    args: [...packageManager.prefixArgs, ...args],
-    env: packageManagerEnvironment(env, packageManager)
-  };
-}
 function buildUvCommand(uv, args, options, python) {
-  const isPip = isUvPipCommand(args);
-  if (isPip && !python?.virtualEnvironment) {
-    throw new Error("uv pip commands require the repo virtual-environment Python interpreter.");
-  }
-  if (isPip)
-    assertSafePackageArguments(args);
-  const env = isPip && python ? uvPipEnvironment(uvEnvironment(options), python) : uvEnvironment(options);
   return {
     executable: uv.executable,
-    args: [...args],
-    env
+    args: python ? targetUvArguments(args, python) : [...args],
+    env: uvCommandEnvironment(uvEnvironment(options), python)
   };
 }
 function optionsForInvocation(pyfigOptions, spawnEnv) {
@@ -1443,41 +1095,29 @@ function optionsForInvocation(pyfigOptions, spawnEnv) {
 }
 function resolveSynchronously(target, options) {
   const resolved = resolveOptions(options);
-  const cacheKey = `${target}:${configurationFingerprint(resolved)}`;
-  return memoizeSync("sync-resolution", cacheKey, resolved.cacheTtlMs, synchronousResolutionIsPresent, () => {
-    const request = { target, options: resolved };
-    const result = import_node_child_process3.spawnSync(process.execPath, [runtimeFile("sync-resolver")], {
-      input: JSON.stringify(request),
-      encoding: "utf8",
-      env: resolved.env,
-      timeout: synchronousResolutionTimeout(resolved),
-      maxBuffer: 4 * 1024 * 1024,
-      windowsHide: true
-    });
-    if (result.status !== 0 || result.error) {
-      const detail = result.stderr.trim() || result.error?.message || `exit ${result.status}`;
-      throw new Error(`Could not resolve ${target} synchronously: ${detail}`);
-    }
-    try {
-      return JSON.parse(result.stdout);
-    } catch (error) {
-      const detail = error instanceof Error ? error.message : String(error);
-      throw new Error(`Could not parse synchronous ${target} resolution: ${detail}`);
-    }
+  const request = { target, options: resolved };
+  const result = import_node_child_process2.spawnSync(process.execPath, [runtimeFile("sync-resolver")], {
+    input: JSON.stringify(request),
+    encoding: "utf8",
+    env: resolved.env,
+    timeout: synchronousResolutionTimeout(resolved),
+    maxBuffer: 4 * 1024 * 1024,
+    windowsHide: true
   });
+  if (result.status !== 0 || result.error) {
+    const detail = result.stderr.trim() || result.error?.message || `exit ${result.status}`;
+    throw new Error(`Could not resolve ${target} synchronously: ${detail}`);
+  }
+  try {
+    return JSON.parse(result.stdout);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`Could not parse synchronous ${target} resolution: ${detail}`);
+  }
 }
 function synchronousResolutionTimeout(options) {
   return options.coordinationTimeoutMs + options.downloadTimeoutMs + 2 * options.installTimeoutMs + 4 * options.probeTimeoutMs + 60000;
 }
-function synchronousResolutionIsPresent(resolution) {
-  if ("packageManager" in resolution) {
-    return import_node_fs6.default.existsSync(resolution.python.executable) && import_node_fs6.default.existsSync(resolution.packageManager.executable);
-  }
-  if ("uv" in resolution) {
-    return import_node_fs6.default.existsSync(resolution.uv.executable) && import_node_fs6.default.existsSync(resolution.python.executable);
-  }
-  return import_node_fs6.default.existsSync(resolution.executable);
-}
 
 // src/client.ts
 function createPyfig(options = {}) {
@@ -1485,18 +1125,15 @@ function createPyfig(options = {}) {
     ...options,
     env: options.env ? { ...options.env } : undefined
   };
+  const baseEnvironment = import_loqkit2.memoize(() => ensureEnvironment(scopedOptions));
+  const uvInfo = import_loqkit2.memoize(() => ensureUv(scopedOptions));
   return {
-    prepare: () => ensureEnvironment(scopedOptions),
-    pythonInfo: () => ensureVirtualEnvironment(scopedOptions),
-    uvInfo: () => ensureUv(scopedOptions),
-    python: (args = [], spawnOptions = {}) => pythonSpawn(args, spawnOptions, scopedOptions),
-    pythonSync: (args = [], spawnOptions = {}) => pythonSpawnSync(args, spawnOptions, scopedOptions),
-    pip: (args = [], spawnOptions = {}) => pipSpawn(args, spawnOptions, scopedOptions),
-    pipSync: (args = [], spawnOptions = {}) => pipSpawnSync(args, spawnOptions, scopedOptions),
+    prepare: (dependencies = [], dependencyOptions = {}) => dependencies.length === 0 && !dependencyOptions.allExtras && (dependencyOptions.extras?.length ?? 0) === 0 && (dependencyOptions.groups?.length ?? 0) === 0 ? baseEnvironment() : ensureEnvironment(scopedOptions, dependencies, dependencyOptions),
+    pythonInfo: async () => (await baseEnvironment()).python,
+    uvInfo,
     uv: (args = [], spawnOptions = {}) => uvSpawn(args, spawnOptions, scopedOptions),
-    uvSync: (args = [], spawnOptions = {}) => uvSpawnSync(args, spawnOptions, scopedOptions),
-    clearCache: clearPyfigCaches
+    uvSync: (args = [], spawnOptions = {}) => uvSpawnSync(args, spawnOptions, scopedOptions)
   };
 }
 
-//# debugId=940E4B4A4836D48C64756E2164756E21
+//# debugId=5564427996CDDBA964756E2164756E21