docs: record Stage 1, and what the next session needs to know
ROADMAP Phase 2 gains a Stage 1 table — what landed, and the four bugs that were not in the plan, all of which came from running things rather than reading them. It also names the three deferrals explicitly, with the slice each belongs to, because "we'll get to it" is how the plan-progress payload stayed unimplementable for a whole milestone. CLAUDE.md's "current state" was still describing the bridge as names-only. It now says the app runs, and lists the four things a next session would otherwise discover by breaking them: the bindings staleness check, the L4 goldens as an output contract, the two tests holding the wire format, and — the one that earned its place — run it, don't just test it. Three more entries under "things that look like bugs but are not", each a decision someone would reasonably try to undo: the `serde(alias)` on snapshot::Meta (remove them and every existing snapshot stops parsing), the deliberate split between take_snapshot() and execute(), and the fixture redaction. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
1 parent
a553bf7460
commit
d7da4d72e2
2 files changed
+56
-13
No files matched your search
@@ -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).
|
||||
+24
-5
@@ -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)
|
||||
|
||||
|
||||
Reference in new issue
Block a user