docs: close M1, and correct the M2 estimate against what the bridge actually is
ROADMAP said L2 "has never run". It had, three times, failing each time; record
what failed and why, since both causes were in the harness rather than the product
and neither is obvious from the job name.
M2 was estimated at 3-4 weeks. Surveying the code for it shows the bridge is
scaffolding: 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 moves to 7-8 weeks to match it, and three pieces with no
home in the core yet are named so they get sequenced before the screens rather
than discovered during them:
- the flow layer, since plan_and_run is ~200 lines of DATA-FLOW section 3 living
only in the CLI, and duplicating it would mean two implementations of the hard
invariants
- cancellation, which does not exist at all -- plan_cancel is a declared TS name
with no Rust counterpart, and exec.rs's watchdog drops the future rather than
killing the child
- progress, where ProgressEvent.step is hardcoded 0 at all four producers and
scan-progress has no producer
Also: ARCHITECTURE section 10 still said uv "0.9.x line, minimum pinned after
SP-1" when SP-1 pinned 0.10.0 and shipped it as UV_MIN_VERSION; CLAUDE.md said
"Status: Phase 0" three lines above a paragraph saying M1 was substantially
complete; and the fixture redaction now needs recording under "things that look
like bugs but are not", because "these are not literal engine bytes" is exactly
the kind of thing someone will otherwise try to helpfully undo.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
1 parent
4066aa63d4
commit
465b54f7e8
3 files changed
+44
-12
No files matched your search
@@ -1,7 +1,7 @@
|
||||
# PipDock — working notes for Claude
|
||||
|
||||
Windows GUI + CLI for bulk-managing Python packages. Tauri 2 + Rust core + React 19.
|
||||
Repo `poli0981/pipdock` · GPL-3.0 · **Status: Phase 0 (scaffold + spike week)**.
|
||||
Repo `poli0981/pipdock` · GPL-3.0 · **Status: M1 complete (core + CLI); M2 (Tauri GUI) starting**.
|
||||
|
||||
## Read the docs before changing anything
|
||||
|
||||
@@ -59,13 +59,15 @@ Every caller needs an explicit `permissions:` block — callers without one defa
|
||||
|
||||
## Current state
|
||||
|
||||
**M1 substantially 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, what changed
|
||||
during implementation, and what is still owed — notably TESTING L2 has never actually run in CI,
|
||||
and the L4 golden-output tests are not written.
|
||||
**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.
|
||||
|
||||
Next is M2, the Tauri GUI. The core already carries everything it needs; the shell, design tokens
|
||||
and locale catalogs are scaffolded and the IPC command names are fixed in `ui/src/ipc`.
|
||||
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.
|
||||
|
||||
## Things that look like bugs but are not
|
||||
|
||||
@@ -75,3 +77,13 @@ and locale catalogs are scaffolded and the IPC command names are fixed in `ui/sr
|
||||
deliberate: they are excluded from the pin set and reported separately rather than dropped.
|
||||
- `pipdock engine uv` failing when uv is not on PATH is intentional — storing a preference that
|
||||
cannot be honoured just moves the failure to the next command.
|
||||
- Fixtures under `tests/fixtures/{pip,uv}/` are **not** literal engine bytes: `spikes/capture.py`
|
||||
redacts absolute paths, object addresses, progress bars and uv's timings. Without that they
|
||||
differ on every run and every machine, so the weekly drift job could never go green — and pip's
|
||||
"[notice] To update, run: …" shipped the capturing user's home directory to a public repo. It is
|
||||
safe because nothing reads a path or a duration out of them: every `CLASSIFIERS` entry keys off
|
||||
message text, and the uv adapter only tests `contains("Resolved ")`. Line endings are still
|
||||
byte-exact, which is what `.gitattributes`' `-text` protects.
|
||||
- `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.
|
||||
@@ -135,7 +135,7 @@ Zustand stores: `useEnvStore`, `usePlanStore`, `useIndexStore`, `useSettingsStor
|
||||
| Vite / Tailwind | 8.1.x (Rolldown line) / 4.x |
|
||||
| Node (dev only) | 24 LTS (Active LTS; EOL 2028-04) |
|
||||
| pip engine | ≥ 24.0 supported; latest is 26.1.x. `--dry-run --report` requires ≥ 22.2 — PipDock offers to upgrade older pips before first plan. |
|
||||
| uv engine | latest stable (0.9.x line at writing); minimum pinned after SP-1 |
|
||||
| uv engine | latest stable (0.11.x line at writing); **minimum 0.10.0**, pinned by SP-1 (`UV_MIN_VERSION`, `engine/mod.rs`) |
|
||||
| Managed Pythons | 3.10 – 3.14 (3.9 is EOL) |
|
||||
| Windows | 10 (1809+) / 11; WebView2 Evergreen assumed present; `longPathAware` manifest enabled |
|
||||
| rusqlite | **held at 0.37** (`libsqlite3-sys` 0.35). 0.40 pulls `libsqlite3-sys` 0.38.1, whose build script uses the unstable `cfg_select!` and therefore does not compile on stable Rust 1.94.1. Revisit when the toolchain advances. |
|
||||
|
||||
+24
-4
@@ -56,28 +56,48 @@ Verified against real environments, not only unit tests:
|
||||
### Not yet done
|
||||
|
||||
- **`health`** — belongs to M3 with the tools venv (CODE-HEALTH-SPEC).
|
||||
- **TESTING L2 in CI** — `ci-integration.yml` is written but has never run; it needs a push to GitHub and the repo settings from RELEASE-CI §5.
|
||||
- **TESTING L2 in CI** — ~~has never run~~. It ran nightly on 2026-07-28 and 2026-07-29 and failed both times, for two causes that were diagnosed and fixed on 2026-07-29 (see *L2's first runs* below). Re-verify with `gh workflow run ci-integration.yml`.
|
||||
- **TESTING L4** — `assert_cmd` is a dependency and the clap surface is covered, but the golden-output tests per command are not written.
|
||||
- **The SP-5 tangle env** — the exit criterion names a real numpy/scipy/pandas environment. The httpx/httpcore construction proved the mechanism; the large-environment run is still owed, and is the natural first dogfooding step.
|
||||
- **Settings beyond engine choice** — locale, thresholds and the PEP 668 override land with the GUI in M2.
|
||||
|
||||
### L2's first runs — what actually failed (2026-07-29)
|
||||
|
||||
The job ran and failed three times. Neither cause was a product bug; both were in the test harness, and both are fixed.
|
||||
|
||||
**1. The rollback assertion targeted the wrong snapshot.** The step did `snapshot create` → `update --all` → `snapshot rollback latest` → `snapshot diff latest`, asserting the prose `matches snapshot`. But `latest` moves twice during that flow: `update --all` writes a `Trigger::Plan` snapshot before mutating, and `snapshot rollback` writes a `Trigger::Rollback` one before restoring (DATA-FLOW §8 — rollback is itself reversible). So the final `diff latest` compared the restored environment against the *pre-rollback* state and correctly reported every package as changed. The rollback itself had worked. Fixed by pinning the id from `snapshot list --json` immediately after `create`, and asserting structurally on `diff --json` rather than on prose.
|
||||
|
||||
**2. `fixture-drift` could never have gone green.** `spikes/capture.py` built each scenario in a `mkdtemp` directory whose name carries a random suffix, and `redact()` replaced only the temp *root* — so the suffix survived into every committed sidecar, and every re-capture differed. Four further sources of churn were found underneath it: pip's `[notice] To update, run: <venv>\Scripts\python.exe` (which also leaked the capturing user's home directory into a public repo), CPython object addresses in urllib3 retry warnings, pip's download progress bar with its transfer rate, and uv's per-phase timings (`Resolved 3 packages in 775ms`). Fixed by redacting all of them in `capture.py`, splitting the sidecar into `meta.json` (contract, gated) and `capture-provenance.json` (versions and argv, excluded from the gate), and capturing cache-free so a warm dev machine and a cold runner agree.
|
||||
|
||||
Verified by running both engines' captures twice back to back: **0 of 96 fixture files differ between two identical runs**, and 173 tests stay green.
|
||||
|
||||
Two things worth keeping in mind, both recorded in `.gitattributes` and `CLAUDE.md`: `-text` is what preserves the CRLF bytes the fixtures need, and `-diff` — which was also set — only suppressed the textual diff, so the drift job's own diagnostics could report nothing but "Binary files differ". And the weekly drift job's `if:` matched the *nightly* cron, so the PyPI-heavy job the comment says would be "rude" to run daily was running daily; it now has its own `'17 4 * * 1'` entry.
|
||||
|
||||
### Where to pick up
|
||||
|
||||
Pushed to `main` and green: **CI / Rust, CI / Node and CodeQL all pass** on the published commit. Three configuration bugs were fixed getting there, each recorded in its own commit message: caller workflows must grant *at least* what the callee declares (a `startup_failure` with no logs), `cargo audit` was pinned to a toolchain too old to build itself, and its informational advisories needed scoping rather than silencing.
|
||||
|
||||
Immediate, in rough order:
|
||||
|
||||
1. **Close the two Dependabot PRs that would break the build** — TypeScript 7 and rusqlite 0.40. Both are the holds listed in ARCHITECTURE §10, and their CI already fails. The `actions/setup-*` bumps are fine to merge.
|
||||
2. **Let `ci-integration.yml` run.** It has never executed: it triggers on PRs touching engine/plan/snapshot/graph paths, or nightly. Watch the first run rather than assuming it passes — it is the only thing standing behind the L2 exit criterion.
|
||||
1. **Triage six open Dependabot PRs.** Close #3 (TypeScript 7) and #4 (rusqlite 0.40) — both are the holds listed in ARCHITECTURE §10, and §10's rule is that those are closed rather than merged. #1 and #2 (`actions/setup-python`, `actions/setup-node` 6→7) show a stale `cargo audit` failure predating `566ee27` and need a rebase before their CI means anything. #6 (schemars 1.2.2) should land before M2 starts, since the type-generation strategy rides on schemars output. #5 (@types/node) whenever.
|
||||
2. **Re-verify `ci-integration.yml`** with `gh workflow run` on both matrix legs after the fixes above.
|
||||
3. **Repo settings** — branch protection, secrets, and the updater keypair, per RELEASE-CI §5. None of these are committable and all are owner-only.
|
||||
4. **Dogfood on a real environment** — the SP-5 numpy/scipy/pandas tangle, which is both the outstanding M1 exit criterion and the first honest test of the held-back sentences at scale.
|
||||
|
||||
Then M2. The core carries everything the GUI needs; `ui/src/ipc` fixes the command names, the design tokens and EN/VI catalogs are scaffolded, and the shell renders.
|
||||
|
||||
## Phase 2 — M2 "GUI shell + core flows" (~3–4 weeks)
|
||||
## Phase 2 — M2 "GUI shell + core flows" (~7–8 weeks)
|
||||
|
||||
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.
|
||||
|
||||
Three pieces of M2 have no home in the core yet and should be sequenced before the screens:
|
||||
|
||||
- **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.
|
||||
|
||||
## Phase 3 — M3 "Health + polish" (~2 weeks)
|
||||
|
||||
Tools venv, deptry/vulture/ruff runners + report UI + gated fix, pip upkeep, bug-report deep link, offline states, keyboard map, icon/branding pass. **Exit:** CODE-HEALTH flows pass on two real projects (one pyproject, one requirements-only).
|
||||
|
||||
Reference in new issue
Block a user