poli0981andClaude Opus 5 545ca7fc89 feat(cli): pipdock health --fix, prompting the way the dialog does
Replaces the `PD-INT-001` refusal P3 left in place. CLI-SPEC §1.1 says the two heads share
behaviour, and this is the one operation neither of them can undo, so the CLI refuses in the
same places the dialog will.

**The `--yes` decision is the sharpest one in the slice, and it turns on recoverability.**
CLI-SPEC §1.2's "never force" cannot mean "never fix", or `--fix` is useless in the
pre-commit hook the exit-code rule was written for. So: a clean tree proceeds under `--yes`,
because one `git checkout .` puts it back. A dirty tree — or no repository at all — refuses
with exit 2, because those are the cases where a script could destroy work with no way back.

The escape hatch is deliberately **not a flag**. It is `git commit` or `git stash`, which is
the actual remedy and leaves something to return to; a `--force-fix` would exist only to be
pasted into a CI file once and never reconsidered. CLI-SPEC §4 sketches a "second `-y`" for
the resolve countdown, but `--yes` is a bool here, and inventing flag machinery inside the
slice that introduces source-tree writes is the wrong trade.

`--tool deptry --fix` is a usage error rather than a silent no-op: ruff is the only tool with
a write path. Exit 0 only when the *whole* report is clean afterwards — deptry and vulture
are untouched by a ruff fix, so their findings still count — which is what makes
`pipdock health --fix && …` mean something.

**`--json --fix` prints one document, and getting there took looking at the output.** It
printed two: the pre-fix report and then the `FixReport`. The first describes a state that no
longer exists by the time the command returns, and CLI-SPEC §6 states the contract as one
document. The human form still prints both, because there the report is what makes the fix
summary legible.

Verified against a seeded repository, release build — this is the slice where running it is
not optional:

* 6 fixable across 2 files, one `E722` with no fix in a third. After `--fix`, `git diff --stat`
  lists **exactly those two files**; the third is untouched, which is what rules out a stray
  `ruff format` in the argv. `fixed: 2 file(s); 1 finding(s) remain`, exit 1.
* Non-TTY without `--yes`: refused, exit 2.
* Dirty tree with `--yes`: refused naming the entry count, exit 2, and `git status` shows the
  source files were not written.
* `attrib +R` on one of the two targets: `PD-PRM-003` naming that file — and the **other**
  file, perfectly writable, was not written either. The fix refuses as a whole rather than
  half-rewriting a source tree nothing can restore.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 19:30:12 +07:00
2026-07-27 12:02:38 +07:00

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.

PipDock does not update itself — grab a new build from the same page when you want one. That is deliberate: a self-updater is a standing remote-code-execution path into a tool that already runs subprocesses against your interpreters, and it is not worth the convenience (see docs/SECURITY.md §5).

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:

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 Product goals, personas, feature matrix P0–P2, non-goals
docs/ARCHITECTURE.md Crate layout, Engine trait, IPC surface, storage
docs/DATA-FLOW.md State machines for update / install / uninstall, engine command mapping
docs/UI-SPEC.md Terminal-tech design system, screens, click budgets
docs/CLI-SPEC.md Commands, flags, exit codes, JSON contracts
docs/CODE-HEALTH-SPEC.md deptry / vulture / ruff integration
docs/ERROR-CATALOG.md Error codes, stderr detection patterns, user guidance
docs/SECURITY.md Threat model, PEP 668 policy, supply-chain hygiene
docs/TESTING.md Test strategy incl. disposable-venv integration tests
docs/RELEASE-CI.md CI callers into poli0981/.github, release pipeline
docs/I18N.md EN/VI localization rules
docs/ROADMAP.md Spike week, milestones, exit criteria
legal/ EULA, Disclaimer, Privacy Policy, Third-Party Notices (linked by the in-app legal gate)

License

GPL-3.0. See LICENSE (add the standard GPL-3.0 text at repo creation). The legal documents in 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.

S
Description
No description provided
Readme GPL-3.0
3.4 MiB
0 Stars 1 Watchers 0 Forks
Languages
Rust 62.8%
TypeScript 32.9%
Python 2.4%
JavaScript 1.5%
CSS 0.4%