# PipDock — Product Requirements Document *Version 0.1 · 2026-07-17 · Owner: Kokone (poli0981)* ## 1. Problem statement Managing an existing Python environment with pip is a blind, one-package-at-a-time chore: 1. `pip list --outdated` tells you *what* is outdated but not *what will happen* if you upgrade it. 2. pip's resolver silently holds packages back or fails with a wall of red text (`ResolutionImpossible`) that most users cannot act on. 3. `pip uninstall` will happily remove a package that ten other packages depend on, without warning. 4. A failed package in a manual bulk update leaves the environment in an unknown intermediate state with no record of what it looked like before. 5. GUI alternatives are either abandoned, IDE-locked (PyCharm's package tool), or thin wrappers that hide the resolver instead of explaining it. PipDock's thesis: **don't reimplement the resolver — explain it.** Wrap pip/uv's own dry-run resolution in a UI that previews changes, names the package responsible for every conflict, and makes every destructive operation reversible. ## 2. Goals - G1 — Every mutating operation (install / update / uninstall) is **previewed** via engine dry-run before execution. - G2 — Conflicts are **explained in one sentence** ("`requests 2.32` is held back because `apiclient 1.4` requires `requests<2.31`") and resolved with a 3-way choice. - G3 — Every batch operation is **reversible** via automatic snapshots. - G4 — Core happy paths complete in **≤ 5 clicks** (see UI-SPEC click budgets). - G5 — GUI and CLI share **one Rust core**; behavior never diverges. - G6 — PipDock **never modifies its own runtime** (standalone binary; the managed environments are external). - G7 — Zero telemetry; **PyPI is the only host PipDock connects to.** It does not update itself, so it never calls home; GitHub, the ruff docs, OSV's advisory pages and the author's contact page are only ever handed to the browser as a link the user clicked (SECURITY §4/§5). ## 3. Personas | Persona | Situation | What PipDock gives them | |---|---|---| | **The hobby dev** | One global venv per project, updates rarely, terrified of breaking things | Preview + rollback = confidence to update at all | | **The data tinkerer** | 200-package Anaconda-refugee env, numpy/pandas/scipy pin tangle | Held-back explanations; "compatible" strategy resolves the tangle without force | | **The automation writer** (Kokone's own use case) | Many small venvs for bots/scrapers, wants scripted upkeep | `pipdock update --all --json` in scheduled tasks; per-env pins | | **The cleanup-minded maintainer** | Inherited project with mystery dependencies | Code Health: deptry finds unused deps, vulture finds dead code | ## 4. Feature matrix ### P0 — v1.0 (ship blockers) | # | Feature | Notes | |---|---|---| | P0-1 | Environment discovery & switcher | PEP 514 registry + `py -0p` + `uv python list` + known venv dirs + manual browse. Recents persisted. **Manual browse shipped in 1.6.0**, the last command `NOT_YET` held: *Add interpreter…* on Environments (and `pipdock env add`) puts any `python.exe` on a list stored in `index.db` and shown after discovery's own, and *Remove from list* (`env remove`) takes it off. Before it the GUI saw a venv only as a `.venv`, `venv`, `env` or `.env` in its working directory — the install folder, for an installed app — so almost no project venv was reachable from the GUI. **Recents:** the CLI's `env use` default is stored and, since 1.4.0, honoured; the GUI's selection lasts for the session. | | P0-2 | PEP 668 guard | Detect `EXTERNALLY-MANAGED`; block by default with explanation; explicit opt-in override only. **The override works since 1.4.0.** It saved and nothing read it, so turning it on changed nothing — and the guard decided on whatever the caller last cached, while the rollback flow had no guard at all. Every mutating flow now decides on a fresh probe; turning the override on asks first, and a chip is shown wherever it applies (SECURITY §3). | | P0-3 | Installed list | Per-env; up-to-date rows dimmed; outdated rows badged and mirrored into Updates tab. | | P0-4 | Updates flow | Group dry-run resolve → preview diff → 3-way conflict choices → two-phase execution → `pip check` post-verify → summary report. **Three parts of this worked only from 1.4.0:** *Force latest* was recorded and never read, so a forced resolve was the held-back one again — it now forces, and the preview names what it breaks before anything runs (DISCLAIMER §2); a post-run check that could not run reported `ok`, and now says it could not; and PipDock enforces `Requires-Python` itself (hard invariant 10), where PD-PKG-001 had never been raised. | | P0-5 | Search & install | Local PEP 691 name-index cache + fuzzy search; per-package metadata on demand (PyPI JSON API); install queue ("dock bay"). | | P0-6 | Bulk uninstall + reverse-dep guard | Warn "removing X breaks Y, Z" before execution; `--force` override. | | P0-7 | Pins | Per-env pin list; pinned packages excluded from *Select all*; lock icon in lists. | | P0-8 | Snapshots & rollback | Auto snapshot (freeze + metadata) before every batch; diff view; minimal-ops rollback. | | P0-9 | Engine setting (pip / uv) | Auto-detect uv on first run; switch any time in Settings; engine badge in status bar. **Auto-detect is not implemented, and is owed** (audit backlog X19): a fresh install drives pip (`Settings::default`). `settings.rs` places the detection in Settings, as a choice made where it can be seen, rather than in a read of an empty store — and the CLI follows the stored setting rather than probing `PATH` — but nothing in Settings makes it yet. What exists since 1.4.0 is the half it needs: Settings shows each engine's version for the selected environment beside its radio, *not found* when it is not installed. | **Not planned (maintenance mode, 1.6.0)**: the owner decided on 2026-11-21 that the half which exists — Settings shows each engine and its version, and switching is one click — is enough, and a first-run prompt is a new surface rather than a fix. | P0-10 | pip upkeep | Show pip version per env; one-click `python -m pip install --upgrade pip`. | | P0-11 | Code Health tab | deptry + vulture + ruff from PipDock's isolated tools env; report + safe `ruff --fix`. (Promoted to v1 by owner decision 2026-07.) | | P0-12 | CLI core parity | env / list / search / install / update / uninstall / pin / snapshot / doctor / health. JSON output. | | P0-13 | Legal gate | First-run modal: EULA, License, Disclaimer, Privacy, Third-Party → GitHub links; consent stored with docs-version hash. | | P0-14 | i18n EN + VI | GUI fully localized; CLI English-only in v1. | | P0-15 | Summary reports | "13 successful, 2 failed" + per-package error-catalog reason; copy log; Report-bug deep link. Since 1.4.0 each row says what it moved from, and the bug report carries the environment's Python version and the engine's. | | P0-16 | Structured logging | Rolling local log files (tracing); in-app live console during execution. **Met in 1.4.0.** The live console shipped earlier; the log files did not exist until then — `tracing` was a dependency of three crates and called zero times. Now one file per UTC day under `%LOCALAPPDATA%\PipDock\data\logs\` (`pipdock..log` for the GUI, `pipdock-cli..log` for the CLI, so the two never interleave), swept after 14 days: every spawn's argv, exit code and duration, each resolve, snapshot and run outcome, a panic's report, and at DEBUG the engine's own lines. The CLI's `--verbose` and `--log-file` work; Settings shows the folder and copies the recent log; a GUI that cannot open its data folder says so in a dialog naming the log. Nothing in it is sent anywhere. | ### P1 — v1.x | # | Feature | Notes | |---|---|---| | P1-1 | **Shipped 1.2.0.** Security tab | pip-audit (freeze-file mode) listing known advisories per installed package. **Not severity-sorted, because pip-audit has no severity field** — under either vulnerability service its findings carry only `id`, `fix_versions`, `aliases` and `description`, verified against the pinned 2.10.1. Ordered by package, then by whether anything *fixes* it, then by id: the one distinction that changes what the user can do. The CVE is an **alias**; the primary id is a `PYSEC-*`. | | P1-2 | Pin auto-suggest | **Shipped post-1.0 (P1-A).** Reverse-dependency count ≥ threshold (default 5, configurable in Settings; zero is off) ⇒ suggest pin with reason. Counts in-force edges only — extras and other-Python markers do not qualify a package, and since 1.4.0, when platform markers began to be read, neither do requirements gated to another platform. | | P1-3 | **Shipped 1.1.0.** Export / import | `requirements.txt` and `constraints.txt` export; import-as-queue. | | P1-4 | **Partly shipped, 1.1.0.** Cache manager | Shows and clears **PipDock's own** disk usage: snapshots, the Code Health tools venv and, since 1.2.0, the Security tab's audit venv. Logs (1.4.0) are not a target — the sweep keeps 14 days and nothing more, and Settings' Logs row says where they are. `index.db` is reported but not clearable — it holds settings, pins and the consent record in the same file, so "clear the cache" must never take them. **The engine caches (`pip cache`, `uv cache`) are not covered** and are a separate item: they belong to the engine, live outside `%LOCALAPPDATA%\PipDock\`, and purging them is a subprocess rather than a file delete. | | P1-5 | **Shipped 1.1.0.** Command palette | Ctrl+K fuzzy action launcher (terminal-tech signature feature). | | P1-6 | **Shipped 1.3.0.** Dependency view | "Who holds this back" for a selected package: the focused package between its dependents and its dependencies, each edge carrying the specifier written on it, each neighbour clickable to re-centre, plus the two transitive counts and any requirement nothing installed satisfies. **Not a node-link diagram, and that is a measurement rather than a shortcut** — on a 352-package environment a depth-1 neighbourhood is a median of 7 nodes but depth 2 is a median of 172 and exceeds 60 for 212 of 352 packages, and there are over 2000 distinct paths from `setuptools` to a root. So it is drawn at depth 1, depth is navigated by re-centring, and the transitive answer is a count. Added no runtime dependency. | | P1-7 | **Not planned (maintenance mode, 1.6.0).** Scheduled check | Optional background outdated-check with toast (no auto-apply, ever). Every prerequisite is absent — no toast, no notification, autostart or tray plugin, nothing on a timer, no surface for a background failure (ROADMAP) — and the persona it serves already has the CLI in Task Scheduler, a recipe CLI-SPEC ships. Building it would be one plugin and a permanent background process for one line of text. | ### P2 — later **Not planned while PipDock is in maintenance mode (from 1.6.0).** Kept as the record of what was considered; CONTRIBUTING.md says what is taken instead. | # | Feature | Notes | |---|---|---| | P2-1 | macOS / Linux builds | Tauri makes this near-free; test matrix is the real cost. | | P2-2 | Per-env engine override | e.g. uv globally, pip for one legacy env. | | P2-3 | Elevation broker | Manage admin-owned Pythons (Program Files) via the CommandForge two-process pattern. v1 detects read-only site-packages and blocks with guidance instead. | | P2-4 | Conda detection | Read-only awareness + "open in conda" hand-off. Never mutate conda envs with pip. | | P2-5 | Portable mode | Config beside the exe for USB use. | | P2-6 | JP locale | Extend i18n to EN/VI/JP baseline. | ## 5. Non-goals (v1) - **Not a project manager.** PipDock manages *environments*, not `pyproject.toml` workflows. It does not create lockfiles, does not replace `uv sync` / poetry, and never edits the user's project files (Code Health reports; only `ruff --fix` writes, and only on explicit click). - **No conda support.** Mixing pip into conda envs corrupts them; v1 refuses with an explanation. - **No auto-updates of user packages.** PipDock never applies changes without an explicit confirm. Scheduled *checks* only (P1-7). - **No package publishing / building.** Out of scope entirely. - **No elevation in v1** (see P2-3). ## 6. Success metrics | Metric | Target | |---|---| | Clicks for "update everything" happy path | ≤ 4 | | Cold outdated-scan, 200-pkg env, uv engine | < 3 s | | Fuzzy search keystroke → results | < 50 ms (local index) | | Batch of 15 with 2 failures | 13 applied, 2 reported with catalog codes, env passes `pip check` | | Rollback of any snapshot | Env diff vs snapshot = ∅ (excluding unavailable-on-PyPI edge case, which must be reported) | | Crash-free sessions | > 99.5 % | ## 7. Open questions (tracked for spike week) 1. Exact shape of `uv pip install --dry-run` output for adapter parsing (no stable JSON report — see ROADMAP SP-1). 2. pip-audit invocation mode for auditing a *foreign* env (freeze-file vs `--python`) — SP-4. 3. Whether PEP 691 full-name-index download size/refresh cadence needs delta handling — SP-3.