Files
pipdock/docs/PRD.md
T
poli0981andClaude Opus 5 02cc17d95d docs: the dependency view recorded, and 1.3.0
UI-SPEC §4 gains the screen and **loses the sentence it contradicted**.
It said the third row action folds all three into a `⋮` menu "with the
budget intact"; that makes uninstall four clicks where §5's table
records three, hand-counted. The correction is written as a correction
rather than an overwrite, because the reason it slipped through is the
useful part: four is under the ceiling of five, and a ceiling is not a
ratchet — a table of measured counts is. §5 gains the row, §6 the
component, ARCHITECTURE §4 the forward direction and the whole-graph
value.

**The dangling cross-reference is repaired by writing what it promised.**
`ROADMAP.md` has pointed at "the analysis above" for what blocks P1-6
and P1-7 since 1.2.0, and no such analysis was anywhere in the document
— the survey lived only outside the repository, and the sentence had
been copied into CLAUDE.md as well. P1-6's half is its slice record.
P1-7's is now written too, and counted against the tree rather than
recalled: no toast component, no notification/autostart/tray dependency,
one plan-scoped `tokio::spawn` and zero intervals in either head, and no
surface that can report a failure at 03:00 while `logs_tail` is still
`NOT_YET`. Drafting this commit I nearly shipped a CLAUDE.md line
claiming that survey existed before I had written it, which is the same
defect one layer up.

Version in five places, moved together: the workspace inherits it, so
`Cargo.toml`, `package.json` and `tauri.conf.json` are the only hand
edits and the two lockfiles are regenerated. Hand-editing `Cargo.lock`
would have been wrong twice over — `scopeguard` and `simd_cesu8` are
also at 1.2.0 and `fs_extra` was already at 1.3.0. `cargo metadata
--locked` passes, which is the one-command check.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-21 08:35:15 +07:00

9.1 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 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.
P0-2 PEP 668 guard Detect EXTERNALLY-MANAGED; block by default with explanation; explicit opt-in override only.
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.
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.
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.
P0-16 Structured logging Rolling local log files (tracing); in-app live console during execution.

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.
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 and the Code Health tools venv. 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 Scheduled check Optional background outdated-check with toast (no auto-apply, ever).

P2 — later

# 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.