CODE-HEALTH-SPEC §3 said the environment is "passed to deptry so installed vs declared vs imported compares against reality". deptry 0.25.1 has no such option, ignores VIRTUAL_ENV, and reads whatever its own interpreter can import — so §2's isolation and §3's comparison are in conflict and isolation wins. §3 now says that, names the bounded cost, and says why DEP003 is kept rather than suppressed. §3 also gains what the tools actually emit, since §5's sketch predates anyone running them: deptry's flat list keyed by module and written to a file *path*, vulture having no machine-readable output and one message shape with no identifier, ruff's URL keyed by rule name, and all three exiting non-zero on findings with vulture using 3. ARCHITECTURE §7 and CLI-SPEC §6 both typed the report CheckReport, which engine.check() already owns and which is a published `pipdock schema` contract — two unrelated shapes sharing one name on the wire. It is HealthReport. CLI-SPEC §5's code 1 now covers "health found something", which is the behaviour a pre-commit hook needs and the one doctor already had. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
18 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 return Result<T, PdError> where PdError carries a catalog code, and are async except app_info, which is a compile-time constant. Each is a thin wrapper over a pipdock_core function — a wrapper that starts making decisions is logic the CLI will not inherit, and G5 promises the two heads never diverge.
This table is the surface. A command that is not listed here does not exist; adding one means amending this section in the same commit. It was written as a prose list of 26 with a|b|c groupings, which made the count ambiguous and let two Stage 1 additions land undocumented — hence the table.
| Command | Returns | Purpose |
|---|---|---|
app_info |
AppInfo |
PipDock's version, and the hash of the legal documents this build ships against. |
env_scan |
EnvRow[] |
Discover environments, streaming scan-progress. A probe failure is reported on its own row, never fatal to the scan. |
env_add_manual |
EnvRow |
Persist an interpreter chosen through Browse…. |
env_probe |
EnvRow |
Probe one interpreter without persisting it. |
pkg_list |
Dist[] |
Installed distributions, read from probe.py rather than the engine — see §4 and DATA-FLOW §7. |
pkg_outdated |
OutdatedDist[] |
Outdated distributions, via the configured engine. |
index_search |
Hit[] |
Fuzzy search over the in-memory name index. |
index_refresh |
RefreshReport |
Re-download the PEP 691 name index. |
pkg_metadata |
PackageMeta |
Cached PyPI metadata for the details panel, with its freshness. |
plan_resolve |
FlowStep |
Begin an update or install flow: dry-run resolve, then derive held-back items. |
plan_decide |
FlowStep |
Apply the user's 3-way conflict decisions and re-resolve. |
plan_execute |
ExecutionOutcome |
Take the snapshot, then run the two-phase execution (§8). Returns the summary and the snapshot meta: the CLI prints the id before execution and the summary sheet needs it afterwards to offer the rollback, so one envelope beats a second command to go and look it up. |
plan_cancel |
bool |
Stop the session, and say whether there was one. A parked flow counts and is discarded — it has no process to kill, and leaving it refuses the next plan on behalf of a preview nobody is looking at. |
uninstall_guard |
GuardReport |
Reverse-dependency check over a removal set, parking the flow that would run it. Called again with withDependents for DATA-FLOW §5's Remove dependents too, so a dependent of a dependent surfaces on the next pass. |
uninstall_execute |
ExecutionOutcome |
Snapshot, then remove. Takes force — §5's Force remove only X; without it a removal the guard objected to is refused with PD-RES-004 before the snapshot is written. |
pin_list |
Pin[] |
Pins for an environment. |
pin_add |
() |
Add or replace a pin. |
pin_remove |
bool |
Remove a pin; reports whether one existed. |
snapshot_list |
SnapshotMeta[] |
Snapshots for an environment, newest first. Takes the env_hash, not a PyEnv: snapshots outlive the interpreter that made them, and an environment whose Python is gone still has a history worth showing. |
snapshot_create |
SnapshotMeta |
Take a snapshot on demand, outside any plan. |
snapshot_diff |
Diff |
The environment against a snapshot. Claims no session — browsing a timeline must not start a flow. |
snapshot_rollback_preview |
RollbackPreview |
What restoring a snapshot would do, parking the flow that would do it. Split from the execute for the reason plan_resolve is: what the user confirms must be the plan they were shown. |
snapshot_rollback |
ExecutionOutcome |
Restore the parked snapshot — itself snapshotted first, per DATA-FLOW §8, which is why the outcome always carries one. |
health_run |
HealthReport |
Run the Code Health tools against a project folder. Not CheckReport — that name is taken by engine.check() and is already a published pipdock schema contract, so two unrelated shapes would have shared one name on the wire. |
health_fix |
ExecutionSummary |
Apply the gated ruff fix. |
engine_info |
EngineInfo[] |
Detected version and availability per engine. Settings shows both, so this returns both. |
pip_upgrade |
StepResult |
Upgrade pip itself in the selected environment. Not ExecutionSummary — there is no plan, no phase and no per-package counts, and inventing them would be four lies for one step. Carries no versions either (from/to are always absent): the caller re-probes, which it must do anyway to refresh the row. |
settings_get |
Settings |
Read stored settings. |
settings_set |
Settings |
Persist settings, returning what was actually stored rather than what was sent. |
legal_consent_get |
ConsentState |
Whether the legal gate can be skipped for this build's documents. |
legal_consent_set |
Consent |
Record acceptance. |
logs_tail |
string[] |
Tail of the in-memory log ring buffer, for the console drawer. |
report_bug_url |
string |
Prefilled GitHub issue URL (ERROR-CATALOG §4). Built in Rust so it cannot drift from pipdock self report-bug. Nothing is ever sent automatically. |
Events (Tauri event channel): plan-progress streams live subprocess output to the in-app console; scan-progress; health-progress.
plan-progress carries a tagged lifecycle, not a bare line — amended in S3, where the console drawer and the live region were first built:
kind |
Payload | Meaning |
|---|---|---|
stepStarted |
step, total, pkg?, phase |
Opens a section in the console drawer |
line |
step, pkg?, phase, stream, line |
One line of engine output, verbatim and never localized |
stepFinished |
step, total, pkg?, phase, status |
Closes the section; advances the "13 of 15 complete" live region |
It was originally specified as { step, pkg, phase, line }, which made both of those features unimplementable: there was no event meaning "a step began" to group a section under, and none meaning "one finished" to count. Neither is recoverable from the text — engine output does not reliably name the package it concerns, and counting lines is not counting steps. Every step now emits exactly one stepStarted, any number of lines, and exactly one stepFinished, whichever way it ended. stream distinguishes stdout from stderr, which matters for uv in particular: uv writes its plan to stderr (SP-1), so stderr does not mean failure.
One mutation session at a time, across all of them. Update, install, uninstall and rollback share a single slot, so a second one is refused with PD-RES-003 rather than allowed to interleave engine commands against the same environment. The commands that resume a session (plan_decide, plan_execute, uninstall_execute, snapshot_rollback) name the flow they expect and get PD-INT-001 if a different one is parked — a frontend sequencing bug, reported as one instead of running the wrong plan.
Long operations are cancellable: plan_cancel trips the plan's token, which kills the child and its whole process tree (a Windows Job Object — python -m pip spawns build backends), and remaining steps are reported Skipped with ExecutionSummary.cancelled set. Already-completed steps stay applied; the 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). No tauri-plugin-updater — PipDock does not update itself (SECURITY §5) |
| 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).