pyfig 0.3.1 → 0.5.0

package/README.md

@@ -1,6 +1,8 @@
 # pyfig
 
-`pyfig` creates or reuses `<project-root>/.venv` and binds every Python and package subprocess to that environment from Bun or Node.js. A valid existing venv is the first choice. Otherwise Pyfig discovers a compatible interpreter, installs its checksum-verified uv and managed Python when necessary, and provisions the root venv without requiring Python or Node to be preinstalled alongside Bun.
+`pyfig` prepares uv and a compatible Python virtual environment from Bun or Node.js. It prefers a valid uv already on the system, reuses a compatible venv, and searches system Python with downloads disabled before considering any managed Python download.
+
+Pyfig never invokes standalone `pip`, never writes `pyproject.toml` or requirements files, and never creates a project-root `.venv`. When no compatible venv exists, its private environment is `<project-root>/node_modules/.pyfig/venv`.
 
 ## Install
 
@@ -8,156 +10,146 @@
 bun add pyfig
 ```
 
-## Library
+## Use
 
 ```ts
 import { createPyfig } from 'pyfig';
 
 const pyfig = createPyfig({
-  pythonRange: '>=3.11.0 <4.0.0',
-  pipRange: '>=23.0.0',
-  requireEmbedding: true, // require compatible CPython headers, library, and architecture
-  requireGil: true,       // reject free-threaded CPython ABIs
+  requiresPython: '>=3.11,<4',
+  requireEmbedding: true,
+  requireGil: true,
 });
-const environment = await pyfig.prepare();
 
+const environment = await pyfig.prepare(
+  ['requests>=2.32'],
+  { extras: ['database'] },
+);
+
+console.log(environment.uv);
 console.log(environment.python);
-console.log(environment.packageManager);
+console.log(environment.managed);
+
+await pyfig.uv(
+  ['run', '--', 'python', 'script.py'],
+  { stdio: 'inherit' },
+);
 ```
 
-Run Python, pip, and uv with standard argument arrays and child-process spawn options:
+`prepare()` accepts PEP 508 dependency specifiers plus optional `extras`, `groups`, or `allExtras`. If the project has a `pyproject.toml`, uv resolves that read-only input together with a temporary dependency file. Pyfig installs the resolved result with `uv pip install -r`, which preserves unrelated packages. Temporary inputs are created outside the repository and removed afterward.
+
+The same uv-only surface handles direct commands:
 
 ```ts
-import {
-  pipSpawn,
-  pipSpawnSync,
-  pythonSpawn,
-  pythonSpawnSync,
-  uvSpawn,
-  uvSpawnSync,
-} from 'pyfig';
-
-const python = await pythonSpawn(['script.py', '--verbose'], { stdio: 'inherit' });
-const pythonVersion = pythonSpawnSync(['--version'], { encoding: 'utf8' });
-
-const pip = await pipSpawn(['install', 'ruff'], { stdio: 'inherit' });
-const installed = pipSpawnSync(['list', '--format', 'json'], { encoding: 'utf8' });
-
-const uv = await uvSpawn(['python', 'list'], { stdio: 'inherit' });
-const uvVersion = uvSpawnSync(['--version'], { encoding: 'utf8' });
-```
+import { uvSpawn, uvSpawnSync } from 'pyfig';
 
-The asynchronous helpers return `Promise<ChildProcess>` because discovery or installation may precede the spawn. Synchronous helpers perform the same setup in a child launched with `process.execPath`, so Bun stays Bun and Node stays Node; no `node` executable is assumed. Python execution only requires the venv, not pip or uv. Package helpers additionally resolve uv and receive `VIRTUAL_ENV`, the venv scripts directory at the front of `PATH`, and the exact venv interpreter.
+await uvSpawn(['pip', 'list'], { stdio: 'inherit' });
 
-Pass any `PyfigOptions` as the third argument when a helper needs a custom Python range, pip range, project root, cache directory, or installation policy.
+const result = uvSpawnSync(
+  ['run', '--', 'python', '-c', 'import sys; print(sys.executable)'],
+  { encoding: 'utf8' },
+);
+```
 
-Pyfig publishes matching ESM and CommonJS entry points. The root API intentionally contains only configuration constants, the scoped client, preparation helpers, spawn helpers, project-root discovery, public result types, and cache invalidation. Probe and lock internals are not package exports.
+For `uv pip` and `uv run`, Pyfig selects the venv and injects its exact interpreter. Caller-supplied target overrides such as `--python`, `--system`, `--target`, `--prefix`, and `--user` are rejected. Inherited target-changing environment variables are removed. Other uv commands run with Pyfig's cache and system-Python preference but are otherwise unchanged.
 
