diff --git a/CLAUDE.md b/CLAUDE.md index d774381..039509d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 6f9b6b3..42d91ff 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -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. | diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index b92846b..e0ae9fa 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -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: \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).