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>
12 KiB
PipDock — Architecture
Version 0.1 · 2026-07-17
1. Design principles
- One core, two heads. All domain logic lives in
pipdock-core(Rust). The Tauri GUI and the clap CLI are thin adapters over the same functions; neither contains business logic. - Explain, don't reimplement. Dependency resolution is always performed by the selected engine (pip or uv) in dry-run mode. PipDock parses and presents; it never computes version resolution itself.
- Out-of-band by construction. PipDock ships as a standalone signed binary. It is never installed into a Python environment, so no operation it performs can break its own runtime (G6).
- Everything mutating is previewed and snapshotted. No code path may call a mutating engine command without (a) a prior dry-run plan and (b) a pre-execution snapshot.
- Subprocess, never shell. Engines are invoked with argv arrays (
tokio::process::Command), never through a shell. Package names are validated against the PEP 508 name grammar before ever reaching argv.
2. Repository layout
pipdock/
├─ crates/
│ ├─ pipdock-core/ # domain logic (this is the product)
│ │ ├─ src/engine/ # Engine trait + pip.rs + uv.rs adapters
│ │ ├─ src/envs/ # discovery (PEP 514, py launcher, uv, venv scan), PEP 668
│ │ ├─ src/index/ # PEP 691 name cache, fuzzy search (nucleo), PyPI JSON metadata
│ │ ├─ src/plan/ # PlanRequest → ResolutionReport → ExecutionReport
│ │ ├─ src/graph/ # reverse-dependency graph from env introspection
│ │ ├─ src/snapshot/ # freeze snapshots, diff, minimal-ops rollback
│ │ ├─ src/pins/ # pin store + auto-suggest scoring
│ │ ├─ src/health/ # tools-venv manager, deptry/vulture/ruff runners
│ │ ├─ src/errors/ # error catalog (codes + stderr classifiers)
│ │ └─ src/probe.py # embedded env-introspection helper (see §4)
│ └─ pipdock-cli/ # clap binary `pipdock`
├─ src-tauri/ # Tauri 2 app (commands + events only)
├─ ui/ # React 19 + TS + Tailwind 4 + Vite 8 + Zustand + i18next
├─ legal/ # EULA, Disclaimer, Privacy, Third-Party (public — legal gate links here)
├─ .github/ # caller workflows into poli0981/.github + issue templates
└─ docs/
Naming conventions: crates pipdock-*; React components prefixed Pd* (PdPackageRow, PdConflictDialog); Tauri identifier com.skullmute.pipdock; CLI binary pipdock.
3. The Engine trait
#[async_trait]
pub trait Engine: Send + Sync {
fn id(&self) -> EngineId; // Pip | Uv
async fn info(&self, env: &PyEnv) -> EngineInfo; // version, availability
async fn list_installed(&self, env: &PyEnv) -> Result<Vec<Dist>>;
async fn list_outdated(&self, env: &PyEnv) -> Result<Vec<OutdatedDist>>;
async fn resolve(&self, env: &PyEnv, req: &PlanRequest) -> Result<ResolutionReport>;
async fn install(&self, env: &PyEnv, specs: &[PinnedSpec], mode: ExecMode,
sink: EventSink) -> Result<StepResult>;
async fn uninstall(&self, env: &PyEnv, names: &[PkgName], sink: EventSink) -> Result<StepResult>;
async fn check(&self, env: &PyEnv) -> Result<CheckReport>; // pip check / uv pip check
async fn upgrade_pip(&self, env: &PyEnv) -> Result<StepResult>; // pip engine only; uv returns Unsupported
}
Key model types:
PlanRequest— the user's intent:{ upgrades: Vec<PkgName>, installs: Vec<Spec>, strategy: Compatible | ForceLatest(per-pkg overrides) }.ResolutionReport— normalized output of the dry-run:{ changes: Vec<Change>, held_back: Vec<HeldBack{ pkg, resolved, latest, blockers: Vec<Blocker{by, constraint}> }>, impossible: Option<ImpossibleDetail>, raw: String }. Both adapters must emit this same shape — this is the whole point of the trait. The pip adapter fills it from--dry-run --reportJSON; the uv adapter from its dry-run plan output (format pinned during spike SP-1; fixtures undercrates/pipdock-core/tests/fixtures/).Blockercomputation: the engine's report says what was held back; who is responsible comes from cross-referencing the reverse-dependency graph (§4) with each blocker'sRequires-Distconstraints. If attribution is ambiguous, show constraints without a culprit rather than guessing.
Requires-Python is enforced by PipDock, not the engine
Owner decision 2026-07-27 (spike SP-2). The two engines disagree: scipy==1.7.3 declares Requires-Python >=3.7,<3.11, and on Python 3.12 pip refuses it while uv plans to install it. Since G5 promises one behavior across heads, the preview must not change shape because the user flipped the engine radio — so pipdock-core evaluates Requires-Python itself in src/compat.rs, before any candidate reaches an engine command, and reports rejects as PD-PKG-001 with the required range against the environment's version.
This does not violate "explain, don't reimplement" (§1.2): resolution is still entirely the engine's. compat.rs only filters candidates the engine should never have been offered, using a narrow slice of PEP 440 — the comparison, wildcard and compatible-release operators as they appear in Requires-Python. Specifiers it cannot parse are treated as compatible, because PipDock failing to read metadata must never be the reason an installable package is refused.
Engine selection
Settings.engine ∈ {pip, uv}. First run: probe uv --version on PATH → preselect uv if present, else pip; user can change any time. The status bar always shows the active engine. Per-env override is P2.
4. Environment introspection: probe.py
Rust cannot cheaply read a foreign env's installed metadata. PipDock embeds a single-file, stdlib-only helper (probe.py, ~150 lines, no third-party imports) executed as <env-python> probe.py --json, printing one JSON document:
{ "python": "3.12.4", "prefix": "...", "externally_managed": false,
"is_venv": true, "hidden_user_site": null,
"dists": [ { "name": "requests", "version": "2.32.3",
"requires_dist": ["urllib3<3,>=1.21.1", "..."],
"requires_python": ">=3.8" } ] }
hidden_user_site is non-null only when -I is actually hiding packages from the listing — see SECURITY §2 for the decision and the UI note it drives.
From requires_dist the core builds the reverse-dependency graph used by: held-back attribution, uninstall guard, and pin auto-suggest. The helper is written to a temp file per invocation and never installed into the env. Compatibility floor: Python 3.10 (uses importlib.metadata only).
5. Index & metadata
- Name index: PyPI Simple Index in PEP 691 JSON form → SQLite (
index.db, tablenames(name, normalized)), refreshed manually or every 7 days. Fuzzy search runs in Rust (nucleo matcher) over the normalized column; target < 50 ms per keystroke. - Metadata on demand:
GET https://pypi.org/pypi/<name>/json→ summary, latest version, requires-python, license, project URLs. Cached inmeta_cachewith 24 h TTL. Strict HTTPS, no redirects offpypi.org. - Offline: search still works over the cached index; metadata panel shows a cached/offline badge.
6. Storage (%LOCALAPPDATA%\PipDock\)
config.json # settings: engine, locale, thresholds, consent {docsHash, timestamp}
index.db # SQLite: names, meta_cache, envs(recent), pins(env_hash, pkg, mode, reason)
snapshots/<envhash>/<iso-ts>.freeze.txt + .meta.json
tools/.venv/ # Code Health tools env (see CODE-HEALTH-SPEC)
logs/pipdock.<date>.log # tracing rolling files, 14-day retention
env_hash = SHA-256 of the canonicalized interpreter path. Snapshot .meta.json records trigger (which plan), engine, package count, and app version.
7. Tauri IPC surface
Commands (all async, all returning Result<T, PdError> where PdError carries a catalog code):
env_scan, env_add_manual, env_probe, pkg_list, pkg_outdated, index_search, pkg_metadata, plan_resolve, plan_execute, plan_cancel, uninstall_guard, uninstall_execute, pin_list|add|remove, snapshot_list|diff|rollback, health_run, health_fix, settings_get|set, logs_tail, pip_upgrade, legal_consent_get|set.
Events (Tauri event channel): plan-progress { step, pkg, phase, line } streams live subprocess output to the in-app console; scan-progress; health-progress. Long operations are cancellable: plan_cancel kills the current child process group and marks remaining steps Skipped(UserCancelled) — already-completed steps stay applied (snapshot covers full revert).
8. Execution model (two-phase)
Given a confirmed ResolutionReport (see DATA-FLOW §3 for the state machine):
- Phase A — batch fast path: one engine invocation installing the full pinned set. Fast (especially uv) and atomic-ish. If it exits 0 → done.
- Phase B — isolation pass: on Phase-A failure, re-run per package (
<engine> install pkg==ver) sequentially in resolver-report order, collecting individualStepResults. Failures are classified via the error catalog and do not stop the loop (owner requirement: skip and continue). - Post-run:
engine.check(); summary aggregates Phase A/B results + check findings.
Uninstalls are always sequential (cheap) with the reverse-dep guard evaluated once up front against the full removal set.
9. Frontend architecture
Zustand stores: useEnvStore, usePlanStore, useIndexStore, useSettingsStore, useHealthStore. All engine data enters via typed IPC wrappers (ui/src/ipc/*.ts) mirroring the Rust types (generated with specta/tauri-specta to prevent drift). No component calls invoke directly. i18next with en/vi JSON catalogs (see I18N.md). Styling via Tailwind 4 tokens defined in UI-SPEC.
10. Version manifest (verified 2026-07; re-verify at implementation)
| Component | Version policy |
|---|---|
| Tauri | 2.10.x (latest 2.x line) + tauri-plugin-updater |
| Rust | latest stable toolchain, pinned via rust-toolchain.toml |
| React / TypeScript | 19.x / latest stable |
| 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.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. |
| TypeScript | held at 6.0.x. 7.x is latest, but typescript-eslint peers on >=4.8.4 <6.1.0; taking 7 breaks npm run lint. Revisit when typescript-eslint supports TS 7. |
| ESLint | 10.x, with eslint-plugin-react deliberately absent. That plugin caps at ESLint 9, which drags in a minimatch/brace-expansion chain carrying six high-severity advisories and would fail npm audit in CI. The one rule it was wanted for — no hardcoded JSX strings (I18N §1) — is a local rule in eslint.config.js, which also implements the documented allowlist precisely. |
Dependabot will keep proposing the held versions. Each hold above is a compile or lint failure, not a preference, so those PRs are closed rather than merged until the stated condition changes. cargo audit informational advisories are handled separately in .cargo/audit.toml (SECURITY §7).
Dependabot + cargo audit + npm audit in CI keep this table honest (RELEASE-CI.md §2).