-Defaults are Python `>=3.10.0 <4.0.0`, pip `>=20.3.0`, managed Python `3.12`, pinned uv `0.13.6`, and system uv `>=0.13.6 <1.0.0`.
+The async spawn helper returns `Promise<ChildProcess>` because uv or environment setup may happen before spawning. The synchronous helper performs setup through `process.execPath`, so a Bun process remains Bun and does not assume a `node` command exists.
 
-Package mutation is always performed by uv, whose own target-environment lock protects concurrent installs and removals. When uv installation is explicitly disabled, the venv interpreter's `python -m pip` remains available for read-only commands such as `list`; mutable pip commands are rejected. Standalone `pip` and `pip3` executables are never discovered or executed.
+## Selection policy
 
-Native consumers can set `requireEmbedding: true` to require CPython, `Python.h`, a linkable library, and architecture/pointer-width compatibility with the JavaScript runtime. Probe results include implementation, architecture, pointer width, release level, base executable, and library kind. Set `requireGil: true` when an addon targets the standard GIL-enabled ABI.
+Pyfig uses this order:
 
-Given the same `PyfigOptions`, `pipSpawn(['install', 'xyz'])` and `uvSpawn(['pip', 'install', 'xyz'])` resolve the same project root, `.venv`, and interpreter. Target-changing arguments such as `--python`/`-p`, `--system`, `--target`/`-t`, `--prefix`, and `--user` are rejected. Target-changing environment variables are removed, persistent package-manager configuration is disabled for these commands, and uv receives the exact venv interpreter through `UV_PYTHON`.
+1. A compatible configured or `PATH` uv.
+2. Pyfig's cached, checksum-verified uv.
+3. A compatible explicitly configured venv, active `VIRTUAL_ENV`, root `.venv`, or Pyfig-owned venv.
+4. Every installed system Python reported by uv, with downloads disabled, until one passes all capability checks.
+5. An already-cached uv-managed Python that passes the same checks.
+6. A managed Python download, only when installation policy allows it.
 
-Project-root discovery uses Pacwich for workspace repositories. Single-package projects recognize Bun, npm, pnpm, Yarn, uv, and `pyproject.toml` metadata before falling back to a Git root, the nearest package manifest, or the current directory. Set `projectRoot` or `PYFIG_PROJECT_ROOT` to make ownership explicit.
+An explicit `python` option is strict: an unavailable or incompatible interpreter is an error. Incompatible external venvs are preserved and skipped. Only an incompatible environment under `node_modules/.pyfig/venv` may be rebuilt.
 
-## Decision flows
+![Pyfig prefers existing uv, compatible venvs, and system Python before managed downloads](docs/diagrams/python-selection.png)
 
-### Python, venv, and package manager
+[Mermaid source](docs/diagrams/python-selection.mmd)
 
-```mermaid
-graph TD;
-    A[Ensure environment] --> V{Repository virtual environment usable};
-    V -->|Yes| Q{Compatible uv available};
-    V -->|No| B{Configured Python supplied};
-    B -->|Valid| P[Select base Python];
-    B -->|Invalid| X[Fail explicit configuration];
-    B -->|No| C{Managed uv Python compatible};
-    C -->|Yes| P;
-    C -->|No| D{System Python compatible};
-    D -->|Yes| P;
-    D -->|No| E{Python installation allowed};
-    E -->|No| X2[Fail without changes];
-    E -->|Yes| U[Install pinned uv];
-    U --> M[Install managed Python];
-    M --> P;
+Native consumers can set `requireEmbedding: true` to require CPython, `Python.h`, a linkable embedding library, and architecture/pointer-width compatibility with the JavaScript runtime. Set `requireGil: true` when the native addon requires the standard GIL-enabled ABI. These checks apply to system, existing-venv, cached, and downloaded interpreters alike.
 
-    P --> W{uv available or installable};
-    W -->|Yes| UVV[Create virtual environment with uv];
-    W -->|No| SV[Create virtual environment with Python];
-    UVV --> Q;
-    SV --> Q;
+## Runtime dependency resolution
 
-    Q -->|Yes| R[Use uv pip with selected Python];
-    Q -->|No| S{Python module pip compatible};
-    S -->|Read only| T[Use Python module pip];
-    S -->|Mutation or missing| X3[Require uv or fail];
+```ts
+await pyfig.prepare(
+  ['orjson>=3.10', 'httpx[http2]'],
+  {
+    extras: ['postgres'],
+    groups: ['runtime'],
+  },
+);
 ```
 
-### Direct uv spawning
-
-```mermaid
-graph TD;
-    A[Start uv helper] --> B{Compatible uv available};
-    B -->|Yes| H[Spawn uv with pyfig cache environment];
-    B -->|No| C{Automatic setup enabled};
-    C -->|No| F[Fail without installing];
-    C -->|Yes| I[Download verified platform uv archive];
-    I --> J{Installed uv validates};
-    J -->|No| K[Fail installation];
-    J -->|Yes| H;
-```
-
-## CLI
+Resolution follows the equivalent of:
 
 ```sh
