feat(app): uninstall_guard and uninstall_execute, and the re-guard they make possible

The last two mutating commands. Both were rows in ARCHITECTURE §7 and names in
`COMMANDS` with nothing behind them.

`uninstall_guard` parks the flow it built, so `uninstall_execute` runs the
removal the user was actually shown rather than re-deriving it from names that
may have moved. *Remove dependents too* is this command called **again** over
`withDependents`, which is what DATA-FLOW §5 means by re-guarding: widening a
removal must not skip the check that justified widening it, and a dependent of a
dependent has to surface on the next pass instead of going unannounced. The
previous pass's flow is discarded, exactly as `plan_resolve` discards a previous
preview.

`uninstall_execute` refuses with `PD-RES-004` **before** the snapshot when the
guard objected and `force` is false, via a new `UninstallFlow::check` that shares
its implementation with the one `execute` enforces — one rule, two call sites, so
a plan that will not run leaves no snapshot behind.

Both read the store and drop the guard before awaiting. `Store` is not `Sync`, so
a future holding one is not `Send` and the command would not compile — and where
it does compile it serializes every other command behind a subprocess. Checked
with `cargo check -p pipdock-app` as soon as the signatures were written, which
is the cheap version of finding this out.

ARCHITECTURE §7 corrected in the same commit, as it requires. Four return types
were wrong: `plan_execute` and `uninstall_execute` return `ExecutionOutcome`, not
`ExecutionSummary`, and `plan_cancel` returns `bool`, not `()`. §7 also now
states the one-session-at-a-time rule spans all four flows.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-08-09 21:46:25 +07:00
1 parent fc0aa4ccf6
commit d36e30dd6c
5 files changed
+142 -5

No files matched your search

