diff --git a/CLAUDE.md b/CLAUDE.md index 8d4e42c..aafabe4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -61,15 +61,28 @@ Every caller needs an explicit `permissions:` block — callers without one defa ## Current state -**M1 complete.** The CLI works against real environments: every P0 command except `health` (which -belongs to M3). See `docs/ROADMAP.md` Phase 1 for what is verified and what changed during -implementation. Still owed: the L4 golden-output tests (`assert_cmd` and `insta` are dev-deps and -currently unused) and the SP-5 numpy/scipy/pandas dogfood. +**M1 complete. M2 Stage 1 (the IPC bridge) complete 2026-07-30.** The app runs: legal gate → +Environments → Settings, over real commands. `docs/ROADMAP.md` Phase 2 has the full Stage 1 table +and says where to pick up — read it before starting a slice. -Next is M2, the Tauri GUI. Read `docs/ROADMAP.md` Phase 2 before starting — the bridge is thinner -than it looks: `ui/src/ipc/index.ts` fixes 26 command *names* with zero wrappers, `src-tauri` -registers exactly one command (`app_info`, a smoke test), and 2 of 16 `Pd*` components, 1 of 5 -Zustand stores and 2 of 14 locale catalogs exist. +Next is **S2** (Installed + Updates, read-only), then **S3** (the mutation spine, the biggest +slice). Three things are deliberately deferred to the slice that can verify them, and ROADMAP +Phase 2 lists them: the `plan-progress` lifecycle enum, a Windows Job Object for whole-tree kill, +and the post-cancel summary copy. + +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 + 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 + `SCHEMA_TYPES` property may contain `_`. Both fail at `cargo test`. +- **Run it, don't just test it.** Every one of the four unplanned bugs found during Stage 1 came + from executing against a real environment or a real runner, not from reading code or passing + tests: the watchdog that never killed anything, `--json` that never parsed, attribution that + told 3.12 users something false, and a drift job that could not go green. ## Things that look like bugs but are not @@ -95,3 +108,14 @@ Zustand stores and 2 of 14 locale catalogs exist. - `meta.json` next to `capture-provenance.json` is a deliberate split. `meta.json` is the contract the drift gate watches; provenance records engine/interpreter versions and argv, churns on every release, and is excluded from the gate. +- **`snapshot::Meta` carries `#[serde(alias)]` on its renamed fields.** It is the on-disk + `.meta.json` *and* an IPC type; without the aliases every snapshot written before the camelCase + change becomes unparseable, and the rollback the user was relying on silently is not offered. + Removable only once no pre-1.0 snapshot can still be on disk. +- **`take_snapshot()` and `execute()` are two calls on purpose**, so the CLI can print the snapshot + id before execution and the GUI can draw DATA-FLOW §3's distinct states. The cost is that + skipping the snapshot becomes expressible, which is why `flow::proof_from` refuses `NotTaken` + with `PD-SNP-001`. Do not "simplify" them back into one. +- **Fixtures under `tests/fixtures/{pip,uv}/` are not literal engine bytes** — see the redaction + note above. Related: `ScanProgress.label` and every path, version and engine id in the UI are + data and are never translated (I18N §2). diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 0ae8b89..fe84376 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -132,13 +132,32 @@ Then M2. The core carries everything the GUI needs; `ui/src/ipc` fixes the comma Tauri app, design tokens, Environments/Installed/Updates/Search/Pins screens, preview + 3-way conflict UX, console drawer, summary sheet, snapshots UI, legal gate, EN/VI catalogs, settings. **Exit:** all UI-SPEC click budgets met by manual count; L3 green; VI sweep clean. -The estimate was 3–4 weeks until 2026-07-29, when surveying the code for M2 showed the bridge is scaffolding rather than substance: `ui/src/ipc/index.ts` fixes 26 command **names** with zero wrappers, `src-tauri` registers exactly one command (`app_info`, a smoke test), and 2 of 16 `Pd*` components, 1 of 5 Zustand stores and 2 of 14 locale catalogs exist. Scope is unchanged; the estimate moved to match it. +The estimate was 3–4 weeks until 2026-07-29, when surveying the code for M2 showed the bridge was scaffolding rather than substance: 26 command **names** with zero wrappers, one registered Tauri command, 2 of 16 `Pd*` components, 1 of 5 stores. Scope is unchanged; the estimate moved to match it. -Three pieces of M2 have no home in the core yet and should be sequenced before the screens: +### Stage 1 — the IPC bridge — **done 2026-07-30** -- **A shared flow layer.** `plan_and_run` (`crates/pipdock-cli/src/run.rs`, ~200 lines) is the whole DATA-FLOW §3 machine and lives only in the CLI — PEP 668 gate, pins filtering, the conflict re-resolve loop, snapshot-or-waive, `AcceptedPlan::accept`, two-phase execute. So do rollback execution and the uninstall guard. The GUI needs all of it, and duplicating it would mean two implementations of the hard invariants. -- **Cancellation.** Nothing exists: no token, no `child.kill()`. `plan_cancel` is a declared TS name with no Rust counterpart, and `exec.rs`'s 600 s watchdog uses `tokio::time::timeout`, which drops the future — tokio children are not kill-on-drop, so the child outlives it today. -- **Progress.** `ProgressEvent.step` is hardcoded `0` at all four producer sites, so the console drawer's per-package markers and the live region's "13 of 15" are unimplementable as written; and `scan-progress` has no producer at all. +Ten commits, `0ccee04..a553bf7`. Everything M2's screens stand on now exists, and there is a running app. + +| | What landed | +|---|---| +| **Wire format** | `#[serde(rename)]` on all 30 `Code` variants so they serialize as `PD-*`, and `rename_all = "camelCase"` on every IPC-crossing struct. `--json` had never matched DATA-FLOW §6 or ERROR-CATALOG §3 — and the two `--json` paths in the binary disagreed with each other. Held by a `Code::ALL` round-trip test and a test that walks every `SCHEMA_TYPES` schema rejecting any property containing `_`. | +| **Codegen** | `ui/src/ipc/generated.ts` from schemars via `cargo run -p xtask -- bindings`. Deviates from ARCHITECTURE §9's specta; reasoning and the revisit condition are in `crates/pipdock-core/src/bindings.rs`. Drift is a **test** failure, so it fires locally as well as in CI. | +| **`core::flow`** | `UpdateFlow`, `UninstallFlow`, `RollbackFlow` — resumable state machines, because the GUI's two decision points are IPC round trips with a render in between. `plan::execute_rollback` is new: core had `rollback_plan()` and nothing to run it, so the CLI hand-assembled an `ExecutionSummary`. **The flow never prints.** | +| **Cancellation** | `CancellationToken` through `exec.rs`, plus `kill_on_drop(true)` — the 600 s watchdog had never killed anything. A cancelled Phase A does **not** fall through to Phase B, and a step killed by us is `Skipped`, not `Failed`. | +| **Progress** | `ProgressSink` carries `step`/`total`; `scan-progress` finally has a producer and a payload (`ScanProgress`). | +| **Vertical slice** | Legal gate, Environments, Settings. `core::settings`, `docsHash` computed in `build.rs`, capabilities split and scoped. | + +**Four bugs turned up that were not in the plan**, all found by running things rather than reading them: the watchdog leak; `--json` unparseable because `snapshot … written` went to stdout; blocker attribution naming constraints from other Pythons (the SP-5 dogfood); and `updater:default` granted to a plugin whose pubkey was a placeholder. + +### Stage 2 onward — where to pick up + +Slices, sizing and exit checks are in the plan; the order is **S2 → S3 → S4 → S5 → S6 → S7**. S2 (Installed + Updates, read-only) is next and needs a virtualization library — `@tanstack/react-virtual` is the recommendation, and any addition must survive `npm audit --audit-level=high`. + +Three things are deliberately deferred and should be picked up **with the slice that can verify them**, not before: + +1. **The `plan-progress` lifecycle enum** (`StepStarted` / `Line` / `StepFinished`) and Tauri-side event coalescing. Belongs with the console drawer in **S3**, where a running UI can show whether the per-package markers actually work. Changing the payload shape amends ARCHITECTURE §7. +2. **A Windows Job Object** (`JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`) so cancellation kills the whole process tree. Today it reaches the direct child only; the measured consequence is recorded on `exec::Command::build`. `python -m pip` spawns build backends, so this matters for **S3**. +3. **`ExecutionSummary.cancelled` copy.** Nothing specifies what to tell a user whose install was interrupted, and killing pip mid-install can leave site-packages partially written. The summary should say so and point at the snapshot. ## Phase 3 — M3 "Health + polish" (~2 weeks)