pyfig 0.4.0 → 0.6.0

package/README.md

@@ -16,7 +16,8 @@ bun add pyfig
 import { createPyfig } from 'pyfig';
 
 const pyfig = createPyfig({
-  pythonRange: '>=3.11.0 <4.0.0',
+  requiresPython: '>=3.11,<4',
+  requiresUv: '>=0.10,<1',
   requireEmbedding: true,
   requireGil: true,
 });
@@ -36,7 +37,7 @@ await pyfig.uv(
 );
 ```
 
-`prepare()` accepts runtime requirement strings plus optional `extras`, `groups`, or `allExtras`. If the project has a `pyproject.toml`, uv resolves that read-only input together with a temporary requirements 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.
+`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:
 
@@ -89,19 +90,19 @@ await pyfig.prepare(
 Resolution follows the equivalent of:
 
 ```sh
-uv pip compile pyproject.toml /temporary/runtime-requirements.txt \
+uv pip compile pyproject.toml /temporary/runtime-dependencies.txt \
   --extra postgres --group runtime \
   --python /selected/venv/python \
-  --output-file /temporary/resolved-requirements.txt
+  --output-file /temporary/resolved-dependencies.txt
 
 uv pip install \
   --python /selected/venv/python \
-  -r /temporary/resolved-requirements.txt
+  -r /temporary/resolved-dependencies.txt
 ```
 
-When no `pyproject.toml` exists, only the temporary requirements 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.
+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 requirements are resolved in temporary files before installation](docs/diagrams/runtime-dependencies.png)
+![Runtime dependencies are resolved in temporary files before installation](docs/diagrams/runtime-dependencies.png)
 
 [Mermaid source](docs/diagrams/runtime-dependencies.mmd)
 
@@ -121,11 +122,11 @@ Set `projectRoot` explicitly in reusable libraries and unusual workspace layouts
 | Export | Responsibility |
 | --- | --- |
 | `createPyfig(options)` | Create a scoped client with memoized base preparation. |
-| `client.prepare(requirements?, options?)` | Select a venv and optionally resolve/install runtime dependencies. |
+| `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?, requirements?, dependencyOptions?)` | Standalone preparation API. |
+| `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. |
@@ -136,13 +137,14 @@ The package exposes matching ESM and CommonJS entry points. Probe, download, loc
 
 Precedence is API or CLI option, environment variable, then default.
 
+`requiresPython` and `requiresUv` use PEP 440 specifiers. Comma-separated clauses, compatible releases (`~=`), exclusions (`!=`), wildcard equality, arbitrary equality (`===`), and pre-release versions are supported. For example: `requiresPython: '>=3.10,!=3.12.*,<4'` and `requiresUv: '==0.13.*'`. Pyfig reuses a compatible installed or cached uv first. When installation is necessary, it resolves the greatest published uv release satisfying `requiresUv` and containing the required platform assets.
+
 | API option | Environment variable | Default |
 | --- | --- | --- |
 | `python` | `PYFIG_PYTHON` | uv discovery |
-| `pythonRange` | `PYFIG_PYTHON_RANGE` | `>=3.10.0 <4.0.0` |
+| `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.10.0 <1.0.0` |
+| `requiresUv` | `PYFIG_REQUIRES_UV` | `>=0.10,<1` |
 | `cacheDir` | `PYFIG_HOME` | OS cache directory |
 | `projectRoot` | `PYFIG_PROJECT_ROOT` | `INIT_CWD`, Git root, or current directory |
 | `requireEmbedding` | `PYFIG_REQUIRE_EMBEDDING` | `false` |
@@ -163,7 +165,8 @@ Set `PYFIG_UV` to choose an explicit uv executable. Set `PYFIG_AUTO_INSTALL=0` o
 ```sh
 bunx --bun pyfig
 bunx --bun pyfig --check
-bunx --bun pyfig --python-range '>=3.12.0 <3.14.0'
+bunx --bun pyfig --requires-python '>=3.12,<3.14'
+bunx --bun pyfig --requires-uv '>=0.12,<1'
 bunx --bun pyfig --require-embedding --require-gil
 bunx --bun pyfig --project-root /path/to/repository
 bunx --bun pyfig --json
@@ -173,13 +176,13 @@ bunx --bun pyfig --json
 
 ## Concurrency and installation safety
 
-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.
+Pyfig resolves a compatible uv release from Astral's GitHub releases, downloads that exact archive over HTTPS, verifies its adjacent SHA-256 checksum, validates the staged executable version, and atomically publishes it in Pyfig's cache. A compatible cached executable is probed locally without a network request. Release metadata is cached on disk for 24 hours; stale metadata is refreshed under a Loqkit lock and remains available as a fallback when GitHub's API is temporarily unavailable. Pyfig does not execute installer scripts or modify shell profiles.
 
-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.
+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. Compatible managed uv executables are cached by resolved version; Loqkit coordinates both the `requiresUv` policy lookup and exact release publication. 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.
 
 ## Platform support
 
-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 through 26 and Bun 1.2+ are supported. Other JavaScript runtimes may work when they provide compatible Node built-ins and process semantics.
+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
 

package/SECURITY.md

@@ -2,8 +2,8 @@
 
 Pyfig can download Astral uv release archives and can ask uv to download Python distributions. Automatic installation is enabled by default; set `autoInstall: false`, pass `--check`, or set `PYFIG_AUTO_INSTALL=0` when downloads are not allowed.
 
-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.
+Pyfig resolves a uv release allowed by `requiresUv`, then fetches that exact release URL over HTTPS with bounded redirects and timeouts. GitHub release metadata is cached for 24 hours under Loqkit coordination, with validated stale metadata available if refresh fails. 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 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.