docs: record S5, and the controls that are deliberately absent
ROADMAP gains the Stage 5 table it never had — the whole S5/S6/S7 definition lived outside the repo, so `main` described the order and nothing else. Five live bugs are recorded there because none of them were S5 features: the wedged slot, the missing lifecycle markers, the removal that ignored its cancellation token, the swallowed `--no-snapshot`, and the pin button that was a tab stop. DATA-FLOW §5 now says the dialog is not the enforcement point, and §9.1 names its proof per plan shape: a `ResolutionReport` for a resolve, a `GuardReport` plus a `GuardAck` for a removal, a `RollbackPlan` for a restore. It had required a `ResolutionReport` "accepted in this session", which the uninstall path cannot produce — there is nothing to resolve — so the one flow with no preview was also the one flow the invariant did not describe. UI-SPEC §4 records two inline row buttons rather than the `⋮` menu it specified, with the click arithmetic that forced it, and the Pins screen's Exclude-only scope with the reason: `pins::hold_requirements` has no caller and `plan_requirements` restates the installed version, so a Hold at another version is a promise nothing keeps. §5 states the click-counting convention it had been applying inconsistently. §6 corrects the inventory to **13 of 16** — the "16 of 16" claim after S4 had folded in components that are not on that list — and names the four that are load-bearing but unlisted. CLI-SPEC §5 and §7 follow the exit code from 1 to 2. TESTING §1.5 says the guard must be enforced and not merely reported. CLAUDE.md: 31 → 32 codes, and adding one now re-blesses every schema that *embeds* `Code`, not just `Code`; 46 → 52 goldens; and the rule S5 leaves behind — a decision that sits between two IPC messages needs a value the executing call demands, or "somebody forgot to look" stays expressible. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
1 parent
f5badf2750
commit
f354030ed9
6 files changed
+113
-19
No files matched your search
@@ -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
|
||||
|
||||
+2
-2
@@ -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"
|
||||
```
|
||||
+17
-1
@@ -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.
|
||||
|
||||
+52
-4
@@ -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.
|
||||
|
||||
|
||||
+1
-1
@@ -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
|
||||
|
||||
|
||||
+24
-3
@@ -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.
|
||||
|
||||
Reference in new issue
Block a user