diff --git a/CLAUDE.md b/CLAUDE.md index b538103..ae886c4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -12,11 +12,12 @@ The design is fully specified. Read in this order; do not invent behaviour that 3. `docs/DATA-FLOW.md` — update/install/uninstall/rollback state machines, engine command mapping, **invariants §9** 4. `docs/UI-SPEC.md` — design tokens, screens, click budgets, keyboard map 5. `docs/CLI-SPEC.md` — commands, flags, exit codes, JSON contracts -6. `docs/ERROR-CATALOG.md` — the launch codes and their stderr classifiers. **31 in Rust** - (`Code::ALL`, pinned by two tests); the doc tabulates 29 because it folds `PD-HLT-001..003` +6. `docs/ERROR-CATALOG.md` — the launch codes and their stderr classifiers. **32 in Rust** + (`Code::ALL`, pinned by two tests); the doc tabulates 30 because it folds `PD-HLT-001..003` into one row. Adding a code means the catalog, `Code::ALL`, both counts, the - "no code without a fixture" gate in `classifier_corpus.rs`, both locale catalogs, and a - re-blessed `golden__schema-Code.snap` — the gate will tell you which you forgot + "no code without a fixture" gate in `classifier_corpus.rs`, both locale catalogs, and + re-blessed goldens — `golden__schema-Code.snap` **and every schema that embeds it** + (`StepResult`, `ExecutionSummary`) — the gate will tell you which you forgot 7. `docs/CODE-HEALTH-SPEC.md`, `docs/SECURITY.md`, `docs/TESTING.md`, `docs/RELEASE-CI.md`, `docs/I18N.md`, `docs/ROADMAP.md` 8. `legal/` — EULA, Disclaimer, Privacy, Third-Party Notices (public; the in-app legal gate links to these GitHub URLs) @@ -63,15 +64,17 @@ Every caller needs an explicit `permissions:` block — callers without one defa ## Current state -**M1 complete. M2 Stages 1–4 done** (IPC bridge 2026-07-30; Installed+Updates, the mutation spine +**M1 complete. M2 Stages 1–5 done** (IPC bridge 2026-07-30; Installed+Updates, the mutation spine and search+install all 2026-08-04). The app discovers, lists, previews, decides, executes, streams, summarises and installs over real commands. **"Update everything" is 4 clicks and "install one" is 4 clicks**, both counted by hand in the running app; search is **22 ms median per keystroke** against a 50 ms budget. All 16 of UI-SPEC §6's components exist. `docs/ROADMAP.md` Phase 2 has a table per stage and says where to pick up; read it before starting a slice. -Next is **S5 — uninstall, the guard dialog and the Pins screen**, and it is a small one: the pin -commands already exist from S2, and DATA-FLOW §5's three-option dialog is fully specified. +Next is **S6 — snapshots, the env detail and rollback**. S5 landed `Session::Rollback` and +`RollbackFlow::cancel_handle`, so S6 adds a call site rather than another widening; what it needs is +`RollbackPreview` crossing IPC, the five `snapshot_*` commands, and the env-detail surface UI-SPEC §4 +assumes and which does not exist. Three rules from S2/S3 that bind everything after them: @@ -86,6 +89,12 @@ Three rules from S2/S3 that bind everything after them: (inside core) it serializes every other command behind a network call. Read what you need, drop the guard, then await. This is why `UpdateFlow::start` takes pins rather than a `&Store`, and why `index::metadata`/`refresh` take the app-data path. It has bitten twice; assume it will again. +- **A dialog is not an enforcement point.** DATA-FLOW §5's three options are what the user *sees*; + what stops a removal is `GuardAck` inside `UninstallFlow::execute`, beside `SnapshotProof`. The + same shape twice: the report and the proof are produced in one call and consumed in another, so + the only way "somebody forgot to look" cannot happen is a value the executing call demands. Any + future flow with a decision between two IPC messages needs its own. + - **Measure in `--release`, and say which build a number came from.** A debug build measures bounds checks: the same index load is 572 ms in debug and 140 ms in release, and the same keystroke is 176 ms against 16 ms. A design was justified with a figure four times too large before anyone @@ -95,7 +104,7 @@ Things worth knowing before you change any of it: - **`cargo test` fails when `ui/src/ipc/generated.ts` is stale.** Fix with `cargo run -p xtask -- bindings`; the failure names that command and the first differing line. -- **The L4 goldens (`crates/pipdock-cli/tests/golden.rs`, 46 snapshots) are the CLI's output +- **The L4 goldens (`crates/pipdock-cli/tests/golden.rs`, 52 snapshots) are the CLI's output contract.** A diff there is a real behaviour change — re-bless deliberately, never reflexively. They are what made the `core::flow` refactor provably behaviour-preserving. - **Two tests hold the wire format**: `Code::ALL` must serialize as `as_str()`, and no diff --git a/docs/CLI-SPEC.md b/docs/CLI-SPEC.md index 9c22210..ac19dd3 100644 --- a/docs/CLI-SPEC.md +++ b/docs/CLI-SPEC.md @@ -61,7 +61,7 @@ requests held back at 2.30.0 (latest 2.32.3) — blocked by apiclient 1.4 (requ |---|---| | 0 | success, all steps ok | | 1 | completed with per-package failures (see JSON `counts.failed`) | -| 2 | plan aborted (resolution impossible & user/skip policy removed everything) | +| 2 | plan aborted, nothing executed (resolution impossible & user/skip policy removed everything; uninstall guard tripped without `--force`, PD-RES-004) | | 3 | environment error (PD-ENV-*, incl. PEP 668 block) | | 4 | engine unavailable / version too old (PD-ENG-*) | | 5 | snapshot failure — nothing was executed (PD-SNP-001) | @@ -86,6 +86,6 @@ pipdock update --all --env C:\bots\scraper\.venv --yes --json --log-file C:\logs # Audit what an upgrade would do without touching anything: pipdock update pandas numpy --dry-run --json | jq '.held_back' -# Refuse-to-break uninstall in CI (exit 1 if guard trips): +# Refuse-to-break uninstall in CI (exit 2 — plan aborted — if the guard trips): pipdock uninstall legacylib --json || echo "dependents exist, aborting" ``` diff --git a/docs/DATA-FLOW.md b/docs/DATA-FLOW.md index b6b8130..1a65dbb 100644 --- a/docs/DATA-FLOW.md +++ b/docs/DATA-FLOW.md @@ -83,6 +83,18 @@ Selection → [Uninstall] → GuardCheck: reverse-dep graph over full removal se Rationale: bare `pip uninstall` performs **no** dependency check — this guard is a core value-add. +**The dialog is not the enforcement point.** *Remove dependents too* is the caller running the guard +*again* over the widened set, because pulling Y in can break Z and stopping after one level hands the +user a set that still breaks something. And the removal itself refuses to run unless the guard was +clear or the user explicitly accepted the breakage — `flow::GuardAck`, checked in +`UninstallFlow::execute` the way `SnapshotProof` is, so a caller that never looked at the report +cannot proceed by omission. Attempting it anyway is **PD-RES-004**, raised before the snapshot is +written so a plan that will not run leaves nothing behind. + +A removal is blocked on a PEP 668 environment exactly as an update is: §2's preamble is "all mutating +flows", and removing from a system Python is the more dangerous of the two, since no resolver stands +between the user and the damage. + ## 6. Summary model (owner requirement) ```json @@ -125,7 +137,11 @@ Snapshot selected → Diff = (current freeze) vs (snapshot freeze) ## 9. Data-flow invariants (enforced in `pipdock-core`, tested) -1. No mutating engine call without a `ResolutionReport` accepted in this session. +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 + 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. 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. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 0b1fee5..aec5b53 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -232,8 +232,9 @@ one synchronous read at each call site, and the flow no longer touches a databas ### Stage 4 — search, the dock bay and install — **done 2026-08-04** -Five commits. Both exit criteria met and measured in the running app, and 16 of UI-SPEC §6's 16 -components now exist. +Five commits. Both exit criteria met and measured in the running app. *(The "16 of 16 components" +claim recorded here was wrong: the count had folded in components that are not on UI-SPEC §6's list. +It was 13 of 16 then and after S5 — see §6, which now says so.)* | | What landed | |---|---| @@ -267,9 +268,56 @@ debug** rather than printing a number that means nothing. 2. **Every result offered [Add], including installed packages**, because only `PdPackages` ever loaded the installed set. That is exactly the mistake DATA-FLOW §4's chips exist to prevent. -### Stage 5 onward — where to pick up +### Stage 5 — uninstall, the guard dialog and the Pins screen — **done 2026-08-09** -Slices, sizing and exit checks are in the plan; the order is **S2 → S3 → S4 → S5 → S6 → S7**. S2, S3 and S4 are done (above). **S5 — uninstall, the guard dialog and the Pins screen — is next**, and it is a small one: `uninstall_guard` and `uninstall_execute` are the last two mutating commands, DATA-FLOW §5's three-option dialog is fully specified, and the pin commands already exist from S2. Exit: uninstall = 3 clicks, and *Remove dependents too* re-guards rather than proceeding. +Twelve commits. Every mutating command in ARCHITECTURE §7 now exists, and removal is the first flow +whose *whole* value is refusing to do what was asked. + +| | What landed | +|---|---| +| **Core** | `GuardReport.breaks` carries `BrokenDependent { pkg, version, constraint }` — the specifier, not just the name. `GuardAck` makes the guard an enforcement point rather than a dialog. PEP 668 refused on removal. New code **PD-RES-004**. | +| **Execution** | `execute_uninstall` emits the `stepStarted`/`stepFinished` lifecycle it never had, checks the cancellation token in its loop, takes a `base` step index shared with `execute_rollback`, and honours `--no-snapshot`. | +| **Bridge** | One `Session` enum for all four flows, with typed claims; `uninstall_guard`, `uninstall_execute`; `plan_cancel` async, and now discarding a parked session. | +| **UI** | `PdDialog` (the repo's first modal), `PdUninstallDialog`, `PdPinChip`, the Pins screen, the row's ✕, and the `failed` phase. | +| **L3** | The first mocked `@/ipc`, the first store test, the first screen test. 6 files → 9; 59 tests → 79. | + +**Exit criteria, counted and verified in a running app** (driven in the Browser pane against a +stubbed bridge, per the recipe that found Stage 2's double fetch): uninstall is **exactly 3 clicks** +— Installed → row ✕ → *Remove* — and 4 when the guard trips, by design. The dialog reads +`pandas 2.1.4 requires numpy<2,>=1.26.0`, naming the dependent **and** its constraint. *Remove +dependents too* issues a **second** `uninstall_guard` over the widened set with **no** +`uninstall_execute` in between. At the CLI, against a real venv, the guard refuses and exits 2 with +every package still installed. + +**Five live bugs came out of it, none of them S5 features:** + +1. **A claim that found nothing wedged the slot.** `plan_decide`/`plan_execute` wrote `Busy` before + discovering there was no plan, and never released — so one out-of-order call from the UI made + every later command answer `PD-RES-003` for a plan that had never existed. +2. **`execute_uninstall` emitted no lifecycle markers**, and every line carried `step: 0`. The CLI + never noticed because it prints `event.line()` and nothing else; the console drawer groups on + `stepStarted` and the live region counts `stepFinished`, so the GUI would have shown an empty + drawer against a green suite. +3. **A cancelled removal removed everything, then reported `cancelled: true`.** The loop had no + token check at all. +4. **`--no-snapshot` was parsed and ignored on the uninstall path** — the same waiver meant "waive" + for an update and nothing for a removal, the one operation with no way back. +5. **The pin button was a tab stop**, so Space on it toggled the row's *selection* instead of + pinning. The rule was enforced on the checkbox and forgotten one element later. + +**And one specification gap closed:** DATA-FLOW §9.1 required "a `ResolutionReport` accepted in this +session", which the uninstall path cannot produce — there is nothing to resolve. It now names the +proof per plan shape, so the one flow with no preview is no longer the one flow the invariant did not +describe. + +### Stage 6 onward — where to pick up + +The order is **S5 → S6 → S7**, then Phase 3. S5 is done (above). **S6 — snapshots, the env detail and +rollback — is next.** `Session::Rollback` and `RollbackFlow::cancel_handle` already landed in S5, so +S6 adds a constructor call site rather than another widening; what it needs is `RollbackPreview` +crossing IPC, the five `snapshot_*` commands, and the env-detail surface UI-SPEC §4 assumes and which +does not exist. Exit: rollback = 4 clicks, and the preview lists `unrestorable_lines` explicitly as +`PD-SNP-002` rather than dropping them. **All three Stage 1 deferrals are closed**, each in S3 as planned — the `plan-progress` lifecycle enum, the Windows Job Object, and the `ExecutionSummary.cancelled` copy. Deferring them to the slice that could verify them worked: each was finished against a running UI or a real process tree rather than against a guess. diff --git a/docs/TESTING.md b/docs/TESTING.md index ccf086a..a744db8 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -8,7 +8,7 @@ 2. The data-flow invariants (DATA-FLOW §9): no mutation without accepted plan + snapshot. 3. Conflict presentation: held-back attribution sentences must match fixture ground truth. 4. Skip-and-continue semantics and summary counts. -5. Reverse-dependency guard correctness. +5. Reverse-dependency guard correctness — including that it is *enforced*, not merely reported: a removal the user never accepted must be refused (`GuardAck`, PD-RES-004), and widening a removal must re-run the guard rather than proceed. ## 2. Layers diff --git a/docs/UI-SPEC.md b/docs/UI-SPEC.md index f8312a8..9f699d3 100644 --- a/docs/UI-SPEC.md +++ b/docs/UI-SPEC.md @@ -51,7 +51,10 @@ Sidebar is icon+label, collapsible to icons. Status line (mono) always shows env **Environments.** Auto-discovered list (source chip: registry / py launcher / uv / manual) with python version and package count; PEP 668 envs carry a red `MANAGED` chip and a disabled state explaining PD-ENV-002. Actions: *Browse…*, *Rescan*, star-as-default. -**Installed.** Virtualized table: name (mono) · version · latest · size · chips. When the env's `hidden_user_site` is non-null (non-venv system Pythons only — see SECURITY §2), an inline `--color-info` note above the table says user-account packages are not listed and names the path; it is informational, never a block, and never appears for a venv. Up-to-date rows use `--color-text-dim` (owner's "dimmed" requirement); outdated rows show an `UPDATE` badge; pinned rows a 🔒 `--color-info` chip. Row actions: pin/unpin, uninstall, details. Multi-select via checkboxes; bulk action bar appears on selection. +**Installed.** Virtualized table: name (mono) · version · latest · size · chips. When the env's `hidden_user_site` is non-null (non-venv system Pythons only — see SECURITY §2), an inline `--color-info` note above the table says user-account packages are not listed and names the path; it is informational, never a block, and never appears for a venv. Up-to-date rows use `--color-text-dim` (owner's "dimmed" requirement); outdated rows show an `UPDATE` badge; pinned rows a 🔒 `--color-info` chip. Row actions: pin/unpin and uninstall, as two inline buttons rather than a `⋮` menu. A menu would +spend one click opening and one choosing, leaving one of §5's three for a confirm that has to name +what breaks; "details" has no panel to open yet, and when it does all three fold into a menu with the +budget intact. Neither button is a tab stop — the row is (see §8). Multi-select via checkboxes; bulk action bar appears on selection. **Updates.** Same table filtered to outdated, badge count in sidebar. Header: *Select all* (excludes pinned; shows "3 pinned excluded"), *Update selected*. After resolve → **Preview panel** replaces the table: grouped sections — *Will upgrade* (A `1.2 → 2.0`), *Will downgrade*, *Will install*, *New dependencies*, *Needs decision* (held-back in `--color-warn` with one-line blocker sentence; impossible in `--color-danger`). Each needs-decision row hosts a segmented control: **Keep compatible · Skip · Force latest** (Force opens an inline confirm naming what breaks). Footer: `Confirm (n changes)` / `Back`. @@ -63,7 +66,13 @@ Sidebar is icon+label, collapsible to icons. Status line (mono) always shows env **Search.** Search field autofocused; results stream under 50 ms per keystroke from the local index. Result row: name · summary (from cached metadata) · latest · `INSTALLED ✓`/`UPDATE` chip when applicable · **[Add]**. Right detail panel: description, requires-python, license, links. Queue ("**dock bay**") docks along the right edge as a slim column of added packages with editable version fields and `Install (n)`. -**Pins.** Pin list with reason field; (P1) auto-suggest section: "`urllib3` — 12 packages depend on it. Pin?". +**Pins.** Pin list with reason field, committed on blur; unpin per row. **Exclude pins only**: a +`Hold` pin is rendered faithfully if one exists, but creating one is not offered, because +`pins::hold_requirements` has no caller and `engine::plan_requirements` restates every package at its +*installed* version — a hold at any other version is a promise nothing keeps, and the CLI cannot +create one either. With no environment selected the screen says so rather than "no pins": pins are +keyed by `env_hash`, so that is not an empty list. (P1) auto-suggest section: "`urllib3` — 12 +packages depend on it. Pin?". **Snapshots** (surfaced under Environments → env detail): timeline of snapshots with trigger label, diff viewer (added/removed/changed in mono), `Rollback…` with its own preview per DATA-FLOW §8. @@ -75,12 +84,15 @@ Sidebar is icon+label, collapsible to icons. Status line (mono) always shows env ## 5. Click budgets (owner ceiling: 5) +Every click counts, including the one that opens the tab — except on Environments, which is where the +app lands. Counted by hand in the running app, never inferred from the markup. + | Flow | Clicks | Path | |---|---|---| | Update everything | **4** | Updates → Select all → Update → Confirm (app auto-scans on env open) | | Update everything, 1 conflict kept compatible | **4** | default choice needs no extra click | | Install one package | **4** + typing | Search (autofocus) → result [Add] → Install → Confirm | -| Uninstall one package | **3** | Installed row ⋮ → Uninstall → Confirm | +| Uninstall one package | **3** | Installed → row ✕ → *Remove* (4 when the guard trips: → *Remove the dependents too* → *Remove*) | | Rollback last snapshot | **4** | Env detail → snapshot → Rollback → Confirm | | Switch engine | **3** | Settings → engine radio → (auto-saved) back | | Run Code Health | **3** | Health → Run (folder persisted) → view | @@ -89,6 +101,15 @@ Sidebar is icon+label, collapsible to icons. Status line (mono) always shows env `PdSidebar`, `PdStatusLine`, `PdEnvSwitcher`, `PdPackageTable` (virtualized), `PdPackageRow`, `PdBadge`, `PdPreviewDiff`, `PdConflictRow` (segmented 3-way), `PdDockBay` (queue), `PdConsoleDrawer`, `PdSummarySheet`, `PdSnapshotTimeline`, `PdHealthReport`, `PdLegalGate`, `PdEmptyState`, `PdOfflineBanner`. +**13 of those 16 exist** as of S5. Absent: `PdEnvSwitcher` and `PdSnapshotTimeline`, which arrive +with the env detail in S6, and `PdHealthReport`, which arrives with Code Health in M3. (ROADMAP and +CLAUDE.md both claimed 16 of 16 after S4; the count had quietly folded in components that are not on +this list.) Four components not on this list have +turned out to be load-bearing and are listed here so the inventory stays honest: `PdErrorRow` +(ERROR-CATALOG §3's row, used by every error surface), `PdDialog` (the shared modal §7's destructive +confirms need), `PdUninstallDialog` (§5's three options) and `PdPinChip` (the 🔒 chip, shared by the +table and the Pins screen). + ## 7. States & feedback - Loading: skeleton rows in surface-2, never spinners longer than 300 ms without text.