feat(app): pip_upgrade, the command P0-10 needs

P0-10 is a ship blocker that has had an Engine method, a CLI command and no way to reach it
from the app. This is the bridge, and NOT_YET is one shorter.

Returns StepResult. ARCHITECTURE §7 typed it ExecutionSummary, which would need an invented
plan_id, phase, CheckReport and counts — four lies for one step. It carries no versions
either; the caller re-probes, which it must do anyway to refresh the row.

Two DATA-FLOW §9 amendments, both narrow and both written down rather than assumed.

§9.1 gains a fourth plan shape: pip upkeep, which is not resolver-planned and cannot be.
This is S5's lesson a second time — the invariant named the shapes that could produce a
proof and left out the one that structurally cannot. pip below 22.2 cannot emit
--dry-run --report at all, which is exactly the case the feature exists for, so demanding
a report would refuse the only environments that need it. One IPC message parking nothing,
so no waiver type: those exist for a decision made in one message and consumed in another.

§9.2 gains an exemption: no snapshot. A snapshot's only restore path is
`pip install pip==X` executed by pip, so one taken to protect against a broken pip has no
consumer that could use it. Made visible rather than silent — the dialog will say so — which
is what keeps it an exemption instead of an erosion.

The slot is claimed and released on both paths. Two pip invocations against one
site-packages would interleave, and a claim that is never released leaves every later
command answering PD-RES-003 for a plan that never existed (S5 bug 1).

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 c281d054c0
commit 5bd21de203
5 files changed
+69 -9

No files matched your search

