docs: add design documentation baseline

Commits the full v0.1 design suite written during the design phase:
PRD, architecture, data flow, UI/CLI specs, code-health spec, error
catalog, security, testing, release/CI and i18n docs, plus the roadmap.

The legal documents (EULA, disclaimer, privacy policy, third-party
notices) must be committed publicly because the in-app legal gate links
to their GitHub URLs at first run.

Also adds .gitignore, which the repo was missing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-07-27 17:08:14 +07:00
1 parent c395f976e5
commit 5e8d78bb27
19 files changed
+1268

No files matched your search

+64
View File
@@ -0,0 +1,64 @@
name: Bug report
description: Report a problem with PipDock (the in-app "Report bug" button prefills this form)
title: "[Bug]: "
labels: ["bug", "triage"]
body:
- type: markdown
attributes:
value: |
Thanks for the report! If you came here from the in-app **Report bug** button, most fields
are prefilled and the full log was copied to your clipboard — paste it below if asked.
Vui lòng viết bằng English hoặc Tiếng Việt đều được.
- type: input
id: pd-version
attributes:
label: PipDock version
placeholder: "1.0.0"
validations:
required: true
- type: input
id: os
attributes:
label: Windows version
placeholder: "Windows 11 24H2 (26100.x)"
validations:
required: true
- type: dropdown
id: engine
attributes:
label: Engine
options: [pip, uv, "not sure"]
validations:
required: true
- type: input
id: python
attributes:
label: Environment Python / engine versions
placeholder: "Python 3.12.4 · pip 26.1.2 (or uv 0.9.x)"
- type: input
id: error-code
attributes:
label: Error code (if shown)
placeholder: "PD-BLD-002"
- type: textarea
id: what-happened
attributes:
label: What happened / steps to reproduce
placeholder: "1. Selected env … 2. Update all … 3. …"
validations:
required: true
- type: textarea
id: log-excerpt
attributes:
label: Log excerpt
description: Prefilled by the app (last ~6 KB). Paste the full clipboard log if it was truncated.
render: text
- type: checkboxes
id: checks
attributes:
label: Checks
options:
- label: I searched existing issues for this problem
required: true
- label: The log excerpt contains no private information I don't want public
required: true
+43
View File
@@ -0,0 +1,43 @@
# Rust
/target/
/src-tauri/target/
**/*.rs.bk
# Node
node_modules/
dist/
dist-ssr/
.vite/
*.tsbuildinfo
# Tauri build output
/src-tauri/gen/
# Environments (test venvs created by the integration suite / spikes)
.venv/
venv/
__pycache__/
*.py[cod]
# Editors / IDEs
.idea/
.vs/
.vscode/*
!.vscode/extensions.json
*.swp
# OS
Thumbs.db
Desktop.ini
.DS_Store
# Secrets & local config
.env
.env.*
!.env.example
*.key
tauri-signing-private.key*
# Logs & scratch
*.log
/spikes/out/
+85
View File
@@ -0,0 +1,85 @@
# PipDock
**A friendly dock for your Python environments.** Inspect, install, update, and clean up Python packages in bulk — through a keyboard-first GUI or a scriptable CLI — without ever hand-typing another `pip install` incantation or guessing why an upgrade broke your project.
> Repo: `poli0981/pipdock` · License: **GPL-3.0** · Platform: **Windows 10/11 (v1)** · Status: **design phase**
---
## Why PipDock
`pip` is powerful but unforgiving: it does not preview what an upgrade will change, `pip uninstall` removes packages that other packages still need without a word of warning, and a failed bulk update leaves you guessing what state your environment is in. PipDock wraps the official resolvers (pip or uv — your choice) with:
- **Preview before touch** — every install/update runs a dry-run resolve first and shows you exactly what will change.
- **Three-way conflict handling** — when the latest version of a package would break another, choose *compatible version* (safe default), *skip*, or *force latest* with a clear "this will break X" warning.
- **Snapshots & rollback** — a `pip freeze` snapshot is taken before every batch operation; one click restores it.
- **Reverse-dependency guard** — uninstalling a package that others depend on triggers a warning listing exactly what would break.
- **Skip-and-continue execution** — one failed package never aborts the batch; you get a final report: *"13 successful, 2 failed"* with per-package reasons.
- **Never touches itself** — PipDock is a standalone binary that lives outside every environment it manages, so it can never break itself mid-update.
## Features (v1)
| Area | What you get |
|---|---|
| Environments | Auto-discovery of venvs / uv venvs / system Pythons (PEP 514 + `py` launcher), manual add, PEP 668 guard |
| Installed | Full package list per env; up-to-date packages dimmed, outdated badged |
| Updates | Bulk update with group dry-run resolve, held-back explanations, 3-way conflict choices |
| Search & Install | Instant fuzzy search over a locally cached PyPI name index (PEP 691), metadata on demand, install queue |
| Uninstall | Bulk uninstall with reverse-dependency warnings |
| Pins | Exclude packages from bulk updates; auto-suggest pinning heavily-depended-on packages |
| Snapshots | Automatic pre-batch snapshots, diff view, one-click rollback |
| Engine | pip **or** uv, selectable in Settings (uv auto-detected on first run) |
| Code Health | deptry + vulture + ruff against a project folder — unused deps, dead code, style — run from PipDock's own isolated tools env |
| pip upkeep | Check & update pip itself per environment |
| CLI | `pipdock` — full parity for core operations, JSON output, CI-friendly exit codes |
| i18n | English + Tiếng Việt |
| Privacy | No telemetry. Network traffic goes only to PyPI (package data) and GitHub (app updates) |
## Install
Download the installer (NSIS `.exe` or `.msi`) from [GitHub Releases](https://github.com/poli0981/pipdock/releases). Auto-updates are delivered via signed Tauri updater artifacts from the same Releases page.
> Windows SmartScreen may warn on first run because binaries are not EV-code-signed. Verify the SHA-256 checksum published with each release.
## Quick start
**GUI:** launch PipDock → accept the first-run legal gate → pick an environment (auto-discovered or *Browse…*) → the *Updates* tab shows what's outdated → *Select all* → *Update* → review the preview → *Confirm*. Four clicks.
**CLI:**
```text
pipdock env list
pipdock update --all --env C:\proj\.venv --strategy compatible --yes
pipdock doctor
pipdock snapshot rollback latest
```
## Documentation
| Doc | Purpose |
|---|---|
| [docs/PRD.md](docs/PRD.md) | Product goals, personas, feature matrix P0–P2, non-goals |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Crate layout, Engine trait, IPC surface, storage |
| [docs/DATA-FLOW.md](docs/DATA-FLOW.md) | State machines for update / install / uninstall, engine command mapping |
| [docs/UI-SPEC.md](docs/UI-SPEC.md) | Terminal-tech design system, screens, click budgets |
| [docs/CLI-SPEC.md](docs/CLI-SPEC.md) | Commands, flags, exit codes, JSON contracts |
| [docs/CODE-HEALTH-SPEC.md](docs/CODE-HEALTH-SPEC.md) | deptry / vulture / ruff integration |
| [docs/ERROR-CATALOG.md](docs/ERROR-CATALOG.md) | Error codes, stderr detection patterns, user guidance |
| [docs/SECURITY.md](docs/SECURITY.md) | Threat model, PEP 668 policy, supply-chain hygiene |
| [docs/TESTING.md](docs/TESTING.md) | Test strategy incl. disposable-venv integration tests |
| [docs/RELEASE-CI.md](docs/RELEASE-CI.md) | CI callers into `poli0981/.github`, release & updater pipeline |
| [docs/I18N.md](docs/I18N.md) | EN/VI localization rules |
| [docs/ROADMAP.md](docs/ROADMAP.md) | Spike week, milestones, exit criteria |
| [legal/](legal/) | EULA, Disclaimer, Privacy Policy, Third-Party Notices (linked by the in-app legal gate) |
## License
GPL-3.0. See [LICENSE](LICENSE) (add the standard GPL-3.0 text at repo creation). The legal documents in [legal/](legal/) must be committed publicly so the in-app legal gate can link to them on GitHub.
PipDock is an independent project. It is not affiliated with or endorsed by the Python Software Foundation (Python, pip, PyPI) or Astral (uv, ruff).
---
## Tiếng Việt (tóm tắt)
PipDock là ứng dụng Windows (GUI + CLI) giúp kiểm tra, cài đặt, cập nhật và gỡ **hàng loạt** gói thư viện Python một cách an toàn: luôn chạy dry-run xem trước thay đổi, xử lý xung đột phiên bản với 3 lựa chọn rõ ràng, tự chụp snapshot trước mỗi lần chạy để rollback một chạm, cảnh báo khi gỡ gói mà gói khác đang phụ thuộc, và tổng kết "13 thành công, 2 thất bại" kèm lý do từng gói. Hỗ trợ engine pip hoặc uv (chọn trong Settings), tìm gói tức thì nhờ cache chỉ mục PyPI, kèm module Code Health (deptry/vulture/ruff) để dọn dependency thừa và dead code. Không thu thập dữ liệu. Giấy phép GPL-3.0.
+133
View File
@@ -0,0 +1,133 @@
# PipDock — Architecture
*Version 0.1 · 2026-07-17*
## 1. Design principles
1. **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.
2. **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.
3. **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).
4. **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.
5. **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
```text
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
```rust
#[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 --report` JSON; the uv adapter from its dry-run plan output (format pinned during spike SP-1; fixtures under `crates/pipdock-core/tests/fixtures/`).
- `Blocker` computation: the engine's report says *what* was held back; *who* is responsible comes from cross-referencing the reverse-dependency graph (§4) with each blocker's `Requires-Dist` constraints. If attribution is ambiguous, show constraints without a culprit rather than guessing.
### 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:
```json
{ "python": "3.12.4", "prefix": "...", "externally_managed": false,
"dists": [ { "name": "requests", "version": "2.32.3",
"requires_dist": ["urllib3<3,>=1.21.1", "..."],
"requires_python": ">=3.8" } ] }
```
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`, table `names(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 in `meta_cache` with 24 h TTL. Strict HTTPS, no redirects off `pypi.org`.
- Offline: search still works over the cached index; metadata panel shows a cached/offline badge.
## 6. Storage (`%LOCALAPPDATA%\PipDock\`)
```text
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):
1. **Phase A — batch fast path:** one engine invocation installing the full pinned set. Fast (especially uv) and atomic-ish. If it exits 0 → done.
2. **Phase B — isolation pass:** on Phase-A failure, re-run per package (`<engine> install pkg==ver`) sequentially in resolver-report order, collecting individual `StepResult`s. Failures are classified via the error catalog and **do not stop the loop** (owner requirement: skip and continue).
3. 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.9.x line at writing); minimum pinned after SP-1 |
| Managed Pythons | 3.10 – 3.14 (3.9 is EOL) |
| Windows | 10 (1809+) / 11; WebView2 Evergreen assumed present; `longPathAware` manifest enabled |
Renovate + `cargo audit` + `npm audit` in CI keep this table honest (RELEASE-CI.md).
+87
View File
@@ -0,0 +1,87 @@
# PipDock — CLI Specification
*Version 0.1 · 2026-07-17 · Binary: `pipdock` (clap, from `pipdock-cli` crate, same `pipdock-core` as the GUI)*
## 1. Principles
1. **Same core, same behavior.** Every CLI command maps 1:1 onto the core functions the GUI uses; the CLI adds no logic of its own.
2. **Safe by default, scriptable on request.** Interactive prompts appear on a TTY; in scripts (`--yes` / no TTY), conflicts default to **skip**, never force.
3. **Machine-readable everywhere.** `--json` on every read/report command emits the same structs the GUI receives.
4. English-only in v1 (GUI carries EN/VI); messages reuse catalog codes so they stay greppable.
## 2. Global options
```text
--env <path> interpreter or env dir (default: last used / auto-detected .venv in CWD)
--engine <pip|uv> override configured engine for this invocation
--json machine-readable output (NDJSON for streaming commands)
--yes / -y assume defaults on all prompts (conflicts → skip)
--quiet / --verbose log level; --log-file <path> to tee
--no-snapshot DANGEROUS: skip pre-batch snapshot (CI images only; prints warning)
```
## 3. Commands
```text
pipdock env list # discovered envs, sources, PEP 668 flags
pipdock env use <path> # set default env
pipdock list [--outdated] # installed table; dims/badges become columns in --json
pipdock search <query> [--limit n] # local fuzzy index search
pipdock info <pkg> # cached PyPI metadata
pipdock install <spec...> [--dry-run] # spec = name[==version]; dry-run prints the ResolutionReport
pipdock update [--all | <pkg...>]
[--strategy compatible|latest] # latest == force; requires --yes off-TTY acknowledgement
[--except <pkg,...>] # ad-hoc exclusions on top of pins
[--dry-run]
pipdock uninstall <pkg...> [--force] # guard prints breakage list; --force overrides
pipdock pin add|remove <pkg> [--reason "…"] | pin list
pipdock snapshot list | create | diff <id> | rollback <id|latest>
pipdock doctor # engine check + env sanity + (P1) audit summary
pipdock health [--path <dir>] [--tool deptry|vulture|ruff] [--fix] # --fix = ruff only, prompts
pipdock pip-upgrade # upgrade pip inside --env (pip engine paths only)
pipdock engine [pip|uv] # show or set configured engine
pipdock index refresh # re-pull PEP 691 name index
pipdock self report-bug # prints prefilled GitHub issue URL (ERROR-CATALOG §4)
```
## 4. Interactive conflict handling (TTY)
`update`/`install` render the preview, then per needs-decision package:
```text
requests held back at 2.30.0 (latest 2.32.3) — blocked by apiclient 1.4 (requires <2.31)
[C]ompatible (default) [S]kip [F]orce latest [A]bort plan
```
`--yes` answers `C` for held-back and `S` for impossible. `--strategy latest` pre-answers `F` and prints the breakage warning before a mandatory 3-second countdown (skippable with a second `-y`).
## 5. Exit codes
| Code | Meaning |
|---|---|
| 0 | success, all steps ok |
| 1 | completed with per-package failures (see JSON `counts.failed`) |
| 2 | plan aborted (resolution impossible & user/skip policy removed everything) |
| 3 | environment error (PD-ENV-*, incl. PEP 668 block) |
| 4 | engine unavailable / version too old (PD-ENG-*) |
| 5 | snapshot failure — nothing was executed (PD-SNP-001) |
| 6 | network/index error (PD-NET-*) |
| 10 | internal error (PD-INT-*; log path printed) |
| 130 | user cancelled (Ctrl-C; child processes reaped, partial summary printed) |
## 6. JSON contracts
`--json` payloads are the serde-serialized core types (`Dist`, `OutdatedDist`, `ResolutionReport`, `ExecutionSummary`, `CheckReport`) — schema documented by `pipdock schema <type>` which prints the JSON Schema generated from the Rust types, so scripts can pin against it. Streaming commands (`update`, `install`, `health`) with `--json` emit NDJSON events matching the GUI's `plan-progress` payloads, terminated by a final `summary` object.
## 7. Examples
```bash
# Nightly maintenance of a bot venv (task scheduler), safe strategy, log kept:
pipdock update --all --env C:\bots\scraper\.venv --yes --json --log-file C:\logs\pd.json
# Audit what an upgrade would do without touching anything:
pipdock update pandas numpy --dry-run --json | jq '.held_back'
# Refuse-to-break uninstall in CI (exit 1 if guard trips):
pipdock uninstall legacylib --json || echo "dependents exist, aborting"
```
+66
View File
@@ -0,0 +1,66 @@
# PipDock — Code Health Specification
*Version 0.1 · 2026-07-17 · In v1 by owner decision. The Python analogue of npm's knip, scoped tightly.*
## 1. Concept & boundaries
Code Health answers three questions about a **project folder** (not an environment):
| Question | Tool | Output |
|---|---|---|
| Which declared dependencies are unused, missing, or transitive-only? | **deptry** | dependency issues table |
| Which code is dead (unused functions/classes/vars)? | **vulture** | dead-code findings with confidence % |
| Does the code violate common standards, and what can be auto-fixed? | **ruff** (`check`, opt-in `--fix`, opt-in `format --check`) | lint findings; safe-fix count |
Hard boundaries: **report-only** for deptry and vulture (no auto-removal of code or dependencies — too dangerous to automate); the only write path is `ruff --fix`/`ruff format`, gated behind an explicit confirm; PipDock never edits `pyproject.toml`/`requirements.txt` for the user — deptry findings link to the *Uninstall* flow instead, where the reverse-dep guard applies.
## 2. Isolation: the tools venv
The three tools are **never installed into the user's environment**. PipDock maintains its own hidden env:
```text
%LOCALAPPDATA%\PipDock\tools\
├─ .venv/ # created with the newest discovered Python (≥3.10)
├─ tools-requirements.txt # exact pins, shipped with the app, updated per release via Renovate
└─ manifest.json # installed pin set + hash; mismatch with shipped pins ⇒ re-sync
```
Bootstrap: on first Health run (or pin-set change), create/sync the venv from `tools-requirements.txt` using the configured engine, with progress in the console drawer. Pin policy: exact `==` pins resolved at PipDock release time (Renovate PRs bump them); no floating versions at runtime. Offline: if bootstrap can't reach PyPI, Health reports PD-NET-011 and stays disabled; other tabs unaffected.
## 3. Inputs
- **Project folder** (persisted per environment in `index.db`): must contain Python sources; detection order for declared deps: `pyproject.toml` → `requirements*.txt` → none (deptry limited-mode notice).
- **Associated environment**: the currently selected env; passed to deptry so "installed vs declared vs imported" compares against reality.
## 4. Invocations (from the tools venv's interpreter; argv arrays, CWD = project folder)
```text
deptry . --json-output <tmp>\deptry.json
vulture . --min-confidence <settings, default 80> # parse text output (stable format)
ruff check . --output-format json
ruff check . --fix # only from the Fix button / `pipdock health --fix` after confirm
ruff format --check . # optional toggle, default off
```
Exclusions honored: `.venv`, `venv`, `node_modules`, `build`, `dist`, `.git`, plus user globs in Settings. Each tool has a watchdog timeout (default 120 s) → PD-HLT-003 partial report.
## 5. Results model & UI
```json
{ "project":"C:\\proj\\bot", "env":"…", "ranAt":"…", "toolVersions":{"deptry":"x","vulture":"y","ruff":"z"},
"deptry":[{"code":"DEP002","dep":"httpx","kind":"unused","locations":[]}],
"vulture":[{"path":"bot/util.py","line":88,"name":"old_parse","confidence":90}],
"ruff":{"findings":[…],"fixable":17} }
```
UI (Health tab): run header (folder picker · env chip · Run) → three result tabs with counts; deptry unused-dep rows offer **"Review in Uninstall…"** (jumps to the guarded flow); ruff tab shows `Fix 17 safely fixable issues` → confirm dialog states file count and recommends a clean git tree (PipDock checks `git status --porcelain` if a repo is detected and warns on dirty). Export: `Save report` writes Markdown + JSON to a user-chosen path. CLI mirror: `pipdock health [--tool …] [--fix] [--json]`.
## 6. Interpretation guidance (shown as inline help)
- deptry `DEP001` (missing) often means a dep used but undeclared — the fix is declaring it, which PipDock does **not** automate; copy suggests the exact line to add.
- vulture confidence < 100 can be a false positive (dynamic dispatch, exported API); copy says "review before deleting" and links vulture's whitelist mechanism.
- ruff findings link to the rule's docs anchor (`https://docs.astral.sh/ruff/rules/<code>`).
## 7. Non-goals
No mypy/pytest orchestration, no complexity metrics, no CI annotations in v1 (the JSON export enables users to wire their own). No support for notebooks in v1 (`*.ipynb` excluded; noted in the report footer).
+123
View File
@@ -0,0 +1,123 @@
# PipDock — Data Flow
*Version 0.1 · 2026-07-17. This document is the corrected, authoritative version of the original concept flows.*
## 1. Correction log vs. original concept
| Original concept | Corrected design | Why |
|---|---|---|
| "Check Conflict → If True → update" | **No conflict → update.** Conflict → explain → 3-way choice | Original condition was inverted; binary Yes/No hid the safe middle option |
| Per-package conflict check | **Group dry-run resolve** of the whole selection | Resolving A+B+D together often succeeds where one-by-one is stuck; matches how pip's resolver actually works |
| "Show the full list of all Python packages" | **Search-first** over a locally cached PyPI name index | PyPI hosts ~600 k projects; a browsable list is unusable and unfetchable |
| (absent) | **Environment selection + PEP 668 guard** as step zero | Without it, users mutate system Python by accident — the worst possible outcome |
| (absent) | **Snapshot before every batch** | Makes every flow reversible; prerequisite for user trust |
## 2. Shared preamble (all mutating flows)
```text
[Select env] → probe.py → env facts (python ver, PEP 668, dist metadata)
│
├─ EXTERNALLY-MANAGED detected → BLOCKED banner (PD-ENV-002)
│ └─ explicit override in Settings → proceed with persistent warning chip
└─ ok → flow continues; reverse-dep graph built from probe data
```
## 3. Update flow (state machine)
```text
Idle
└─ env selected → Scanning engine.list_outdated()
└─ SelectionReady rows: name, current → latest, pinned rows locked out of Select-all
└─ user selects + [Update] → Resolving
│ engine.resolve(PlanRequest{upgrades, strategy: Compatible})
├─ error → Failed(code) catalog-classified; retry available
└─ PreviewReady ResolutionReport rendered as a diff:
│ · clean upgrades (A 1.2 → 2.0)
│ · new transitive installs
│ · held-back items (B → 0.1.9, latest 0.5.0, blocked by A: "requests<0.2")
│ · impossible items
├─ conflicts exist → ConflictDecision (per held-back/impossible pkg):
│ [Keep compatible] default; accept resolver's version (held-back only)
│ [Skip] drop pkg from this plan
│ [Force latest] adds per-pkg override; warning names what breaks
│ any Force/Skip chosen → re-Resolve with overrides → PreviewReady (loop, max 3 rounds
│ then require manual pruning — prevents decision ping-pong)
└─ [Confirm] → Snapshotting freeze + meta written; failure here ABORTS the plan (PD-SNP-001)
└─ Executing
Phase A: single batch install of pinned set ── ok ──→ PostCheck
Phase B (on A-failure): per-pkg sequential, skip-and-continue,
live stderr → console via plan-progress events
└─ PostCheck engine.check(); findings appended to summary
└─ Summary see §6
```
Cancellation: allowed in Resolving/Executing; kills child process group; completed steps remain; summary marks the rest `Skipped(UserCancelled)`; snapshot offers full revert.
## 4. Install flow
```text
SearchIdle → (keystrokes) → QueryingIndex (local fuzzy, <50 ms) → Results
└─ row focus → MetadataFetch (PyPI JSON, cached 24 h) → detail panel
└─ [Add] → Queue ("dock bay", persists across searches; versions default latest, editable to spec)
Queue → [Install n packages] → Resolving (PlanRequest{installs}) → PreviewReady → … same tail as §3
```
Installed-tab presentation (per original concept, kept): up-to-date rows **dimmed**, outdated rows carry an `UPDATE` badge and are mirrored into the Updates tab; already-installed packages appearing in search results show an `INSTALLED ✓` chip (or `UPDATE` if outdated) instead of [Add].
## 5. Uninstall flow
```text
Selection → [Uninstall] → GuardCheck: reverse-dep graph over full removal set
├─ breaks nothing → Confirm dialog (lists removals)
└─ breaks {Y,Z} → Warning dialog: "Removing X breaks Y (requires X>=1), Z"
options: [Cancel] [Remove dependents too] (adds Y,Z to set, re-guard) [Force remove only X]
→ Snapshot → sequential engine.uninstall per pkg (skip-and-continue) → Summary
```
Rationale: bare `pip uninstall` performs **no** dependency check — this guard is a core value-add.
## 6. Summary model (owner requirement)
```json
{ "planId":"…","phase":"B","results":[
{"pkg":"httpx","from":"0.27.0","to":"0.28.1","status":"ok"},
{"pkg":"oldlib","to":"2.0.0","status":"failed","code":"PD-BLD-002",
"reason":"build backend error in pyproject.toml","stderrTail":"…"}],
"check":{"ok":true,"findings":[]},
"counts":{"ok":13,"failed":2,"skipped":1} }
```
Rendered as: **"13 successful, 2 failed, 1 skipped"** with an expandable row per failure (catalog code, human reason EN/VI, stderr tail, *Copy log*, *Report bug* deep link — see ERROR-CATALOG §4).
## 7. Engine command mapping
| Operation | pip (`<py> -m pip …`) | uv (`uv pip … --python <py>`) | Adapter notes |
|---|---|---|---|
| List installed | `list --format=json` | `list --format=json` | shapes differ slightly; normalize to `Dist` |
| List outdated | `list --outdated --format=json` | `list --outdated --format=json` | uv output pinned in SP-1 fixtures |
| Dry-run resolve | `install -U --dry-run --quiet --report -` (JSON to stdout) | `uv pip install -U --dry-run` (**text plan; no stable JSON report**) | uv adapter parses text; exact format frozen via SP-1 fixtures + snapshot tests |
| Install pinned | `install pkg==v [--no-deps in Phase A per-report set]` | `uv pip install pkg==v` | Phase A passes the full pinned set in one call |
| Uninstall | `uninstall -y pkg` | `uv pip uninstall pkg` | |
| Env check | `check` | `uv pip check` | normalize findings |
| Freeze (snapshots) | `freeze --all` | `uv pip freeze` | pip's `--all` includes pip/setuptools; record engine in snapshot meta |
| Upgrade pip | `install -U pip` | *(n/a — surface "pip upkeep" only when pip engine active or pip present in env)* | |
Version floors: pip ≥ 22.2 for `--dry-run --report` (offer in-app pip upgrade when older); uv minimum pinned after SP-1.
## 8. Rollback flow
```text
Snapshot selected → Diff = (current freeze) vs (snapshot freeze)
→ plan: uninstall {added}, install {removed ∪ changed @ snapshot versions}
→ dry-run resolve the restore set (a yanked/deleted release cannot be restored → PD-SNP-002,
listed explicitly; user may proceed partially)
→ snapshot current state first (rollback is itself reversible) → execute two-phase → summary
```
## 9. Data-flow invariants (enforced in `pipdock-core`, tested)
1. No mutating engine call without a `ResolutionReport` accepted in this session.
2. No mutating engine call without a successful snapshot write.
3. `plan_execute` refuses a report older than 10 minutes or if the env's probe hash changed (env drifted → re-resolve).
4. Every failure surfaced to UI/CLI carries a catalog code.
5. Pinned packages never appear in a `PlanRequest.upgrades` unless the user explicitly unpinned them this session.
+54
View File
@@ -0,0 +1,54 @@
# PipDock — Error Catalog
*Version 0.1 · 2026-07-17. Single source of truth: `crates/pipdock-core/src/errors/catalog.rs`. Every user-visible failure carries exactly one code; classifiers run over engine stderr in priority order (first match wins), falling back to `PD-ENG-999`.*
## 1. Code space
`PD-<AREA>-<NNN>` — areas: `ENV` environment, `ENG` engine, `RES` resolution, `BLD` build, `PKG` package/index, `NET` network, `PRM` permissions, `SNP` snapshot, `SYS` system, `HLT` health, `INT` internal.
## 2. Catalog (v1 launch set)
| Code | Detection (stderr/context pattern) | Cause | User action (EN; VI mirrored in locale files) |
|---|---|---|---|
| PD-ENV-001 | interpreter path missing/not executable | env deleted or moved | Re-scan environments; remove stale entry |
| PD-ENV-002 | `externally-managed-environment` / `EXTERNALLY-MANAGED` marker | PEP 668 protected Python | Use a virtual env; system override only via Settings (discouraged) |
| PD-ENV-003 | probe.py non-zero / unparseable | broken env metadata | Open logs; recreate the venv |
| PD-ENG-001 | engine binary not found | pip/uv missing | Install engine or switch engine in Settings |
| PD-ENG-002 | pip < 22.2 with plan requested | no `--dry-run --report` | One-click "Upgrade pip" then retry |
| PD-ENG-003 | uv output shape unrecognized | uv newer than adapter | Update PipDock; temporarily switch engine to pip |
| PD-RES-001 | `ResolutionImpossible` / uv equivalent | constraints cannot be satisfied | Per-package Skip/Force choices in the preview |
| PD-RES-002 | plan stale (>10 min) or env drift hash mismatch | env changed since preview | Re-run preview |
| PD-BLD-001 | `Microsoft Visual C++ 14.0 or greater is required` | missing MSVC build tools | Install VS Build Tools, or prefer a wheel-providing version |
| PD-BLD-002 | `error in pyproject.toml` / `Backend … failed` / `metadata-generation-failed` | broken sdist build backend | Try previous version; report upstream (owner's example case) |
| PD-BLD-003 | `error: Microsoft Visual C++`-absent + `Failed building wheel` generic | sdist-only build failed | Same as above; details in log |
| PD-PKG-001 | `No matching distribution found` + requires-python mismatch in metadata | package needs different Python | Shows required range vs env version |
| PD-PKG-002 | `No matching distribution found` (plain) | name/version typo or yanked | Check spelling/version; `pipdock info <pkg>` |
| PD-PKG-003 | `File was already yanked` / yanked marker | yanked release requested | Pick a non-yanked version |
| PD-PKG-004 | hash mismatch / `THESE PACKAGES DO NOT MATCH THE HASHES` | corrupted download | Purge engine cache (P1 UI; CLI: engine cache purge) and retry |
| PD-NET-001 | timeout / `Connection aborted` / DNS failure | offline or PyPI unreachable | Offline banner; retry; search stays local |
| PD-NET-002 | TLS/SSL verification failure | proxy/AV interception | Corporate proxy note; never suggests disabling verification |
| PD-NET-010 | index refresh failed | PEP 691 fetch error | Retry later; stale index still searchable (staleness shown) |
| PD-NET-011 | tools venv bootstrap fetch failed | offline during Health setup | Health disabled until online |
| PD-PRM-001 | `PermissionError` writing site-packages | admin-owned Python (Program Files) | v1 blocks: use a venv (elevation is P2-3) |
| PD-PRM-002 | file lock (`WinError 32`) | package in use by a running process | Close Python processes using the env; retry |
| PD-SNP-001 | snapshot write failed pre-execution | disk/permission issue on app data | **Plan aborted, nothing executed**; free space / check AV |
| PD-SNP-002 | rollback target release unavailable on PyPI | deleted/yanked upstream | Partial rollback offered; affected pins listed |
| PD-SYS-001 | `path too long` patterns | MAX_PATH without long-path opt-in | Enable Windows long paths (help link) |
| PD-SYS-002 | disk full (`No space left`/`WinError 112`) | storage | Free space |
| PD-HLT-001..003 | tool missing / non-zero / watchdog timeout | tools venv issue | Re-sync tools env; partial report shown |
| PD-INT-001 | panic/unexpected | PipDock bug | Report-bug deep link prefilled |
| PD-ENG-999 | unclassified engine failure | unknown | stderr tail shown; report-bug encouraged (feeds catalog growth) |
Classifier hygiene: patterns live beside unit tests with captured real stderr fixtures (collected in spike SP-2 and grown from bug reports); a fixture must exist for every code before it ships.
## 3. Presentation rules
GUI: `code · localized one-liner · [Details ⌄ stderr tail ≤ 40 lines] · [Copy full log] · [Report bug]`. CLI: `error[PD-XXX-NNN]: <one-liner>` on stderr; `--json` embeds `{code, reason, stderrTail}`. Localization: only the one-liner and action text are localized; codes and stderr never are.
## 4. Bug-report pipeline (owner requirement: console error attached to template)
1. App keeps a per-plan ring buffer (last 64 KB) of engine stdout/stderr plus the app log tail.
2. **Report bug** builds a prefilled GitHub new-issue URL against `.github/ISSUE_TEMPLATE/bug_report.yml`:
`https://github.com/poli0981/pipdock/issues/new?template=bug_report.yml&pd-version=…&os=…&engine=…&python=…&error-code=…&log-excerpt=…`
3. URL budget: GitHub rejects very long URLs, so `log-excerpt` is truncated to ≈ 6 000 characters (tail-biased); the full log is simultaneously copied to the clipboard and the dialog says so ("paste into the issue if asked").
4. Nothing is ever sent automatically — the user reviews the issue form in their browser. This is the entire "telemetry" story.
+41
View File
@@ -0,0 +1,41 @@
# PipDock — Internationalization (EN + VI)
*Version 0.1 · 2026-07-17 · Scope decision: EN + VI in v1; JP is P2-6.*
## 1. Mechanics
- **GUI:** i18next + react-i18next; catalogs at `ui/src/locales/{en,vi}/{common,envs,packages,plan,health,legal,errors}.json`. `en` is the source of truth; a CI script fails the build if `vi` is missing keys (untranslated keys fall back to EN at runtime with a console warning, never raw key names in the UI).
- **Core:** Rust emits **codes and structured data only** (catalog codes, counts, package names); all human phrasing happens in the frontend catalogs. This keeps CLI (English-only v1) and GUI consistent without duplicating strings in Rust.
- **No hardcoded strings rule:** enforced by an eslint rule on JSX literals (allowlist: `PipDock`, package names, versions, codes).
- Interpolation via ICU-style placeholders: `"updateSummary": "{{ok}} successful, {{failed}} failed"` / `"{{ok}} thành công, {{failed}} thất bại"`. Plurals: use i18next plural forms; note Vietnamese has a single plural form — never build strings by concatenating `s`.
## 2. Locale behavior
Default locale = OS UI language if `vi`, else `en`; switchable in Settings, applied live. Dates via `Intl.DateTimeFormat` with the active locale; file sizes binary (MiB) with locale decimal separators. Package names, versions, engine output, and error codes are **never** translated or reshaped.
## 3. Glossary (consistency contract)
| EN | VI | Note |
|---|---|---|
| environment | môi trường | |
| package | gói | not "thư viện" in UI copy (broader than libraries) |
| update / upgrade | cập nhật | one term for both in UI |
| held back | bị giữ lại | conflict preview |
| pin / pinned | ghim / đã ghim | |
| snapshot / rollback | ảnh chụp / khôi phục | "khôi phục" for the action |
| uninstall | gỡ cài đặt | |
| dependency | phụ thuộc | |
| force latest | ép bản mới nhất | keep the "ép" bluntness — it should sound risky |
| dry run / preview | xem trước | user-facing term is always "xem trước" |
| queue ("dock bay") | hàng chờ | dock-bay flavor stays EN-only in code names |
## 4. Copy rules
- Vietnamese copy uses "bạn", concise and direct; avoid literal translations of English idioms.
- Warning copy must not soften risk in translation — "this will break X" ⇒ "thao tác này sẽ làm hỏng X".
- Legal gate summaries are localized, but the linked legal documents themselves are EN (governing) with a VI courtesy note at top of each (see legal/ files).
- Error one-liners ≤ 90 chars in both languages (fit the inline row).
## 5. QA
Pseudo-locale build target (`en-XA`-style bracketed expansion) to catch clipping; VI sweep of all mutation dialogs is part of the manual release charter (TESTING §4); screenshots in both locales attached to release PRs for the three core screens.
+105
View File
@@ -0,0 +1,105 @@
# 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; network traffic limited to PyPI + GitHub Releases.
## 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 | Security tab | pip-audit (freeze-file mode) listing known CVEs per installed package, severity-sorted. |
| P1-2 | Pin auto-suggest | Reverse-dependency count ≥ threshold (default 5, configurable) ⇒ suggest pin with reason. |
| P1-3 | Export / import | `requirements.txt` and `constraints.txt` export; import-as-queue. |
| P1-4 | Cache manager | Show / purge engine cache (`pip cache`, `uv cache`) and PipDock's index cache. |
| P1-5 | Command palette | Ctrl+K fuzzy action launcher (terminal-tech signature feature). |
| P1-6 | Dependency graph view | Visual "who holds this back" graph for a selected package. |
| 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.
+53
View File
@@ -0,0 +1,53 @@
# PipDock — Release & CI
*Version 0.1 · 2026-07-17 · CI is built as thin callers into the `poli0981/.github` ops repo's reusable workflows (align exact workflow filenames with the ops repo's current Rust/Node/Tauri suite at repo creation).*
## 1. Caller workflows (`.github/workflows/`)
| Caller | Reusable target (ops repo) | Triggers | Jobs |
|---|---|---|---|
| `ci-rust.yml` | reusable Rust workflow | PR, push main | fmt, clippy `-D warnings`, `cargo test --locked`, `cargo audit` |
| `ci-node.yml` | reusable Node workflow | PR, push main | Node 24, `npm ci`, eslint, Vitest, `npm audit --audit-level=high`, `vite build` |
| `ci-integration.yml` | (project-local) | PR touching `engine|plan|snapshot|graph`, nightly | Windows runner, disposable-venv suite (TESTING L2), weekly latest-engine parser job |
| `codeql.yml` | reusable CodeQL workflow | PR, schedule | JS/TS + Rust where supported |
| `release.yml` | reusable Tauri/build + project steps | tag `v*` | build, sign, bundle, publish (see §3) |
| `notify.yml` | reusable notify workflow → `notify.py` | release published | cross-post Telegram/Discord/Bluesky/Mastodon/X/Facebook |
**Permissions matrix (explicit in every caller — the Phase-5 lesson: callers without a `permissions:` block default everything to `none`):**
```yaml
# codeql.yml
permissions: { actions: read, contents: read, security-events: write }
# notify.yml
permissions: { contents: read, actions: read }
# release.yml
permissions: { contents: write } # release assets
# ci-*.yml
permissions: { contents: read }
```
## 2. Branch & version policy
`main` protected (PR + green CI required). SemVer; tags `vX.Y.Z`. Conventional commits feed the changelog generator. Renovate config extends the ops-repo preset: weekly grouped PRs for crates/npm, **separate immediate PRs** for security advisories and for `tools-requirements.txt` (Code Health pins), and a watch on `pip`/`uv` releases to trigger the parser-fixture job.
## 3. Release pipeline (tag `v*`)
1. Windows runner: `npm ci && vite build` → `cargo tauri build --locked` producing NSIS `.exe` + `.msi`.
2. Sign updater artifacts with `TAURI_SIGNING_PRIVATE_KEY` (repo secret; public key baked into `tauri.conf.json`); generate `latest.json` for `tauri-plugin-updater` pointing at the GitHub Release assets.
3. Compute and publish `SHA256SUMS.txt`.
4. Draft GitHub Release with generated changelog; manual publish (owner review) → `notify.yml` fires.
5. Post-release checklist issue auto-opened: verify updater from previous version, verify SmartScreen behavior, spot-check EN/VI in the shipped build.
Secrets bootstrap: extend the ops repo's `setup-secrets.sh` with `TAURI_SIGNING_PRIVATE_KEY` / `TAURI_SIGNING_PRIVATE_KEY_PASSWORD` entries for this repo.
## 4. Artifact & support policy
Two active lines at most: latest release gets features; previous minor gets security-only patches for 90 days. Updater always targets latest. MSI provided for org deployment; winget manifest submission is P2 (tracked in ROADMAP).
## 5. Repo scaffolding checklist (day one)
- [ ] GPL-3.0 `LICENSE` at root; `legal/` committed **publicly** (the in-app legal gate links to these GitHub URLs — CommandForge lesson: don't leave them gitignored).
- [ ] `.github/ISSUE_TEMPLATE/bug_report.yml` (shipped in this suite) + `config.yml` disabling blank issues.
- [ ] Branch protection, Renovate, CodeQL, secrets via `setup-secrets.sh`.
- [ ] `rust-toolchain.toml`, `.nvmrc` (24), `Cargo.lock`/`package-lock.json` committed.
- [ ] README badges: CI, CodeQL, release, license.
+45
View File
@@ -0,0 +1,45 @@
# PipDock — Roadmap
*Version 0.1 · 2026-07-17*
## Phase 0 — Spike week (before any feature code)
The entire architecture stands on assumptions that must be verified on a real machine first (the FrameLedger/QuoteAtlas discipline). Each spike is a small script + captured fixtures committed to `crates/pipdock-core/tests/fixtures/`.
| # | Spike | Question to answer | Exit criterion |
|---|---|---|---|
| SP-1 | **uv dry-run shape** | Exact stdout of `uv pip install -U --dry-run` (current + previous uv) across: clean upgrade, held-back, impossible. Is held-back attribution derivable, or does uv only show the resolved set? | Fixture set committed; adapter parsing strategy written; uv minimum version pinned. **Go/no-go for launching with both engines** — if uv's plan output is too lossy, v1.0 ships pip-primary with uv behind a "beta engine" flag. |
| SP-2 | **pip report & stderr corpus** | Capture `--dry-run --report` JSON + real stderr for every ERROR-CATALOG build/network/permission case (broken sdist, MSVC-missing, PEP 668, locked file, yanked, hash mismatch). | ≥ 1 fixture per launch catalog code. |
| SP-3 | **PEP 691 index economics** | Full name-index size, download time on VN broadband, SQLite ingest time, fuzzy-search latency on ~600 k names. | < 60 s cold refresh, < 50 ms search on the i7-14700KF and on a low-end reference VM; else design delta/compression fallback. |
| SP-4 | **pip-audit foreign-env mode** | Correct invocation for auditing an env the tool isn't installed in (freeze-file `--no-deps` vs newer options). | Command line + JSON fixture pinned (P1 feature, but flags decided now). |
| SP-5 | **Held-back attribution accuracy** | On a real numpy/scipy/pandas pin tangle: does graph-based blocker attribution match reality? | Preview sentences verified by hand against the tangle; ambiguity fallback path exercised. |
| SP-6 | **Windows env discovery sweep** | PEP 514 registry + `py -0p` + Microsoft Store Python + uv-managed on a real machine; Store-Python aliasing quirks. | Discovery module design note updated; Store Python either supported or explicitly detected-and-explained. |
## Phase 1 — M1 "Core + CLI" (~3–4 weeks)
Engine trait + both adapters (per SP-1 outcome), probe.py, discovery, index cache + search, plan/resolve/execute two-phase, snapshots, pins, guard graph, error catalog, CLI over all of it. **Exit:** TESTING L1+L2+L4 green in CI; `pipdock update --all` survives the SP-5 tangle env with correct summary; dogfood on Kokone's own bot venvs begins.
## Phase 2 — M2 "GUI shell + core flows" (~3–4 weeks)
Tauri app, design tokens, Environments/Installed/Updates/Search/Pins screens, preview + 3-way conflict UX, console drawer, summary sheet, snapshots UI, legal gate, EN/VI catalogs, settings. **Exit:** all UI-SPEC click budgets met by manual count; L3 green; VI sweep clean.
## Phase 3 — M3 "Health + polish" (~2 weeks)
Tools venv, deptry/vulture/ruff runners + report UI + gated fix, pip upkeep, bug-report deep link, offline states, keyboard map, icon/branding pass. **Exit:** CODE-HEALTH flows pass on two real projects (one pyproject, one requirements-only).
## Phase 4 — RC → v1.0 (~1–2 weeks)
Release pipeline live (signing, updater, checksums), manual charter executed, docs/README screenshots, legal files public, updater tested from RC→GA. **Exit:** RELEASE-CI §5 checklist fully checked; v1.0.0 published + notify fan-out.
## Post-1.0 (P1 wave)
Security tab (pip-audit), pin auto-suggest, requirements/constraints export-import, cache manager, command palette, dependency graph view, scheduled check. Then P2 candidates by demand: macOS/Linux, per-env engine, elevation broker, winget, JP locale.
## Standing risks
| Risk | Mitigation |
|---|---|
| uv output churn between releases | weekly latest-engine parser CI job (TESTING L1) + PD-ENG-003 graceful degrade + "switch to pip" escape hatch |
| pip UX flags deprecations (e.g. report format changes) | same job covers pip; adapter version-gates per engine version |
| Index size growth | SP-3 fallback design kept in the drawer |
| Scope creep from Health into a linter IDE | CODE-HEALTH §7 non-goals are contractual |
+52
View File
@@ -0,0 +1,52 @@
# PipDock — Security
*Version 0.1 · 2026-07-17*
## 1. Threat model (scoped)
PipDock's job is to run package managers against local environments. The realistic risks are: (a) PipDock being tricked into running something other than the intended engine command, (b) users being nudged into damaging their system Python, (c) compromised update delivery of PipDock itself, and (d) PipDock's own dependency supply chain. Malicious *packages* the user chooses to install are out of scope — pip/uv execute setup code by design; PipDock's mitigations are the preview step, snapshots, and the (P1) audit tab, not sandboxing.
## 2. Command execution hygiene
- All engine/tool invocations use argv arrays via `tokio::process::Command`; **no shell is ever involved**, so quoting/injection classes are structurally absent.
- Package names are validated against the PEP 508 name grammar (`^[A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?$` after normalization) and version specs against PEP 440 before entering argv; anything else is rejected client-side with PD-PKG-002.
- Interpreter paths come only from discovery (registry/launcher/uv) or an explicit user file-pick; they are canonicalized and existence-checked (PD-ENV-001) before use.
- `probe.py` is stdlib-only, written to a temp file with a random name, executed with `-I` (isolated mode: ignores `PYTHONPATH`, user site) so a poisoned env cannot inject code into the probe.
- Child processes run with inherited user privileges only; PipDock never elevates in v1 (PD-PRM-001 blocks instead — elevation broker is P2 with its own review).
## 3. PEP 668 policy (protecting the system Python)
Environments carrying an `EXTERNALLY-MANAGED` marker are **blocked by default** with an explanation and a "create a venv instead" pointer. The override lives in Settings, off by default, with explicit warning copy; when enabled, every mutating screen for that env shows a persistent warning chip, and the flag corresponding to `--break-system-packages` is passed only then. PipDock never adds that flag silently — this is a hard rule.
## 4. Network surface
| Destination | Purpose | Notes |
|---|---|---|
| `pypi.org` | PEP 691 name index, per-package JSON metadata | HTTPS with certificate verification; redirects restricted to `pypi.org`/`files.pythonhosted.org` |
| `github.com` (Releases) | PipDock's own updates | via `tauri-plugin-updater`, see §5 |
| — everything else | none | engines make their own PyPI connections per their configs (user `pip.ini`/`uv.toml` respected, incl. private indexes — PipDock does not rewrite index URLs) |
No telemetry, no crash reporting endpoints, no analytics. TLS failures surface as PD-NET-002 and the app **never** offers to disable verification.
## 5. Update integrity (PipDock itself)
`tauri-plugin-updater` with the Tauri signing key: release artifacts + `latest.json` are signed at build; the app verifies signatures before applying. The private key lives only in GitHub Actions secrets (`TAURI_SIGNING_PRIVATE_KEY`); SHA-256 checksums are published per release for manual verification (SmartScreen note in README). Installer artifacts: NSIS + MSI from the Tauri bundler.
## 6. Auditing user environments (P1 Security tab)
pip-audit runs **from the tools venv** in freeze-file mode: snapshot-freeze the target env → `pip-audit -r <freeze> --no-deps --format json` → findings joined to installed rows (CVE/GHSA id, severity, fixed-in). Exact flags validated in spike SP-4 (pip-audit's foreign-env options evolve). Findings link to the OSV entry; "update to fixed version" hands off to the normal Update flow — audit never auto-applies anything.
## 7. Supply chain of PipDock itself
- CI: `cargo audit` (RustSec) + `npm audit --audit-level=high` gate every PR; Renovate keeps Rust/npm/tools-requirements pins current (see RELEASE-CI.md).
- `Cargo.lock` and `package-lock.json` committed; builds are `--locked`.
- CodeQL enabled via the ops-repo caller with the established permissions block.
- Third-party licenses tracked in `legal/THIRD-PARTY-NOTICES.md`; `cargo about`/`license-checker` regenerate the inventory at release.
## 8. Data & privacy engineering
All state is local under `%LOCALAPPDATA%\PipDock\`. Logs may contain package names and paths — the bug-report flow shows the user exactly what will be prefilled and requires manual submission (ERROR-CATALOG §4). No identifiers are generated or stored beyond the random consent record. Deleting the app data folder is a complete reset (documented in Settings → Legal & About).
## 9. Vulnerability reporting
`SECURITY.md` at repo root (this file doubles as it) will carry a private reporting channel via GitHub Security Advisories on `poli0981/pipdock`; target acknowledgment ≤ 7 days. Coordinated disclosure preferred; in-range CVEs in shipped dependencies trigger a patch release via the standard pipeline.
+56
View File
@@ -0,0 +1,56 @@
# PipDock — Testing Strategy
*Version 0.1 · 2026-07-17*
## 1. What must never regress
1. Adapter parsing of pip/uv output (the product stands on it).
2. The data-flow invariants (DATA-FLOW §9): no mutation without accepted plan + snapshot.
3. Conflict presentation: held-back attribution sentences must match fixture ground truth.
4. Skip-and-continue semantics and summary counts.
5. Reverse-dependency guard correctness.
## 2. Layers
### L1 — Core unit tests (Rust, `cargo test`)
- **Parser fixtures:** captured real outputs under `tests/fixtures/{pip,uv}/{list,outdated,report,errors}/…` (seeded by spikes SP-1/SP-2, grown from every new engine release and every triaged bug). `insta` snapshot tests assert the normalized `ResolutionReport`. A CI job runs the capture script against the *latest* engine versions weekly and fails on unrecognized shapes → PD-ENG-003 before users hit it.
- **Error classifiers:** every catalog code has ≥ 1 stderr fixture; a test enforces "no code without fixture."
- **Graph:** reverse-dep construction and blocker attribution over synthetic metadata sets, including cycles and extras (`pkg[extra]`) markers.
- **Snapshot diff/rollback planner:** property-style tests — `apply(plan(diff(a,b)), b) == a` over generated freeze pairs.
- **Name/spec validation:** PEP 508/440 accept/reject tables.
### L2 — Engine integration (disposable venvs, Windows CI runner)
Each test creates a throwaway venv (`python -m venv` and `uv venv`), then exercises real engines:
| Scenario | Assertion |
|---|---|
| Fresh venv + install 3 small pure wheels | summary 3/0; `check` clean |
| Seed known conflict (install `A==old` requiring `B<x`, then plan `B` latest) | plan shows held-back with correct blocker; Compatible path succeeds; Force path warns and `check` reports breakage |
| Batch with 1 deliberately broken sdist | Phase B isolates it; counts n-1 ok / 1 failed with PD-BLD-*; env passes `check` |
| Uninstall a depended-on package | guard lists dependents; `--force` proceeds |
| Snapshot → mutate → rollback | env freeze equals snapshot |
| PEP 668 marker file planted | PD-ENV-002 block; override path passes flag |
Fixture packages are tiny pinned PyPI wheels (documented list in `tests/integration/pins.toml`) so CI is deterministic; network-touching tests are tagged and can run against a local `pypiserver` mirror when offline determinism is needed.
### L3 — Frontend (Vitest + Testing Library)
Component tests for `PdConflictRow` (3-way state), `PdPreviewDiff` grouping, `PdSummarySheet` counts, dimming/badging rules on `PdPackageTable`, and the design-token contrast test (all text/surface pairs ≥ WCAG AA computed at build). IPC mocked at the typed wrapper layer with recorded core payloads — the same JSON as L1 fixtures, guaranteeing UI and core agree on shapes (types generated via tauri-specta make drift a compile error).
### L4 — CLI (assert_cmd + insta)
Golden-output tests per command against a mocked core; TTY vs non-TTY prompt behavior; exit-code table verified exhaustively; `--json` payloads validated against `pipdock schema` output.
### L5 — E2E smoke (tauri-driver, P1 gate for release)
One scripted run on a Windows runner: launch → legal gate → select seeded venv → update-all happy path → summary visible → rollback. Kept minimal; breadth lives in L2.
## 3. Coverage & gates
Core target ≥ 85 % line coverage (`cargo llvm-cov`), classifiers and plan module ≥ 95 %. PRs blocked on: fmt, clippy `-D warnings`, L1, L3, L4; L2 runs on PRs touching `engine|plan|snapshot|graph` paths and nightly otherwise. The weekly latest-engine parser job files an issue automatically on failure (feeds PD-ENG-003 early warning).
## 4. Manual test charter (per release)
A short exploratory pass on a real machine: dirty 150+ package env, corporate-proxy simulation (PD-NET-002 copy), non-ASCII Windows username paths, VI locale sweep of all mutation dialogs, cancel mid-Phase-B, and SmartScreen/first-run installer experience.
+96
View File
@@ -0,0 +1,96 @@
# PipDock — UI Specification
*Version 0.1 · 2026-07-17 · Direction: **dark terminal-tech** (owner decision 2026-07)*
## 1. Design intent
PipDock should feel like a **precision instrument docked over a terminal** — the calm confidence of a good TUI with the affordances of a native app. Not a neon cyberpunk cliché, not a generic admin dashboard: restrained phosphor-green on near-black, monospace where data lives, one accent doing real work. Signature moves: a terminal-style **status line** pinned to the bottom, a live **execution console** that streams real engine output, and (P1) a Ctrl+K command palette.
Anti-goals: gradients-everywhere SaaS look, rounded-blob cards, decorative glow. Any glow is functional (focus rings, live-activity pulse) and subtle.
## 2. Design tokens (Tailwind 4 `@theme`)
| Token | Value | Use |
|---|---|---|
| `--color-bg` | `#0A0E0C` | app background |
| `--color-surface` | `#101612` | panels, rows |
| `--color-surface-2` | `#161E18` | hover, elevated |
| `--color-border` | `#1F2B23` | hairlines |
| `--color-accent` | `#4ADE80` | primary actions, focus, live pulse |
| `--color-accent-dim` | `#22935B` | secondary accents, links |
| `--color-text` | `#E7F0EA` | primary text |
| `--color-text-dim` | `#8AA394` | secondary text, **dimmed up-to-date rows** |
| `--color-warn` | `#F5B94A` | held-back, warnings |
| `--color-danger` | `#F0574F` | impossible, failures, force actions |
| `--color-info` | `#5BC0DE` | pinned, informational chips |
Type: **Inter** (UI), **JetBrains Mono** (package names, versions, console, status line — both OFL-licensed, bundled). Base 14 px, mono data 13 px. Radius 6 px; borders 1 px; shadows minimal. Motion: 120–160 ms ease-out; live-activity pulse on the status-line engine badge during execution; `prefers-reduced-motion` respected.
## 3. Layout
```text
┌──────────────────────────────────────────────────────────────┐
│ ⌂ PipDock [env: .venv (Py 3.12) ▾] [engine: uv] │ top bar
├───────────┬──────────────────────────────────────────────────┤
│ Environments │ │
│ Installed │ │
│ Updates (7) │ content area │
│ Search │ │
│ Pins │ │
│ Health │ │
│ Security (P1) │ │
│ Settings │ │
├───────────┴──────────────────────────────────────────────────┤
│ ▸ .venv · Py 3.12.4 · uv 0.9.x · idle log ⌄ ⚠ 0 │ status line
└──────────────────────────────────────────────────────────────┘
```
Sidebar is icon+label, collapsible to icons. Status line (mono) always shows env · python · engine · state, plus a log-drawer toggle. The **console drawer** slides up over the status line during execution, streaming `plan-progress` lines with per-package section markers; collapsible, never modal.
## 4. Screens
**Environments.** Auto-discovered list (source chip: registry / py launcher / uv / manual) with python version and package count; PEP 668 envs carry a red `MANAGED` chip and a disabled state explaining PD-ENV-002. Actions: *Browse…*, *Rescan*, star-as-default.
**Installed.** Virtualized table: name (mono) · version · latest · size · chips. Up-to-date rows use `--color-text-dim` (owner's "dimmed" requirement); outdated rows show an `UPDATE` badge; pinned rows a 🔒 `--color-info` chip. Row actions: pin/unpin, uninstall, details. Multi-select via checkboxes; bulk action bar appears on selection.
**Updates.** Same table filtered to outdated, badge count in sidebar. Header: *Select all* (excludes pinned; shows "3 pinned excluded"), *Update selected*. After resolve → **Preview panel** replaces the table: three grouped sections — *Will upgrade* (A `1.2 → 2.0`), *New dependencies*, *Needs decision* (held-back in `--color-warn` with one-line blocker sentence; impossible in `--color-danger`). Each needs-decision row hosts a segmented control: **Keep compatible · Skip · Force latest** (Force opens an inline confirm naming what breaks). Footer: `Confirm (n changes)` / `Back`.
**Search.** Search field autofocused; results stream under 50 ms per keystroke from the local index. Result row: name · summary (from cached metadata) · latest · `INSTALLED ✓`/`UPDATE` chip when applicable · **[Add]**. Right detail panel: description, requires-python, license, links. Queue ("**dock bay**") docks along the right edge as a slim column of added packages with editable version fields and `Install (n)`.
**Pins.** Pin list with reason field; (P1) auto-suggest section: "`urllib3` — 12 packages depend on it. Pin?".
**Snapshots** (surfaced under Environments → env detail): timeline of snapshots with trigger label, diff viewer (added/removed/changed in mono), `Rollback…` with its own preview per DATA-FLOW §8.
**Health.** Project-folder picker (persisted per env) → run panel with three result tabs (deptry / vulture / ruff) per CODE-HEALTH-SPEC; `Fix with ruff` gated behind explicit confirm listing file count.
**Settings.** Engine (pip/uv radio + detected versions), locale (EN/VI), thresholds (pin auto-suggest count, snapshot retention), index refresh, PEP 668 override (off by default, scary copy), *Open logs folder*, *Legal & About* (links to GitHub legal docs + re-open legal gate).
**Legal gate (first run).** Modal listing the five documents with GitHub links and a summarized disclaimer sentence; single checkbox "I have read and accept" → `Continue`. Decline exits the app. Consent stored with docs-version hash; hash bump re-triggers the gate.
## 5. Click budgets (owner ceiling: 5)
| Flow | Clicks | Path |
|---|---|---|
| Update everything | **4** | Updates → Select all → Update → Confirm (app auto-scans on env open) |
| Update everything, 1 conflict kept compatible | **4** | default choice needs no extra click |
| Install one package | **4** + typing | Search (autofocus) → result [Add] → Install → Confirm |
| Uninstall one package | **3** | Installed row ⋮ → Uninstall → Confirm |
| Rollback last snapshot | **4** | Env detail → snapshot → Rollback → Confirm |
| Switch engine | **3** | Settings → engine radio → (auto-saved) back |
| Run Code Health | **3** | Health → Run (folder persisted) → view |
## 6. Component inventory (prefix `Pd`)
`PdSidebar`, `PdStatusLine`, `PdEnvSwitcher`, `PdPackageTable` (virtualized), `PdPackageRow`, `PdBadge`, `PdPreviewDiff`, `PdConflictRow` (segmented 3-way), `PdDockBay` (queue), `PdConsoleDrawer`, `PdSummarySheet`, `PdSnapshotTimeline`, `PdHealthReport`, `PdLegalGate`, `PdEmptyState`, `PdOfflineBanner`.
## 7. States & feedback
- Loading: skeleton rows in surface-2, never spinners longer than 300 ms without text.
- Empty states: one mono glyph + one sentence + one action (e.g. Updates empty: `▸ all packages up to date`).
- Offline: banner chip in top bar; search works (local index), metadata panel shows cached-at timestamp.
- Errors: inline with catalog code, human message (localized), and *Details* expanding stderr tail. Toasts only for background completions.
- Destructive confirms (`Force latest`, uninstall with breakage, PEP 668 override) use `--color-danger` primary buttons and require the dialog's default focus to be **Cancel**.
## 8. Keyboard & accessibility
Full keyboard traversal: `Ctrl+1..8` sidebar tabs, `/` focuses search, `Space` toggles row selection, `Ctrl+A` select-all-visible, `Enter` primary action, `Esc` closes drawers. Contrast: all text tokens meet WCAG AA on their surfaces (verified in the design-token test); focus ring 2 px accent, never removed. Screen-reader labels on all icon buttons; live region announces execution progress summaries ("13 of 15 complete"). Windows high-contrast mode: tokens fall back to system colors.
+33
View File
@@ -0,0 +1,33 @@
# PipDock — Disclaimer
*Version 1.0 · Effective 2026-07-17 · Governing language: English.*
## 1. Modifying environments carries inherent risk
PipDock installs, upgrades, and removes Python packages. Even with previews, dependency resolution, snapshots, and post-checks, **any change to an environment can break projects that depend on it** — including in ways no tool can predict (runtime behavior changes between package versions, compiled-extension ABI issues, packages with incorrect metadata). Use the preview step, keep snapshots, and test your projects after significant updates. Do not run bulk updates on environments backing production systems without your own backups and change process.
## 2. Forced operations are at your own risk
The "Force latest" and forced-uninstall options exist for expert use. When you choose them, PipDock shows which requirements will be violated; proceeding **knowingly puts the environment into a state its own metadata declares broken**. The resulting behavior of affected packages is undefined.
## 3. System Python
PipDock blocks modification of externally-managed (PEP 668) Python installations by default. If you enable the override, you accept that modifying an OS-managed or vendor-managed Python can damage tooling on your system beyond Python projects.
## 4. Information accuracy
Package metadata, latest-version information, vulnerability findings (where enabled), and code-health reports are derived from third-party sources (PyPI, the OSV database, deptry/vulture/ruff output) and from heuristics such as reverse-dependency analysis. They may be incomplete, outdated, or wrong — for example, dead-code detection produces false positives on dynamically referenced code. **Review before acting**; PipDock's reports are assistance, not authority.
## 5. Not professional advice; no affiliation
Nothing in PipDock constitutes professional, security, or legal advice. PipDock is an independent project, not affiliated with or endorsed by the Python Software Foundation (Python, pip, PyPI), Astral (uv, ruff), or the authors of deptry, vulture, pip-audit, or any package it manages.
## 6. Warranty and liability
The no-warranty and limitation-of-liability terms of the GPL-3.0 (§15–16), restated in the [EULA](EULA.md), apply to all of the above.
---
## Tóm tắt Tiếng Việt (tham khảo)
Mọi thay đổi lên môi trường Python đều có rủi ro làm hỏng dự án phụ thuộc vào nó, kể cả khi đã xem trước và có snapshot — hãy tự sao lưu và kiểm thử sau khi cập nhật lớn. Tùy chọn "Ép bản mới nhất" và gỡ cưỡng bức đặt môi trường vào trạng thái mà chính metadata của nó tuyên bố là hỏng — bạn tự chịu rủi ro. Thông tin phiên bản, lỗ hổng, dead code đến từ nguồn bên thứ ba và có thể sai — hãy xem xét trước khi hành động. PipDock độc lập, không liên kết với PSF hay Astral. Điều khoản miễn trừ bảo hành theo GPL-3.0 §15–16 áp dụng.
+37
View File
@@ -0,0 +1,37 @@
# PipDock — End User License Agreement (Terms of Use)
*Version 1.0 · Effective 2026-07-17 · Governing language: English (bản Tiếng Việt tóm tắt ở cuối chỉ mang tính tham khảo).*
## 1. License
PipDock is free software, licensed under the **GNU General Public License, version 3** (GPL-3.0). The full license text is available in the repository ([LICENSE](../LICENSE)) and at <https://www.gnu.org/licenses/gpl-3.0.html>. Your rights to use, study, modify, and redistribute PipDock come from the GPL-3.0, and **nothing in this document adds restrictions to, or removes rights granted by, that license** (per GPL-3.0 §7, any such added restriction would be void). This document only (a) restates the GPL's warranty and liability terms as they apply to you as a user, and (b) records acknowledgments the application asks for at first run.
## 2. What PipDock does (acknowledgment)
PipDock installs, upgrades, and removes packages in Python environments **at your direction**, by invoking third-party package managers (pip, uv) and analysis tools (deptry, vulture, ruff, and optionally pip-audit). These operations modify software environments on your computer and can affect the behavior of your projects. You are responsible for reviewing each preview and confirmation the application presents before applying changes.
## 3. No warranty
As stated in GPL-3.0 §15: THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. THE PROGRAM IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.
## 4. Limitation of liability
As stated in GPL-3.0 §16: IN NO EVENT, UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING, WILL ANY COPYRIGHT HOLDER BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS).
## 5. Third-party software and services
Packages you choose to install come from the Python Package Index or other indexes you have configured; they are published by third parties under their own licenses, and installing them may execute their build code. PipDock does not review, endorse, or warrant any third-party package. Third-party components bundled with or invoked by PipDock are listed in [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).
## 6. Trademarks
"Python", "pip", and "PyPI" are trademarks of the Python Software Foundation. "uv" and "ruff" are projects of Astral. PipDock is an independent project and is not affiliated with, sponsored, or endorsed by these organizations.
## 7. Acceptance record
The application records your acceptance of this document (together with the Disclaimer and Privacy Policy) locally on your device, keyed to the documents' version hash. If these documents change materially, the application will ask again.
---
## Tóm tắt Tiếng Việt (tham khảo)
PipDock là phần mềm tự do theo giấy phép GPL-3.0; tài liệu này không thêm bất kỳ hạn chế nào ngoài GPL. Ứng dụng thay đổi các môi trường Python **theo lệnh của bạn** thông qua pip/uv; phần mềm được cung cấp "nguyên trạng", không bảo hành, và các tác giả không chịu trách nhiệm cho thiệt hại phát sinh (theo GPL-3.0 §15–16). Gói bên thứ ba do bạn chọn cài thuộc trách nhiệm của nhà phát hành gói đó. Việc chấp thuận được lưu cục bộ trên máy bạn.
+47
View File
@@ -0,0 +1,47 @@
# PipDock — Privacy Policy
*Version 1.0 · Effective 2026-07-17 · Governing language: English.*
## 1. The short version
**PipDock collects nothing.** No telemetry, no analytics, no crash reporting, no accounts, no identifiers. The developer receives no data from your use of the application unless you personally choose to open a bug report.
## 2. Data stored locally on your device
All application data lives under `%LOCALAPPDATA%\PipDock\` and never leaves your machine:
| Data | Purpose |
|---|---|
| Settings (engine, locale, thresholds, consent record) | app configuration |
| Environment list & package index cache | discovery and instant search |
| Snapshots (package lists of your environments) | rollback |
| Pins | update exclusions |
| Log files (14-day rotation) | troubleshooting; may contain package names and file paths |
Deleting this folder is a complete reset. No data is synced or backed up anywhere by PipDock.
## 3. Network connections
PipDock connects only to: **pypi.org / files.pythonhosted.org** (package name index and metadata — standard web requests carrying no personal data beyond your IP address, as with any website) and **github.com** (checking for and downloading PipDock's own updates). The pip/uv engines make their own connections to the package indexes configured on your system (including any private indexes you have set up); PipDock does not alter or observe those configurations beyond invoking the engines.
## 4. Bug reports (opt-in, manual)
The in-app **Report bug** button prepares a GitHub issue in your browser, prefilled with app version, Windows version, engine and Python versions, the error code, and a short log excerpt; the full log is copied to your clipboard. **Nothing is transmitted until you personally review and submit the issue on GitHub**, under GitHub's own terms and privacy policy. Check the excerpt for paths or names you consider private before submitting — the template reminds you to.
## 5. Children
PipDock is a developer tool and is not directed at children; it processes no personal data regardless of the user's age.
## 6. Changes
Material changes to this policy bump the legal documents' version hash, and the application will present the legal gate again before continuing. History is visible in the repository's git log.
## 7. Contact
Privacy questions: open a discussion or issue at <https://github.com/poli0981/pipdock>.
---
## Tóm tắt Tiếng Việt (tham khảo)
PipDock **không thu thập bất kỳ dữ liệu nào**: không telemetry, không analytics, không tài khoản. Mọi dữ liệu (cài đặt, cache chỉ mục, snapshot, log) nằm trong `%LOCALAPPDATA%\PipDock\` trên máy bạn; xóa thư mục này là xóa sạch. Ứng dụng chỉ kết nối tới pypi.org (dữ liệu gói) và github.com (cập nhật chính PipDock). Nút báo lỗi chỉ mở form GitHub đã điền sẵn — không gì được gửi đi cho tới khi bạn tự xem lại và bấm gửi.
+48
View File
@@ -0,0 +1,48 @@
# PipDock — Third-Party Notices
*Version 1.0 · 2026-07-17 · This inventory is regenerated at each release (`cargo about` + `license-checker`); the lists below name the principal components. All bundled licenses are GPL-3.0-compatible; full license texts ship in the release under `licenses/`.*
## A. Bundled / linked components (distributed with PipDock)
| Component | License | Role |
|---|---|---|
| Tauri 2 (+ plugins: updater, dialog, shell) | MIT OR Apache-2.0 | application framework |
| React 19, react-dom | MIT | UI |
| TypeScript | Apache-2.0 | build-time |
| Vite 8, Rolldown toolchain | MIT | build-time |
| Tailwind CSS 4 | MIT | styling |
| Zustand | MIT | state |
| i18next, react-i18next | MIT | localization |
| tokio, serde, clap, tracing, async-trait | MIT OR Apache-2.0 | Rust core |
| nucleo (fuzzy matcher) | MPL-2.0 | search (file-level copyleft; compatible) |
| rusqlite / SQLite | MIT / Public Domain | local cache |
| specta / tauri-specta | MIT | type generation |
| Inter typeface | SIL OFL 1.1 | UI font |
| JetBrains Mono typeface | SIL OFL 1.1 | mono font |
| Microsoft Edge WebView2 Runtime | proprietary, system component | rendering (not distributed by PipDock; Evergreen runtime assumed present per Microsoft's terms) |
## B. External tools invoked as separate processes (NOT distributed with PipDock)
These run as independent programs from your system or from PipDock's isolated tools environment; they are separate works under their own licenses, obtained by you from PyPI/their distributors:
| Tool | License | Invoked for |
|---|---|---|
| pip | MIT | engine |
| uv | MIT OR Apache-2.0 | engine |
| deptry | MIT | Code Health — dependency issues |
| vulture | MIT | Code Health — dead code |
| ruff | MIT | Code Health — lint/format |
| pip-audit | Apache-2.0 | Security tab (when enabled) |
| CPython | PSF License | the environments themselves |
## C. Services
PyPI (operated by the Python Software Foundation) supplies the package name index and metadata under its Terms of Use. GitHub supplies release hosting for PipDock's own updates.
## D. Trademarks
"Python", "pip", "PyPI" — Python Software Foundation. "uv", "ruff" — Astral. "Windows", "Edge WebView2" — Microsoft. Used for identification only; no affiliation or endorsement implied.
---
*Cảm ơn các dự án mã nguồn mở trên — PipDock đứng trên vai họ. / PipDock stands on the shoulders of the projects above — thank you.*