-bunx --bun pyfig
-bunx --bun pyfig --check
-bunx --bun pyfig --python-range '>=3.12.0 <3.14.0' --pip-range '>=24.0.0'
-bunx --bun pyfig --require-embedding --require-gil
-bunx --bun pyfig --project-root /path/to/repository
-bunx --bun pyfig --json
+uv pip compile pyproject.toml /temporary/runtime-dependencies.txt \
+  --extra postgres --group runtime \
+  --python /selected/venv/python \
+  --output-file /temporary/resolved-dependencies.txt
+
+uv pip install \
+  --python /selected/venv/python \
+  -r /temporary/resolved-dependencies.txt
 ```
 
-`bunx --bun` runs the CLI with Bun itself and does not require a separate Node.js executable.
+When no `pyproject.toml` exists, only the temporary dependency input is compiled. Extras and dependency groups require an existing `pyproject.toml`. Pyfig does not use `uv add` or `uv pip sync`: the former would edit project metadata, while the latter could remove unrelated packages from the venv.
+
+![Runtime dependencies are resolved in temporary files before installation](docs/diagrams/runtime-dependencies.png)
+
+[Mermaid source](docs/diagrams/runtime-dependencies.mmd)
 
-`--check` prohibits virtual-environment creation and tool installation, and exits nonzero when no compatible environment exists.
+## Project root
+
+Pyfig does not interpret `package.json`, workspace metadata, `pyproject.toml`, or lockfiles to choose ownership. Root precedence is:
+
+1. `projectRoot`
+2. `PYFIG_PROJECT_ROOT`
+3. nearest Git worktree marker above `INIT_CWD`, when set, otherwise the current directory
+4. that starting directory when no Git marker exists
+
+Set `projectRoot` explicitly in reusable libraries and unusual workspace layouts.
 
 ## Public API
 
 | Export | Responsibility |
 | --- | --- |
-| `createPyfig(options)` | Bind one immutable policy object to preparation and spawn operations. |
-| `ensureEnvironment()` | Return the root venv Python and its safe package manager. |
-| `ensureVirtualEnvironment()` | Return the root venv Python without requiring package tooling. |
-| `ensureUv()` | Return a compatible system uv or the verified managed uv. |
-| `pythonSpawn[Sync]()` | Run the root venv interpreter. |
-| `pipSpawn[Sync]()` | Run package commands against the root venv; mutations require uv. |
-| `uvSpawn[Sync]()` | Run uv; direct `uv pip` calls receive the same strict target policy. |
-| `resolveProjectRoot()` | Resolve workspace, package-manager, Python, or Git ownership. |
-| `clearPyfigCaches()` | Invalidate realm-local validated resolution caches. |
-
-The standalone functions remain convenient for scripts. Long-lived consumers such as Pynect should prefer `createPyfig()` so every call shares one policy and the validated memoization path.
+| `createPyfig(options)` | Create a scoped client with memoized base preparation. |
+| `client.prepare(dependencies?, options?)` | Select a venv and optionally resolve/install runtime dependencies. |
+| `client.pythonInfo()` | Return the selected interpreter and embedding metadata. |
+| `client.uvInfo()` | Return the selected uv executable and version. |
+| `client.uv()` / `client.uvSync()` | Spawn uv and pin pip/run commands to the selected venv. |
+| `ensureEnvironment(options?, dependencies?, dependencyOptions?)` | Standalone preparation API. |
+| `ensureUv(options?)` | Prefer existing uv, otherwise bootstrap verified uv when allowed. |
+| `uvSpawn()` / `uvSpawnSync()` | Standalone uv spawn API. |
+| `resolveProjectRoot(start?)` | Resolve the nearest Git root without reading manifests. |
+
+The package exposes matching ESM and CommonJS entry points. Probe, download, lock, and command-policy internals are not exported.
 
 ## Configuration
 
-Precedence is API/CLI option, environment variable, then default.
+Precedence is API or CLI option, environment variable, then default.
+
+`requiresPython` uses the same PEP 440 specifier syntax as `[project].requires-python` in `pyproject.toml`. Comma-separated clauses, compatible releases (`~=`), exclusions (`!=`), wildcard equality (`==3.12.*`), arbitrary equality (`===`), and pre-release versions are supported. For example: `>=3.10,!=3.12.*,<4`.
 
 | API option | Environment variable | Default |
 | --- | --- | --- |
-| `python` | `PYFIG_PYTHON` | auto-detect |
-| `pythonRange` | `PYFIG_PYTHON_RANGE` | `>=3.10.0 <4.0.0` |
-| `pipRange` | `PYFIG_PIP_RANGE` | `>=20.3.0` |
+| `python` | `PYFIG_PYTHON` | uv discovery |
+| `requiresPython` | `PYFIG_REQUIRES_PYTHON` | `>=3.10,<4` |
 | `managedPython` | `PYFIG_MANAGED_PYTHON` | `3.12` |
 | `uvVersion` | `PYFIG_UV_VERSION` | `0.13.6` |
-| `uvRange` | `PYFIG_UV_RANGE` | `>=0.13.6 <1.0.0` |
+| `uvRange` | `PYFIG_UV_RANGE` | `>=0.10.0 <1.0.0` |
 | `cacheDir` | `PYFIG_HOME` | OS cache directory |
-| `projectRoot` | `PYFIG_PROJECT_ROOT` | auto-detected from current directory |
+| `projectRoot` | `PYFIG_PROJECT_ROOT` | `INIT_CWD`, Git root, or current directory |
 | `requireEmbedding` | `PYFIG_REQUIRE_EMBEDDING` | `false` |
 | `requireGil` | `PYFIG_REQUIRE_GIL` | `false` |
-| `autoInstall` | `PYFIG_AUTO_INSTALL` | `true` (fallback for the three policies below) |
+| `autoInstall` | `PYFIG_AUTO_INSTALL` | `true` |
 | `installPython` | `PYFIG_INSTALL_PYTHON` | `autoInstall` |
 | `installUv` | `PYFIG_INSTALL_UV` | `autoInstall` |
 | `createVirtualEnvironment` | `PYFIG_CREATE_VIRTUAL_ENVIRONMENT` | `autoInstall` |
@@ -165,43 +157,44 @@ Precedence is API/CLI option, environment variable, then default.
 | `installTimeoutMs` | `PYFIG_INSTALL_TIMEOUT_MS` | `600000` |
 | `downloadTimeoutMs` | `PYFIG_DOWNLOAD_TIMEOUT_MS` | `300000` |
 | `coordinationTimeoutMs` | `PYFIG_COORDINATION_TIMEOUT_MS` | install + download + 60 seconds |
-| `cacheTtlMs` | `PYFIG_CACHE_TTL_MS` | `30000` (`0` disables completed-result caching) |
 
-Set `PYFIG_UV` to select an existing uv executable.
+Set `PYFIG_UV` to choose an explicit uv executable. Set `PYFIG_AUTO_INSTALL=0` or use the CLI's `--check` flag on hosts where downloads and environment creation are prohibited.
 
-## Platform support
+## CLI
 
-Pyfig bootstraps uv on x64 and arm64 Windows, macOS, and Linux. Linux uses Astral's fully static musl artifact, which also runs on glibc systems. The practical platform minimums follow uv: Windows 10 or Server 2016 and macOS 13; macOS 12 may work when `realpath` is installed. Other architectures fail before downloading an incorrect artifact.
+```sh
+bunx --bun pyfig
+bunx --bun pyfig --check
+bunx --bun pyfig --requires-python '>=3.12,<3.14'
+bunx --bun pyfig --require-embedding --require-gil
+bunx --bun pyfig --project-root /path/to/repository
+bunx --bun pyfig --json
+```
 
-Node.js 22 through 26 and Bun 1.2+ are supported. Bun-only hosts do not need a `node` executable because synchronous bridges relaunch `process.execPath`. Other JavaScript runtimes are outside the supported contract unless they provide compatible Node built-ins and process semantics.
+`bunx --bun` runs the CLI with Bun and does not require a separate Node.js executable.
 
-## Installation safety
+## Concurrency and installation safety
 
-Pyfig downloads the platform's version-pinned uv archive from Astral's GitHub release, streams it through a bounded request with environment-proxy support, verifies the adjacent SHA-256 checksum, validates the staged executable's exact version, and atomically publishes it into Pyfig's cache. It does not execute an installer script or modify shell profiles.
+Pyfig downloads an exact uv release archive over HTTPS, verifies its adjacent SHA-256 checksum, validates the staged executable version, and atomically publishes it in Pyfig's cache. It does not execute installer scripts or modify shell profiles.
 
-Virtual-environment creation, uv installation, and managed Python installation share one coordination utility with this order:
+Provisioning mutations use Loqkit's layered in-memory, worker, native-file-lock-when-available, and portable-file coordination with capability checks before and after acquisition. uv supplies its own target-environment lock for installs. Base client preparation is memoized; dependency preparation is intentionally rerun so uv can cheaply verify current inputs through its shared cache.
 
-1. Check for a usable tool.
-2. Queue behind the current JavaScript realm's mutex.
-3. Use Node's cross-worker `LockManager` when the runtime provides it.
-4. Use the system `flock` command when it is available and functional.
-5. Acquire the portable heartbeat-based filesystem lease used by every runtime.
-6. Check again and install only when the resource is still absent.
+## Platform support
 
-Long child operations are asynchronous so the filesystem lease heartbeat remains live. uv supplies the separate target-venv lock for package mutations. Resolution results are memoized for a short, configurable interval and revalidated against executable paths before reuse.
+Pyfig bootstraps uv on x64 and arm64 Windows, macOS, and Linux. Linux uses Astral's static musl artifact, which also runs on glibc. Node.js 22.11+ on the 22.x line, Node.js 24.10 through 26.x, and Bun 1.2+ are supported. Other JavaScript runtimes may work when they provide compatible Node built-ins and process semantics.
 
 ## Publishing
 
-Pyfig publishes only from a `v<package-version>` Git tag through `.github/workflows/publish.yml`. The workflow validates the exact tag, rejects a version already present on npm, builds and audits one tarball, and publishes that same archive through npm Trusted Publishing with provenance. It uses the GitHub `npm` environment and does not accept an npm token.
+Pyfig publishes from a `v<package-version>` Git tag through `.github/workflows/publish.yml`. The trusted-publishing workflow validates the tag, rejects an existing registry version, builds and audits one archive, and publishes that archive with provenance.
 
-Before pushing a release tag, commit the matching `package.json` version and run:
+From a clean, synchronized `main` branch:
 
 ```sh
