feat: rename --min-python to --python, add --isolated flag

- --python replaces --min-python across install.sh, install.ps1, setup.py
- Default mode passes --python-preference system to uv: prefer system
  Python, fall back to uv-managed if no match
- --isolated passes --python-preference only-managed: always use a
  uv-managed Python, unconditionally adds bin/ to PATH in env files
- distro.toml [install] section records python and isolated keys
- README updated with revised option descriptions and mode guidance

Author: codemedic

README.md

@@ -40,7 +40,7 @@ Expand-Archive managed-python.zip
 ```bash
 ./install.sh \
   --prefix ~/.local/redmatter/python \
-  --min-python 3.10 \
+  --python 3.10 \
   --uv-env REDMATTER_UV \
   --python-env REDMATTER_PYTHON
 
@@ -52,7 +52,7 @@ source ~/.local/redmatter/python/env.sh
 ```powershell
 .\install.ps1 `
   -Prefix "$env:USERPROFILE\.local\redmatter\python" `
-  -MinPython "3.10" `
+  -Python "3.10" `
   -UvEnv "REDMATTER_UV" `
   -PythonEnv "REDMATTER_PYTHON"
 
@@ -66,14 +66,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" -MinPython "3.10" -UvEnv "REDMATTER_UV" -PythonEnv "REDMATTER_PYTHON"
+> install.bat -Prefix "$env:USERPROFILE\.local\redmatter\python" -Python "3.10" -UvEnv "REDMATTER_UV" -PythonEnv "REDMATTER_PYTHON"
 > 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" -MinPython "3.10" -UvEnv "REDMATTER_UV" -PythonEnv "REDMATTER_PYTHON"
+> install.bat -Prefix "%USERPROFILE%\.local\redmatter\python" -Python "3.10" -UvEnv "REDMATTER_UV" -PythonEnv "REDMATTER_PYTHON"
 > call "%USERPROFILE%\.local\redmatter\python\env.bat"
 > ```
 >
@@ -85,7 +85,7 @@ source ~/.local/redmatter/python/env.sh
 ```bash
 ./install.sh \
   --prefix ~/.local/redmatter/python \
-  --min-python 3.10 \
+  --python 3.10 \
   --uv-env REDMATTER_UV \
   --python-env REDMATTER_PYTHON \
   --quiet
@@ -99,12 +99,16 @@ source ~/.local/redmatter/python/env.sh
 | Flag | Required | Purpose |
 |------|----------|---------|
 | `--prefix PATH` | yes | Install location |
-| `--min-python X.Y` | yes | Minimum Python version for venv |
+| `--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 |
+| `--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 |
 
+> [!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.
+
 ## Usage
 
 ```bash
@@ -152,10 +156,11 @@ uv_version = "0.10.6"
 
 [install]
 prefix       = "/home/user/.local/redmatter/python"
-min_python   = "3.10"
+python       = "3.10"
 uv_env       = "REDMATTER_UV"
 python_env   = "REDMATTER_PYTHON"
 shell_profile = false
+isolated      = false
 ```
 
 ## Idempotency

install.ps1

@@ -10,15 +10,16 @@
 
 .EXAMPLE
     .\install.ps1 -Prefix "$env:USERPROFILE\.local\redmatter\python" `
-                  -MinPython "3.10" -UvEnv "REDMATTER_UV" -PythonEnv "REDMATTER_PYTHON"
+                  -Python "3.10" -UvEnv "REDMATTER_UV" -PythonEnv "REDMATTER_PYTHON"
 #>
 param(
     [Parameter(Mandatory=$true)]  [string]$Prefix,
-    [Parameter(Mandatory=$true)]  [string]$MinPython,
+    [Parameter(Mandatory=$true)]  [string]$Python,
     [Parameter(Mandatory=$true)]  [string]$UvEnv,
     [Parameter(Mandatory=$true)]  [string]$PythonEnv,
     [switch]$ShellProfile,
-    [switch]$Quiet
+    [switch]$Quiet,
+    [switch]$Isolated
 )
 
 function Write-Msg($msg) { if (-not $Quiet) { Write-Host $msg } }
