feat: uvx parity + --env-prefix shorthand

[codemedic]

Summary

• --env-prefix option (setup.py, install.ps1): callers can now pass a single prefix (e.g. REDMATTER) instead of spelling out all three env var names individually. The prefix derives {PREFIX}_UV, {PREFIX}_UVX, and {PREFIX}_PYTHON automatically.
• Mutual exclusivity enforced: mixing --env-prefix with any of --uv-env/--uvx-env/--python-env errors with a clear message; omitting both also errors. Existing invocations using explicit flags are unchanged.
• Windows parity (install.ps1): added -EnvPrefix parameter with matching validation; $setupArgs construction branches on which style is used.
• env.sh on Windows (install.ps1): generates env.sh for Git Bash compatibility alongside env.ps1.

Test plan

• bash install.sh --prefix /tmp/test-mp --python 3.10 --env-prefix REDMATTER — succeeds; generated env.sh exports REDMATTER_UV, REDMATTER_UVX, REDMATTER_PYTHON
• bash install.sh --prefix /tmp/test-mp --python 3.10 --uv-env FOO_UV --uvx-env FOO_UVX --python-env FOO_PY — succeeds as before
• bash install.sh --prefix /tmp/test-mp --python 3.10 --env-prefix REDMATTER --uv-env CUSTOM — errors with clear message
• bash install.sh --prefix /tmp/test-mp --python 3.10 — errors, prompts to use --env-prefix or individual flags

[orca-security-eu]

Orca Security Scan Summary

Status	Check	Issues by priority
Passed	Infrastructure as Code	0   0   0   0	View in Orca
Passed	SAST	0   0   0   0	View in Orca
Passed	Secrets	0   0   0   0	View in Orca
Passed	Vulnerabilities	0   0   0   0	View in Orca

[oliver-cieliszak-natterbox]

PR Review: feat: uvx parity + --env-prefix shorthand

+143 / -43 across 5 files

---

Positives

• Consistent pattern: every place uv was handled now has a matching uvx entry — no spots missed.
• --env-prefix validation is tight on both setup.py and install.ps1 — mutual exclusivity and missing-field checks are correct.
• _to_sh_path() for Windows Git Bash compatibility is a nice touch.
• Docs, test matrix, and distro.toml format all updated in lockstep.

---

Issues & Suggestions

1. install.sh vs install.ps1 asymmetry (low)

install.ps1 explicitly parses -EnvPrefix while install.sh silently forwards "$@" to setup.py. This works, but the asymmetry could confuse future maintainers — worth a comment in install.sh noting that --env-prefix is handled by setup.py directly.

2. Missing uvx.exe null guard in install.ps1 (medium)

$uvxSrc = Get-ChildItem $tmpDir -Filter "uvx.exe" -Recurse | Select-Object -First 1
Copy-Item $uvxSrc.FullName (Join-Path $Prefix "uvx.exe") -Force

If uvx.exe isn't in the archive, $uvxSrc is $null and .FullName blows up with a confusing error. The install.sh equivalent correctly guards against this. Suggestion:

if (-not $uvxSrc) { Write-Error "Failed to locate uvx.exe in archive"; exit 1 }

3. Positional arg ordering is a maintenance risk (low, follow-up)

_write_env_sh, _write_env_ps1, _write_env_bat, and _write_installed_distro_toml all take uv_env, uvx_env, python_env as positional args. With 6–8 positional parameters it's easy to silently swap two. Consider bundling into a dataclass or using keyword-only args in a follow-up.

4. README could lead with --env-prefix (nit)

The first usage example still shows the verbose --uv-env / --uvx-env / --python-env form. Since --env-prefix is the simpler happy path, consider leading with it.

---

Verdict

Approve with one requested change: add the null guard for $uvxSrc in install.ps1 (item 2). The rest are nits/suggestions for follow-up.

[codemedic]

All addressed:

• Item 1 — added a comment in install.sh at the exec line explaining that --env-prefix (and all other flags) are forwarded verbatim to setup.py, which owns env var name resolution.
• Item 2 — null guard added for $uvxSrc in install.ps1, matching the existing pattern for $uvSrc.
• Item 3 — skipped. With 5 positional args (not 6–8), clear names, type hints, and all call sites in one function, the practical risk is low. Happy to revisit if the signature grows.
• Item 4 — README Quick Start, scripted install, install.bat examples, and the Options table all updated to lead with --env-prefix.