pyfig 0.6.3 → 0.7.1

package/README.md

@@ -1,8 +1,8 @@
 # pyfig
 
-`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`.
+`pyfig` resolves compatible uv and Python executables from Node.js or Bun and
+exposes one guarded `uv run` spawn method. Its only managed state is a uv tool
+cache; uv retains responsibility for Python, environments, and dependencies.
 
 ## Install
 
@@ -10,193 +10,100 @@ Pyfig never invokes standalone `pip`, never writes `pyproject.toml` or requireme
 bun add pyfig
 ```
 
+Pyfig reuses a compatible uv from `PATH` or its OS cache. When neither exists,
+it installs the greatest official uv release allowed by the requested version.
+Python discovery and managed installation are delegated to
+[`uv python find`](https://docs.astral.sh/uv/reference/cli/#uv-python-find).
+
 ## Use
 
 ```ts
-import { createPyfig } from 'pyfig';
+import { pyfig } from 'pyfig';
 
-const pyfig = createPyfig({
-  requiresPython: '>=3.11,<4',
-  requiresUv: '>=0.10,<1',
+const python = await pyfig({
+  uv: '>=0.10,<1',
+  python: '>=3.11,<4',
   requireEmbedding: true,
   requireGil: true,
 });
 
-const environment = await pyfig.prepare(
-  ['requests>=2.32'],
-  { extras: ['database'] },
-);
-
-console.log(environment.uv);
-console.log(environment.python);
-console.log(environment.managed);
-
-await pyfig.uv(
-  ['run', '--', 'python', 'script.py'],
-  { stdio: 'inherit' },
-);
-```
-
-`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:
+console.log(python.uv);
+console.log(python.python);
 
-```ts
-import { uvSpawn, uvSpawnSync } from 'pyfig';
-
-await uvSpawn(['pip', 'list'], { stdio: 'inherit' });
-
-const result = uvSpawnSync(
-  ['run', '--', 'python', '-c', 'import sys; print(sys.executable)'],
-  { encoding: 'utf8' },
-);
+python.run('python', '--version', { stdio: 'inherit' });
 ```
 
-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.
-
-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.
-
-## Selection policy
-
-Pyfig uses this order:
-
-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.
+`pyfig()` returns a `PythonContext` containing:
 
-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.
-
-![Pyfig prefers existing uv, compatible venvs, and system Python before managed downloads](docs/diagrams/python-selection.png)
-
-[Mermaid source](docs/diagrams/python-selection.mmd)
-
-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.
+| Field | Meaning |
+| --- | --- |
+| `uv` | Absolute path to the resolved uv executable. |
+| `python` | Absolute path to the resolved Python interpreter. |
+| `run(...args)` | Spawn `uv run` with that Python interpreter. |
 
-## Runtime dependency resolution
+`run()` treats a final object as Node `SpawnOptions`. When no `--` argument is
+present, every string is treated as command argv:
 
 ```ts
-await pyfig.prepare(
-  ['orjson>=3.10', 'httpx[http2]'],
-  {
-    extras: ['postgres'],
-    groups: ['runtime'],
-  },
-);
+python.run('python', '--version');
+// uv run --python /resolved/python -- python --version
 ```
 
-Resolution follows the equivalent of:
+When `--` is present, strings before it are passed to uv and strings after it
+are command argv:
 
-```sh
-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
+```ts
+python.run('--no-project', '--with', 'httpx', '--', 'python', 'script.py', {
+  cwd: '/workspace',
+  stdio: 'inherit',
+});
 ```
 
-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)
-
-## 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.
+Pyfig inserts `--python <python>` immediately before the separator. Caller
+supplied `--python <value>` and `--python=<value>` arguments are rejected before
+`--`; Python is selected only by `pyfig()`. A `--python` appearing after
+`--` belongs to the command and is left untouched.
 
-## Public API
+`pyfig()` accepts:
 
-| Export | Responsibility |
-| --- | --- |
-| `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 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.
-
-When embedding files are available, `PythonInfo.embedding.stableAbiLibraryPath` identifies the platform's Python 3 Stable ABI import library when the installation provides one. Consumers can use it to build a single Limited API binary for multiple CPython 3 minor versions while retaining `libraryPath` for version-specific embedding.
-
-| API option | Environment variable | Default |
+| Option | Default | Meaning |
 | --- | --- | --- |
-| `python` | `PYFIG_PYTHON` | uv discovery |
-| `requiresPython` | `PYFIG_REQUIRES_PYTHON` | `>=3.10,<4` |
-| `managedPython` | `PYFIG_MANAGED_PYTHON` | `3.12` |
-| `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` |
-| `requireGil` | `PYFIG_REQUIRE_GIL` | `false` |
-| `autoInstall` | `PYFIG_AUTO_INSTALL` | `true` |
-| `installPython` | `PYFIG_INSTALL_PYTHON` | `autoInstall` |
-| `installUv` | `PYFIG_INSTALL_UV` | `autoInstall` |
-| `createVirtualEnvironment` | `PYFIG_CREATE_VIRTUAL_ENVIRONMENT` | `autoInstall` |
-| `probeTimeoutMs` | `PYFIG_PROBE_TIMEOUT_MS` | `10000` |
-| `installTimeoutMs` | `PYFIG_INSTALL_TIMEOUT_MS` | `600000` |
-| `downloadTimeoutMs` | `PYFIG_DOWNLOAD_TIMEOUT_MS` | `300000` |
-| `coordinationTimeoutMs` | `PYFIG_COORDINATION_TIMEOUT_MS` | install + download + 60 seconds |
-
-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.
-
-## CLI
-
-```sh
-bunx --bun pyfig
-bunx --bun pyfig --check
-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
-```
-
-`bunx --bun` runs the CLI with Bun and does not require a separate Node.js executable.
-
-## Concurrency and installation safety
-
-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. Set `GITHUB_TOKEN` or `GH_TOKEN` to authenticate release discovery on CI and other rate-limited hosts. Pyfig does not execute installer scripts or modify shell profiles.
+| `uv` | `>=0.10,<1` | uv executable or PEP 440 version constraint. |
+| `python` | system, then managed | Python executable or PEP 440 version constraint. |
+| `requireEmbedding` | `false` | Require CPython headers, a linkable library, and matching architecture. |
+| `requireGil` | `false` | Reject free-threaded Python builds. |
+| `cwd` | `process.cwd()` | Directory used for uv configuration and project discovery. |
+| `env` | `process.env` | Environment used to locate executables and invoke child processes. |
+
+For both `uv` and `python`, Pyfig first checks whether the value resolves to an
+executable. An executable wins over version parsing. An explicit uv executable
+is trusted without a version check or setup. An explicit Python executable skips
+version selection and installation, but it must still be a working Python and
+satisfy requested embedding, architecture, and GIL capabilities. A value that
+is not executable must be a valid PEP 440 specifier.
+
+For a Python version specifier, Pyfig first asks uv for a matching system
+interpreter. If it is absent or fails the requested capabilities, Pyfig asks uv
+for a managed interpreter. For a uv version specifier, Pyfig checks `PATH`, then
+its cache, then downloads a matching checksum-verified release. Cached
+executables are used without a metadata or network request. Release metadata is
+cached for 24 hours and refreshed under Loqkit's layered check-lock-check flow.
+The cache lives below `%LOCALAPPDATA%\pyfig` on Windows,
+`~/Library/Caches/pyfig` on macOS, and `${XDG_CACHE_HOME:-~/.cache}/pyfig` on
+Linux.
+
+Executable paths can be used directly:
 
-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.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 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.
-
-From a clean, synchronized `main` branch:
-
-```sh
-bun run release
+```ts
+const python = await pyfig({
+  uv: '/opt/bin/uv',
+  python: '/opt/python/bin/python3',
+  requireEmbedding: true,
+});
 ```
 
-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.
+The runtime package exports `pyfig` and `PythonContext`. TypeScript also exposes
+`PyfigOptions`. Matching ESM and CommonJS entry points are published.
 
 ## Development
 
@@ -204,7 +111,11 @@ The local gate derives the next version from remote GitHub tags, verifies locall
 bun install --ignore-scripts
 bun run verify
 bun run build
-bun pm pack --dry-run
 ```
 
-MIT licensed.
+## Publishing
+
+From a clean, synchronized `main` branch, `bun run release` verifies locally,
+builds and audits the package, commits the next version, creates its Git tag,
+and pushes both atomically. The tag workflow publishes that exact package to
+npm through trusted publishing.

package/SECURITY.md

@@ -1,9 +1,20 @@
 # Security
 
-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.
+Pyfig spawns only the uv executable resolved from `uv`, found on `PATH`, or
+installed in its OS cache. Setup downloads an official Astral release archive
+and adjacent SHA-256 checksum over HTTPS, verifies the archive before
+publication, and probes the staged executable. It never runs an installer
+script, invokes a shell by default, or modifies shell and project configuration.
 
-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.
+Compatible cached uv executables are used without network access. GitHub release
+metadata is cached for 24 hours, with valid stale metadata retained as a network
+fallback. Cache publication and metadata refresh use Loqkit's in-memory,
+worker, native-flock-when-available, and portable file-lock coordination.
 
-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 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.
+The executable path, working directory, environment, version requests, uv
+arguments, command arguments, and spawn options are trusted caller input. The
+`run()` method can execute arbitrary commands, and callers can explicitly
+enable shell execution through `SpawnOptions`. uv owns Python discovery and
+managed-Python downloads. Supply an explicit uv executable or pre-populate the
+cache when setup downloads are prohibited, and configure uv itself when Python
+downloads must be offline or restricted by organizational policy.