# uv

Route Python package tooling through `uv`.

## Install / load

Loaded through the root `pi-ext` package.
See [root README](../../README.md).

## Commands / tools / settings

- Commands:
  none
- Tools:
  - `bash` replacement
- Hooks:
  - `session_start`
- Settings:
  none

## Behavior

This extension registers a wrapped `bash` tool.

Operational behavior:

- prepends `intercepted-commands/` to `PATH` on Unix
- blocks `pip` and `pip3` with `uv add` / `uv run --with` guidance
- blocks `poetry` with `uv init`, `uv add`, `uv sync`, and `uv run` guidance
- blocks explicit `python -m pip`, `python -m venv`, and `python -m py_compile`
- routes `python` and `python3` PATH shim calls through `uv run --python <real-python> python`
- avoids shim recursion by resolving a Python interpreter outside `intercepted-commands/`
- skips extensionless shell shims on Windows; spawn-time blockers still apply
- warns on session start when `uv` is missing from `PATH`

Explicit interpreter paths can bypass PATH shims.
Spawn-time blockers still catch `python -m pip`, `python -m venv`, and `python -m py_compile`.

## Debug

Opt-in metadata diagnostics: [debug contract](../DEBUG.md).
Safe events: `session.start`, `session.shutdown`, `availability.check.start`, `availability.check.finish`, `availability.check.error`.

## Performance

Every Bash execution runs the spawn hook, so command matchers and static guidance are initialized once instead of rebuilt per call.
POSIX uses the case-sensitive `PATH` key directly; Windows retains case-insensitive lookup where required.
`mise run //extensions/uv:bench` measures allowed-command checks, blocked-command checks, and PATH rewriting with a 100-variable environment.
`mise run //extensions/uv:profile` records a Node CPU profile under `.research/uv`.
`mise run //extensions/uv:benchstat <baseline> <candidate>` performs statistical comparison.