feat: uvx parity + --env-prefix shorthand (#4)

* feat: expose uvx with full parity to uv

Extract uvx binary from the uv release archive alongside uv, create bin/uvx
wrappers/symlinks, export $REDMATTER_UVX via env.sh/env.ps1/env.bat, and
record uvx_env in the installed distro.toml. Update README and TESTING docs.

* feat: generate env.sh on Windows for Git Bash compatibility

* feat: add --env-prefix option to derive env var names from a common prefix

Callers can now pass --env-prefix REDMATTER instead of spelling out
--uv-env REDMATTER_UV --uvx-env REDMATTER_UVX --python-env REDMATTER_PYTHON.

The two styles are mutually exclusive; mixing them or omitting both
produces a clear error. Existing invocations using the individual flags
are unchanged.

* docs/fix: address PR review — uvx null guard, install.sh comment, README env-prefix examples

---------

Co-authored-by: Dino Korah <691011+codemedic@users.noreply.github.com>

Author: codemedic

README.md

@@ -41,8 +41,7 @@ Expand-Archive managed-python.zip
 ./install.sh \
   --prefix ~/.local/redmatter/python \
   --python 3.10 \
-  --uv-env REDMATTER_UV \
-  --python-env REDMATTER_PYTHON
+  --env-prefix REDMATTER
 
 source ~/.local/redmatter/python/env.sh
 ```
@@ -53,8 +52,7 @@ source ~/.local/redmatter/python/env.sh
 .\install.ps1 `
   -Prefix "$env:USERPROFILE\.local\redmatter\python" `
   -Python "3.10" `
-  -UvEnv "REDMATTER_UV" `
-  -PythonEnv "REDMATTER_PYTHON"
+  -EnvPrefix "REDMATTER"
 
 . "$env:USERPROFILE\.local\redmatter\python\env.ps1"
 ```
@@ -66,14 +64,14 @@ source ~/.local/redmatter/python/env.sh
 > **PowerShell** — evaluate `env.ps1` as a string (bypasses script execution policy):
 >
 > ```powershell
-> install.bat -Prefix "$env:USERPROFILE\.local\redmatter\python" -Python "3.10" -UvEnv "REDMATTER_UV" -PythonEnv "REDMATTER_PYTHON"
+> install.bat -Prefix "$env:USERPROFILE\.local\redmatter\python" -Python "3.10" -EnvPrefix "REDMATTER"
 > Invoke-Expression (Get-Content "$env:USERPROFILE\.local\redmatter\python\env.ps1" -Raw)
 > ```
 >
 > **CMD** — use `call` to load `env.bat` into the current session:
 >
 > ```bat
-> install.bat -Prefix "%USERPROFILE%\.local\redmatter\python" -Python "3.10" -UvEnv "REDMATTER_UV" -PythonEnv "REDMATTER_PYTHON"
+> install.bat -Prefix "%USERPROFILE%\.local\redmatter\python" -Python "3.10" -EnvPrefix "REDMATTER"
 > call "%USERPROFILE%\.local\redmatter\python\env.bat"
 > ```
 >
@@ -86,8 +84,7 @@ source ~/.local/redmatter/python/env.sh
 ./install.sh \
   --prefix ~/.local/redmatter/python \
   --python 3.10 \
-  --uv-env REDMATTER_UV \
-  --python-env REDMATTER_PYTHON \
+  --env-prefix REDMATTER \
   --quiet
 
 source ~/.local/redmatter/python/env.sh
@@ -100,12 +97,16 @@ source ~/.local/redmatter/python/env.sh
 |------|----------|---------|
 | `--prefix PATH` | yes | Install location |
 | `--python X.Y` | yes | Python version for venv. Default mode: prefer matching system Python, fall back to uv-managed. Isolated mode: always uv-managed. |
-| `--uv-env NAME` | yes | Env var name for the uv binary path |
-| `--python-env NAME` | yes | Env var name for the python binary path |
+| `--env-prefix NAME` | yes* | Derives `NAME_UV`, `NAME_UVX`, and `NAME_PYTHON` — preferred over the three flags below |
+| `--uv-env NAME` | yes* | Env var name for the uv binary path |
+| `--uvx-env NAME` | yes* | Env var name for the uvx binary path |
+| `--python-env NAME` | yes* | Env var name for the python binary path |
 | `--isolated` | no | Force uv-managed Python (ignores system Python); always adds `bin/` to PATH |
 | `--shell-profile` | no | Append `source <prefix>/env.sh` to shell rc |
 | `--quiet` / `-q` | no | Suppress all output except warnings |
 
+\* Use either `--env-prefix` **or** all three of `--uv-env` / `--uvx-env` / `--python-env` — they are mutually exclusive.
+
 > [!NOTE]
 > **Choosing a mode:** Use the default on developer machines where a system Python already exists. Use `--isolated` in CI, containers, or shared servers where you need a fully reproducible environment independent of whatever Python is (or isn't) installed on the host.
 
@@ -118,6 +119,9 @@ source ~/.local/redmatter/python/env.sh
 # Run a script with dependencies (pyproject.toml in app dir)
 "$REDMATTER_UV" run --project /path/to/app my-script.py
 
+# Run a tool without installing it
+"$REDMATTER_UVX" ruff --version
+
 # Install a package into the shared venv (use sparingly)
 "$REDMATTER_UV" pip install --python "$REDMATTER_PYTHON" some-package
 
@@ -131,11 +135,14 @@ exec "$PYTHON" script.py
 ```text
 <prefix>/
   uv                          # uv binary
+  uvx                         # uvx binary
   bin/
     python -> ../venv/bin/python   # symlink (Linux/macOS)
     uv -> ../uv                    # symlink (Linux/macOS)
+    uvx -> ../uvx                  # symlink (Linux/macOS)
     python.cmd                     # wrapper (Windows)
     uv.cmd                         # wrapper (Windows)
+    uvx.cmd                        # wrapper (Windows)
   venv/
     bin/python                # Linux/macOS
     Scripts/python.exe        # Windows
@@ -158,6 +165,7 @@ uv_version = "0.10.6"
 prefix       = "/home/user/.local/redmatter/python"
 python       = "3.10"
 uv_env       = "REDMATTER_UV"
+uvx_env      = "REDMATTER_UVX"
 python_env   = "REDMATTER_PYTHON"
 shell_profile = false
 isolated      = false

TESTING.md

@@ -16,18 +16,18 @@ rm -rf /tmp/mp-test
 
 ```bash
 ./install.sh --prefix /tmp/mp-test --python 3.10 \
-  --uv-env TEST_UV --python-env TEST_PYTHON
+  --uv-env TEST_UV --uvx-env TEST_UVX --python-env TEST_PYTHON
 ```
 
 **Expect:**
 
 - uv downloaded (or skipped if already current)
 - venv created using system Python if a matching version exists, otherwise uv-managed
-- `distro.toml` contains `isolated = false`
-- `env.sh` contains `export PATH=...` (system python found → shadow warning; no system python → silently added)
+- `distro.toml` contains `isolated = false` and `uvx_env = "TEST_UVX"`
+- `env.sh` contains `export TEST_UVX=...` and `export PATH=...` (system python found → shadow warning; no system python → silently added)
 
 ```bash
-grep -A7 '^\[install\]' /tmp/mp-test/distro.toml
+grep -A8 '^\[install\]' /tmp/mp-test/distro.toml
 cat /tmp/mp-test/env.sh
 ```
 
@@ -36,7 +36,7 @@ cat /tmp/mp-test/env.sh
 ```bash
 rm -rf /tmp/mp-test
 ./install.sh --prefix /tmp/mp-test --python 3.10 \
-  --uv-env TEST_UV --python-env TEST_PYTHON --isolated
+  --uv-env TEST_UV --uvx-env TEST_UVX --python-env TEST_PYTHON --isolated
 ```
 
 **Expect:**
@@ -47,7 +47,7 @@ rm -rf /tmp/mp-test
 - `venv/bin/python` is a uv-managed build (not `/usr/bin/python*`)
 
 ```bash
-grep -A7 '^\[install\]' /tmp/mp-test/distro.toml
+grep -A8 '^\[install\]' /tmp/mp-test/distro.toml
 cat /tmp/mp-test/env.sh
 /tmp/mp-test/venv/bin/python --version
 ```
@@ -56,7 +56,7 @@ cat /tmp/mp-test/env.sh
 
 ```bash
 ./install.sh --prefix /tmp/mp-test --python 3.10 \
-  --uv-env TEST_UV --python-env TEST_PYTHON --isolated
+  --uv-env TEST_UV --uvx-env TEST_UVX --python-env TEST_PYTHON --isolated
 ```
 
 **Expect:**
@@ -69,7 +69,7 @@ cat /tmp/mp-test/env.sh
 
 ```bash
 ./install.sh --prefix /tmp/mp-test --min-python 3.10 \
-  --uv-env TEST_UV --python-env TEST_PYTHON
+  --uv-env TEST_UV --uvx-env TEST_UVX --python-env TEST_PYTHON
 ```
 
 **Expect:** exits with `ERROR: --python is required`
@@ -90,19 +90,19 @@ Remove-Item -Recurse -Force C:\Users\Quickemu\temp\mp-test -ErrorAction Silently
 
 ```powershell
 .\install.ps1 -Prefix "C:\Users\Quickemu\temp\mp-test" -Python "3.10" `
-  -UvEnv "TEST_UV" -PythonEnv "TEST_PYTHON"
+  -UvEnv "TEST_UV" -UvxEnv "TEST_UVX" -PythonEnv "TEST_PYTHON"
 Get-Content C:\Users\Quickemu\temp\mp-test\distro.toml
 Get-Content C:\Users\Quickemu\temp\mp-test\env.ps1
 ```
 
-**Expect:** `isolated = false` in distro.toml; PATH added only if no system python/uv found.
+**Expect:** `isolated = false` and `uvx_env = "TEST_UVX"` in distro.toml; PATH added only if no system python/uv found.
 
 ### Test 2 — Isolated
 
 ```powershell
 Remove-Item -Recurse -Force C:\Users\Quickemu\temp\mp-test
 .\install.ps1 -Prefix "C:\Users\Quickemu\temp\mp-test" -Python "3.10" `
-  -UvEnv "TEST_UV" -PythonEnv "TEST_PYTHON" -Isolated
+  -UvEnv "TEST_UV" -UvxEnv "TEST_UVX" -PythonEnv "TEST_PYTHON" -Isolated
 Get-Content C:\Users\Quickemu\temp\mp-test\distro.toml
 Get-Content C:\Users\Quickemu\temp\mp-test\env.ps1
 & "C:\Users\Quickemu\temp\mp-test\venv\Scripts\python.exe" --version
@@ -114,7 +114,7 @@ Get-Content C:\Users\Quickemu\temp\mp-test\env.ps1
 
 ```powershell
 .\install.ps1 -Prefix "C:\Users\Quickemu\temp\mp-test" -Python "3.10" `
-  -UvEnv "TEST_UV" -PythonEnv "TEST_PYTHON" -Isolated
+  -UvEnv "TEST_UV" -UvxEnv "TEST_UVX" -PythonEnv "TEST_PYTHON" -Isolated
 ```
 
 **Expect:** uv and venv skipped; env files regenerated.
@@ -123,7 +123,7 @@ Get-Content C:\Users\Quickemu\temp\mp-test\env.ps1
 
 ```powershell
 .\install.ps1 -Prefix "C:\Users\Quickemu\temp\mp-test" -MinPython "3.10" `
-  -UvEnv "TEST_UV" -PythonEnv "TEST_PYTHON"
+  -UvEnv "TEST_UV" -UvxEnv "TEST_UVX" -PythonEnv "TEST_PYTHON"
 ```
 
 **Expect:** PowerShell parameter binding error — `-MinPython` is not a recognised parameter.

install.ps1

@@ -8,20 +8,41 @@
     All configuration (env.ps1, env.sh, bin\ wrappers, shell profile) is
     handled by setup.py.
 
+.EXAMPLE
+    .\install.ps1 -Prefix "$env:USERPROFILE\.local\redmatter\python" -Python "3.10" -EnvPrefix "REDMATTER"
+
 .EXAMPLE
     .\install.ps1 -Prefix "$env:USERPROFILE\.local\redmatter\python" `
-                  -Python "3.10" -UvEnv "REDMATTER_UV" -PythonEnv "REDMATTER_PYTHON"
+                  -Python "3.10" -UvEnv "REDMATTER_UV" -UvxEnv "REDMATTER_UVX" -PythonEnv "REDMATTER_PYTHON"
 #>
 param(
     [Parameter(Mandatory=$true)]  [string]$Prefix,
     [Parameter(Mandatory=$true)]  [string]$Python,
-    [Parameter(Mandatory=$true)]  [string]$UvEnv,
-    [Parameter(Mandatory=$true)]  [string]$PythonEnv,
+    [Parameter(Mandatory=$false)] [string]$EnvPrefix,
+    [Parameter(Mandatory=$false)] [string]$UvEnv,
+    [Parameter(Mandatory=$false)] [string]$UvxEnv,
+    [Parameter(Mandatory=$false)] [string]$PythonEnv,
     [switch]$ShellProfile,
     [switch]$Quiet,
     [switch]$Isolated
 )
 
+if ($EnvPrefix) {
+    if ($UvEnv -or $UvxEnv -or $PythonEnv) {
+        Write-Error "-EnvPrefix cannot be combined with -UvEnv, -UvxEnv, or -PythonEnv"
+        exit 1
+    }
+} else {
+    $missing = @()
+    if (-not $UvEnv)     { $missing += "-UvEnv" }
+    if (-not $UvxEnv)    { $missing += "-UvxEnv" }
+    if (-not $PythonEnv) { $missing += "-PythonEnv" }
+    if ($missing.Count -gt 0) {
+        Write-Error "The following parameters are required: $($missing -join ', ') (or use -EnvPrefix)"
+        exit 1
+    }
+}
+
 function Write-Msg($msg) { if (-not $Quiet) { Write-Host $msg } }
 
 Set-StrictMode -Version Latest
@@ -72,6 +93,9 @@ if ($currentVer -eq $UvVersion) {
         Expand-Archive $tmp $tmpDir -Force
         $uvSrc = Get-ChildItem $tmpDir -Filter "uv.exe" -Recurse | Select-Object -First 1
         Copy-Item $uvSrc.FullName $UvExe -Force
+        $uvxSrc = Get-ChildItem $tmpDir -Filter "uvx.exe" -Recurse | Select-Object -First 1
+        if (-not $uvxSrc) { Write-Error "Failed to locate uvx.exe in archive"; exit 1 }
+        Copy-Item $uvxSrc.FullName (Join-Path $Prefix "uvx.exe") -Force
     } catch {
         Write-Error "Failed to download uv $UvVersion from $url`: $_"
         exit 1
@@ -108,7 +132,11 @@ if (Test-Path $VenvPy) {
 Write-Msg ""
 
 # Hand off to setup.py
-$setupArgs = @("--prefix", $Prefix, "--python", $Python, "--uv-env", $UvEnv, "--python-env", $PythonEnv)
+if ($EnvPrefix) {
+    $setupArgs = @("--prefix", $Prefix, "--python", $Python, "--env-prefix", $EnvPrefix)
+} else {
+    $setupArgs = @("--prefix", $Prefix, "--python", $Python, "--uv-env", $UvEnv, "--uvx-env", $UvxEnv, "--python-env", $PythonEnv)
+}
 if ($ShellProfile) { $setupArgs += "--shell-profile" }
 if ($Isolated) { $setupArgs += "--isolated" }
 if ($Quiet) { $setupArgs += "--quiet" }

install.sh

@@ -88,6 +88,13 @@ _bootstrap_uv() {
     fi
     cp "$uv_src" "$uv_bin"
     chmod +x "$uv_bin"
+    local uvx_src
+    uvx_src="$(find "$tmp" -name "uvx" -type f | head -1 || true)"
+    if [[ -z "$uvx_src" || ! -f "$uvx_src" ]]; then
+        printf "ERROR: failed to locate uvx binary in downloaded archive\n" >&2; exit 1
+    fi
+    cp "$uvx_src" "${prefix}/uvx"
+    chmod +x "${prefix}/uvx"
     _msg "  ✓ uv $uv_version installed"
 }
 
@@ -146,6 +153,8 @@ main() {
     _bootstrap_venv "$prefix" "$min_python" "$isolated"
 
     _msg ""
+    # All flags (including --env-prefix / --uv-env / --uvx-env / --python-env) are forwarded
+    # verbatim to setup.py, which owns env var name resolution and validation.
     exec "${prefix}/venv/bin/python" "${script_dir}/setup.py" "$@"
 }