+12
View File
@@ -480,6 +480,18 @@ impl UninstallFlow {
&self.guard
}
/// Would [`Self::execute`] accept this acknowledgement?
///
/// The same rule `execute` enforces, exposed so a caller can refuse *before* writing a
/// snapshot for a removal that will not happen. `execute` still checks: this is the polite
/// early exit, not the guard.
///
/// # Errors
/// `PD-RES-004` when the guard found dependents and `ack` does not accept breaking them.
pub fn check(&self, ack: GuardAck) -> Result<()> {
ack_ok(&self.guard, ack)
}
/// Write the pre-removal snapshot, or record the waiver.
///
/// Takes a [`SnapshotPolicy`] for the same reason [`UpdateFlow::take_snapshot`] does: without
+6 -4
View File
@@ -123,10 +123,10 @@ This table is the surface. A command that is not listed here does not exist; add
| `pkg_metadata` | `PackageMeta` | Cached PyPI metadata for the details panel, with its freshness. |
| `plan_resolve` | `FlowStep` | Begin an update or install flow: dry-run resolve, then derive held-back items. |
| `plan_decide` | `FlowStep` | Apply the user's 3-way conflict decisions and re-resolve. |
| `plan_execute` | `ExecutionSummary` | Take the snapshot, then run the two-phase execution (§8). |
| `plan_cancel` | `()` | Trip the running plan's cancellation token. |
| `uninstall_guard` | `GuardReport` | Reverse-dependency check over a removal set. |
| `uninstall_execute` | `ExecutionSummary` | Snapshot, then remove. |
| `plan_execute` | `ExecutionOutcome` | Take the snapshot, then run the two-phase execution (§8). Returns the summary **and** the snapshot meta: the CLI prints the id before execution and the summary sheet needs it afterwards to offer the rollback, so one envelope beats a second command to go and look it up. |
| `plan_cancel` | `bool` | Stop the session, and say whether there was one. A *parked* flow counts and is discarded — it has no process to kill, and leaving it refuses the next plan on behalf of a preview nobody is looking at. |
| `uninstall_guard` | `GuardReport` | Reverse-dependency check over a removal set, parking the flow that would run it. Called **again** with `withDependents` for DATA-FLOW §5's *Remove dependents too*, so a dependent of a dependent surfaces on the next pass. |
| `uninstall_execute` | `ExecutionOutcome` | Snapshot, then remove. Takes `force` — §5's *Force remove only X*; without it a removal the guard objected to is refused with `PD-RES-004` before the snapshot is written. |
| `pin_list` | `Pin[]` | Pins for an environment. |
| `pin_add` | `()` | Add or replace a pin. |
| `pin_remove` | `bool` | Remove a pin; reports whether one existed. |
@@ -157,6 +157,8 @@ Events (Tauri event channel): `plan-progress` streams live subprocess output to
It was originally specified as `{ step, pkg, phase, line }`, which made both of those features unimplementable: there was no event meaning "a step began" to group a section under, and none meaning "one finished" to count. Neither is recoverable from the text — engine output does not reliably name the package it concerns, and counting lines is not counting steps. Every step now emits exactly one `stepStarted`, any number of `line`s, and exactly one `stepFinished`, whichever way it ended. `stream` distinguishes stdout from stderr, which matters for uv in particular: uv writes its **plan** to stderr (SP-1), so stderr does not mean failure.
**One mutation session at a time, across all of them.** Update, install, uninstall and rollback share a single slot, so a second one is refused with `PD-RES-003` rather than allowed to interleave engine commands against the same environment. The commands that resume a session (`plan_decide`, `plan_execute`, `uninstall_execute`, `snapshot_rollback`) name the flow they expect and get `PD-INT-001` if a different one is parked — a frontend sequencing bug, reported as one instead of running the wrong plan.
Long operations are cancellable: `plan_cancel` trips the plan's token, which kills the child **and its whole process tree** (a Windows Job Object — `python -m pip` spawns build backends), and remaining steps are reported `Skipped` with `ExecutionSummary.cancelled` set. Already-completed steps stay applied; the snapshot covers full revert.
## 8. Execution model (two-phase)
+94
View File
@@ -500,6 +500,100 @@ pub async fn plan_cancel(state: tauri::State<'_, AppState>) -> Wire<bool> {
Ok(state.stop().await)
}
/// Check what a removal would break, and park the flow that would do it (DATA-FLOW §5).
///
/// Called again with a wider set for *Remove dependents too*: that option is not a variant of the
/// flow but the caller starting over with `GuardReport.withDependents`, so a dependent of a
/// dependent surfaces on the next pass instead of being removed unannounced. The parked flow from
/// the previous pass is discarded here, exactly as `plan_resolve` discards a previous preview.
///
/// # Errors
/// `PD-RES-003` when a plan is already executing, `PD-ENV-002` for a PEP 668 environment,
/// `PD-PKG-002` for a name that is not a package, `PD-ENV-003` when the probe fails.
#[tauri::command]
pub async fn uninstall_guard(
state: tauri::State<'_, AppState>,
env: PyEnv,
pkgs: Vec<String>,
) -> Wire<pipdock_core::graph::GuardReport> {
let _ = state.claim().await?;
// Read, then drop, before any await: `Store` is not `Sync`, so a future holding the guard is
// not `Send` and this command would not compile — and where it does compile it serializes
// every other command behind a subprocess.
let engine = {
let store = state.store.lock().await;
engine::for_id(settings::load(&store)?.engine)
};
match flow::UninstallFlow::start(env, engine, &pkgs).await {
Ok((flow, report)) => {
state.park(Session::Uninstall(Box::new(flow))).await;
Ok(report)
}
Err(e) => {
state.release().await;
Err(e.into())
}
}
}
/// Snapshot, then remove (DATA-FLOW §5's tail).
///
/// `force` is §5's *Force remove only X*: the user was shown what breaks and chose it. Without it
/// a removal the guard objected to is refused with `PD-RES-004` **before** the snapshot is
/// written, so a plan that will not run does not leave one behind.
///
/// # Errors
/// `PD-RES-004` when the guard objected and `force` is false, `PD-SNP-001` when the snapshot
/// cannot be written — in which case nothing is removed — and `PD-INT-001` when no guard has run.
#[tauri::command]
pub async fn uninstall_execute(
app: tauri::AppHandle,
state: tauri::State<'_, AppState>,
force: bool,
) -> Wire<ExecutionOutcome> {
let mut flow = state.sessions.claim_uninstall().await?;
state.set_cancel(Some(flow.cancel_handle()));
let ack = if force {
flow::GuardAck::ForcedDespiteBreakage
} else {
flow::GuardAck::Clear
};
if let Err(e) = flow.check(ack) {
state.release().await;
return Err(e.into());
}
let snapshot = match flow
.take_snapshot(flow::SnapshotPolicy::Take, &state.app_data)
.await
{
Ok(meta) => meta,
Err(e) => {
state.release().await;
return Err(e.into());
}
};
let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel();
let emitter = app.clone();
tokio::spawn(async move {
while let Some(event) = rx.recv().await {
let _ = emitter.emit("plan-progress", &event);
}
});
let result = flow.execute(ack, tx).await;
state.release().await;
Ok(ExecutionOutcome {
summary: result?,
snapshot,
})
}
/// Read the stored settings.
///
/// # Errors
+2
View File
@@ -46,6 +46,8 @@ pub fn run() {
commands::plan_decide,
commands::plan_execute,
commands::plan_cancel,
commands::uninstall_guard,
commands::uninstall_execute,
commands::index_search,
commands::index_refresh,
commands::pkg_metadata,
+28 -1
View File
@@ -23,6 +23,7 @@ import type {
EnvSource,
ExecutionSummary,
FlowStep,
GuardReport,
Intent,
OutdatedDist,
PackageMeta,
@@ -247,9 +248,35 @@ export const planDecide = (decisions: Record<string, Decision>): Promise<FlowSte
*/
export const planExecute = (): Promise<ExecutionOutcome> => invoke('plan_execute')
/** Stop the running plan. Resolves to whether anything was actually in flight. */
/**
* Stop the running plan. Resolves to whether there was anything to stop.
*
* A plan that is merely parked — a preview on screen, a guard dialog open — counts and is
* discarded: it has no process to kill, and leaving it refuses the next plan on behalf of
* something nobody is looking at.
*/
export const planCancel = (): Promise<boolean> => invoke('plan_cancel')
/**
* Check what removing `pkgs` would break, and park the flow that would do it (DATA-FLOW §5).
*
* Call it **again** with `report.withDependents` for *Remove dependents too*. That option is not a
* variant of the flow — it is this call repeated over a wider set, so a dependent of a dependent
* surfaces on the next pass rather than being removed unannounced. The previous pass's flow is
* discarded, as starting a new plan discards a previous preview.
*/
export const uninstallGuard = (env: PyEnv, pkgs: string[]): Promise<GuardReport> =>
invoke('uninstall_guard', { env, pkgs })
/**
* Snapshot, then remove. Streams `plan-progress`, and summarises like any other plan.
*
* `force` is §5's *Force remove only X*. Without it a removal the guard objected to rejects with
* `PD-RES-004` before the snapshot is written, so a plan that will not run leaves nothing behind.
*/
export const uninstallExecute = (force: boolean): Promise<ExecutionOutcome> =>
invoke('uninstall_execute', { force })
/**
* Subscribe to execution progress. Returns the unlisten function.
*