+1 -1
View File
@@ -138,7 +138,7 @@ This table is the surface. A command that is not listed here does not exist; add
| `health_run` | `CheckReport` | Run the Code Health tools against a project folder. |
| `health_fix` | `ExecutionSummary` | Apply the gated `ruff` fix. |
| `engine_info` | `EngineInfo[]` | Detected version and availability per engine. Settings shows both, so this returns both. |
| `pip_upgrade` | `ExecutionSummary` | Upgrade pip itself in the selected environment. |
| `pip_upgrade` | `StepResult` | Upgrade pip itself in the selected environment. **Not `ExecutionSummary`** — there is no plan, no phase and no per-package counts, and inventing them would be four lies for one step. Carries no versions either (`from`/`to` are always absent): the caller re-probes, which it must do anyway to refresh the row. |
| `settings_get` | `Settings` | Read stored settings. |
| `settings_set` | `Settings` | Persist settings, returning what was actually stored rather than what was sent. |
| `legal_consent_get` | `ConsentState` | Whether the legal gate can be skipped for this build's documents. |
+13 -3
View File
@@ -155,10 +155,20 @@ M3 rather than bolted onto a preview. Until then the preview's promise is precis
1. No mutating engine call without an **accepted proof** for this session: a `ResolutionReport` for
a resolve-shaped plan (update, install), a `GuardReport` plus a `GuardAck` for a removal (§5), a
`RollbackPlan` for a restore (§8). Originally written as "a `ResolutionReport`", which the
`RollbackPlan` for a restore (§8), and **nothing for pip upkeep, which is not resolver-planned
and cannot be** (§7; added by P1). Originally written as "a `ResolutionReport`", which the
uninstall path cannot produce — there is nothing to resolve — leaving the one flow with no
preview also the one flow the invariant did not describe.
2. No mutating engine call without a successful snapshot write.
preview also the one flow the invariant did not describe. The fourth shape is the same lesson a
second time: pip below 22.2 cannot produce `--dry-run --report` output *at all*, which is
precisely the case the feature exists for, so demanding a report would refuse the only
environments that need it. `pip_upgrade` is one IPC message parking nothing, so it needs no
waiver type either — those exist for a decision made in one message and consumed in another.
2. No mutating engine call without a successful snapshot write, **except pip upkeep** (added by P1).
A snapshot's only restore path is `pip install pip==X` executed *by pip*, so one taken to protect
against a broken pip has no consumer that could use it. The exemption is **made visible rather
than silent**: the confirm dialog states that no snapshot is taken. That is what keeps it an
exemption rather than an erosion — every other mutating path still writes one, and
`flow::proof_from` still refuses `NotTaken` with `PD-SNP-001`.
3. `plan_execute` refuses a report older than 10 minutes or if the env's probe hash changed (env drifted → re-resolve).
4. Every failure surfaced to UI/CLI carries a catalog code.
5. Pinned packages never appear in a `PlanRequest.upgrades` unless the user explicitly unpinned them this session.
+38 -2
View File
@@ -8,11 +8,11 @@
//! `Serialize` error type, and the frontend contract in `ui/src/ipc` is a flat
//! `{ code, message, stderrTail }`. One conversion here beats a shape the UI has to unwrap.
use pipdock_core::engine;
use pipdock_core::engine::{self, Engine as _, pip::PipEngine};
use pipdock_core::envs::{self, ScanProgress};
use pipdock_core::flow;
use pipdock_core::index::{self, NameIndex};
use pipdock_core::model::EnvSource;
use pipdock_core::model::{EnvSource, StepResult};
use pipdock_core::pins::{self, Pin};
use pipdock_core::plan::{Decision, ExecutionSummary};
use pipdock_core::settings::{self, Consent, Settings};
@@ -746,6 +746,42 @@ fn forward_progress(
});
}
/// Upgrade pip inside `env` (PRD P0-10).
///
/// **`PipEngine` unconditionally**, never `engine::for_id(settings.engine)`. Upgrading pip is a pip
/// operation by definition; the engine setting is a preference about how the *user's* environments
/// are resolved, and DATA-FLOW §7 (as amended by P1) says so. The CLI does the same.
///
/// **Returns `StepResult`, not `ExecutionSummary`.** ARCHITECTURE §7's row was wrong: there is no
/// plan, no phase and no per-package counts here, and inventing them would be four lies for one
/// step. The before/after version pair is not in it either — the caller re-probes, which it has to
/// do anyway to refresh the row.
///
/// **No snapshot** (DATA-FLOW §9.2's exemption, and it is deliberate). A snapshot's only restore
/// path is `pip install pip==X` executed *by pip*, so one taken to protect against a broken pip has
/// no consumer that could use it. The exemption is made visible rather than silent: the confirm
/// dialog says no snapshot is taken.
///
/// Claims the mutation slot because two pip invocations against one site-packages would interleave.
///
/// # Errors
/// `PD-ENV-002` on a PEP 668 environment; `PD-RES-003` when a plan is already in flight; whatever
/// `classify_stderr` makes of a failed install.
#[tauri::command]
pub async fn pip_upgrade(state: tauri::State<'_, AppState>, env: PyEnv) -> Wire<StepResult> {
// `claim` rather than `claim_update`: there is nothing parked to expect. It discards a parked
// session, which is reachable only if a preview is open — and the plan panel replaces the whole
// content area while one is, so the Environments row is not clickable.
state.sessions.claim().await?;
let result = PipEngine.upgrade_pip(&env).await;
// Released on **both** paths. A claim that is never released leaves every later command
// answering PD-RES-003 for a plan that never existed — S5 bug 1, and the reason this is not an
// early `?`.
state.release().await;
Ok(result?)
}
/// Detected version and availability for **both** engines (ARCHITECTURE §7).
///
/// Both, not the configured one: Settings shows a radio with a version beside each option, so
+3 -3
View File
@@ -24,9 +24,8 @@ pub mod state;
/// `COMMANDS` and reality disagree in either direction.
pub const NOT_YET: &[(&str, &str)] = &[
("env_add_manual", "M3 — Browse… has no surface yet"),
("health_run", "Phase 3 — Code Health"),
("health_fix", "Phase 3 — Code Health"),
("pip_upgrade", "Phase 3 P1 — pip upkeep"),
("health_run", "Phase 3 P3 — the runners"),
("health_fix", "Phase 3 P5 — the gated ruff --fix"),
("logs_tail", "M3 — needs the logging subsystem"),
];
@@ -71,6 +70,7 @@ pub fn run() {
commands::snapshot_rollback,
commands::report_bug_url,
commands::engine_info,
commands::pip_upgrade,
commands::index_search,
commands::index_refresh,
commands::pkg_metadata,
+14
View File
@@ -35,6 +35,7 @@ import type {
RefreshReport,
RollbackPreview,
SnapshotMeta,
StepResult,
} from './generated'
export type * from './generated'
@@ -341,6 +342,19 @@ export const reportBugUrl = (env?: PyEnv, code?: string): Promise<BugReportLink>
*/
export const engineInfo = (env: PyEnv): Promise<EngineInfo[]> => invoke('engine_info', { env })
/**
* Upgrade pip inside `env` (PRD P0-10).
*
* Runs pip whatever engine is configured — upgrading pip is a pip operation by definition
* (DATA-FLOW §7, amended by P1).
*
* Returns a `StepResult` carrying no versions: `from` and `to` are always absent, because the
* adapter runs one command and never reads a version. The caller re-probes the environment to
* refresh the row, which it has to do anyway. **No snapshot is taken** — DATA-FLOW §9.2's
* exemption, because a snapshot restored by pip is no use when pip is what is broken.
*/
export const pipUpgrade = (env: PyEnv): Promise<StepResult> => invoke('pip_upgrade', { env })
/**
* Subscribe to execution progress. Returns the unlisten function.
*