Files
pipdock/CLAUDE.md
T
poli0981andClaude Opus 5 f354030ed9 docs: record S5, and the controls that are deliberately absent
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>
2026-08-09 21:46:25 +07:00

12 KiB
Raw Blame History

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.

  1. docs/PRD.md — goals G1–G7, personas, P0/P1/P2 feature matrix, non-goals
  2. docs/ARCHITECTURE.md — crate layout, Engine trait, probe.py, storage, Tauri IPC, version manifest
  3. docs/DATA-FLOW.md — update/install/uninstall/rollback state machines, engine command mapping, invariants §9
  4. docs/UI-SPEC.md — design tokens, screens, click budgets, keyboard map
  5. docs/CLI-SPEC.md — commands, flags, exit codes, JSON contracts
  6. docs/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 folds PD-HLT-001..003 into one row. Adding a code means the catalog, Code::ALL, both counts, the "no code without a fixture" gate in classifier_corpus.rs, both locale catalogs, and re-blessed goldens — golden__schema-Code.snap and every schema that embeds it (StepResult, ExecutionSummary) — the gate will tell you which you forgot
  7. docs/CODE-HEALTH-SPEC.md, docs/SECURITY.md, docs/TESTING.md, docs/RELEASE-CI.md, docs/I18N.md, docs/ROADMAP.md
  8. legal/ — EULA, Disclaimer, Privacy, Third-Party Notices (public; the in-app legal gate links to these GitHub URLs)

Hard invariants — never violate these

  1. No mutating engine call without (a) a ResolutionReport accepted this session and (b) a successful snapshot write. Snapshot failure aborts the plan, executing nothing (PD-SNP-001). See DATA-FLOW §9.
  2. Subprocess via argv arrays only — never a shell. tokio::process::Command with explicit args. Package names validated against PEP 508 and versions against PEP 440 before they reach argv. See SECURITY §2.
  3. Never reimplement dependency resolution. The selected engine resolves in dry-run mode; PipDock parses and explains. See ARCHITECTURE §1.2.
  4. 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.
  5. --break-system-packages is 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)

  1. 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.
  2. Every pip invocation needs PYTHONIOENCODING=utf-8 + PYTHONUTF8=1. Without it --dry-run --report - crashes on Windows/cp1252 (pip 25 and 26), data-dependently.
  3. uv writes its plan to stderr, so classify errors only after a plan-parse attempt.
  4. env_hash lowercases the interpreter path on Windows, or one env splits its pins and snapshots in two.
  5. PipDock enforces Requires-Python itself (src/compat.rs) — the engines disagree, and the preview must not depend on which one is selected.

Conventions

  • Crates pipdock-*; React components prefixed Pd (PdPackageRow, PdConflictDialog)
  • Tauri identifier com.skullmute.pipdock; CLI binary pipdock
  • Frontend lives in ui/, but package.json sits at the repo root so the ops-repo reusable-web-react.yml (which has no working-directory input) works unmodified; Vite is configured with root: './ui'
  • Rust ↔ TS types are generated with specta/tauri-specta — never hand-mirror a type
  • No component calls invoke directly; everything goes through the typed wrappers in ui/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_upgrades at the plan boundary; a preview must show the flow's excluded_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) because pkg_list is local and pkg_outdated is 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, and Store is not Sync. 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 why UpdateFlow::start takes pins rather than a &Store, and why index::metadata/refresh take 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 GuardAck inside UninstallFlow::execute, beside SnapshotProof. 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.rs refuses to run in debug for that reason.

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, 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 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 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, --json that 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 real pip 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.py is 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.files looks harmless and costs 10×; read the metadata files directly and measure before committing.

Things that look like bugs but are not

  • probe.py reporting fewer packages than pip list on a non-venv Python is the documented -I trade-off; hidden_user_site is non-null exactly then.
  • snapshot diff showing 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 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.
  • 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 verify SHA256SUMS.txt. Do not reintroduce it without an explicit owner decision.
  • 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.
  • 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).