@@ -88,16 +89,17 @@ if ($currentVer -eq $UvVersion) {
 if (Test-Path $VenvPy) {
     Write-Msg "  ✓ venv already exists"
 } else {
-    Write-Msg "  → Creating Python $MinPython venv"
-    $venvArgs = @("venv", "--python", $MinPython)
+    Write-Msg "  → Creating Python $Python venv"
+    $pythonPref = if ($Isolated) { "only-managed" } else { "system" }
+    $venvArgs = @("venv", "--python", $Python, "--python-preference", $pythonPref)
     if ($Quiet) { $venvArgs += "--quiet" }
     & $UvExe @venvArgs (Join-Path $Prefix "venv")
     if ($LASTEXITCODE -ne 0) {
-        Write-Error "Failed to create Python $MinPython venv — see uv error above"
+        Write-Error "Failed to create Python $Python venv — see uv error above"
         exit $LASTEXITCODE
     }
     if (-not (Test-Path $VenvPy)) {
-        Write-Error "Failed to create Python $MinPython venv — python.exe not found at $VenvPy"
+        Write-Error "Failed to create Python $Python venv — python.exe not found at $VenvPy"
         exit 1
     }
     Write-Msg "  ✓ venv created"
@@ -106,8 +108,9 @@ if (Test-Path $VenvPy) {
 Write-Msg ""
 
 # Hand off to setup.py
-$setupArgs = @("--prefix", $Prefix, "--min-python", $MinPython, "--uv-env", $UvEnv, "--python-env", $PythonEnv)
+$setupArgs = @("--prefix", $Prefix, "--python", $Python, "--uv-env", $UvEnv, "--python-env", $PythonEnv)
 if ($ShellProfile) { $setupArgs += "--shell-profile" }
+if ($Isolated) { $setupArgs += "--isolated" }
 if ($Quiet) { $setupArgs += "--quiet" }
 & $VenvPy (Join-Path $ScriptDir "setup.py") @setupArgs
 exit $LASTEXITCODE

install.sh

@@ -2,7 +2,7 @@
 # install.sh — Bootstrap uv + Python venv, then hand off to setup.py
 #
 # Usage:
-#   ./install.sh --prefix PATH --min-python X.Y --uv-env NAME --python-env NAME [--shell-profile]
+#   ./install.sh --prefix PATH --python X.Y --uv-env NAME --python-env NAME [--isolated] [--shell-profile]
 #
 # Bootstrap phase (this script): download uv, create venv.
 # Configuration phase (setup.py): env.sh, env.ps1, bin/ wrappers, shell profile.
@@ -92,14 +92,16 @@ _bootstrap_uv() {
 }
 
 _bootstrap_venv() {
-    local prefix="$1" min_python="$2"
+    local prefix="$1" min_python="$2" isolated="${3:-}"
 
     if [[ -x "${prefix}/venv/bin/python" ]]; then
         _msg "  ✓ venv already exists"; return
     fi
 
     _msg "  → Creating Python $min_python venv"
-    "${prefix}/uv" venv --python "$min_python" ${quiet:+--quiet} "${prefix}/venv" \
+    local pref_args="--python-preference system"
+    [[ "$isolated" == "1" ]] && pref_args="--python-preference only-managed"
+    "${prefix}/uv" venv --python "$min_python" $pref_args ${quiet:+--quiet} "${prefix}/venv" \
         || { printf "ERROR: Failed to create Python %s venv — see uv error above\n" "$min_python" >&2; exit 1; }
     _msg "  ✓ venv created"
 }
@@ -114,33 +116,34 @@ main() {
     uv_version="$(grep '^uv_version' "${script_dir}/distro.toml" \
         | sed -E 's/^[^=]+=\s*"?([^"#]+)"?.*/\1/' | tr -d '[:space:]')"
 
-    # Extract --prefix, --min-python, and --quiet for bootstrap (all flags forwarded to setup.py)
-    local prefix="" min_python="" quiet=""
+    # Extract --prefix, --python, --isolated, and --quiet for bootstrap (all flags forwarded to setup.py)
+    local prefix="" min_python="" isolated="" quiet=""
     local i j
     for (( i=1; i<=$#; i++ )); do
         case "${!i}" in
             --prefix)
                 j=$((i+1))
                 if (( j > $# )); then printf "ERROR: --prefix requires a value\n" >&2; exit 1; fi
                 prefix="${!j}"; prefix="${prefix/#\~/$HOME}" ;;
-            --min-python)
+            --python)
                 j=$((i+1))
-                if (( j > $# )); then printf "ERROR: --min-python requires a value\n" >&2; exit 1; fi
+                if (( j > $# )); then printf "ERROR: --python requires a value\n" >&2; exit 1; fi
                 min_python="${!j}" ;;
+            --isolated) isolated=1 ;;
             --quiet|-q) quiet=1 ;;
         esac
     done
 
     [[ -z "$prefix" ]]     && { printf "ERROR: --prefix is required\n" >&2; exit 1; }
-    [[ -z "$min_python" ]] && { printf "ERROR: --min-python is required\n" >&2; exit 1; }
+    [[ -z "$min_python" ]] && { printf "ERROR: --python is required\n" >&2; exit 1; }
 
     _msg ""
     _msg "managed-python bootstrap"
     _msg "  prefix  $prefix"
     _msg ""
 
     _bootstrap_uv   "$prefix" "$uv_version" "${script_dir}/distro.toml"
-    _bootstrap_venv "$prefix" "$min_python"
+    _bootstrap_venv "$prefix" "$min_python" "$isolated"
 
     _msg ""
     exec "${prefix}/venv/bin/python" "${script_dir}/setup.py" "$@"

setup.py

@@ -140,7 +140,7 @@ def _create_bin(prefix: Path) -> None:
 
 # ── env.sh ────────────────────────────────────────────────────────────────────
 
-def _write_env_sh(prefix: Path, uv_env: str, python_env: str, distro_version: str) -> None:
+def _write_env_sh(prefix: Path, uv_env: str, python_env: str, distro_version: str, *, isolated: bool = False) -> None:
     if _IS_WINDOWS:
         _info("Skipping env.sh on Windows — use env.ps1 instead")
         return
@@ -150,7 +150,11 @@ def _write_env_sh(prefix: Path, uv_env: str, python_env: str, distro_version: st
     venv_py = prefix / "venv" / "bin" / "python"
     bin_dir = prefix / "bin"
 
-    add_to_path, notes = _path_decision(bin_dir)
+    if isolated:
+        add_to_path = True
+        notes = ["--isolated: always adding bin/ to PATH"]
+    else:
+        add_to_path, notes = _path_decision(bin_dir)
 
     lines: list[str] = [
         f"# managed-python v{distro_version} \u2014 generated by setup.py",
@@ -176,7 +180,7 @@ def _write_env_sh(prefix: Path, uv_env: str, python_env: str, distro_version: st
 
 # ── env.ps1 ───────────────────────────────────────────────────────────────────
 
-def _write_env_ps1(prefix: Path, uv_env: str, python_env: str, distro_version: str) -> None:
+def _write_env_ps1(prefix: Path, uv_env: str, python_env: str, distro_version: str, *, isolated: bool = False) -> None:
     _step("Writing env.ps1")
 
     uv_exe  = prefix / ("uv.exe" if _IS_WINDOWS else "uv")
@@ -185,7 +189,11 @@ def _write_env_ps1(prefix: Path, uv_env: str, python_env: str, distro_version: s
     )
     bin_dir = prefix / "bin"
 
-    add_to_path, notes = _path_decision(bin_dir)
+    if isolated:
+        add_to_path = True
+        notes = ["--isolated: always adding bin/ to PATH"]
+    else:
+        add_to_path, notes = _path_decision(bin_dir)
 
     lines: list[str] = [
         f"# managed-python v{distro_version} -- generated by setup.py",
@@ -210,15 +218,19 @@ def _write_env_ps1(prefix: Path, uv_env: str, python_env: str, distro_version: s
 
 # ── env.bat ───────────────────────────────────────────────────────────────────
 
-def _write_env_bat(prefix: Path, uv_env: str, python_env: str, distro_version: str) -> None:
+def _write_env_bat(prefix: Path, uv_env: str, python_env: str, distro_version: str, *, isolated: bool = False) -> None:
     if not _IS_WINDOWS:
         return
 
     uv_exe  = prefix / "uv.exe"
     venv_py = prefix / "venv" / "Scripts" / "python.exe"
     bin_dir = prefix / "bin"
 
-    add_to_path, notes = _path_decision(bin_dir)
+    if isolated:
+        add_to_path = True
+        notes = ["--isolated: always adding bin/ to PATH"]
+    else:
+        add_to_path, notes = _path_decision(bin_dir)
 
     lines: list[str] = [
         f"@echo off",
@@ -250,6 +262,7 @@ def _write_installed_distro_toml(
     uv_env: str,
     python_env: str,
     shell_profile: bool,
+    isolated: bool = False,
 ) -> None:
     """
     Write distro.toml to the prefix, appending an [install] section that
@@ -259,10 +272,11 @@ def _write_installed_distro_toml(
     install_section = (
         f"\n\n[install]\n"
         f'prefix       = "{prefix.as_posix()}"\n'
-        f'min_python   = "{min_python}"\n'
+        f'python       = "{min_python}"\n'
         f'uv_env       = "{uv_env}"\n'
         f'python_env   = "{python_env}"\n'
         f"shell_profile = {'true' if shell_profile else 'false'}\n"
+        f"isolated      = {'true' if isolated else 'false'}\n"
     )
     (prefix / "distro.toml").write_text(source + install_section, encoding="utf-8")
 
@@ -311,10 +325,11 @@ def _parse_args() -> argparse.Namespace:
         description="Post-bootstrap configuration for managed-python (stdlib, no deps).",
     )
     p.add_argument("--prefix",       required=True,                help="Install prefix")
-    p.add_argument("--min-python",   required=True, dest="min_python")
+    p.add_argument("--python",       required=True, dest="python_version")
     p.add_argument("--uv-env",       required=True, dest="uv_env",     help="Env var name for uv path")
     p.add_argument("--python-env",   required=True, dest="python_env", help="Env var name for python path")
     p.add_argument("--shell-profile", action="store_true", dest="shell_profile")
+    p.add_argument("--isolated",     action="store_true", dest="isolated")
     p.add_argument("--quiet", "-q", action="store_true", dest="quiet",
                    help="Suppress all output except warnings")
     return p.parse_args()
@@ -330,11 +345,12 @@ def main() -> None:
     distro_version = _toml_get(script_dir / "distro.toml", "version")
 
     _create_bin(prefix)
-    _write_env_sh(prefix, args.uv_env, args.python_env, distro_version)
-    _write_env_ps1(prefix, args.uv_env, args.python_env, distro_version)
-    _write_env_bat(prefix, args.uv_env, args.python_env, distro_version)
+    _write_env_sh(prefix, args.uv_env, args.python_env, distro_version, isolated=args.isolated)
+    _write_env_ps1(prefix, args.uv_env, args.python_env, distro_version, isolated=args.isolated)
+    _write_env_bat(prefix, args.uv_env, args.python_env, distro_version, isolated=args.isolated)
     _write_installed_distro_toml(
-        script_dir, prefix, args.min_python, args.uv_env, args.python_env, args.shell_profile
+        script_dir, prefix, args.python_version, args.uv_env, args.python_env, args.shell_profile,
+        isolated=args.isolated,
     )
 
     if args.shell_profile: