diff --git a/.gitignore b/.gitignore index 5a421ca..58b351c 100644 --- a/.gitignore +++ b/.gitignore @@ -16,6 +16,10 @@ dist-ssr/ # Environments (test venvs created by the integration suite / spikes) .venv/ venv/ +# Verifying an environment feature by hand needs a venv the GUI can *see*, and `env_add_manual` +# (Browse…) is still owed — so venv_scan's "below the working directory" is the only way in, which +# means the repo root. `.venv-oldpip` for the pip-upkeep floor, and whatever the next one needs. +/.venv-*/ __pycache__/ *.py[cod] # ci-integration.yml builds these in the workspace. Harmless on an ephemeral runner, but a diff --git a/crates/pipdock-cli/src/run.rs b/crates/pipdock-cli/src/run.rs index c7a3dc9..8cc3e22 100644 --- a/crates/pipdock-cli/src/run.rs +++ b/crates/pipdock-cli/src/run.rs @@ -921,14 +921,20 @@ fn describe_need(need: &health::SyncNeed) -> String { /// `pipdock pip-upgrade` /// +/// **`PipEngine`, not `engine_for(opts)`.** Upgrading pip is a pip operation by definition — there +/// is no uv way to do it, which is why `UvEngine::upgrade_pip` refuses. Dispatching on the +/// configured engine meant `--engine uv` failed at `PD-ENG-001` for a preference about the *user's* +/// environments, on the one command that has nothing to do with resolving anything; the line below +/// was already reaching past the abstraction to read the version. Same reasoning as the tools venv +/// (CODE-HEALTH-SPEC §2 as amended by P2): pip is present wherever Python is. +/// /// # Errors -/// `PD-ENG-001` when uv is the active engine, which cannot upgrade pip (DATA-FLOW §7). +/// `PD-ENV-002` on a PEP 668 environment; whatever `classify_stderr` makes of a failed install. pub async fn pip_upgrade(opts: &GlobalOpts) -> Result { let env = select_env(opts).await?; - let engine = engine_for(opts); let before = PipEngine.info(&env).await; - engine.upgrade_pip(&env).await?; + PipEngine.upgrade_pip(&env).await?; let after = PipEngine.info(&env).await; println!( diff --git a/crates/pipdock-core/src/engine/pip.rs b/crates/pipdock-core/src/engine/pip.rs index 44af19e..75bb8e9 100644 --- a/crates/pipdock-core/src/engine/pip.rs +++ b/crates/pipdock-core/src/engine/pip.rs @@ -6,7 +6,7 @@ use async_trait::async_trait; -use crate::errors::{PdError, Result}; +use crate::errors::{Code, PdError, Result}; use crate::exec::Command; use crate::model::{ CheckReport, Dist, EngineId, EngineInfo, ExecMode, OutdatedDist, PinnedSpec, PkgName, PyEnv, @@ -205,6 +205,19 @@ impl Engine for PipEngine { } async fn upgrade_pip(&self, env: &PyEnv) -> Result { + // DATA-FLOW §2's preamble is "all mutating flows", and replacing pip in site-packages is + // one. `UpdateFlow` and `UninstallFlow` have refused these at their entry points since S1 + // and S5; this had no guard at all, which did not matter while the only caller was a CLI + // command nobody had wired to a button. P1 gives it one, so it needs the same refusal — + // copied from `UninstallFlow::start`, not reworded, so the three cannot drift. + if env.externally_managed { + return Err(PdError::new( + Code::EnvExternallyManaged, + "this Python is externally managed (PEP 668). Use a virtual environment; \ + the override lives in Settings and is discouraged", + )); + } + let out = Command::python(&env.interpreter) .args(["-m", "pip", "install", "-U", "pip"]) .run() @@ -278,4 +291,31 @@ mod tests { fn freeze_uses_all_so_snapshots_include_pip_itself() { assert!(PipEngine::argv_freeze().contains(&"--all".to_string())); } + + /// DATA-FLOW §2's preamble is "all mutating flows". `UpdateFlow` and `UninstallFlow` refuse a + /// PEP 668 environment at their entry points; this path had no guard at all, which only stayed + /// harmless while nothing but a CLI command could reach it. + /// + /// The interpreter path is deliberately nonsense: the guard must return *before* anything is + /// spawned, so a test that needs a real Python would be testing the wrong thing. + #[tokio::test] + async fn an_externally_managed_python_is_refused_before_anything_runs() { + let env = PyEnv { + interpreter: r"C:\does\not\exist\python.exe".into(), + prefix: r"C:\usr".into(), + python_version: "3.12.4".into(), + externally_managed: true, + hidden_user_site: None, + source: crate::model::EnvSource::Registry, + }; + + let err = PipEngine + .upgrade_pip(&env) + .await + .expect_err("PEP 668 blocks pip upkeep"); + + assert_eq!(err.code, Code::EnvExternallyManaged); + // Not PD-ENG-001: reaching the spawn would mean the guard ran too late. + assert!(!err.message.contains("could not run"), "{}", err.message); + } } diff --git a/crates/pipdock-core/src/engine/uv.rs b/crates/pipdock-core/src/engine/uv.rs index 151d072..2bbb67a 100644 --- a/crates/pipdock-core/src/engine/uv.rs +++ b/crates/pipdock-core/src/engine/uv.rs @@ -228,10 +228,14 @@ impl Engine for UvEngine { } async fn upgrade_pip(&self, _env: &PyEnv) -> Result { - // Documented behaviour, not a gap: pip upkeep is a pip-engine concern (DATA-FLOW §7). + // Unreachable through either head as of P1: both call `PipEngine::upgrade_pip` directly, + // because upgrading pip is a pip operation by definition and the engine setting is a + // preference about the *user's* environments (DATA-FLOW §7, amended). The refusal stays + // rather than becoming an `unreachable!()`: the trait is public, `for_id` can still hand a + // caller this adapter, and a panic is a worse answer than a catalog code. Err(crate::errors::PdError::new( crate::errors::Code::EngNotFound, - "pip upkeep is not available while uv is the active engine", + "pip upkeep is not available through the uv adapter; call PipEngine::upgrade_pip", )) } } diff --git a/docs/DATA-FLOW.md b/docs/DATA-FLOW.md index 6ab8787..7240639 100644 --- a/docs/DATA-FLOW.md +++ b/docs/DATA-FLOW.md @@ -119,7 +119,11 @@ Rendered as: **"13 successful, 2 failed, 1 skipped"** with an expandable row per | Uninstall | `uninstall -y pkg` | `uv pip uninstall pkg` | | | Env check | `check` | `uv pip check` | normalize findings | | Freeze (snapshots) | `freeze --all` | `uv pip freeze` | pip's `--all` includes pip/setuptools; record engine in snapshot meta | -| Upgrade pip | `install -U pip` | *(n/a — surface "pip upkeep" only when pip engine active or pip present in env)* | | +| Upgrade pip | `install -U pip` | *(n/a — **always runs through the pip adapter**, whatever engine is configured)* | | + +**Pip upkeep does not dispatch on the configured engine** (amended by Phase 3 · P1). Upgrading pip is a pip operation by definition; there is no uv way to do it, and `UvEngine::upgrade_pip` exists only to refuse. Dispatching meant `--engine uv` failed at `PD-ENG-001` for a preference that has nothing to do with the operation, on the one command with no resolver between the user and the result — while the surrounding code was already reaching past the abstraction to read pip's version. Both heads now call `PipEngine::upgrade_pip` directly. Same reasoning as the Code Health tools venv (CODE-HEALTH-SPEC §2 as amended by P2): pip is present wherever Python is, and a feature must not go dark over an unrelated setting. + +The refusal it replaces is also why `PipEngine::upgrade_pip` carries its own PEP 668 guard: §2's preamble is "all mutating flows", and replacing pip in site-packages is one. `UpdateFlow` has refused since S1 and `UninstallFlow` since S5; this path had no guard at all while its only caller was a CLI command with no button behind it. **Neither head lists installed packages through the engine.** `pipdock list` and `pkg_list` both read `probe.py` instead, because the probe carries `Requires-Dist` — which `list --format=json` does not report, and which the reverse-dependency graph, the uninstall guard and blocker attribution are all built from. Reading the engine here would give the Installed screen a different package set than the guard that protects it. The `-I` trade-off this buys is documented in ARCHITECTURE §4 and surfaced as `hidden_user_site`.