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>
12 KiB
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: M1 complete; M2 Stages 1–4 done, S5 next.
Read the docs before changing anything
The design is fully specified. Read in this order; do not invent behaviour that contradicts them.
docs/PRD.md— goals G1–G7, personas, P0/P1/P2 feature matrix, non-goalsdocs/ARCHITECTURE.md— crate layout,Enginetrait,probe.py, storage, Tauri IPC, version manifestdocs/DATA-FLOW.md— update/install/uninstall/rollback state machines, engine command mapping, invariants §9docs/UI-SPEC.md— design tokens, screens, click budgets, keyboard mapdocs/CLI-SPEC.md— commands, flags, exit codes, JSON contractsdocs/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 foldsPD-HLT-001..003into one row. Adding a code means the catalog,Code::ALL, both counts, the "no code without a fixture" gate inclassifier_corpus.rs, both locale catalogs, and re-blessed goldens —golden__schema-Code.snapand every schema that embeds it (StepResult,ExecutionSummary) — the gate will tell you which you forgotdocs/CODE-HEALTH-SPEC.md,docs/SECURITY.md,docs/TESTING.md,docs/RELEASE-CI.md,docs/I18N.md,docs/ROADMAP.mdlegal/— EULA, Disclaimer, Privacy, Third-Party Notices (public; the in-app legal gate links to these GitHub URLs)
Hard invariants — never violate these
- No mutating engine call without (a) a
ResolutionReportaccepted this session and (b) a successful snapshot write. Snapshot failure aborts the plan, executing nothing (PD-SNP-001). See DATA-FLOW §9. - Subprocess via argv arrays only — never a shell.
tokio::process::Commandwith explicit args. Package names validated against PEP 508 and versions against PEP 440 before they reach argv. See SECURITY §2. - Never reimplement dependency resolution. The selected engine resolves in dry-run mode; PipDock parses and explains. See ARCHITECTURE §1.2.
- Rust emits catalog codes and structured data only. All human phrasing lives in the i18next catalogs under
ui/src/locales/. Codes, package names, versions and stderr are never translated. See I18N §1. --break-system-packagesis never passed implicitly. PEP 668 environments are blocked by default; the flag is only sent when the user has explicitly enabled the Settings override. See SECURITY §3.
Two more that follow from them: every user-visible failure carries exactly one catalog code, and a
failed package never aborts a batch (skip-and-continue, then a "13 successful, 2 failed" summary).
What the spikes proved (read spikes/README.md before writing an adapter)
- Every plan must restate the full installed set as explicit requirements.
install -U <pkg>ignores installed packages' constraints in both engines and will break them at exit 0. - Every pip invocation needs
PYTHONIOENCODING=utf-8+PYTHONUTF8=1. Without it--dry-run --report -crashes on Windows/cp1252 (pip 25 and 26), data-dependently. - uv writes its plan to stderr, so classify errors only after a plan-parse attempt.
env_hashlowercases the interpreter path on Windows, or one env splits its pins and snapshots in two.- PipDock enforces
Requires-Pythonitself (src/compat.rs) — the engines disagree, and the preview must not depend on which one is selected.
Conventions
- Crates
pipdock-*; React components prefixedPd(PdPackageRow,PdConflictDialog) - Tauri identifier
com.skullmute.pipdock; CLI binarypipdock - Frontend lives in
ui/, butpackage.jsonsits at the repo root so the ops-reporeusable-web-react.yml(which has noworking-directoryinput) works unmodified; Vite is configured withroot: './ui' - Rust ↔ TS types are generated with
specta/tauri-specta— never hand-mirror a type - No component calls
invokedirectly; everything goes through the typed wrappers inui/src/ipc/
CI reality
docs/RELEASE-CI.md is authoritative as corrected: the ops repo poli0981/.github has no
reusable Rust or Tauri workflow, its notifiers are Discord-only, dependency bumps are
Dependabot (not Renovate), and its CodeQL reusable has no Rust support. So ci-rust.yml and
release.yml are project-local; ci-node.yml, codeql.yml and the notifiers are callers.
Every caller needs an explicit permissions: block — callers without one default to none.
Current state
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 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:
-
"N pinned excluded" in the table is presentation, not enforcement. DATA-FLOW §9.5 is enforced by
pins::filter_upgradesat the plan boundary; a preview must show the flow'sexcluded_pins(), not a number the UI computed, or the two drift. -
Never render a state you have not loaded. Row state is three-valued (
unknown/current/outdated) becausepkg_listis local andpkg_outdatedis networked. Treating "not yet known" as "up to date" dims 200 rows and un-dims a handful a second later. -
A Tauri command's future must be
Send, andStoreis notSync. Never hold the store guard across an await — it does not compile at the command boundary, and where it does compile (inside core) it serializes every other command behind a network call. Read what you need, drop the guard, then await. This is whyUpdateFlow::starttakes pins rather than a&Store, and whyindex::metadata/refreshtake 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
GuardAckinsideUninstallFlow::execute, besideSnapshotProof. 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 noticed.crates/pipdock-core/tests/search_latency.rsrefuses to run in debug for that reason.
Things worth knowing before you change any of it:
cargo testfails whenui/src/ipc/generated.tsis stale. Fix withcargo run -p xtask -- bindings; the failure names that command and the first differing line.- 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 thecore::flowrefactor provably behaviour-preserving. - Two tests hold the wire format:
Code::ALLmust serialize asas_str(), and noSCHEMA_TYPESproperty may contain_. Both fail atcargo test. - Run it, don't just test it. Every unplanned bug in Stage 1 and Stage 2 came from executing
against a real environment, a real runner or a real browser — never from reading code or from a
passing suite. Stage 1: the watchdog that never killed anything,
--jsonthat never parsed, attribution that told 3.12 users something false, a drift job that could not go green. Stage 2: a probe 10× slower than before (found by timing it), a size that was wrong rather than missing for editable installs and a package listed twice (both found by one realpip install -e), and every screen fetching twice on mount (found by logging what actually crossed the bridge). Stage 3: a cancellation test that passed while the orphan lived on. Stage 4: an index load reported four times too large because it was measured in debug, a keystroke budget that was being missed by 30 ms, and a plan started from Search that resolved into a screen which does not render it — the command ran, the flow parked, and the user saw nothing change. probe.pyis on the hot path. The Installed screen re-probes on every environment open, so anything added to_dists()is paid 200+ times per open.Distribution.fileslooks harmless and costs 10×; read the metadata files directly and measure before committing.
Things that look like bugs but are not
probe.pyreporting fewer packages thanpip liston a non-venv Python is the documented-Itrade-off;hidden_user_siteis non-null exactly then.snapshot diffshowing entries a rollback cannot restore (editable installs, direct URLs) is deliberate: they are excluded from the pin set and reported separately rather than dropped.pipdock engine uvfailing when uv is not on PATH is intentional — storing a preference that cannot be honoured just moves the failure to the next command.- The app has no self-update and no
tauri-plugin-updater. Removed on purpose (SECURITY §5): a self-updater is a standing remote-code-execution path into a tool that already runs subprocesses against the user's interpreters, and it has to be defended forever — a key that must never leak, an endpoint that must never be spoofable. Tauri makes adding it back a three-line change, so this is written down. Users get new builds from GitHub Releases and verifySHA256SUMS.txt. Do not reintroduce it without an explicit owner decision. - Fixtures under
tests/fixtures/{pip,uv}/are not literal engine bytes:spikes/capture.pyredacts 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: everyCLASSIFIERSentry keys off message text, and the uv adapter only testscontains("Resolved "). Line endings are still byte-exact, which is what.gitattributes'-textprotects. meta.jsonnext tocapture-provenance.jsonis a deliberate split.meta.jsonis the contract the drift gate watches; provenance records engine/interpreter versions and argv, churns on every release, and is excluded from the gate.snapshot::Metacarries#[serde(alias)]on its renamed fields. It is the on-disk.meta.jsonand 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()andexecute()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 whyflow::proof_fromrefusesNotTakenwithPD-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.labeland every path, version and engine id in the UI are data and are never translated (I18N §2).