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:
1 parent
fc0aa4ccf6
commit
d36e30dd6c
5 files changed
+142
-5
No files matched your search
@@ -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
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
@@ -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.
|
||||
*
|
||||
|
||||
Reference in new issue
Block a user