fix(core): pip upkeep runs pip, whatever engine is configured

`pipdock pip-upgrade --engine uv` failed at PD-ENG-001 — while the line immediately below
had already reached past the abstraction to call PipEngine.info directly for the version.

Upgrading pip is a pip operation by definition. There is no uv way to do it, which is why
UvEngine::upgrade_pip exists only to refuse, and the engine setting is a preference about
the *user's* environments. Dispatching on it meant the one command with no resolver
between the user and the result was also the one that could be blocked by an unrelated
choice. Same reasoning P2 applied to the tools venv: pip is present wherever Python is.

Both heads now call PipEngine::upgrade_pip directly. The uv refusal stays rather than
becoming an unreachable!() — the trait is public and for_id can still hand a caller that
adapter, where a catalog code beats a panic.

That refusal was also the only thing standing in front of this path, so PipEngine now
carries its own PEP 668 guard, copied verbatim from UninstallFlow::start rather than
reworded so the three cannot drift. DATA-FLOW §2's preamble is "all mutating flows" and
replacing pip in site-packages is one; UpdateFlow has refused since S1 and UninstallFlow
since S5, and this had no guard at all. It stayed harmless only while nothing but a CLI
command could reach it — the next commit gives it a button.

Verified by running: `pip-upgrade --engine uv` on a 3.12 venv reports pip 25.0.1 -> 26.2.1
and exits 0, and a second run is idempotent.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-08-12 22:45:02 +07:00
1 parent ef5a1ec805
commit c281d054c0
5 files changed
+65 -7

No files matched your search

+4
View File
@@ -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
+9 -3
View File
@@ -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<Exit> {
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!(
+41 -1
View File
@@ -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<StepResult> {
// 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);
}
}
+6 -2
View File
@@ -228,10 +228,14 @@ impl Engine for UvEngine {
}
async fn upgrade_pip(&self, _env: &PyEnv) -> Result<StepResult> {
// 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",
))
}
}
+5 -1
View File
@@ -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`.