Files
pipdock/docs/PRD.md
T
poli0981andClaude Opus 5.5 cfa5b4e1be docs: Add interpreter… in the specs, ACCESSIBILITY.md and the privacy policy
PRD P0-1, UI-SPEC §4, CLI-SPEC (env add/remove, their JSON, --env's new
refusal), CLI-GUIDE, ERROR-CATALOG (PD-ENV-001's new cases, and the
first button its advice ever had) and TESTING's golden count. SECURITY
§2 claimed for two milestones that interpreter paths were canonicalized
before use while the only check was existence; it now describes the
validator that makes it true. PRD also records P0-9's first-run uv
detection, P1-7 and P2 as not planned in maintenance mode.

legal/PRIVACY-POLICY.md 1.3 names the interpreter paths a person adds,
kept until removed, in both languages. With the repository URL it
already changed, the first-run gate shows once in 1.6.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 23:22:12 +07:00

13 KiB

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.
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.<date>.log for the GUI, pipdock-cli.<date>.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.