-bun install --frozen-lockfile
-bun run verify
-bun run release:check -- v0.3.0
+bun run release
 ```
 
+The local gate derives the next version from remote GitHub tags, verifies locally, audits the package, commits, tags, and atomically pushes. Use `bun run release -- minor`, `bun run release -- major`, or `bun run release -- --dry-run` as needed. Tag publishing intentionally does not repeat the local test suite.
+
 ## Development
 
 ```sh

package/SECURITY.md

@@ -4,6 +4,6 @@ Pyfig can download Astral uv release archives and can ask uv to download Python
 
 The uv release URL is pinned to an exact validated version and fetched over HTTPS with bounded redirects and timeouts. Pyfig verifies the adjacent SHA-256 checksum, validates the staged executable's reported version, and atomically publishes it into its cache. It never executes an installer script or modifies shell profiles or the host `PATH`. Proxy variables are honored through a per-request dispatcher without logging proxy credentials.
 
-Provisioning uses realm, worker, optional native advisory, and portable filesystem coordination followed by a post-lock capability check. Package mutation uses uv's target-environment lock. Pyfig rejects package-manager arguments and removes environment/configuration values that could redirect an operation away from the repository `.venv`.
+Provisioning uses in-process, worker, optional native advisory, and portable filesystem coordination followed by a post-lock capability check. Runtime dependency mutation uses uv's target-environment lock. Pyfig pins uv commands to the selected venv and removes configuration values that could redirect them. It reads an existing `pyproject.toml` only as a resolver input and never writes project manifests or requirements files.
 
-Executable paths, project roots, version ranges, package specifications, indexes, and proxy settings remain trusted configuration. Do not let an untrusted user choose `python`, `PYFIG_UV`, `cacheDir`, package arguments, or related environment variables in a privileged process. A checksum fetched from the same release protects transfer integrity, not a compromised upstream publisher.
+Executable paths, project roots, version specifiers, package specifications, indexes, and proxy settings remain trusted configuration. Do not let an untrusted user choose `python`, `PYFIG_UV`, `cacheDir`, package arguments, or related environment variables in a privileged process. A checksum fetched from the same release protects transfer integrity, not a compromised upstream publisher.