docs: the specs say what the code does; 1.4.0 recorded, with its audit backlog

Every spec checked against the code rather than against itself, in four passes that each read the
branch's commits and then the source:
- CLI-SPEC/CLI-GUIDE: one JSON document per command (with the per-command table and the paths
  that print nothing), environment selection, logging, Ctrl-C and exit 130, the prompts as they
  are rather than the [A]bort and countdown that never existed, `.heldBack`, a `pipdock audit`
  section, and the rules every mutating command now follows.
- ARCHITECTURE/DATA-FLOW/ERROR-CATALOG: the Engine trait's real signatures, Requires-Python's
  three checkpoints, store v4 and the log folder, §7's return types and events, the state machine
  with re-probing and Force latest, where each §9 invariant is enforced, and 35 codes in 32 rows.
- SECURITY/TESTING/RELEASE-CI/CODE-HEALTH-SPEC: the PEP 668 override as built, four browser hosts
  and the exact capability set, attested releases, the new CI, the tools constraints, and test
  tiers that describe what runs rather than what was planned.
- UI-SPEC/PRD/README/I18N: the screens as they render, the keyboard, tokens and their contrast
  sweep, the feature matrix's status, attestation instructions, and I18N's one stated exception.

ROADMAP gets the 1.4.0 record — what was wrong, what running found that reading did not, what was
deliberately not done — and the **Audit backlog**: every finding not fixed, with where it is and
why it waited. CLAUDE.md's counts and contradictions are corrected, with the rules this release
left behind. changelog/1.x.md has the 1.4.0 entry, including "Changed for scripts" and "You will
see this once". AI-DISCLOSURE, README and About say which model and who released what. The legal
documents' effective date moves to the release date.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5.5 committed 2026-10-17 00:55:27 +07:00
1 parent 42f227c1aa
commit 7124227262
19 files changed
+1359 -414

No files matched your search

+60 -24
View File
@@ -1,7 +1,7 @@
# PipDock — working notes for Claude
Windows GUI + CLI for bulk-managing Python packages. Tauri 2 + Rust core + React 19.
Repo `poli0981/pipdock` · GPL-3.0-only · **Status: 1.3.0. M1, M2, Phase 3, Phase 4, the P1 wave, the Security tab and the dependency view are all complete.** 1.0.0 shipped the release pipeline, a protected `main`, the manual charter and legal documents that match the code; 1.1.0 added pin auto-suggest, requirements export/import, the cache manager and the `Ctrl+K` palette; 1.2.0 added the Security tab (PRD P1-1); 1.3.0 added the dependency view (P1-6), which is a *mode of the package screen* rather than a tab and adds no runtime dependency — read its ROADMAP record before touching `graph/`, because the shape of the screen is a consequence of measurements rather than of taste. **What is left of Post-1.0 is one thing** — the scheduled check (P1-7) — and `docs/ROADMAP.md` now carries the survey of what blocks it, which for two versions it was cited for and did not contain: no toast component, no notification/autostart/tray plugin, nothing on a timer, and no surface that can report a background failure.
Repo `poli0981/pipdock` · GPL-3.0-only · **Status: 1.4.0. M1, M2, Phase 3, Phase 4, the P1 wave, the Security tab and the dependency view are all complete.** 1.0.0 shipped the release pipeline, a protected `main`, the manual charter and legal documents that match the code; 1.1.0 added pin auto-suggest, requirements export/import, the cache manager and the `Ctrl+K` palette; 1.2.0 added the Security tab (PRD P1-1); 1.3.0 added the dependency view (P1-6), which is a *mode of the package screen* rather than a tab and adds no runtime dependency — read its ROADMAP record before touching `graph/`, because the shape of the screen is a consequence of measurements rather than of taste. 1.4.0 added no feature: it is the audit release — about 170 findings, every Critical and High fixed with a test that failed first, and the rest in ROADMAP's **Audit backlog**, with file:line and a reason each. Read that table before starting a slice; most of what is wrong with the codebase is already written down there. **What is left of Post-1.0 is one thing** — the scheduled check (P1-7) — and `docs/ROADMAP.md` now carries the survey of what blocks it, which for two versions it was cited for and did not contain: no toast component, no notification/autostart/tray plugin, nothing on a timer, and no surface that can report a background failure.
## Read the docs before changing anything
@@ -12,16 +12,16 @@ The design is fully specified. Read in this order; do not invent behaviour that
3. `docs/DATA-FLOW.md` — update/install/uninstall/rollback state machines, engine command mapping, **invariants §9**
4. `docs/UI-SPEC.md` — design tokens, screens, click budgets, keyboard map
5. `docs/CLI-SPEC.md` — commands, flags, exit codes, JSON contracts
6. `docs/ERROR-CATALOG.md` — the launch codes and their stderr classifiers. **34 in Rust**
6. `docs/ERROR-CATALOG.md` — the launch codes and their stderr classifiers. **35 in Rust**
(`Code::ALL`, pinned by two tests); the doc tabulates fewer rows because it folds
`PD-HLT-001..004` into one, so it shows **31 rows**. Adding a code means the catalog,
`PD-HLT-001..004` into one, so it shows **32 rows**. Adding a code means the catalog,
`Code::ALL`, both counts, the "no code without a fixture" gate in `classifier_corpus.rs`,
**both `locales/*/errors.json`**, a regenerated `codes.json`
(`cargo run -p xtask -- ipc-fixtures`), regenerated bindings, and re-blessed goldens —
`golden__schema-Code.snap` **and every schema that embeds it**, which since 1.2.0 is
**four**: `StepResult`, `ExecutionSummary`, `HealthReport` and `AuditReport`, the last two
via `ToolProblem.code`. **Five snapshot files in all.** This line named three while saying
four, and stayed that way through 1.2.0 — grep `PD-ENV-001` across
`golden__schema-Code.snap` **and every schema that embeds it**, which since 1.4.0 is
**five**: `StepResult`, `ExecutionSummary`, `CheckReport` (its `error`), `HealthReport` and
`AuditReport`, the last two via `ToolProblem.code`. **Six snapshot files in all.** This line
has been wrong about the count twice — grep `PD-ENV-001` across
`crates/pipdock-cli/tests/snapshots/` rather than trusting the list. Nine places; the
gates will tell you which you forgot, including `i18n.test.ts`, which fails on a code with
no copy in either language
@@ -62,7 +62,7 @@ failed package never aborts a batch (skip-and-continue, then a `"13 successful,
minor range at roughly 600 lines and never renumber an existing range file —
`changelog/README.md` is the authority.
- Crates `pipdock-*`; React components prefixed `Pd` (`PdPackageRow`, `PdConflictDialog`)
- Crates `pipdock-*`; React components prefixed `Pd` (`PdPackageRow`, `PdConflictRow`)
- Tauri identifier `com.skullmute.pipdock`; CLI binary `pipdock`
- Frontend lives in `ui/`, but `package.json` sits at the **repo root** so the ops-repo
`reusable-web-react.yml` (which has no `working-directory` input) works unmodified; Vite is
@@ -76,9 +76,18 @@ failed package never aborts a batch (skip-and-continue, then a `"13 successful,
`docs/RELEASE-CI.md` is authoritative *as corrected*: the ops repo `poli0981/.github` has **no
reusable Rust or Tauri workflow**, its notifiers are **Discord-only**, dependency bumps are
**Dependabot** (not Renovate), and its CodeQL reusable has **no Rust support**. So `ci-rust.yml` and
`release.yml` are project-local; `ci-node.yml`, `codeql.yml` and the notifiers are callers.
Every caller needs an explicit `permissions:` block — callers without one default to `none`.
**Dependabot** (not Renovate), and its CodeQL reusable *lists* no Rust but passes `languages`
straight to codeql-action, which analyses Rust and Actions without a build — `codeql.yml` asks for
both. So `ci-rust.yml`, `release.yml` and `security-scan.yml` are project-local; `ci-node.yml`,
`codeql.yml` and the notifiers are callers. Every caller needs an explicit `permissions:` block —
callers without one default to `none` — and a write permission belongs on the job that needs it,
not the workflow.
**`notify-ci-failure.yml` lists its workflows by name, and a new workflow has to be added to it.**
`workflows: ['*']` — the ops repo's own example — is not a wildcard to `workflow_run`: it matched
nothing, and `main` was red from 2026-09-23 for three weeks with no one told. Start any CI
question with `gh run list --branch main`, and remember that `security-scan.yml` exists for the
case no PR will catch: an advisory against something already merged.
## Current state
@@ -93,7 +102,7 @@ has a table per stage and says where to pick up; read it before starting a slice
**Phase 3 is complete** — six slices, exit criteria met and recorded. P4 put Code Health on screen: `PdHealthReport` is UI-SPEC §6's
fifteenth of sixteen, `EnvRow.healthProject` remembers the folder per environment, and
`health_save_report` writes Markdown + JSON. **`NOT_YET` is down to two**, both M3-general — P5 landed the
`health_save_report` writes Markdown + JSON. `NOT_YET` was down to two after it, both M3-general — P5 landed the
gated `ruff --fix`, PipDock's first write outside site-packages and `%LOCALAPPDATA%`. P4 *did* need new commands, contrary to the earlier claim — one shipped, and
cancellation was deferred on a measurement (a warm three-tool run is 1.3 s in release).
@@ -111,16 +120,44 @@ P2 built the tools venv — `health::sync_tools_venv` fills
`%LOCALAPPDATA%\PipDock\data\tools\.venv` from the shipped pins over `pipdock tools sync`, and there is
no `TOOLS_PYTHON_MAX` because deptry ships an abi3 wheel (ROADMAP's premise for that const was
wrong; the record says why). P1 closed **P0-10**: pip's version is on every Environments row and
*Upgrade pip* is 2 clicks. **Next is P3** (the three runners + `HealthReport`), then P4 (the Health
screen) and P5 (the gated `ruff --fix`); `~/.claude/plans/b-n-c-th-b-t-snappy-rabin.md` has all
four decomposed, including six corrections to the specs found by running the pinned tools.
P2 touched no `NOT_YET` entry: it is CLI-only on purpose, so P3's `health_run` owns the
*Upgrade pip* is 2 clicks. P3–P5 followed — the three runners and `HealthReport`, the Health
screen, the gated `ruff --fix` — and are recorded in ROADMAP. P2 touched no `NOT_YET` entry: it is CLI-only on purpose, so P3's `health_run` owns the
implicit sync rather than the frontend getting two ways to reach one operation.
**`NOT_YET` is two**, and only two: `env_add_manual` and `logs_tail`, both M3-general.
`src-tauri/src/lib.rs:25-28` is the authority and three tests keep it honest in both directions —
this file used to say "four" in one paragraph and "two" in another, each true when written and
neither updated.
**`NOT_YET` is one**: `env_add_manual` — *Browse…*, and the next slice. `logs_tail` shipped in
1.4.0 together with the log it tails. `NOT_YET` in `src-tauri/src/lib.rs` is the authority and
three tests keep it honest in both directions — this file has said "four", "two" and "two" in
different paragraphs at once, each true when written and none updated.
**1.4.0, the audit release, left these behind** — most found by running rather than by reading, and each
rule below backed by a test where a test can hold it:
- **A flow is only as safe as what can drive it.** The stale-plan and drift checks (DATA-FLOW
§9.3) never fired, because nothing could run a flow without a real engine, so nothing did.
`FlowOptions`, the `Engine::probe` seam and `tests/flows.rs`'s scripted engine exist so that
every flow decision has a test needing no pip. A new flow decision without one is a regression.
- **A check that cannot run must not report a pass.** `unwrap_or(ok: true)` said "verified"
exactly when nothing was — a pip broken by the run it was checking. `CheckReport.error` says so.
The empty-plan path kept its own copy of the bug until the last UI commit of the release.
- **`python -I` ignores `PYTHONUTF8` and `PYTHONIOENCODING`** (it implies `-E`), so invariant 7's
variables did nothing for the probe, and every venv under a folder named in Vietnamese crashed
it. `-X utf8` survives isolation; `probe.py` runs under it.
- **A grant is a contract no frontend test can see.** Decline on the legal gate did nothing in the
installed app while its test passed: the test mocks `close()`, and `core:default` never granted
`core:window:allow-close`. `lib.rs` pins the webview's exact permissions now — widening them is
a test change, on purpose.
- **Data drift and format drift look identical in a red drift job.** Seven weeks of red were two
causes: PyPI data (idna's newest release, scipy's version list) and uv 0.13 rewriting its error
rendering. Data is redacted in `capture.py`; a format change gets a frozen corpus of its own
(`tests/fixtures/uv-0.11/`, the last miette-style uv) beside the live one (`uv/`).
- **Normalise everything you hash, not most of it.** The legal-docs hash normalised CRLF in the
content and hashed the raw length, so a Windows checkout re-showed the gate for nothing.
- **`--json` is one document.** Scripts parse stdout with one `ConvertFrom-Json`; prose, prompts
and warnings go to stderr. Every command's shape is in CLI-SPEC §6, and the goldens hold it.
- **Never put a backslash in a Bash heredoc** that becomes source code: the tool collapses `\\`
to `\`, which turned `b"\r\n"` test strings into real line breaks and a CRLF test into one that
could not fail. Write such files with the Write/Edit tools, then check the failing-first run
actually failed.
Three rules P1 left behind, all found by running rather than reading:
@@ -201,7 +238,7 @@ Things worth knowing before you change any of it:
- **`cargo test` fails when `ui/src/ipc/generated.ts` is stale.** Fix with
`cargo run -p xtask -- bindings`; the failure names that command and the first differing line.
- **The L4 goldens (`crates/pipdock-cli/tests/golden.rs`, 64 snapshots at 1.1.0) are the CLI's output
- **The L4 goldens (`crates/pipdock-cli/tests/golden.rs`, 68 snapshots at 1.4.0) are the CLI's output
contract.** A diff there is a real behaviour change — re-bless deliberately, never reflexively.
They are what made the `core::flow` refactor provably behaviour-preserving.
- **Two tests hold the wire format**: `Code::ALL` must serialize as `as_str()`, and no
@@ -340,6 +377,5 @@ Things worth knowing before you change any of it:
id before execution and the GUI can draw DATA-FLOW §3's distinct states. The cost is that
skipping the snapshot becomes expressible, which is why `flow::proof_from` refuses `NotTaken`
with `PD-SNP-001`. Do not "simplify" them back into one.
- **Fixtures under `tests/fixtures/{pip,uv}/` are not literal engine bytes** — see the redaction
note above. Related: `ScanProgress.label` and every path, version and engine id in the UI are
data and are never translated (I18N §2).
- `ScanProgress.label` and every path, version and engine id in the UI are data and are never
translated (I18N §2).
+24 -12
View File
@@ -50,22 +50,26 @@
| Area | What you get |
|---|---|
| Environments | Auto-discovery of venvs / uv venvs / system Pythons (PEP 514 + `py` launcher), manual add, PEP 668 guard |
| Environments | Auto-discovery of installed Pythons — the Windows registry (PEP 514), the `py` launcher and the Pythons `uv python list` reports — plus a `.venv`, `venv`, `env` or `.env` folder in the folder PipDock was started from. Adding an environment by path is not in the app yet; the CLI takes any interpreter or environment folder with `--env` |
| PEP 668 guard | Pythons marked externally managed are refused by default. An override in Settings, off by default, asks before it turns on, and while it applies every screen that can change that Python says so |
| 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 |
| Updates | Bulk update with group dry-run resolve, held-back explanations, 3-way conflict choices. The preview names every package *Force latest* would break, anything left out because it needs a different Python, and withdrawn (yanked) releases |
| 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, with a reason. The Pins screen suggests packages a lot of your others depend on, and the threshold is configurable |
| Dependencies | For any package on the Installed list: what requires it and what it requires, with the version constraint on each, how many packages removing it would leave broken, and any requirement nothing installed satisfies |
| Pins | Keep packages out of every update until you unpin them, with a reason. The Pins screen suggests packages a lot of your others depend on, and the threshold is configurable |
| Snapshots | Automatic pre-batch snapshots, diff view, one-click rollback |
| Engine | pip **or** uv, selectable in Settings (uv auto-detected on first run) |
| Engine | pip **or** uv, chosen in Settings, which shows each one's version for the selected environment (or *not found*). pip is the default; uv has to be on your `PATH` |
| Code Health | deptry + vulture + ruff against a project folder — unused deps, dead code, style — run from PipDock's own isolated tools env |
| Security | pip-audit against an environment's packages: each known advisory with the versions that fix it (or *no fix*), its CVE aliases and a link to its OSV entry, run from PipDock's own isolated audit environment |
| pip upkeep | Check & update pip itself per environment |
| CLI | `pipdock` — full parity for core operations, JSON output, CI-friendly exit codes |
| Requirements | Export an environment as `requirements.txt`; import one and preview what it would install, with every line it will not use reported by number |
| Disk usage | See and clear what PipDock has written — snapshots and the Code Health tools environment |
| Keyboard | `Ctrl+K` command palette, `Ctrl+1`–`Ctrl+9` tabs, full keyboard traversal |
| i18n | English + Tiếng Việt |
| Privacy | No telemetry. **PyPI is the only host PipDock connects to.** It does not check for updates, so it never calls home — GitHub and the ruff docs are only ever handed to your browser as a link you clicked |
| Disk usage | Everything PipDock writes is under `%LOCALAPPDATA%\PipDock\data\`. Settings shows it and clears the parts that are safe to clear — snapshots (`snapshots\`), the Code Health tools environment (`tools\`) and the Security tab's audit environment (`audit\`). `index.db` (package index, settings, pins, your acceptance of the legal documents) is shown but never cleared; the logs (`logs\`) are deleted automatically after 14 days |
| Logs | PipDock keeps its own log, one file per day in `data\logs\`, and never sends it anywhere. It records the commands PipDock ran, so it holds package names and file paths. Settings shows the folder and copies the recent lines for a bug report |
| Keyboard | `Ctrl+K` command palette, `Ctrl+1`–`Ctrl+9` tabs (by key position, so AZERTY and other layouts work too), `/` for Search, full keyboard traversal |
| i18n | English + Tiếng Việt, remembered across restarts |
| Privacy | No telemetry. **PyPI is the only host PipDock connects to.** It does not check for updates, so it never calls home — GitHub, the ruff docs, OSV's advisory pages and the author's links page are only ever handed to your browser as a link you clicked |
## Install
@@ -73,17 +77,25 @@ Download the installer (NSIS `.exe` or `.msi`) from [GitHub Releases](https://gi
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](docs/SECURITY.md) §5).
> Windows SmartScreen may warn on first run because the binaries are not EV-code-signed. Every release publishes `SHA256SUMS.txt`; verify your download against it before running:
> Windows SmartScreen may warn on first run because the binaries are not EV-code-signed. Every release publishes `SHA256SUMS.txt`; verify your download against it before running (replace `<version>` with the version in the file name you downloaded):
>
> ```powershell
> (Get-FileHash .\PipDock_1.0.0_x64-setup.exe -Algorithm SHA256).Hash.ToLower()
> (Get-FileHash .\PipDock_<version>_x64-setup.exe -Algorithm SHA256).Hash.ToLower()
> ```
>
> Compare that against the matching line in `SHA256SUMS.txt`. If they differ, do not run the file.
>
> From 1.4.0 the `.exe` and `.msi` also carry a build-provenance attestation. A checksum published beside a file cannot prove where the file came from — whoever could replace one could replace both — but the attestation proves the installer was built by this repository's release workflow. With the [GitHub CLI](https://cli.github.com/):
>
> ```powershell
> gh attestation verify .\PipDock_<version>_x64-setup.exe --repo poli0981/pipdock
> ```
>
> It succeeds only when GitHub holds an attestation from this repository for that exact file. If it fails, do not run the file.
## 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.
**GUI:** launch PipDock → accept the first-run legal gate → pick an environment from the discovered list (the first usable one is already selected; *Use* picks another) → the *Updates* tab shows what's outdated → *Select all* → *Update* → review the preview → *Confirm*. Four clicks.
**CLI:** the installer puts `pipdock.exe` next to the GUI, in `%LOCALAPPDATA%\PipDock\`.
**PipDock does not edit your `PATH`**; add that folder yourself if you want to type `pipdock`
@@ -129,7 +141,7 @@ just stating them. Everything below is for reading the code.
## How this was built
PipDock was written with substantial help from an AI coding assistant — **Claude Opus 5**, made by [Anthropic](https://www.anthropic.com), through [Claude Code](https://claude.com/claude-code) — under human review. It wrote source code, tests, debugging work and the Vietnamese translation. Every change reached `main` through a pull request the maintainer read and merged, `main` is protected and cannot be bypassed, and the built application was driven by hand on three machines before 1.0.0 shipped.
PipDock was written with substantial help from an AI coding assistant — **Claude Opus 5** through 1.3.0 and **Claude Opus 5.5** from 1.4.0, made by [Anthropic](https://www.anthropic.com), through [Claude Code](https://claude.com/claude-code) — under human review. It wrote source code, tests, debugging work and the Vietnamese translation. Every change reached `main` through a pull request, and `main` is protected and cannot be bypassed. Through 1.3.0 the maintainer read and merged each one, and drove the built application by hand on three machines before 1.0.0 shipped; 1.4.0 was released by the assistant on the maintainer's written instruction, once its checks had passed.
That review mattered: **thirty-five defects** reached or nearly reached `main`, and not one was caught by the test suite that was green at the time. They were found by running the thing.
+107
View File
@@ -3,6 +3,113 @@
Newest first. See [`README.md`](README.md) for the conventions, and `docs/ROADMAP.md` for what each
slice cost and what it taught — that is a different document for a different reader.
## 1.4.0 — 2026-10-17
**No new feature: everything PipDock already did, made to do what it said.** A review of the whole
codebase found about 170 problems, and this release fixes every serious one. Several were in the
part that matters most — checking a change before it happens — so if you skip release notes as a
rule, read the first section.
### Fixed — the safety checks
- **A preview that is out of date is refused.** A plan confirmed more than ten minutes after it was
made, or for an environment something else changed in the meantime, is refused before anything
is written (`PD-RES-002`). This check existed and never ran.
- **A version your Python cannot run is never planned.** PipDock now checks every release's
`Requires-Python` itself, for pip and for uv alike. A package that cannot be updated for that
reason is listed under *Left out — needs a different Python*, with the range it needs and the
Python you have, instead of pip's misleading "not found" — or uv quietly planning it anyway.
- **Force latest forces.** It used to change nothing. It now installs the newest release, and the
preview has a **Will break** section naming each package that will stop working and the
requirement of its that is being overridden; the Confirm button counts them.
- **Restoring a snapshot with the other engine no longer removes pip.**
- **`ruff --fix` only changes the files the report showed you.** It used to fix everything it could
reach, including files inside `.venv` and notebooks the report had excluded.
- **A failed build is a failure.** With uv, a package whose build failed showed as "nothing to
change".
- **Stop, a timeout or a network outage mid-install** now ends with a summary of what happened and
the snapshot to restore from, instead of an internal error and nothing else.
- **After a run, a check that could not run says so**, instead of showing nothing — which read as
everything being fine.
### Fixed — everything else
- PipDock **crashed on any environment inside a folder with accented characters in its name** —
every Vietnamese-named folder, for one. It no longer does.
- Interpreters installed under a path with a **space** in it are found.
- Requirements that only apply on another platform (`pexpect; sys_platform != "win32"`) are no
longer reported as missing.
- **The PEP 668 setting now does what it says.** It was a checkbox nothing read. Turning it on asks
you first; while it is on, a red *PEP 668 override* chip shows on every screen where it applies,
and only there.
- **Decline on the first-run screen closes PipDock.** It did nothing.
- **The language you choose is kept** after a restart.
- **The window can be maximized and snapped**, and opens at a size that fits your screen — on a
laptop it used to open with the status line under the taskbar. The content stops widening at a
readable width.
- **Switching environment quickly no longer shows the previous one's data** — package lists,
update badges, snapshot diffs, the dependency view and pin suggestions could all land on the wrong
environment.
- A run that failed to start could leave PipDock refusing every other change ("another change is in
progress") until restart.
- **Back** while a preview is still being worked out now stops the engine, rather than leaving it
running.
- The **Security** tab scrolls.
- Typing `/` puts the cursor in Search from any screen — including Search itself, where it did nothing.
- `Ctrl+1`…`Ctrl+9` work on keyboard layouts where the digits need Shift, such as French.
- F5, Ctrl+R, Ctrl+P and Ctrl+F no longer reload, print or search the app as if it were a web page.
- The package table's headings line up with their columns, and names stay visible at the smallest
window size.
- Text on red badges is easier to read.
- A file PipDock cannot write — read-only, or open in another program — is reported as that, not as
a full disk.
- *Report bug* includes your Python and engine versions, and still opens when the log is full of
accented paths.
- Withdrawn ("yanked") releases in a plan are listed in the preview. They were detected and then
never shown.
- Dialogs open in the middle of the window. They opened in its top-left corner.
- On a fresh install, Search offers to download the package index instead of saying it is
"preparing" indefinitely.
### Added
- **PipDock keeps a log** — one file a day in `%LOCALAPPDATA%\PipDock\data\logs\`, kept for 14
days. **Settings → Logs** shows where, and copies the recent part for a bug report. The privacy
policy has described this log since 1.0; now it exists. Nothing in it is sent anywhere.
- If PipDock cannot open its data folder, it **says so in a dialog**, with the log's location,
instead of not starting.
- **Settings shows each engine's version** for the selected environment, and *not found* when one
is missing.
- The plan panel names the environment it is about to change.
### Changed for scripts (`pipdock` CLI)
- **`--json` prints exactly one JSON document** per command, on stdout. Prompts, warnings and
progress go to stderr. Scripts that read several documents, or skipped a leading line, need
updating — `docs/CLI-SPEC.md` §6 lists every command's document.
- **`pipdock env use` is honoured.** The environment is `--env` if given, then the one `env use`
chose, then a `.venv` in the current folder. Before, `env use` was saved and ignored.
- **Ctrl-C stops a run**: the engine is stopped, what completed is printed with the snapshot to
restore from, and the exit code is 130.
- `--verbose` and `--log-file` work. On an internal error, the log's path is printed.
- `pipdock update` with no package and no `--all` is a usage error (exit 2) rather than a silent
no-op. `pipdock audit` follows `--engine`; `pipdock doctor` no longer requires pip when uv is the
configured engine.
### You will see this once
**The first-run legal screen appears again.** The privacy policy now describes the log and the tool
environments PipDock keeps, and the third-party notices name osv.dev; PipDock also stopped
computing the documents' version differently depending on how the files were checked out. Your
acceptance is recorded against that version, so it asks once more. Nothing else resets.
### Verifying a download
Each installer now carries a **build attestation** as well as its checksum:
`gh attestation verify <installer> --repo poli0981/pipdock` proves it was built by this
repository's release workflow from the tagged commit. `SHA256SUMS.txt` is also readable by
`sha256sum -c` on any system now.
## 1.3.0 — 2026-08-20
The **dependency view** — what depends on a package, what it depends on, and what a removal would
+30 -17
View File
@@ -1,6 +1,6 @@
# AI disclosure
*Last updated 2026-08-14, for PipDock 1.0.0.*
*Last updated 2026-10-17, for PipDock 1.4.0.*
**PipDock was written with substantial help from an AI coding assistant, under human review.** This
page says which model, what it did, what it did not do, and how you can check any of it yourself.
@@ -13,13 +13,13 @@ commit trailers. Nothing here changes the licence or the warranty position — s
| | |
|---|---|
| Model | **Claude Opus 5** |
| Model | **Claude Opus 5** — first commit through 1.3.0 · **Claude Opus 5.5** — from 1.4.0 |
| Vendor | **Anthropic** ([anthropic.com](https://www.anthropic.com)) |
| Interface | [Claude Code](https://claude.com/claude-code), Anthropic's CLI/desktop coding agent |
| Period | 2026-07-27 → 2026-08-14 (first commit to 1.0.0) |
| Period | 2026-07-27 → 2026-08-21 (first commit to 1.3.0) · 2026-10-16 → 2026-10-17 (1.4.0) |
Earlier work in the same repository used earlier Claude models; the trailer on each commit records
which one, and `git log` is the authoritative history.
The trailer on each commit records which model produced it, and `git log` is the authoritative
history — the table above is a summary of it, not a substitute.
## What it was used for
@@ -32,9 +32,13 @@ which one, and `git log` is the authoritative history.
## What review meant in practice
Every change reached `main` through a pull request that the owner read and merged. Beyond reading
diffs, four things were load-bearing, and all four caught real defects the review-by-reading did
not:
Every change reached `main` through a pull request. Through 1.3.0 the owner read and merged each
one. **1.4.0 was different, and is recorded as such:** it was an audit of the whole codebase, and
the owner reviewed and approved a written plan — scope, every decision the plan asked them to make,
and the instruction to carry it through to a release — and the assistant then committed, opened the
pull request, merged it once CI was green, tagged, and published, under that instruction. The pull
request, its checks and every commit are public. Beyond reading diffs, four things were
load-bearing, and all four caught real defects the review-by-reading did not:
1. **A green test suite was never sufficient.** Thirty-five defects reached `main` or nearly did,
and *not one* was caught by the suite that was green at the time. They were found by running
@@ -44,19 +48,27 @@ not:
described: all three Code Health tools exit non-zero on findings and vulture uses 3; deptry
reports a *module* name rather than the distribution providing it; ruff's rule URL is keyed by
rule name, not code. Each is now pinned by a test because a document was not enough.
3. **CI is a second reviewer that cannot be talked round.** `cargo clippy -D warnings`,
`cargo audit`, `npm audit`, CodeQL, and integration tests against real pip and uv in disposable
venvs, all blocking on every pull request. `main` is protected and the owner cannot bypass it.
4. **The owner drove the built application by hand** before 1.0.0 — on a real machine, in Windows
Sandbox and in a Windows 10 VM — following `docs/TESTING.md` §4's charter. Several defects were
found that way and only that way.
3. **CI is a second reviewer that cannot be talked round.** Five checks block every pull
request — formatting, clippy and the test suite; `cargo audit`; `npm audit`; lint, typecheck,
tests and build of the frontend; and CodeQL for JavaScript/TypeScript — and `main` is protected
so that the owner cannot bypass them. Integration tests against real pip and uv in disposable
venvs run on every pull request that touches what they cover, and `cargo deny`, CodeQL for Rust
and Actions, and a Tauri version check run on all of them without being required.
4. **The built application was driven by hand before release.** Before 1.0.0 the owner did it —
on a real machine, in Windows Sandbox and in a Windows 10 VM — following `docs/TESTING.md` §4's
charter, and several defects were found that way and only that way. For 1.4.0 the assistant
drove the installed build itself, through screen control on the owner's machine; the 1.4.0
record in `docs/ROADMAP.md` lists what was checked and what was not.
## What was not delegated
- **Product decisions.** Scope, the feature matrix, the non-goals, and what 1.0 would and would not
ship are the owner's. So is the decision to remove the self-updater, which is why PipDock has no
auto-update path (see [`SECURITY.md`](SECURITY.md) §5).
- **Merging, tagging and publishing.** Every release is a human action.
- **The decision to release.** Through 1.3.0 every merge, tag and publish was the owner's own
action. For 1.4.0 the owner delegated the mechanics, in writing, with the conditions attached —
CI green, and the installers matching `SHA256SUMS.txt` before the draft was published — and the
decision that 1.4.0 should ship remained theirs.
- **Anything requiring a legal or security judgment** was raised for a decision rather than taken —
for example the PEP 668 override's default, and whether a `mailto:` scheme belonged in the
browser-launch allowlist.
@@ -65,8 +77,9 @@ not:
Copyright in PipDock is held by **Kokone (poli0981)**, and the work is licensed **GPL-3.0-only**.
Using an AI assistant does not change either. Commits carry a
`Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>` trailer as an accurate record of how the
work was produced — it is attribution, not an assignment of rights, and Anthropic claims no
`Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>` trailer through 1.3.0 and
`Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>` from 1.4.0, as an accurate record of how
the work was produced — it is attribution, not an assignment of rights, and Anthropic claims no
ownership of output produced with its models.
## Third-party code
+130 -68
View File
@@ -6,9 +6,9 @@
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.
3. **Out-of-band by construction.** PipDock ships as a standalone binary. It is never installed into a Python environment, so no operation it performs can break its own runtime (G6). The binary is **not** code-signed — this line said "signed" until 1.4.0 — so what a user verifies is `SHA256SUMS.txt` and, since 1.4.0, the build-provenance attestation each release carries (SECURITY §5).
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. The two exceptions — pip upkeep, and the gated `ruff --fix`, which writes outside any environment — are named rather than silent; DATA-FLOW §9 says what each mutation must present instead.
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, and versions and specifier sets against PEP 440 (`pep440.rs` — until 1.4.0 a version was any string), before either can reach an engine. The requirement lines of a resolve or an install travel as `-r`/`-c` temp files holding exactly those validated tokens, so the command line no longer grows with the environment (§8).
## 2. Repository layout
@@ -19,12 +19,17 @@ pipdock/
│ │ ├─ 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/plan/ # PlanRequest → ResolutionReport → ExecutionSummary; two-phase execution
│ │ ├─ src/flow/ # update/install, uninstall, rollback as resumable flows; PEP 668 preamble
│ │ ├─ src/graph/ # reverse-dependency graph from env introspection, PEP 508 markers
│ │ ├─ 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/store/ # the SQLite store, index.db (§6)
│ │ ├─ src/*.rs # single-file modules: exec (argv, watchdogs, temp files), compat +
│ │ │ # pep440, release (per-release Requires-Python), logging, audit,
│ │ │ # cache, report, requirements, settings
│ │ └─ src/probe.py # embedded env-introspection helper (see §4)
│ └─ pipdock-cli/ # clap binary `pipdock`
├─ src-tauri/ # Tauri 2 app (commands + events only)
@@ -34,105 +39,151 @@ pipdock/
└─ docs/
```
Naming conventions: crates `pipdock-*`; React components prefixed `Pd*` (`PdPackageRow`, `PdConflictDialog`); Tauri identifier `com.skullmute.pipdock`; CLI binary `pipdock`.
Naming conventions: crates `pipdock-*`; React components prefixed `Pd*` (`PdPackageRow`, `PdConflictRow`); 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
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 resolve(&self, env: &PyEnv, req: &PlanRequest, ctx: &ResolveCtx)
-> Result<ResolutionReport>;
async fn install(&self, env: &PyEnv, set: &InstallSet, mode: ExecMode,
sink: ProgressSink) -> Result<StepResult>;
async fn uninstall(&self, env: &PyEnv, names: &[PkgName], system: SystemPackages,
sink: ProgressSink) -> 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
async fn freeze(&self, env: &PyEnv) -> Result<String>; // snapshots, export, audit
async fn upgrade_pip(&self, env: &PyEnv) -> Result<StepResult>; // pip only; uv refuses (PD-ENG-001)
async fn probe(&self, env: &PyEnv) -> Result<ProbeResult> { // provided: probe.py, §4
envs::probe(&env.interpreter, env.source).await
}
}
pub struct ResolveCtx { cancel: CancellationToken, adjust: GuardAdjust, system: SystemPackages }
pub struct GuardAdjust { pins: Vec<PinnedSpec>, release: Vec<PkgName>, exclude: Vec<PinnedSpec> }
pub struct InstallSet { specs: Vec<PinnedSpec>, constraints: Vec<PinnedSpec>, system: SystemPackages }
pub enum SystemPackages { Protected /* default */, OverrideAllowed }
```
The signatures moved in 1.4.0, each for a defect the old one made expressible:
- **`ResolveCtx`.** A resolve was the one engine call nothing could stop — *Stop* while pip backtracked left it running for up to ten minutes (H13) — so it now carries the flow's cancellation token, and a stopped resolve is a `nothing` step, not an error. `GuardAdjust` is what the *flow* changes about the requirement lines, never an adapter: `pins` are exact requirements whose names leave the upgrade list and the guard set (*Force latest*, `Hold` pins), `release` takes installed packages out of the guard set (what a forced package will break), and `exclude` rides along as `name!=version` (a release whose `Requires-Python` excludes this interpreter). `system` is for uv, which refuses even a dry run in an externally managed environment without the flag; pip's `--dry-run --report` is exempt and is never given it.
- **`InstallSet`.** SP-1's rule — restate the installed set or the resolver breaks it — had been applied to the resolve only, and Phase B ran a bare `pip install name==v`, free to move any dependency. `constraints` is everything that must stay where it is, passed as `-c` (§8).
- **`SystemPackages`** is a named value rather than a `bool` for the reason `SnapshotProof` is a named waiver: hard invariant 5 says `--break-system-packages` is never passed implicitly, and this makes "implicitly" greppable. Only a flow's preamble produces `OverrideAllowed` (DATA-FLOW §2).
- **`probe` is provided and no adapter overrides it** — it is `probe.py`, not an engine command. It is on the trait so a whole flow can be driven against a scripted engine (`crates/pipdock-core/tests/flows.rs`): every flow used to probe through a free function, so nothing `start` decides — the PEP 668 gate, the graph, the drift basis — could be tested without a real interpreter, and the bugs in them were not. `freeze` was on the trait before 1.4.0 and missing from this block.
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/`).
- `PlanRequest` — the user's intent: `{ upgrades: Vec<PkgName>, installs: Vec<Spec>, strategy: Compatible | ForceLatest(per-pkg overrides) }`. A `Spec`'s version requirement is a PEP 440 specifier set, checked by `Spec::parse` and on deserialization.
- `ResolutionReport` — normalized output of the dry-run: `{ changes: Vec<Change>, held_back: Vec<HeldBack{ pkg, resolved, latest, blockers: Vec<Blocker{by, version, constraint}> }>, impossible: Option<ImpossibleDetail>, incompatible: Vec<PythonMismatch{pkg, version, requiresPython, python}>, forced: Vec<HeldBack>, yanked: Vec<YankWarning{pkg, version, reason}> }`; the last three are omitted when empty. **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/` — `uv/` is uv 0.13's `error:`/`cause:` rendering, `uv-0.11/` the frozen miette one, and both are under test). Both read the **exit status first**: zero is a plan, an impossibility is `impossible`, and anything else is classified like every other engine failure. uv's adapter used to hand every outcome to the plan parser, so a failed build that still printed `Resolved 1 package` previewed as "no changes" (C3); pip's impossibility was a hard error that failed the whole preview where uv's offered a per-package *Skip* (H15).
- **What is not on the wire.** `raw` — what the engine wrote while resolving, now pip's stderr and uv's plan text — and `declared_python` — each planned release's `Requires-Python` as pip's report states it — are `#[serde(skip)]`, kept for the log ring and the flow's own check. `raw` used to cross IPC as pip's whole `--report` document, every package's README included, cloned into each `FlowStep` and printed by `--json`: 33 KB for two packages, megabytes for "update all" (H22).
- `incompatible`, `forced` and `yanked` are new in 1.4.0. `incompatible` is DATA-FLOW §2's Requires-Python screening, structured so the preview can show the range against the interpreter (invariant 4); `forced` is the "Will break" section DISCLAIMER §2 requires before anything runs; `yanked` is PD-PKG-003's preview warning, which both parsers had extracted and then dropped (`.map(|p| p.report)`), so it never showed.
- `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.
### Requires-Python is enforced by PipDock, not the engine
**Owner decision 2026-07-27 (spike SP-2).** The two engines disagree: `scipy==1.7.3` declares `Requires-Python >=3.7,<3.11`, and on Python 3.12 pip refuses it while uv plans to install it. Since G5 promises one behavior across heads, the preview must not change shape because the user flipped the engine radio — so `pipdock-core` evaluates `Requires-Python` itself in `src/compat.rs`, before any candidate reaches an engine command, and reports rejects as `PD-PKG-001` with the required range against the environment's version.
**Owner decision 2026-07-27 (spike SP-2).** The two engines disagree: `scipy==1.7.3` declares `Requires-Python >=3.7,<3.11`, and on Python 3.12 pip refuses it while uv plans to install it. Since G5 promises one behavior across heads, the preview must not change shape because the user flipped the engine radio — so `pipdock-core` evaluates `Requires-Python` itself, before any mutating engine command, and reports rejects as `PD-PKG-001` with the required range against the environment's version.
This does not violate "explain, don't reimplement" (§1.2): resolution is still entirely the engine's. `compat.rs` only filters candidates the engine should never have been offered, using a narrow slice of PEP 440 — the comparison, wildcard and compatible-release operators as they appear in `Requires-Python`. Specifiers it cannot parse are treated as **compatible**, because PipDock failing to read metadata must never be the reason an installable package is refused.
**Until 1.4.0 nothing did** (C2): this section described the decision, `PD-PKG-001` sat in the catalog, and no code path raised it. pip refused an incompatible exact pin with the "No matching distribution" it gives a typo, and uv — which honours a lower bound and ignores an upper one — planned `scipy==1.7.3` on Python 3.14 and failed at install time, building it from source. `UpdateFlow` now checks three places, with `src/compat.rs` evaluating the specifier each time:
1. **Exact pins the user typed** (`name==v`, `name===v`), before any engine sees them. A request that is nothing but such pins is `PD-PKG-001`; otherwise the pin is left out and listed in `report.incompatible`.
2. **Forced pins.** Forcing a latest release this interpreter cannot run is dropped from the force and listed the same way.
3. **Every change the engine planned.** pip's report carries each release's `requires_python`, so nothing is asked; uv's plan carries nothing, so PyPI is asked (`src/release.rs`). A violating release is ruled out as `name!=version` (`GuardAdjust.exclude`) and the engine asked again, at most `PYTHON_EXCLUDE_ROUNDS` (2) times — the engine, not PipDock, picks what comes next. Whatever still violates after that stays in the plan and is listed in `report.incompatible` as a warning.
`release.rs` reads `https://pypi.org/pypi/{name}/{version}/json` → `info.requires_python`, at most `LOOKUP_CONCURRENCY` (8) at once with a `LOOKUP_TIMEOUT` (15 s) each, and remembers every answer **forever** in the store's `release_meta` table (§6): an uploaded release's metadata never changes. A failure is not remembered, and is asked again next time. Not screened: a rollback's restore set, which reinstalls what was there (audit backlog N4).
This does not violate "explain, don't reimplement" (§1.2): resolution is still entirely the engine's. `compat.rs` only filters candidates the engine should never have been offered, using a narrow slice of PEP 440 — the comparison, wildcard and compatible-release operators as they appear in `Requires-Python` — and a release it rules out is excluded *by name* for the engine to resolve around. **Unknown never blocks**: a specifier it cannot parse, a release PyPI does not know (a private index), a lookup that is offline or slow — each is treated as **compatible**, because PipDock failing to read metadata must never be the reason an installable package is refused.
### 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.
`Settings.engine ∈ {pip, uv}`, pip by default; user can change any time. First run was specified to probe `uv --version` on PATH and preselect uv if present — **that is not implemented**: an empty store reads as pip (`Settings::default`), and detecting uv at first run is owed (PRD P0-9, audit backlog X19). The status bar always shows the active engine, read when the app starts rather than when Settings is first opened (1.4.0). 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:
Rust cannot cheaply read a foreign env's installed metadata. PipDock embeds a single-file, stdlib-only helper (`probe.py`, ~330 lines, no third-party imports) executed as `<env-python> -X utf8 -I <temp>.py --json` under a 60 s watchdog (`exec::watchdog::PROBE`), printing one JSON document, schema 3:
```json
{ "python": "3.12.4", "prefix": "...", "externally_managed": false,
"is_venv": true, "hidden_user_site": null,
{ "schema": 3, "python": "3.12.4", "implementation": "cpython",
"prefix": "...", "base_prefix": "...", "executable": "...",
"is_venv": true, "externally_managed": false, "hidden_user_site": null,
"markers": { "sys_platform": "win32", "platform_system": "Windows",
"python_version": "3.12", "python_full_version": "3.12.4", "...": "..." },
"dists": [ { "name": "requests", "version": "2.32.3",
"requires_dist": ["urllib3<3,>=1.21.1", "..."],
"requires_python": ">=3.8" } ] }
"requires_python": ">=3.8", "size_bytes": 131072 } ] }
```
`hidden_user_site` is non-null only when `-I` is actually hiding packages from the listing — see SECURITY §2 for the decision and the UI note it drives.
**`-X utf8` is not redundant.** `-I` implies `-E`, which ignores `PYTHONUTF8` and `PYTHONIOENCODING`, so the probe wrote through the ANSI code page: a venv under a folder named with Vietnamese diacritics crashed it with a `UnicodeEncodeError` (`PD-ENV-003`, reproduced) and a Latin-1 path came back as mojibake (H10). `-X` is a command-line option, which isolated mode honours. Schema 3 also reads each distribution's `METADATA` **once** — `dist.metadata`, then `dist.version` and `dist.requires`, had parsed it three times on the path every environment open pays (154 → 118 ms for 64 distributions on CPython 3.14).
From `requires_dist` the core builds the **reverse-dependency graph** used by: held-back attribution, uninstall guard, pin auto-suggest, and the dependency view (P1-6). 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).
**Markers are evaluated against the interpreter the probe ran in** (`ReverseDeps::for_probe`, which every production graph uses — held-back attribution in the update flow, the uninstall guard, `deps_graph`, pin suggestions). Until 1.4.0 only `python_version` and `python_full_version` were read and every other variable counted as unknown, which keeps a requirement in force: ipython's `pexpect; sys_platform != "win32"` made the dependency view report pexpect missing from every Windows environment with ipython, and the guard and suggestions counted an edge that does not exist there (H25). Platform variables compare as strings with `==`, `!=`, `in` and `not in`. Schema 3's `markers` is built from `sys` and `os`, not `platform`: `platform.uname()` is a WMI query on Windows (55 ms on 3.14) for `platform_release` and `platform_version`, which almost no requirement mentions — so those two are omitted on Windows, and a requirement that names them stays in force.
`ReverseDeps` holds **both directions** as of 1.3.0. The first three consumers each look exactly one edge out and only ever asked "who depends on this", so the forward map was never needed; the dependency view asks the other question. Both are built in the same pass from the same parse and filtered by the same `Requirement::applies_in`, and `edges_to` is a projection of `breaking_dependents` rather than a second walk — so the dependents column and the uninstall guard are the same set **by construction**. Two features applying two edge rules is the failure this module exists to prevent, and a second traversal is how it would happen.
**The graph crosses the bridge whole, once per environment** (`deps_graph` → `DepsGraph`), not a package at a time. The view re-centres on a click, so a per-package command would pay the probe again for each one; measured in `--release` on a 352-package environment, the probe is 605 ms while building the graph is 1.8 ms and computing every node's transitive counts is 43 ms, for a 249 KB payload. Nothing about which edges are in force is recomputed in the frontend — marker evaluation and extra-gating live in `graph/markers.rs`, and a JavaScript reimplementation would drift from the guard the user is warned by.
## 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.
- **Name index:** PyPI Simple Index in PEP 691 JSON form → SQLite (`index.db`, table `names(name, normalized)`), refreshed on request — nothing refreshes it on a timer; older than 7 days it is reported stale (`index::is_stale`; `pipdock search` says so). The download is parsed as a typed, borrowing document rather than a `serde_json::Value` of 700k objects, and ingested on a blocking thread; an empty project list is refused rather than ingested over the index (1.4.0). Fuzzy search runs in Rust (nucleo matcher) over an in-memory copy of the normalized column (SP-3), which the GUI loads in the background on a connection of its own: a search that arrives first answers `ready: false` and the screen asks again, rather than holding the store's lock for the 140 ms load (U35). 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 with verification always on; redirects may not leave `pypi.org` or `files.pythonhosted.org`. A TLS failure is recognised by reading the error's whole `source()` chain — reqwest's top-level message never mentions the certificate, so every TLS failure used to read as `PD-NET-001` and `PD-NET-002`'s proxy guidance never showed (M32).
- **Per-release `Requires-Python`** (`release.rs`, 1.4.0): `GET https://pypi.org/pypi/<name>/<version>/json`, for uv's plans and exact pins (§3), through one client shared by the process; remembered forever in `release_meta`.
- Offline: search still works over the cached index; metadata panel shows a cached/offline badge; a `Requires-Python` lookup that cannot be answered never blocks a plan.
## 6. Storage (`%LOCALAPPDATA%\PipDock\data\`)
```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
index.db # SQLite, schema v4: names, meta_cache, envs (recents, default),
# pins(env_hash, pkg, mode, version, reason), health_projects,
# kv (settings, consent, index refresh stamp), release_meta
snapshots/<env_hash>/<id>.freeze.txt + <id>.meta.json # id: 20261016T145809-423560600Z
tools/.venv/ # Code Health tools env (see CODE-HEALTH-SPEC)
logs/pipdock.<date>.log # tracing rolling files, 14-day retention
audit/.venv/ # the Security tab's pip-audit env (PRD P1-1), a sibling cleared separately
logs/pipdock.<date>.log, logs/pipdock-cli.<date>.log # one file per head per UTC day, 14 days
```
`env_hash` = SHA-256 of the canonicalized interpreter path. Snapshot `.meta.json` records trigger (which plan), engine, package count, and app version.
**There is no `config.json`.** This block listed one until 1.4.0; settings and the consent record have always been rows in `index.db`'s `kv` table (`settings::load`), because the store already exists, already handles concurrent access, and a second on-disk format is a second thing to migrate.
`env_hash` = SHA-256 of the canonicalized interpreter path, case-folded on Windows (SP-6). Snapshot `.meta.json` records trigger (which plan), engine, package count, and app version; the engine is what a rollback with the other engine reads (DATA-FLOW §8). Snapshot ids are fixed width, so they sort as the times they name — the timestamp with its punctuation swapped out used to trim its fraction, so `…09-42Z` sorted after `…09-4235606Z` — and the timeline orders by `created_at` either way (M43).
**The store migrates only when it is behind.** `user_version` is compared with `store::SCHEMA_VERSION` (4) and the batch runs only when the database is older: every open used to run it — a `journal_mode` write and eight `CREATE TABLE`s, on a store some paths open twice per lookup — and an older build set the version back down, so the next newer one re-ran them (M38). v4 added `release_meta(normalized, version, requires_python)`: a release's `Requires-Python` as PyPI publishes it, never refreshed because an uploaded release's metadata never changes. A NULL there means "declares none"; "unknown" is never stored.
**The log is new in 1.4.0.** `tracing` had been a dependency of three crates and was called nowhere, and `LOG_RETENTION_DAYS` had no reader. `core::logging` writes one file per UTC day, prefixed by head so the GUI and the CLI never interleave, at `PIPDOCK_LOG` or INFO: every spawn's argv, exit code and duration, every stop and its reason, each resolve's outcome, each snapshot, each run's counts or refusal, and the engine's own lines at DEBUG. Each head sweeps files older than `LOG_RETENTION_DAYS` (14) when it starts and never touches a file it did not name; a panic hook records a crash before the default hook prints it. Nothing is ever written to stdout — the CLI's `--verbose` adds stderr at DEBUG and `--log-file` a copy. The cache manager does not clear the log, and Settings shows where it is (`logs_tail`, §7).
The GUI opens the store **before Tauri starts**, so a data folder that cannot be opened is said in a native dialog — the code, the message and the log's path, in both languages, the one place GUI copy is written in Rust because no webview exists yet to load a catalog. It used to be opened in Tauri's `setup` hook, whose failure is a panic in the event loop; a release build has no console, so the user double-clicked and nothing happened (U18).
## 7. Tauri IPC surface
Commands return `Result<T, PdError>` where `PdError` carries a catalog code, and are `async` except `app_info`, which is a compile-time constant. Each is a **thin** wrapper over a `pipdock_core` function — a wrapper that starts making decisions is logic the CLI will not inherit, and G5 promises the two heads never diverge.
Commands return `Result<T, WireError>` — a `PdError` flattened to `{ code, message, stderrTail? }`, so it carries a catalog code and never the typed `stop` an engine run records — and are `async` except `app_info`, which is a compile-time constant. Each is a **thin** wrapper over a `pipdock_core` function — a wrapper that starts making decisions is logic the CLI will not inherit, and G5 promises the two heads never diverge.
This table is the surface. A command that is not listed here does not exist; adding one means amending this section in the same commit. It was written as a prose list of 26 with `a|b|c` groupings, which made the count ambiguous and let two Stage 1 additions land undocumented — hence the table.
| Command | Returns | Purpose |
|---|---|---|
| `app_info` | `AppInfo` | PipDock's version, and the hash of the legal documents this build ships against. |
| `env_scan` | `EnvRow[]` | Discover environments, streaming `scan-progress`. A probe failure is reported on its own row, never fatal to the scan. Carries `pipVersion` and `healthProject`, both read before the probe loop so the store guard is never held across a probe. |
| `env_add_manual` | `EnvRow` | Persist an interpreter chosen through *Browse…*. |
| `env_scan` | `EnvRow[]` | Discover environments, streaming `scan-progress`. A probe failure is reported on its own row, never fatal to the scan. Carries `pipVersion` and `healthProject`, both read before the probe loop so the store guard is never held across a probe. Probes run four at a time (they ran in series until 1.4.0), each under its own 60 s watchdog, so one hung interpreter costs its own row; rows keep discovery order. |
| `env_add_manual` | `EnvRow` | Persist an interpreter chosen through *Browse…*. **Not implemented** — the one entry left in `NOT_YET` (`src-tauri/src/lib.rs`), owed by M3. |
| `env_probe` | `EnvRow` | Probe one interpreter without persisting it. Takes an optional `source`: absent means *Browse…*, and a **refresh must pass the row's own**, or the row comes back relabelled `manual`. Fills every field `env_scan` does, because `upgradePip` replaces the row wholesale. |
| `env_export` | `string` | Write the environment's `Engine::freeze` document to a user-chosen path and return it (PRD P1-3). Byte for byte, with no formatter: a freeze *is* a requirements file, and a constraints file is the same body under a different name. Rust-side for `health_save_report`'s reason — `dialog:allow-save` asks for a path and grants no `fs`. |
| `requirements_read` | `ParsedRequirements` | Read a `requirements.txt` into install specs **and whatever it could not use**. The skipped lines are the point: an include or an editable install means the file asks for something PipDock will not do, and the user has to see that before a preview claims to represent their file. |
| `pkg_list` | `Dist[]` | Installed distributions, read from `probe.py` rather than the engine — see §4 and DATA-FLOW §7. |
| `pkg_outdated` | `OutdatedDist[]` | Outdated distributions, via the configured engine. |
| `index_search` | `Hit[]` | Fuzzy search over the in-memory name index. |
| `index_search` | `SearchResults` | Fuzzy search over the in-memory name index: `{ hits: Hit[], ready, unavailable? }`. A struct, not the `Hit[]` this row said, because "no such package" and "the index is still loading" are different answers. Never blocks on the load: the first search starts it in the background and answers `ready: false`, and the screen asks again. A load that failed — most often, an index never downloaded — is reported in `unavailable` and **not** retried by the next search, only by a refresh; retrying reset it to warming before the reason could be read, and Search showed "preparing" for ever on a fresh profile. |
| `index_refresh` | `RefreshReport` | Re-download the PEP 691 name index. |
| `pkg_metadata` | `PackageMeta` | Cached PyPI metadata for the details panel, with its freshness. |
| `plan_resolve` | `FlowStep` | Begin an update or install flow: dry-run resolve, then derive held-back items. |
| `plan_decide` | `FlowStep` | Apply the user's 3-way conflict decisions and re-resolve. |
| `plan_execute` | `ExecutionOutcome` | Take the snapshot, then run the two-phase execution (§8). Returns the summary **and** the snapshot meta: the CLI prints the id before execution and the summary sheet needs it afterwards to offer the rollback, so one envelope beats a second command to go and look it up. |
| `plan_cancel` | `bool` | Stop the session, and say whether there was one. A *parked* flow counts and is discarded — it has no process to kill, and leaving it refuses the next plan on behalf of a preview nobody is looking at. |
| `pkg_metadata` | `[PackageMeta, Freshness]` | Cached PyPI metadata for the details panel, and how fresh it is (`fresh`, `cached`, `stale`) — a tuple on the wire, which this row used to write as `PackageMeta` alone. |
| `plan_resolve` | `FlowStep` | Begin an update or install flow: probe, PEP 668 gate, dry-run resolve, then derive held-back items. The cancellation token it registers is **the flow's own**, handed in before the first resolve, so *Stop* reaches that resolve — the one it registered used to be a fresh token nothing listened to (H13). A stopped resolve answers `{ step: "nothing", reason: "cancelled" }`. |
| `plan_decide` | `FlowStep` | Apply the user's 3-way conflict decisions and re-resolve. The flow stays parked whether or not the round succeeds: a failed re-resolve leaves it exactly as it was, so the preview on screen can still be decided or confirmed — it used to be dropped, leaving a Confirm that answered "no plan" (U24). |
| `plan_execute` | `ExecutionOutcome` | Take the snapshot, then run the two-phase execution (§8). The environment is probed again first, and a preview older than ten minutes or no longer describing the environment is refused with `PD-RES-002` before the snapshot is written (DATA-FLOW §9.3). Returns the summary **and** the snapshot meta: the CLI prints the id before execution and the summary sheet needs it afterwards to offer the rollback, so one envelope beats a second command to go and look it up. |
| `plan_cancel` | `bool` | Stop the session, and say whether there was one — a resolve as well as an execution. A *parked* flow counts and is discarded — it has no process to kill, and leaving it refuses the next plan on behalf of a preview nobody is looking at. |
| `uninstall_guard` | `GuardReport` | Reverse-dependency check over a removal set, parking the flow that would run it. Called **again** with `withDependents` for DATA-FLOW §5's *Remove dependents too*, so a dependent of a dependent surfaces on the next pass. |
| `uninstall_execute` | `ExecutionOutcome` | Snapshot, then remove. Takes `force` — §5's *Force remove only X*; without it a removal the guard objected to is refused with `PD-RES-004` before the snapshot is written. |
| `uninstall_execute` | `ExecutionOutcome` | Snapshot, then remove. Takes `force` — §5's *Force remove only X*; without it a removal the guard objected to is refused with `PD-RES-004` before the snapshot is written, and the flow stays parked, so the dialog's *Force remove* is still a choice rather than a button answering "no plan". The environment is probed again before the snapshot: a package installed since the guard ran may depend on what is about to go, so a changed environment is `PD-RES-002` (M44). |
| `pin_list` | `Pin[]` | Pins for an environment. |
| `pin_add` | `()` | Add or replace a pin. |
| `pin_remove` | `bool` | Remove a pin; reports whether one existed. |
@@ -141,27 +192,29 @@ This table is the surface. A command that is not listed here does not exist; add
| `snapshot_list` | `SnapshotMeta[]` | Snapshots for an environment, newest first. Takes the `env_hash`, not a `PyEnv`: snapshots outlive the interpreter that made them, and an environment whose Python is gone still has a history worth showing. |
| `snapshot_create` | `SnapshotMeta` | Take a snapshot on demand, outside any plan. |
| `snapshot_diff` | `Diff` | The environment against a snapshot. Claims no session — browsing a timeline must not start a flow. |
| `snapshot_rollback_preview` | `RollbackPreview` | What restoring a snapshot would do, parking the flow that would do it. Split from the execute for the reason `plan_resolve` is: what the user confirms must be the plan they were shown. |
| `snapshot_rollback` | `ExecutionOutcome` | Restore the parked snapshot — itself snapshotted first, per DATA-FLOW §8, which is why the outcome always carries one. |
| `snapshot_rollback_preview` | `RollbackPreview` | What restoring a snapshot would do, parking the flow that would do it. Split from the execute for the reason `plan_resolve` is: what the user confirms must be the plan they were shown. Gated on PEP 668 like every mutating flow — the rollback flow had no gate at all until 1.4.0 (H12). |
| `snapshot_rollback` | `ExecutionOutcome` | Restore the parked snapshot — itself snapshotted first, per DATA-FLOW §8, which is why the outcome always carries one. The freeze taken for that snapshot must match the one the preview was diffed against, or the restore is refused with `PD-RES-002` and nothing is written. |
| `health_run` | `HealthReport` | Run the Code Health tools against a project folder. **Not `CheckReport`** — that name is taken by `engine.check()` and is already a published `pipdock schema` contract, so two unrelated shapes would have shared one name on the wire. |
| `health_fix` | `FixReport` | Apply the gated `ruff` fix (P5). **Not `ExecutionSummary`** — there is no plan, no phase and no per-package counts in a fix, and inventing them would be four lies for one operation. Same correction §7 needed for `pip_upgrade`. |
| `health_fix` | `FixReport` | Apply the gated `ruff` fix (P5). **Not `ExecutionSummary`** — there is no plan, no phase and no per-package counts in a fix, and inventing them would be four lies for one operation. Same correction §7 needed for `pip_upgrade`. Its argv is the read-only run's plus `--fix`, so it rewrites only what the report covered: it ran `check . --fix` with none of the preview's exclusions until 1.4.0, and rewrote every notebook in the tree (C4, DATA-FLOW §9.1). |
| `health_dirty` | `number \| null` | Uncommitted entries in the parked report's project, so the fix confirm can name one. `null` means no repository, no git, or git failed — a courtesy, not a precondition. Asked again inside `health_fix`: this decides what to render, that decides what to allow. |
| `health_save_report` | `string[]` | Write a finished report as Markdown **and** JSON beside a user-chosen path, returning both. Rust-side rather than a filesystem capability: `dialog:allow-save` lets the webview ask for a path and nothing more. |
| `audit_run` | `AuditReport` | pip-audit over an environment (PRD P1-1). Takes the freeze itself, because pip is invoked with `--all` and uv is not, so the configured engine changes what is audited. Syncs its **own** venv on first use — a `msgpack` wheel gap fails this and leaves Code Health working. pip-audit failing is not an error: it lands in `problems` and the report still returns. |
| `audit_cancel` | `bool` | Stop a running audit, reporting whether there was one. Exists where `health_run` has no equivalent because an audit is **18-68 s** rather than 1.3 s, dominated by a one-off advisory-database fetch. A cancel is a *state* on the report, never `PD-INT-001`. |
| `audit_run` | `AuditReport` | pip-audit over an environment (PRD P1-1). Takes the freeze itself, because pip is invoked with `--all` and uv is not, so the configured engine changes what is audited. Only the freeze's `name==version` pins reach pip-audit: an editable install or a direct reference, which no index can answer for, failed the whole audit until 1.4.0 (H21). Syncs its **own** venv on first use — a `msgpack` wheel gap fails this and leaves Code Health working. pip-audit failing is not an error: it lands in `problems` and the report still returns. |
| `audit_cancel` | `bool` | Stop a running audit, reporting whether there was one. Exists where `health_run` has no equivalent because an audit is **18-68 s** rather than 1.3 s, dominated by a one-off advisory-database fetch. A cancel is a *state* on the report, never `PD-INT-001`. `audit_run` registers its token before anything slow, so a Stop during the freeze is honoured — it was registered after, and such a Stop did nothing (U37). |
| `audit_save_report` | `string[]` | Write a finished audit as Markdown **and** JSON beside a user-chosen path, returning both. `health_save_report`'s shape, for its reasons: `dialog:allow-save` asks for a path and grants no `fs`, and the report comes from the frontend because what the user asked to save is what is on their screen. |
| `engine_info` | `EngineInfo[]` | Detected version and availability per engine. Settings shows both, so this returns both. |
| `engine_info` | `EngineInfo[]` | Detected version and availability per engine, for one environment — pip's version is that environment's pip. Settings shows both, so this returns both. The wrapper had no caller until 1.4.0, when Settings began showing the version beside each engine radio for the selected environment. |
| `pip_upgrade` | `StepResult` | Upgrade pip itself in the selected environment. **Not `ExecutionSummary`** — there is no plan, no phase and no per-package counts, and inventing them would be four lies for one step. Carries no versions either (`from`/`to` are always absent): the caller re-probes, which it must do anyway to refresh the row. |
| `settings_get` | `Settings` | Read stored settings. |
| `settings_set` | `Settings` | Persist settings, returning what was actually stored rather than what was sent. |
| `cache_usage` | `Usage` | What PipDock has written to its own data directory (PRD P1-4). Never fails as a whole; an unreadable path reports zero bytes. |
| `cache_clear` | `number` | Delete one cache target, resolving to the bytes freed. Takes a `Target` **enum, never a path** — `cache::clear` is the only thing that turns one into a directory. `index.db` is deliberately not a target: it holds settings, pins and the consent record as well as the package index, and *clear the cache* must never take a user's pins. |
| `cache_clear` | `number` | Delete one cache target, resolving to the bytes freed. Takes a `Target` **enum, never a path** — `cache::clear` is the only thing that turns one into a directory. `index.db` is deliberately not a target: it holds settings, pins and the consent record as well as the package index, and *clear the cache* must never take a user's pins. Holds the slot of the feature that owns the target — the mutation slot for snapshots, Health's for the tools venv, the Security tab's for the audit venv — so a clear is refused with `PD-RES-003` while that feature runs instead of deleting the venv it is executing from; a session merely parked there is put back (U36). The deletion runs on a blocking thread. |
| `legal_consent_get` | `ConsentState` | Whether the legal gate can be skipped for this build's documents. |
| `legal_consent_set` | `Consent` | Record acceptance. |
| `logs_tail` | `LogTail` | The end of PipDock's own log files (`data\logs\`, kept `LOG_RETENTION_DAYS`) and the folder they are in, for Settings' Logs row. Never fails: no log yet is an empty tail. |
| `report_bug_url` | `string` | Prefilled GitHub issue URL (ERROR-CATALOG §4). Built in Rust so it cannot drift from `pipdock self report-bug`. **Nothing is ever sent automatically.** |
| `report_bug_url` | `BugReportLink` | `{ url, log }`: the prefilled GitHub issue URL (ERROR-CATALOG §4) and the whole log ring for *Copy full log* — two fields, not the `string` this row said, because §4.3 splits the truncated excerpt from the full log. Takes an optional environment and code; given the environment, the URL carries its Python and the engine's version (U31). Built in Rust so it cannot drift from `pipdock self report-bug`. **Nothing is ever sent automatically.** |
Events (Tauri event channel): `plan-progress` streams live subprocess output to the in-app console; `scan-progress`; `health-progress`.
Events (Tauri event channel, the closed set `EVENTS` in `ui/src/ipc/index.ts`): `plan-progress` streams live subprocess output to the in-app console; `scan-progress` (`ScanProgress`, one per discovery source); `health-progress` and `audit-progress`, which carry `plan-progress`'s `ProgressEvent` lifecycle for a tools-venv sync and the tool runs. `audit-progress` shipped with the Security tab in 1.2.0, and this line did not name it until 1.4.0.
**What the webview may call besides these commands is exact.** `src-tauri/capabilities/` grants seven permissions — `core:event:allow-listen` and `-unlisten` for the four channels, `core:window:allow-close` for the legal gate's *Decline*, `dialog:allow-open` and `dialog:allow-save` (both only ask for a path; no `fs` permission exists), `clipboard-manager:allow-write-text`, and `opener:allow-open-url` scoped to four hosts — and `the_webview_is_granted_exactly_what_it_calls` in `src-tauri/src/lib.rs` pins the set. `core:default` stood there until 1.4.0: it granted some sixty core commands nothing called and not `allow-close`, so *Decline* did nothing in the installed app while its component test, which mocks `close()`, passed (U1, U32).
`plan-progress` carries a **tagged lifecycle**, not a bare line — amended in S3, where the console drawer and the live region were first built:
@@ -173,41 +226,50 @@ Events (Tauri event channel): `plan-progress` streams live subprocess output to
It was originally specified as `{ step, pkg, phase, line }`, which made both of those features unimplementable: there was no event meaning "a step began" to group a section under, and none meaning "one finished" to count. Neither is recoverable from the text — engine output does not reliably name the package it concerns, and counting lines is not counting steps. Every step now emits exactly one `stepStarted`, any number of `line`s, and exactly one `stepFinished`, whichever way it ended. `stream` distinguishes stdout from stderr, which matters for uv in particular: uv writes its **plan** to stderr (SP-1), so stderr does not mean failure.
**One mutation session at a time, across all of them.** Update, install, uninstall and rollback share a single slot, so a second one is refused with `PD-RES-003` rather than allowed to interleave engine commands against the same environment. The commands that resume a session (`plan_decide`, `plan_execute`, `uninstall_execute`, `snapshot_rollback`) name the flow they expect and get `PD-INT-001` if a different one is parked — a frontend sequencing bug, reported as one instead of running the wrong plan.
**One mutation session at a time, across all of them.** Update, install, uninstall and rollback share a single slot, so a second one is refused with `PD-RES-003` rather than allowed to interleave engine commands against the same environment. The commands that resume a session (`plan_decide`, `plan_execute`, `uninstall_execute`, `snapshot_rollback`) name the flow they expect and get `PD-INT-001` if a different one is parked — a frontend sequencing bug, reported as one instead of running the wrong plan. Health and the Security tab each have a slot of their own, and `cache_clear` borrows whichever owns its target.
Long operations are cancellable: `plan_cancel` trips the plan's token, which kills the child **and its whole process tree** (a Windows Job Object — `python -m pip` spawns build backends), and remaining steps are reported `Skipped` with `ExecutionSummary.cancelled` set. Already-completed steps stay applied; the snapshot covers full revert.
**A claimed slot releases itself.** A claim is a guard that frees the slot when it is dropped unless it was parked first (1.4.0, U4). Release used to be a call every exit path had to remember, and `plan_resolve`, `uninstall_guard` and the rollback preview each had a `?` between claim and release: one failed settings read left the slot `Busy`, and every later plan answered `PD-RES-003` until a restart. The slot is a `std` mutex, held only to swap a value, so the drop can take it.
Long operations are cancellable: `plan_cancel` trips the plan's token, which kills the child **and its whole process tree** (a Windows Job Object — `python -m pip` spawns build backends). The token is the flow's own from the first resolve (`FlowOptions.cancel`), so a stopped resolve ends as a `nothing` step with reason `cancelled`; a stopped run reports its remaining steps `Skipped` with `ExecutionSummary.cancelled` set — during Phase A as much as Phase B, where Phase A used to surface as `PD-INT-001` with no summary (C5). Already-completed steps stay applied; the 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.
1. **Phase A — batch fast path:** one engine invocation installing the full pinned set, with everything installed that the plan does not touch held at its current version by `-c`. Fast (especially uv) and atomic-ish. If it exits 0 → done. **Its failure is an outcome, never an abort:** a Stop marks every row `Skipped` with `cancelled` set; a failure that is the *environment's* rather than one package's — the network, a read-only site-packages, a full disk, a missing or too-old engine, the watchdog, an interpreter that is gone or managed (`plan::isolates`) — fails every row with the batch's code, the stderr tail on the first row only, and skips Phase B, which would meet the same wall N times after pip's own retry backoff. Until 1.4.0 the adapters' `Err` for a stop, a watchdog or a spawn failure went out of `execute` through a `?` as `PD-INT-001`, with no summary and no rollback offer (C5).
2. **Phase B — isolation pass:** on any other Phase-A failure, re-run per package sequentially in resolver-report order, collecting individual `StepResult`s. Each step installs one pin with the rest of the plan at its planned versions and the untouched set at its current ones as `-c` — it ran a bare `<engine> install pkg==ver`, free to move a dependency past an installed package's bound, which pip only warns about (H16). 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. A check that could not run is `ok: false` with its code in `CheckReport.error` — it reported `ok: true`, "verified" exactly when nothing was, such as after a run that broke pip (M30).
Uninstalls are always sequential (cheap) with the reverse-dep guard evaluated once up front against the full removal set.
Every row says what it moved **from** (`StepResult.from`, taken from the plan's changes — the engines cannot know it, so every upgrade used to read as a fresh install). The summary's `planId` is the flow's for an update or install — the same id its snapshot's trigger records, unique per plan (M31: the snapshot said `update-<env>` for every plan an environment ever had) — and the pre-execution snapshot's id for a removal or a rollback.
**Requirement files, not argv.** Every plan restates the whole installed set (SP-1), and as one argv entry per package that passes Windows' 32 767-character command line at about 1 300 packages: the spawn failed with os error 206 and the user was told to install an engine (H20). `engine::RequirementFiles` writes the requirement lines and the constraints to `-r`/`-c` temp files under fresh random names, created with `create_new` and deleted on drop (`exec::TempFile`), holding exactly the tokens argv held. pip names a requirement read from a file `-r <path> (line N)`, so its messages are rewritten back to the line's own text (`RequirementFiles::humanize`) before they are parsed or shown.
**Watchdogs are per kind of work** (`exec::watchdog`): install and uninstall 30 min, a resolve and `list --outdated` 10 min, local queries (`list`, `freeze`, `check`, `--version`) 3 min, `probe.py` 60 s, the discovery listings (`py -0p`, `uv python list`) 30 s. One 600 s budget used to cover everything, which held the Environments screen for ten minutes on a hung `py -0p` and killed a slow scipy build. A fired watchdog is `PD-ENG-004`, and a stopped run says why in its type — `PdError.stop` is `Cancelled` or `TimedOut`, never on the wire — rather than in a message prefix three modules used to match. A spawn failure maps by cause: a missing interpreter is `PD-ENV-001`, a command line Windows refuses as too long `PD-SYS-001`, anything else `PD-ENG-001`. Output is read as bytes and decoded lossily: tokio's `lines()` stopped at the first non-UTF-8 byte — MSVC prints in the OEM code page — and dropped the pipe, killing the child mid-install.
Uninstalls are always sequential (cheap) with the reverse-dep guard evaluated once up front against the full removal set. A rollback removes what the snapshot does not have, then restores what it does, one package at a time in `Isolated` mode — exactness is the whole job, and a batch resolve is free to pick another version — each restore holding the rest of the restore at the snapshot's versions with `-c`. It no longer runs `pip check` between its removals and its restores.
## 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. **This section originally specified `specta`/`tauri-specta` and that is not what shipped:** `ui/src/ipc/generated.ts` comes from a first-party `xtask` over `schemars`, which makes drift a *test* failure rather than a compile error. `crates/pipdock-core/src/bindings.rs` records why — specta 2 is still `2.0.0-rc`, and a second derive stack over ~40 types was not worth it — and names the condition for revisiting. No component calls `invoke` directly. i18next with `en`/`vi` JSON catalogs (see I18N.md). Styling via Tailwind 4 tokens defined in UI-SPEC.
Zustand stores: `useEnvStore`, `usePlanStore`, `useIndexStore`, `useSettingsStore`, `useHealthStore`, `useSecurityStore`, `useDepsStore`, `useLegalStore`, `useUiStore`. **An answer is applied only if it still answers the question being asked** (1.4.0): a store that fetches per environment checks, after each await, that the environment is still the selected one — the plan store, that its generation is still current — because a slow answer for an environment the user had just left used to land on the one they switched to, and a plan the user had backed out of re-opened its panel (`ui/src/stores/races.test.ts`). All engine data enters via typed IPC wrappers (`ui/src/ipc/*.ts`) mirroring the Rust types. **This section originally specified `specta`/`tauri-specta` and that is not what shipped:** `ui/src/ipc/generated.ts` comes from a first-party `xtask` over `schemars`, which makes drift a *test* failure rather than a compile error. `crates/pipdock-core/src/bindings.rs` records why — specta 2 is still `2.0.0-rc`, and a second derive stack over ~40 types was not worth it — and names the condition for revisiting. 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)
## 10. Version manifest (verified 2026-10-17 for 1.4.0, against `rust-toolchain.toml`, `Cargo.lock` and `package-lock.json`)
| Component | Version policy |
|---|---|
| Tauri | 2.10.x (latest 2.x line). **No `tauri-plugin-updater`** — PipDock does not update itself (SECURITY §5) |
| Rust | latest stable toolchain, pinned via `rust-toolchain.toml` |
| React / TypeScript | 19.x / latest stable |
| Vite / Tailwind | 8.1.x (Rolldown line) / 4.x |
| Tauri | 2.12.x (2.12.4; `tauri-build` 2.7.3), **in lockstep with `@tauri-apps/*` 2.12** — Tauri's own version check requires the crate and the npm package to agree, and CI's `tauri lockstep` job fails when `Cargo.lock` and `package-lock.json` drift apart. **No `tauri-plugin-updater`** — PipDock does not update itself (SECURITY §5) |
| Rust | 1.99.1, pinned via `rust-toolchain.toml`; the workspace's `rust-version` (1.99) moves with the pin, so it never claims a floor it is not built with |
| React / TypeScript | 19.x (19.3.1) / see the TypeScript row |
| Vite / Vitest / Tailwind | 8.x (8.3.4, Rolldown line) / 5.x (5.0.5) / 4.x (4.3.3) |
| 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.11.x line at writing); **minimum 0.10.0**, pinned by SP-1 (`UV_MIN_VERSION`, `engine/mod.rs`) |
| reqwest / tokio | 0.13.x (0.13.5; rustls, no native TLS) / 1.x (1.53.3) |
| pip engine | ≥ 24.0 supported; latest is 26.2.x (the fixtures are 26.2.1). `--dry-run --report` requires ≥ 22.2 — PipDock offers to upgrade older pips before first plan. |
| uv engine | latest stable (0.13.x; the fixtures are 0.13.1, whose `error:`/`cause:` rendering replaced miette's, with 0.11's kept as a frozen corpus); **minimum 0.10.0**, pinned by SP-1 (`UV_MIN_VERSION`, `engine/mod.rs`) — a declared floor nothing enforces yet (audit backlog) |
| Managed Pythons | 3.10 – 3.14 (3.9 is EOL) |
| Windows | 10 (1809+) / 11; WebView2 Evergreen assumed present; `longPathAware` manifest enabled |
| rusqlite | **held at 0.37** (`libsqlite3-sys` 0.35). 0.40 pulls `libsqlite3-sys` 0.38.1, whose build script uses the unstable `cfg_select!` and therefore does not compile on stable Rust 1.94.1. Revisit when the toolchain advances. |
| TypeScript | **held at 6.0.x.** 7.x is latest, but `typescript-eslint` peers on `>=4.8.4 <6.1.0`; taking 7 breaks `npm run lint`. Revisit when typescript-eslint supports TS 7. |
| ESLint | **10.x, with `eslint-plugin-react` deliberately absent.** That plugin caps at ESLint 9, which drags in a `minimatch`/`brace-expansion` chain carrying six high-severity advisories and would fail `npm audit` in CI. The one rule it was wanted for — no hardcoded JSX strings (I18N §1) — is a local rule in `eslint.config.js`, which also implements the documented allowlist precisely. |
| rusqlite | 0.40.x (0.40.2; `libsqlite3-sys` 0.38.2, SQLite 3.53.2). **Held at 0.37 until 1.4.0**: `libsqlite3-sys` 0.38's build script used the then-unstable `cfg_select!`, which did not compile on Rust 1.94.1. It is stable since 1.95, so the toolchain move met the hold's own condition. Nothing here used the `u64`/`usize` `ToSql` impls (off by default since 0.38) or `prepare_cached` (optional since 0.38). |
| TypeScript | **held at 6.0.x** (6.0.3). `typescript-eslint` 8.71.2 peers on `>=4.8.4 <6.1.0`, so anything from 6.1 on — 7.x included — fails `npm ci` with `ERESOLVE` before a single check runs. Revisit when typescript-eslint widens its range. |
| ESLint | **10.x (10.12.0), with `eslint-plugin-react` deliberately absent.** That plugin caps at ESLint 9, which drags in a `minimatch`/`brace-expansion` chain carrying six high-severity advisories and would fail `npm audit` in CI. The one rule it was wanted for — no hardcoded JSX strings (I18N §1) — is a local rule in `eslint.config.js`, which also implements the documented allowlist precisely. |
**Dependabot will keep proposing the held versions.** Each hold above is a compile or lint failure, not a preference, so those PRs are closed rather than merged until the stated condition changes. `cargo audit` informational advisories are handled separately in `.cargo/audit.toml` (SECURITY §7).
**TypeScript is the one hold left, and Dependabot no longer proposes it:** `.github/dependabot.yml` ignores `typescript >=6.1.0`, with the reason beside the rule. A hold is a compile or install failure, not a preference, so such a PR would be closed rather than merged until the stated condition changes. `cargo audit` runs with `--deny warnings`, so a new informational advisory fails CI unless `.cargo/audit.toml` records why it is tolerated (SECURITY §7).
Dependabot + `cargo audit` + `npm audit` in CI keep this table honest (RELEASE-CI.md §2).
Dependabot + `cargo audit` + `cargo deny` + `npm audit` in CI, and both audits daily against `main` (`security-scan.yml`), keep this table honest (RELEASE-CI.md §2).
+230 -54
View File
@@ -3,8 +3,9 @@
`docs/CLI-SPEC.md` is the contract: every flag, every exit code, every JSON shape. This is the
guide — what you actually type, in the order you would need it.
Everything here was run against `pipdock 1.1.0` on Windows. Where a number or a code appears, it
came out of a real invocation, not out of the spec.
Written by running `pipdock` on Windows, and kept to what the code does as the CLI changed: where a
number or a code appears, it came out of a real invocation or out of the code that produces it, not
out of the spec.
---
@@ -30,17 +31,29 @@ pipdock --version
**`--env <PATH>`** picks the interpreter. It accepts either the interpreter itself
(`C:\proj\.venv\Scripts\python.exe`) or the environment directory (`C:\proj\.venv`). Omit it and
PipDock uses the last environment you selected, falling back to a `.venv` in the working directory.
PipDock uses the default you set with `pipdock env use`, falling back to a venv in the working
directory — `.venv`, `venv`, `env` or `.env`, in that order. Choosing an environment in the GUI
does not change what the CLI acts on.
**`--json`** switches to machine-readable output. Streaming commands emit NDJSON — one JSON
document per line — so a long update can be consumed as it runs rather than at the end.
**`--json`** switches to machine-readable output: **exactly one JSON document on stdout**, whatever
the command, so `pipdock install requests --json | ConvertFrom-Json` works. Prompts, warnings,
progress and the engine's own output go to stderr. A failure prints a one-line envelope instead —
`{"code":"PD-ENV-001","message":"…","stderrTail":null}`. Ignore `--help`'s "NDJSON for streaming
commands": no command has ever emitted NDJSON, and until 1.4.0 `install` and `update` printed two
documents — the preview, then the summary — which is exactly what made that pipe fail. CLI-SPEC §6
lists which document each command prints, and the few paths that print none.
Two more worth knowing early:
- **`-y` / `--yes`** assumes the default answer at every prompt. Conflicts resolve to **skip**,
never to force. There is deliberately no flag that makes `--yes` mean "force latest".
- **`-y` / `--yes`** assumes the default answer at every prompt: a held-back package keeps its
compatible version and an impossible one is skipped. `--yes` on its own never forces anything —
see `--strategy latest` below for what does. Off a terminal, a command that would ask first
refuses instead unless you pass it; `uninstall` and `pip-upgrade` never ask.
- **`--engine pip|uv`** overrides the configured engine for one invocation, without changing your
setting.
setting. `pip-upgrade` ignores it: upgrading pip is pip's job, whatever is configured.
The logging flags — `--verbose`, `--log-file`, `--quiet` — are under
[When something goes wrong](#when-something-goes-wrong).
---
@@ -50,8 +63,8 @@ Two more worth knowing early:
pipdock env list
```
Discovery covers venvs in the working directory, the PEP 514 registry and the `py` launcher. Real
output on a machine with two registry Pythons:
Discovery covers venvs in the working directory, the PEP 514 registry, the `py` launcher and
`uv python list`. Real output on a machine with two registry Pythons:
```json
[
@@ -70,7 +83,7 @@ output on a machine with two registry Pythons:
**`hiddenUserSite` is not an error.** PipDock reads a non-venv Python in isolated mode, which skips
the per-user site-packages directory — so its package count can be lower than `pip list`. The field
is non-null exactly when that applies, and null inside a venv. See CLI-SPEC §7.
is non-null exactly when that applies, and null inside a venv. See SECURITY §2.
**`venv_scan` matches exactly four directory names**: `.venv`, `venv`, `env`, `.env`. A virtual
environment called anything else is invisible to `env list`, and you have to name it with `--env`.
@@ -81,6 +94,10 @@ Make one the default so you can stop typing `--env`:
pipdock env use C:\proj\.venv
```
Every later command acts on it — `--env` still wins for one invocation, and the working directory's
venv is only the fallback. If its interpreter goes away, commands say so on stderr and fall back to
the working directory's venv. Until 1.4.0 `env use` stored the default and nothing read it.
---
## Looking before you touch anything
@@ -98,7 +115,19 @@ pipdock doctor
```
`doctor` checks the engine, the interpreter and the environment's sanity, and **exits 1 when it
finds real problems** rather than 0 with a warning. That is what makes it usable as a gate.
finds real problems** rather than 0 with a warning. That is what makes it usable as a gate. The
engine it judges is the one that would run — `--engine`, else your configured one — so a uv-only
venv (`uv venv` makes them without pip) passes under uv. Whether Code Health's tools environment
has been built is reported, and never fails it.
```powershell
pipdock engine
pipdock engine uv
```
`engine` shows both engines and their versions, and needs no environment — without one, pip, which
lives inside an interpreter, reads `no environment selected`. It does not say which engine is
configured. `pipdock engine uv` sets it, and refuses an engine that is not installed.
---
@@ -115,18 +144,41 @@ pipdock update requests urllib3
pipdock update --all --dry-run
```
Every mutating command runs the engine in dry-run first, prints what would change, takes a
snapshot, and only then executes. `--dry-run` stops after the first step.
`update` and `install` run the engine in dry-run first, ask about any conflict, print what would
change and ask once more; only then do they check that the preview still describes the
environment, take a snapshot and execute. `--dry-run` stops at the preview. `pipdock update` with
neither names nor `--all` is a mistake rather than an empty plan, and exits 2.
A preview is good for **ten minutes**, and for the environment it was made against. Confirm later
than that, or after something else changed the environment, and the run is refused with
`PD-RES-002` (exit 2) before the snapshot is written — nothing has happened; re-run the command.
### When a version conflict appears
On a terminal, each held-back package is a question — *Compatible* (the default), *Skip* or *Force
latest* — asked on stderr before the preview, with the installed packages holding it back.
CLI-SPEC §4 has the exact prompt. An impossible set is never a question: its packages are skipped,
and with `--yes` or off a terminal the engine's explanation is printed on stderr first.
```powershell
pipdock update --all --strategy compatible # default: take the resolver's compatible version
pipdock update --all --strategy latest # force the latest, breaking whatever depends on it
```
`--strategy latest` off a TTY requires an explicit acknowledgement — it will not silently break an
environment because a script passed `--yes`.
`--strategy latest` forces only where nothing is asked — with `--yes`, or off a terminal. Then every
held-back package goes to its latest, and the preview's *Forced — will break* section names each
installed package that stops being satisfied, with the requirement of its that is overridden. On a
terminal it changes nothing: each package is still a question, and Enter still means *compatible*.
Off a terminal nothing runs without `--yes` anyway, so for a script the acknowledgement *is*
`--yes` — and under `--json --yes` no preview is printed at all, so read `forced` from a
`--dry-run --json` first. Until 1.4.0 forcing forced nothing: the decision was recorded and the
resolve ignored it.
Updating one package on its own can hold it back with no culprit — the preview says *(nothing
installed explains this)* — when its new release needs a newer version of one of its own
dependencies, because a selective update keeps every package it does not name where it is.
`update --all` is unaffected, and `--strategy latest` works around it (ROADMAP's audit backlog,
BL-1).
### Excluding things for one run
@@ -134,7 +186,8 @@ environment because a script passed `--yes`.
pipdock update --all --except black,mypy
```
`--except` is additive on top of the pin list; it does not replace it.
`--except` is additive on top of the pin list; it does not replace it. It takes a comma-separated
list, and can be repeated.
---
@@ -143,10 +196,13 @@ pipdock update --all --except black,mypy
```powershell
pipdock install requests
pipdock install "django==5.0.1"
pipdock install "django>=5.0,<6"
pipdock install requests --dry-run
```
Specs are `name` or `name==version`. Names are validated against PEP 508 and versions against PEP
A spec is a name, optionally followed by a PEP 440 specifier set — a range included. Extras,
markers and URLs are refused (`PD-PKG-002`). `--help` still says `name` or `name==version`, which
was the whole grammar until 1.4.0. Names are validated against PEP 508 and specifiers against PEP
440 **before** they reach a command line — PipDock never builds a shell string, so there is nothing
for a crafted package name to escape into.
@@ -155,14 +211,58 @@ pipdock uninstall requests
```
Removal runs the reverse-dependency guard first. If something still needs the package, the command
**stops and exits 2** rather than removing it. `--force` proceeds anyway, and prints what will
break before it does.
**stops and exits 2** rather than removing it, and prints the `pipdock uninstall` line that would
remove the dependents too. `--force` proceeds anyway, and prints what will break before it does.
**There is no confirm prompt:** when nothing depends on the package, it is removed at once, after
the snapshot.
### When a release needs a different Python
PipDock checks `Requires-Python` itself, because the engines disagree: pip refuses an incompatible
exact pin with the same "No matching distribution" it gives a typo, and uv plans past an upper
bound and fails later, building from source. On Python 3.14:
```powershell
pipdock install scipy==1.7.3 # PD-PKG-001, exit 1: nothing else was asked for
pipdock install scipy==1.7.3 six==1.17.0 # plans six; scipy is listed as left out
```
The preview's *Left out — needs a different Python* section — `incompatible` in the JSON — names
the release, the range it requires and the Python you have. An update does the same for what the
engine planned: a release that excludes your Python is ruled out and the engine asked again, so it,
not PipDock, picks what comes next. Where the engine does not say what a release requires, PipDock
asks PyPI and remembers the answer; one it cannot get never blocks.
---
## Externally managed Pythons (PEP 668)
A Python marked `EXTERNALLY-MANAGED` by whoever installed it — a uv-managed CPython, for one — is
refused by `install`, `update`, `uninstall` and `snapshot rollback` with `PD-ENV-002`, **exit 3**,
before any engine command runs, and by `pip-upgrade` too. The answer is a virtual environment: a
venv never carries the marker, even one built from such a Python.
There is an override, in the GUI's Settings, and **deliberately no CLI flag**: a flag would put it
one shell-history search away. The CLI reads the setting the GUI stores. With it on, and only for
an environment that carries the marker, PipDock passes `--break-system-packages` — and every run
says so on stderr:
```text
warning: this Python is externally managed (PEP 668) and the Settings override is on, so --break-system-packages will be passed. Prefer a virtual environment.
```
uv takes the flag; pip has since 23.0.1. **pip 23.0 itself is refused** with `PD-ENV-002` even with
the override, because it enforces PEP 668 and has no flag to get past it — and `pip-upgrade` cannot
rescue it, since it refuses a managed environment whatever the setting says. Use `--engine uv`, or
upgrade pip outside PipDock. Below 23.0 pip does not enforce the marker, and nothing is passed.
Until 1.4.0 the override was a checkbox nothing read.
---
## Pins
A pin excludes a package from bulk updates. It is per-environment.
A pin keeps a package out of every update — one that names it as well as `--all` — until it is
unpinned. It is per-environment.
```powershell
pipdock pin add numpy --reason "pytorch build is pinned to this"
@@ -170,8 +270,10 @@ pipdock pin list
pipdock pin remove numpy
```
Pins are enforced at the plan boundary, not in the display layer — an update that would move a
pinned package never reaches the engine.
Pins are enforced at the plan boundary, not in the display layer: a pinned package is taken out of
the request before the engine is asked. The text output says what was left out
(`1 pinned package(s) excluded: numpy`); under `--json` that line is not printed, so a script reads
`pin list --json`.
---
@@ -187,13 +289,22 @@ pipdock snapshot rollback <id>
pipdock snapshot rollback latest
```
Two things worth knowing before you rely on this:
`rollback` shows what it will remove and restore, and asks first — `--yes` skips the question, and
off a terminal it refuses without one. Like any change it is refused for an externally managed
Python, and refused with `PD-RES-002` if the environment changed between the preview and your
answer, or the answer took more than ten minutes.
Three things worth knowing before you rely on this:
- **`diff` lists entries a rollback cannot restore** — editable installs and direct-URL installs.
That is deliberate: they are excluded from the pin set and reported separately rather than
silently dropped. Restoring an editable install means re-running `pip install -e` yourself.
- **A rollback snapshots the current state first**, so one rollback creates a second timeline
entry. The trigger label on each entry is how you tell them apart — `latest` moves twice.
`--no-snapshot` does not apply here.
- **`diff` compares the way a rollback with the current engine would.** uv's freeze never lists
pip, setuptools or wheel, so across engines those three are left out of the comparison, and a
rollback never removes pip. Until 1.4.0 a uv snapshot restored with pip uninstalled pip.
---
@@ -218,6 +329,12 @@ snapshot for it, because no snapshot in PipDock describes a source tree; your ve
the safety net, and the confirm says so. It refuses entirely, before writing a byte, if any target
file cannot be written.
It fixes exactly what the report looked at, with the same exclusions; until 1.4.0 it ran without
them, and rewrote notebooks and, in a project that sets its own `exclude`, files under `.venv`. With
`--yes` it proceeds on a committed tree and refuses, exit 2, on one with uncommitted changes —
commit or stash first. Outside a git repository there is no tree to check, and `--yes` proceeds.
Under `--json` it prints the `FixReport` alone, and nothing at all when no fix ran.
The tools environment is built on first use. To manage it directly:
```powershell
@@ -232,6 +349,32 @@ to compare against, which is disclosed wherever its findings are shown.
---
## Security advisories
```powershell
pipdock audit
pipdock audit --engine pip
```
`audit` checks the environment's installed releases against PyPI's advisory data with pip-audit,
run — like Code Health's tools — from an environment of PipDock's own, never from the one being
checked; the first run builds it. It has no flags of its own. **It exits 1 when it finds an
advisory**, like `health`. A pip-audit that could not run at all exits on its own error code
instead, because an empty list from a tool that never ran must not read as "nothing wrong".
What it checks is the engine's freeze, so `--engine` matters: pip's lists pip, setuptools and
wheel, and uv's does not. Until 1.4.0 `audit` used the configured engine whatever `--engine` said.
Findings are grouped under each package and version: an advisory's id, its fix — `fixed in …`, or
`no fix` — and its aliases. There is no severity, because pip-audit publishes none (SECURITY §6).
`audit` changes nothing; the remedy is an ordinary `pipdock update <pkg>`.
The cost is a network fetch, not the package count: measured at 68 s cold, and about 20 s warm for
one package or twelve — which is why it says how many packages it is checking before the wait
rather than after it.
---
## Search and metadata
```powershell
@@ -252,10 +395,12 @@ pipdock pip-upgrade
```
Upgrades pip **inside the selected environment**, which PipDock is otherwise careful never to
modify without a plan. Worth knowing: every pip below 22.2 is broken on Python 3.12+
(`distutils`, `pkgutil.ImpImporter`), so the one case this command exists for is also a pip that
cannot run — it falls back to `ensurepip`, and decides by asking `pip --version` rather than by
matching a traceback.
modify without a plan. It always uses pip, whatever `--engine` says — there is no uv way to upgrade
pip — and it asks nothing and takes no snapshot: a snapshot's only restore path would be pip
itself. It refuses an externally managed Python whatever the Settings override says. Worth
knowing: every pip below 22.2 is broken on Python 3.12+ (`distutils`, `pkgutil.ImpImporter`), so the
one case this command exists for is also a pip that cannot run — it falls back to `ensurepip`, and
decides by asking `pip --version` rather than by matching a traceback.
---
@@ -263,19 +408,23 @@ matching a traceback.
### Exit codes
Verified by running, not copied from the spec:
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | completed with per-package failures — see `counts.failed` in the JSON; **or `health`/`doctor` found something** |
| 2 | plan aborted, nothing executed (resolution impossible, or the uninstall guard tripped without `--force`) |
| 0 | success — a dry run, and a plan with nothing to do, included |
| 1 | completed with per-package failures — see `counts.failed` in the JSON; **or `health`, `audit` or `doctor` found something**; or a failure coded `PD-PKG`, `PD-BLD`, `PD-PRM`, `PD-SYS` or `PD-HLT`, such as a malformed spec |
| 2 | nothing executed: resolution impossible, the uninstall guard tripped without `--force`, the confirm was declined (or there was no terminal to ask on and no `--yes`), the preview had gone stale, or a usage error |
| 3 | environment error, including a PEP 668 block |
| 4 | engine unavailable or too old |
| 5 | snapshot failed — **nothing was executed** |
| 4 | engine unavailable or too old, or an engine query stopped by its watchdog |
| 5 | snapshot failed — **nothing was executed**; or no such snapshot |
| 6 | network or index error |
| 10 | internal error; the log path is printed |
| 130 | cancelled (Ctrl-C); child processes are reaped and a partial summary is printed |
| 10 | internal error; `log: <path>` follows on stderr |
| 130 | stopped by Ctrl-C during `install`, `update`, `uninstall` or `snapshot rollback`: the engine's process tree is killed, what ran is summarized, and stderr names the snapshot to roll back to. A second Ctrl-C quits at once |
Until 1.4.0 this table said it had been verified by running, and two of its rows were not true:
there was no log for code 10 to point at, and the CLI installed no Ctrl-C handler, so Ctrl-C killed
it outright — no summary, and no 130. Both rows describe the code now. Ctrl-C during any other
command still ends it the way it ends any console program, without a summary; the engine's process
tree goes with it either way.
Code **5** is the one to special-case in CI: it means the snapshot could not be written, so PipDock
refused to run the plan at all. Nothing changed.
@@ -290,7 +439,7 @@ pipdock schema HealthReport
`schema` prints the JSON Schema for a core type, generated from the same Rust definitions the
commands serialize — so a script can validate against it instead of guessing. An unknown type name
exits 1.
exits 1, and lists the names it knows. Which document each command prints is CLI-SPEC §6's table.
### A CI-shaped invocation
@@ -298,19 +447,24 @@ exits 1.
pipdock update --all --env C:\proj\.venv --strategy compatible --yes --json
```
`--yes` with `--strategy compatible` never forces anything; a package that cannot be updated
compatibly is skipped and reported, and one failure does not abort the batch — you get
`"13 successful, 2 failed"` with a reason per package.
`--yes` with `--strategy compatible` never forces anything: a held-back package takes its
compatible version, a package that cannot be updated at all is skipped — and named on stderr — and
one failure does not abort the batch: you get `"13 successful, 2 failed"` with a reason per package.
Its stdout is one document, the `ExecutionSummary` when anything ran. Test `$LASTEXITCODE` before
reading it: exit 0 is also *nothing to do*, which prints a `FlowStep` —
`{"step":"nothing","reason":"nothing-to-do"}` — instead.
**`--no-snapshot` exists and you almost certainly do not want it.** It is the only documented
escape from the snapshot-before-mutation rule, it prints a warning, and it is there for throwaway
CI containers that have nothing to roll back to.
CI containers that have nothing to roll back to. It covers `install`, `update` and `uninstall`;
`snapshot rollback` snapshots the state it replaces regardless.
### Isolating the store
Every path PipDock writes lives under `%LOCALAPPDATA%\PipDock\data\`. Point `LOCALAPPDATA`
somewhere else and you get a throwaway store — useful for testing a workflow without touching your
real index, settings or snapshots:
Everything PipDock keeps for itself — the store, snapshots, the tools and audit environments, the
log — lives under `%LOCALAPPDATA%\PipDock\data\`. Point `LOCALAPPDATA` somewhere else and you get a
throwaway store — useful for testing a workflow without touching your real index, settings or
snapshots:
```powershell
$env:LOCALAPPDATA = 'C:\tmp\pipdock-test'
@@ -322,40 +476,62 @@ pipdock env list
## When something goes wrong
Every user-visible failure carries exactly one catalog code — `PD-ENV-001`, `PD-NET-002`, and so
on. `docs/ERROR-CATALOG.md` lists all 34, what causes each and what to do about it. The code is
stable; the message around it is localised.
on. `docs/ERROR-CATALOG.md` lists all 35 (in 32 rows: `PD-HLT-001..004` share one), what causes
each and what to do about it. The code is stable; the message around it is localised.
Every run is logged, whether you ask or not: one file a day,
`%LOCALAPPDATA%\PipDock\data\logs\pipdock-cli.<date>.log`, beside the GUI's `pipdock.<date>.log`,
kept for 14 days. It records what PipDock ran — the arguments you gave, every command it spawned
with its exit code and duration, each resolve, snapshot and run outcome — and nothing in it is sent
anywhere. When you want more:
```powershell
pipdock --verbose --log-file pipdock.log update --all
$env:PIPDOCK_LOG = 'debug'; pipdock update --all
pipdock self report-bug
```
`self report-bug` prints a prefilled GitHub issue URL carrying the version, OS and engine.
`--verbose` shows the log on stderr as it happens, at DEBUG, which includes every line an install
or a removal printed. `--log-file` appends a copy at the file's level — set `PIPDOCK_LOG` as well if you want
DEBUG in it — wherever a CI job can collect it. Neither ever writes to stdout, so `--json` output
stays one document; `--quiet` only quiets the terminal. An internal error (exit 10) ends with
`log: <path>` on stderr. Until 1.4.0 there was no log at all, and `--verbose` and `--log-file` were
accepted and ignored.
`self report-bug` prints a prefilled GitHub issue URL carrying PipDock's version, the OS, the
engine, and the selected environment's Python and engine versions. It attaches no log excerpt:
attach the day's log yourself, after reading it for paths you would rather not make public.
**Nothing is transmitted** — you open it, read what it filled in, and submit it yourself.
---
## What is GUI-only
1.1.0's four features have **no CLI surface yet**, and that is deliberate rather than an oversight
— each would add a subcommand and churn the help goldens for something nothing scripts against
today. The logic lives in `pipdock-core` (`pins::suggest`, `requirements::parse`, `cache::usage`),
so adding one later is small:
These have **no CLI surface yet**, and that is deliberate rather than an oversight — each would add
a subcommand and churn the help goldens for something nothing scripts against today. The logic
lives in `pipdock-core` (`pins::suggest`, `requirements::parse`, `cache::usage`,
`ReverseDeps::view`), so adding one later is small:
| Feature | Where it is | Nearest CLI equivalent today |
|---|---|---|
| Pin suggestions | Pins screen | none — `pin list` shows what you have pinned |
| Requirements export | Environments → *Open* | `snapshot create`, then read the `.freeze.txt` |
| Requirements import | Environments → *Open* | `install` with the specs, which is what import does anyway |
| Requirements import | Environments → *Open* | `install` with the specs, ranges included, which is what import does anyway |
| Disk usage | Settings | `tools status` reports the tools venv; nothing reports sizes |
| Dependency view | a package row's `⇄` | `list --json` carries each package's `requiresDist`, which the view is drawn from; `doctor` reports requirements the engine's check finds broken |
| Command palette | `Ctrl+K` | not applicable |
If you want one of these on the command line, say so in an
[issue](https://github.com/poli0981/pipdock/issues) — the core function is already there.
**The PEP 668 override is GUI-only for a different reason, and stays so.** It is meant to be hard
to reach — a decision made in the GUI, behind a confirm — and a flag would put it one shell-history
search away. The CLI reads the setting the GUI stores, and says so on stderr every time it applies;
see [Externally managed Pythons](#externally-managed-pythons-pep-668).
## See also
- [CLI-SPEC.md](CLI-SPEC.md) — the contract: exhaustive flags, JSON shapes, exit codes
- [ERROR-CATALOG.md](ERROR-CATALOG.md) — all 34 codes and what to do about each
- [ERROR-CATALOG.md](ERROR-CATALOG.md) — all 35 codes and what to do about each
- [SECURITY.md](SECURITY.md) — threat model, PEP 668 policy, what PipDock connects to
- [CODE-HEALTH-SPEC.md](CODE-HEALTH-SPEC.md) — how deptry, vulture and ruff are invoked
+120 -32
View File
@@ -5,80 +5,166 @@
## 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.
2. **Safe by default, scriptable on request.** Interactive prompts appear on a TTY; in scripts (`--yes` / no TTY), a held-back package keeps its compatible version and an impossible one is **skipped** — never forced, unless `--strategy latest` asked for exactly that (§4). Off a TTY, a command that would ask first refuses instead unless `--yes` is given; `uninstall` and `pip-upgrade` ask nothing (§3).
3. **Machine-readable everywhere.** `--json` makes every command print one JSON document on stdout — the structs the GUI receives, wherever one exists (§6).
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)
--env <path> interpreter or env dir (default: the one `env use` set, else a venv in the 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
--json one JSON document on stdout (§6); prompts, progress and warnings go to stderr
--yes / -y assume defaults on all prompts (held back → compatible, impossible → skip)
--quiet less on the terminal: no streamed engine output, no progress lines
--verbose the log on stderr as well, at DEBUG
--log-file <path> a copy of the log, appended to <path>
--no-snapshot DANGEROUS: skip pre-batch snapshot (CI images only; prints warning)
```
`--quiet` and `--verbose` cannot be combined (clap refuses it, exit 2). `--quiet` keeps the terminal to results, prompts, warnings and errors — `env use` and `tools sync` drop even their one-line confirmation — and changes nothing in the log. `--no-snapshot` applies to `install`, `update` and `uninstall`; `snapshot rollback` always snapshots the state it replaces (DATA-FLOW §8) and accepts the flag without acting on it.
**Which environment.** In order:
1. `--env` — an interpreter, or an environment directory whose `Scripts\python.exe` is used;
2. the default `pipdock env use` stored. If its interpreter is gone, stderr says `` warning: the default environment (<path>) no longer exists; `pipdock env use` sets another `` and the search goes on;
3. the first of `.venv`, `venv`, `env`, `.env` in the working directory that holds an interpreter.
Nothing found is PD-ENV-001 (exit 3), naming all three ways. Only `env use` writes the default — selecting an environment in the GUI does not change what the CLI acts on. `env list`, `info`, `index`, `tools` and `schema` never look for an environment; `search` and `self report-bug` use one when they find one and work without it; `engine` reports without one (§3). Until 1.4.0 the default was written and read by nothing, so `env use` reported success and every later command ignored it (X3).
**Logging.** Every invocation appends to `%LOCALAPPDATA%\PipDock\data\logs\pipdock-cli.<YYYY-MM-DD>.log` — one file per UTC day; the GUI writes `pipdock.<date>.log` beside it, so the two never interleave — and sweeps that folder of dated log files older than `LOG_RETENTION_DAYS` (14), leaving any other file alone. The file's level is `PIPDOCK_LOG`, a `tracing` filter directive such as `debug`, and INFO when it is unset or not a valid directive. At INFO the file holds the invocation's arguments, each subprocess's argv, exit code and duration, every stop and its reason, and each resolve, snapshot and run outcome; the lines an install, a removal or a tools-venv sync prints as it runs are DEBUG. `--verbose` adds stderr at DEBUG, whatever `PIPDOCK_LOG` says. `--log-file` appends the file's lines, at the file's level, to a path of your choosing; one it cannot open is a warning on stderr, not a failure. **Nothing is ever logged to stdout**, so `--json` stays one document under `--verbose`. An internal error (exit 10) prints `log: <today's file>` on stderr, in both modes. Until 1.4.0 there was no log at all: `tracing` was a dependency and never called, and `--verbose` and `--log-file` were parsed and ignored.
## 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 env use <path> # set the default env (§2)
pipdock list [--outdated] # installed packages, from the probe; --outdated asks the index
pipdock search <query> [--limit n] # local fuzzy index search (n defaults to 20)
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
pipdock install <spec...> [--dry-run] # spec = a name, optionally with a PEP 440 specifier set; dry-run prints the ResolutionReport
pipdock update [--all | <pkg...>] # one or the other: neither is a usage error (exit 2)
[--strategy compatible|latest] # latest forces every held-back package, where nothing is asked (§4)
[--except <pkg,...>] # ad-hoc exclusions on top of pins; comma-separated or repeated
[--dry-run]
pipdock uninstall <pkg...> [--force] # guard names each dependent and its constraint; --force overrides
pipdock uninstall <pkg...> [--force] # guard names each dependent and its constraint; --force overrides; no prompt
pipdock pin add|remove <pkg> [--reason "…"] | pin list
pipdock snapshot list | create | diff <id> | rollback <id|latest>
pipdock doctor # engine check + env sanity
pipdock doctor # the engine that would run + env sanity; exit 1 on real problems
pipdock audit # known advisories in the selected environment; exit 1 on findings
pipdock health [--path <dir>] [--tool deptry|vulture|ruff] [--fix] # --fix = ruff only, prompts
# --yes: proceeds on a clean tree,
# REFUSES on a dirty one (exit 2)
pipdock pip-upgrade # upgrade pip inside --env (pip engine paths only)
pipdock engine [pip|uv] # show or set configured engine
pipdock pip-upgrade # upgrade pip inside the selected env: always pip, no snapshot
pipdock engine [pip|uv] # no argument: both engines' versions; with one: set it
pipdock index refresh # re-pull PEP 691 name index
pipdock tools sync [--force] [--python <path>] # build/re-sync the Code Health tools venv
pipdock tools status # where it is, and whether it matches the shipped pins
pipdock schema <type> # JSON Schema for a core type, so scripts can pin against it (§6)
pipdock self report-bug # prints prefilled GitHub issue URL (ERROR-CATALOG §4)
```
**Specs.** `install` takes a name, optionally followed by a PEP 440 specifier set: `requests`, `django==5.0.1`, `"django>=5.0,<6"`, `"attrs ~= 23.1"`, `pkg===1.0`. An extra, a marker, a URL or anything else PEP 440 does not define is PD-PKG-002 (exit 1), refused before it reaches argv (SECURITY §2). `install --help` still says "`name` or `name==version`", which until 1.4.0 was the whole grammar: a request was split on `==`, so `django>=5.0,<6` became a package name.
**Before anything changes.** `install`, `update`, `uninstall` and `snapshot rollback` begin with a fresh probe of the environment, and three rules follow from it.
- *PEP 668* (SECURITY §3). An environment carrying the `EXTERNALLY-MANAGED` marker is refused with PD-ENV-002 (exit 3) before any engine command runs. The only way past is the GUI's Settings override, which the CLI reads from the store both heads share — **there is deliberately no CLI flag for it**: the override is meant to be hard to reach, and a flag would put it one shell-history search away. With the override on *and* the marker present, every mutating engine call is given `--break-system-packages`, and so is uv's dry-run resolve, which refuses a managed environment without it (pip's `--dry-run --report` never is). uv takes the flag in every version PipDock supports, pip from 23.0.1, which added it. Every such run says so on stderr: `warning: this Python is externally managed (PEP 668) and the Settings override is on, so --break-system-packages will be passed. Prefer a virtual environment.` pip 23.0 enforces PEP 668 with no way past it, so it is refused with PD-ENV-002 even then (`pip 23.0 enforces PEP 668 and has no override; --break-system-packages arrived in pip 23.0.1`); `--engine uv` gets through, and `pip-upgrade` does not help, because it refuses a managed environment whatever the override says. Below 23.0 pip enforces nothing and is passed nothing. A venv never carries the marker. Until 1.4.0 the override was saved and read by nothing, the gate trusted a cached flag rather than a probe, and a rollback had no gate at all.
- *Requires-Python* (hard invariant 10). PipDock enforces it itself, because the engines disagree: pip refuses an incompatible exact pin with the "No matching distribution" it gives a typo, and uv plans past an upper bound. An exact pin the user typed (`name==v`, `name===v`) is checked before any engine sees it; a release *Force latest* would install is checked before it is forced; and every release the engine planned is checked after. pip's report says what each planned release requires; for the rest — exact pins, forced releases, anything uv plans — PipDock asks PyPI (`https://pypi.org/pypi/<name>/<version>/json`), remembers each answer, and never blocks on one it cannot get. A planned release that excludes this interpreter is ruled out by name and the engine asked again, at most twice, so the engine rather than PipDock picks what comes next; one still planned after that stays in the plan, as a warning. Every such release is in the report's `incompatible` (§6), which the preview prints as *Left out — needs a different Python*; a request that is nothing but such pins fails with PD-PKG-001 instead (exit 1), naming the range and the interpreter's version. Until 1.4.0 nothing raised PD-PKG-001.
- *A preview is good for ten minutes, and for the environment it was made against* (DATA-FLOW §9.3). Between the decision and the snapshot — after the confirm, or after the guard for `uninstall` — the environment is probed again, or re-frozen for a rollback, and a preview older than ten minutes, or one the environment no longer matches, is refused with PD-RES-002 (exit 2). The refusal comes before the snapshot, so it costs nothing; re-run the command. Until 1.4.0 both checks existed and neither could fire.
**`uninstall` asks nothing.** The guard runs once over the whole removal set before anything is touched (DATA-FLOW §5). Clear, the packages are removed at once, after the snapshot. Tripped, the command refuses with PD-RES-004 and exit 2 and prints the `pipdock uninstall …` line that would remove the dependents too — unless `--force` was given, which prints `warning: --force given; proceeding despite the breakage above` and removes. `--yes` changes nothing here.
**`pip-upgrade`** always runs pip, whatever `--engine` or the configured engine says: there is no uv way to upgrade pip (DATA-FLOW §7). It asks nothing and takes no snapshot (DATA-FLOW §9's pip-upkeep exemption), refuses a PEP 668 environment whatever the override says, and falls back to `ensurepip` for a pip too broken to run — every pip below 22.2 on Python 3.12+.
**`doctor`** judges the engine that would run — `--engine`, else the configured one — and exits 1 when that engine is unavailable, or its check finds broken requirements or cannot run. Until 1.4.0 it required pip whatever was configured, which failed every uv-only venv (`uv venv` makes them without pip). Whether the Code Health tools venv is built is reported and never affects the exit.
**`audit`** checks the engine's freeze, so `--engine` decides what is audited: pip's `freeze --all` lists pip, setuptools and wheel, and uv's freeze does not. pip-audit runs from a venv of its own (`data\audit\`, built on first use; SECURITY §6) against PyPI's advisory service. Exit 1 on findings; a pip-audit that could not run exits on its problem's code instead (§5), so an empty report from a tool that never ran cannot read as clean. Until 1.4.0 it used the configured engine whatever `--engine` said.
**`engine`** with no argument reports both engines' availability and version, and needs no environment: uv is a standalone binary, and pip, a module of some interpreter, is reported unavailable without one. It does not say which engine is configured. With an argument it sets the configured engine — the setting the GUI shows — and refuses (PD-ENG-001) one that is not available here, because storing a preference that cannot be honoured moves the failure to the next command; setting pip needs an environment to look for it in. Until 1.4.0 the report failed in any directory without a `.venv`.
**`health --fix`** under `--yes` proceeds on a clean tree and refuses a dirty one (`error[PD-RES-002]: … uncommitted change(s) here; --yes will not rewrite files you have not committed. Commit or stash first.`, exit 2): the default over uncommitted work is *don't*, and the remedy is `git commit` or `git stash` rather than a flag. Outside a git repository, or without git, there is no tree to be dirty, and `--yes` proceeds. Off a TTY without `--yes` it refuses (exit 2), and `--fix` with a `--tool` list that leaves out ruff is refused before anything runs (`error[PD-PKG-002]: --fix needs ruff; it is the only tool that writes`, exit 2).
## 4. Interactive conflict handling (TTY)
`update`/`install` render the preview, then per needs-decision package:
`update`/`install` resolve, then ask about each held-back package before the preview is printed — on stderr, in both modes, like every prompt:
```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
requests held back at 2.30.0 (latest 2.32.3)
— apiclient 1.4 requires requests<2.31
[C]ompatible (default) [S]kip [F]orce latest:
```
`--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`).
`s` drops the package from this plan, and `f` forces its latest and names what that breaks (` this will break: apiclient`); anything else — Enter, `c`, even `skip` — keeps the compatible version. Any answer but *Compatible* re-resolves, and the questions repeat for whatever the new report holds back, for at most three rounds (`MAX_CONFLICT_ROUNDS`); after that the plan is confirmable as it stands. An impossibility is not asked about: its packages are skipped — and on a TTY, as the code stands, nothing says so, because the engine's explanation is printed only where nothing is asked (below). Then the preview, and the confirm, which is where a plan is abandoned:
```text
Apply 4 change(s)? [y/N]:
```
`y` or `yes` proceeds; anything else prints `aborted` and exits 2 — under `--json`, with the `ResolutionReport` as the document. `--dry-run` stops at the preview, but after the questions, because the decisions are part of what the report describes.
**With `--yes`, or without a TTY on stdin,** nothing is asked: a held-back package keeps its compatible version and an impossibility's packages are skipped. The impossibility is said first, on stderr — the engine's explanation, then `skipping: <names>` — so `every package was skipped` does not arrive unexplained. Off a TTY *without* `--yes` the confirm refuses rather than assuming: `error[PD-RES-002]: not a terminal; pass --yes to apply without confirming`, exit 2. (PD-RES-002 describes a stale preview; a code for "confirmation required" is the audit backlog's X17, ROADMAP.)
**`--strategy latest`** answers *Force latest* for every held-back package — only where nothing is asked, so with `--yes` or off a TTY. The report then carries `forced` (§6), and the preview a *Forced — will break* section naming each installed package whose requirement is overridden. On a TTY it changes nothing: each package is still a question, and Enter is still *Compatible*. Off a TTY nothing runs without `--yes` in any case, which makes `--yes` the "explicit acknowledgement" its help text describes; `--yes` without `--strategy latest` never forces. Under `--json --yes` no preview is printed at all, so a script that forces should read `forced` from a `--dry-run` first.
> **Corrected in 1.4.0.** This section said the preview came before the questions, offered an `[A]bort plan` answer, and had `--strategy latest` print its breakage warning before "a mandatory 3-second countdown (skippable with a second `-y`)". The binary has asked first since its first version, and has never had an abort answer — abandoning a plan is the final confirm's `N` — or a countdown; `--yes` is a bool, so there is no second `-y`, which `health --fix` already recorded. Nor did forcing force anything until 1.4.0: the decision was recorded in the request and no resolve read it.
## 5. Exit codes
| Code | Meaning |
|---|---|
| 0 | success, all steps ok |
| 1 | completed with per-package failures (see JSON `counts.failed`); **or `health` found something** — a linter that exits 0 on findings is useless in a pre-commit hook, and `doctor` already uses this code for "found real problems" |
| 2 | plan aborted, nothing executed (resolution impossible & user/skip policy removed everything; uninstall guard tripped without `--force`, PD-RES-004) |
| 0 | success, all steps ok — a dry run, a plan with nothing to change and `nothing-to-do` included |
| 1 | completed with per-package failures (see JSON `counts.failed`); **or `health` or `audit` found something** — a linter that exits 0 on findings is useless in a pre-commit hook, and `doctor` already uses this code for "found real problems"; or a failure coded PD-PKG-*, PD-BLD-*, PD-PRM-*, PD-SYS-* or PD-HLT-*, such as a malformed spec (PD-PKG-002) or a request this Python cannot install (PD-PKG-001) |
| 2 | plan aborted, nothing executed: resolution impossible and the skip policy removed everything (`everything-skipped`); uninstall guard tripped without `--force` (PD-RES-004); the confirm declined, or not askable — no TTY and no `--yes`; a stale or drifted preview (PD-RES-002); `health --fix` refused or declined; or a usage error — clap's own, `update` with neither names nor `--all`, `--fix` with a `--tool` list that leaves out ruff |
| 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) |
| 4 | engine unavailable / version too old / stopped by its watchdog (PD-ENG-*) — outside a batch; inside one, a watchdog is a per-package failure (1) |
| 5 | snapshot failure — nothing was executed (PD-SNP-001); or no such snapshot (PD-SNP-002) |
| 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) |
| 10 | internal error (PD-INT-*); `log: <path>` on stderr, in both modes (§2) |
| 130 | stopped by Ctrl-C or Ctrl-Break during `install`, `update`, `uninstall` or `snapshot rollback`; see below |
An error's exit is derived from its code's area (`run::exit_for`) rather than written out per call site, so a new code cannot land on an undocumented number, and a test holds every code in `Code::ALL` to this table.
**Ctrl-C** — or Ctrl-Break, which a supervising process can send to one process group — during `install`, `update`, `uninstall` or `snapshot rollback` stops the run rather than the process. stderr says `stopping — press Ctrl-C again to quit now`, the flow's cancellation token trips, and the engine's whole process tree is killed (exec's job object). What completed is summarized — under `--json` the `ExecutionSummary`, with `"cancelled": true` — and stderr names the way back: `` stopped. What ran is above; `pipdock snapshot rollback <id>` puts back the state from before this run. `` Exit 130. Stopped during a resolve, nothing was planned or run: the document is `{"step":"nothing","reason":"cancelled"}`, stderr says `stopped before anything was planned; nothing ran`, exit 130. A **second** Ctrl-C exits 130 at once, with no summary, for a step that is not listening — a probe, a snapshot write. Every other command installs no handler, and Ctrl-C ends it the way it ends any console program: no summary, and not 130. Either way the engine's process tree goes with it. Until 1.4.0 that was true of every command, so Ctrl-C mid-batch printed nothing and said nothing about the snapshot just written (X6).
## 6. JSON contracts
`--json` payloads are the serde-serialized core types (`Dist`, `OutdatedDist`, `ResolutionReport`, `ExecutionSummary`, `CheckReport`, `GuardReport`, `HealthReport`) — 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.
**`--json` prints exactly one JSON document on stdout per command, and nothing else goes there.** Prompts, the preview shown before a prompt, warnings, progress prose and the engine's streamed output go to stderr — in both modes — and so does the log under `--verbose` (§2). Each document is the serde-serialized core type where one exists, the structs the GUI receives, pretty-printed; `pipdock schema <type>` prints the JSON Schema generated from the Rust type, so scripts can pin against it, and an unknown name lists the types it knows (PD-PKG-002, exit 1).
> **Not implemented, recorded 2026-08-12 (Phase 3 · P2).** No command in the binary emits NDJSON. `update`, `install`, `uninstall` and `tools sync` all stream engine output as plain lines to **stderr** and print a single final object to stdout; `health` does the same since P3, and `health --fix` prints one document — the `FixReport`, not the pre-fix report, which describes a state that no longer exists by the time the command returns. Either this paragraph or four commands are wrong, and closing it means changing the output shape of every streaming command at once — so it is its own slice, not a thing to half-do while adding a fifth. `tools sync` matches the existing behaviour deliberately rather than becoming the one command that is inconsistent with the other four.
| Command | The document |
|---|---|
| `install`, `update` | The `ResolutionReport` when nothing runs — `--dry-run` or a plan with no changes (exit 0), a confirm declined or not askable (exit 2). The `ExecutionSummary` when something runs (0, 1 or 130). A `FlowStep` when there is nothing to plan: `{"step":"nothing","reason":…}` with `nothing-to-do` (0), `everything-skipped` (2) or `cancelled` (130) |
| `uninstall` | The `GuardReport` when the guard trips without `--force` (exit 2); otherwise the `ExecutionSummary`. With `--force`, the summary alone |
| `snapshot rollback` | The `RollbackPreview` when nothing runs — the environment already matches (0), or the confirm was declined or not askable (2); otherwise the `ExecutionSummary` |
| `snapshot create` | The new snapshot's `SnapshotMeta` |
| `snapshot list` | `[SnapshotMeta]` |
| `snapshot diff` | `Diff`, as a rollback with this engine would see it; the lines no index can restore are printed in text mode only |
| `env list` | An array, one object per discovered interpreter: `interpreter`, `source`, `python`, `externallyManaged`, `hiddenUserSite`, `packages` (a count), `envHash`, `pipVersion` — or `interpreter`, `source` and `error: {code, message}` for one that could not be probed, without failing the rest |
| `env use` | The `PyEnv` that is now the default |
| `list` | `[Dist]`, from the probe; with `--outdated`, `[OutdatedDist]` |
| `search` | `[Hit]` |
| `info` | `{meta: PackageMeta, freshness: Freshness}` |
| `pin list` | `[Pin]` |
| `pin add` | The `Pin` written — always `"mode": "exclude"` |
| `pin remove` | `{pkg, removed}`; `removed` is false, and the exit still 0, when it was not pinned |
| `doctor` | `{interpreter, python, envHash, externallyManaged, hiddenUserSite, engines: {pip, uv}, check, toolsVenv: {path, need, manifest}}`; `check` is null when the check could not run |
| `audit` | `AuditReport` |
| `health` | `HealthReport`; with `--fix`, the `FixReport` alone when a fix ran — see below |
| `pip-upgrade` | `{before, after}`, each pip's `EngineInfo` |
| `engine` | `[EngineInfo, EngineInfo]`, pip then uv |
| `engine <pip\|uv>` | The `EngineInfo` of the engine just set |
| `index refresh` | `RefreshReport` |
| `tools sync` | `{"state": "fresh"}` when the venv already matched (without `--force`); otherwise the venv's manifest after the sync |
| `tools status` | `{path, need, manifest}` |
| `schema <type>` | The JSON Schema, printed with or without `--json` |
| `self report-bug` | `{url}` |
**A failure prints the envelope and only the envelope** — `{"code":"PD-ENV-001","message":"…","stderrTail":null}`, on one line, with the exit §5 gives its code; `stderrTail` is the engine's stderr tail when there was one. Without `--json` the same failure is `error[PD-ENV-001]: …` on stderr.
**What prints no document.** Usage errors — clap's own, `update` with neither names nor `--all`, `--fix` with a `--tool` list that leaves out ruff — say so on stderr and exit 2 with stdout empty. `health --fix` prints the `FixReport` alone when a fix ran, because the pre-fix report describes a state that no longer exists by the time the command returns; when no fix runs — nothing was safely fixable (exit 0 or 1, by the findings), or the fix was refused or declined (exit 2) — it prints nothing, the report having been withheld for a `FixReport` that never came. A second Ctrl-C (§5) exits wherever it is.
**What 1.4.0 added and removed.** `ResolutionReport` always carries `changes` and `heldBack`; `impossible` is omitted when there is none, and the three fields 1.4.0 added — `incompatible`, `forced`, `yanked` — when they are empty, so a report that needs none of them reads as it did, less `raw`. `incompatible` (PD-PKG-001) is what was left out because its `Requires-Python` excludes this interpreter — `{pkg, version, requiresPython, python}`, structured so a head can set the range against the version rather than print a sentence (hard invariant 4). `forced` is each package *Force latest* moves, in `heldBack`'s shape: `latest` is the version it is forced to, and `blockers` are the installed packages whose requirement it breaks — DISCLAIMER §2's *Will break* rows, before anything runs. `yanked` (PD-PKG-003) is each withdrawn release the plan would install, with upstream's `reason` when it gave one: a warning rather than a failure, since both engines install them — and only the JSON carries it, because the text preview does not print it. `raw` left the wire: it was pip's whole `--report` document, every package's README included, and nothing read it. In `ExecutionSummary`, a row's `from` is the version it moved from — until 1.4.0 always null, so every upgrade read as a fresh install — `check.ok` is true only when the post-run check **ran** and found nothing, with `check.error` carrying the code when it could not run (a case that used to read `ok: true`), and `cancelled` is §5's Ctrl-C.
> **Settled in 1.4.0.** This section promised NDJSON for the streaming commands — events matching the GUI's `plan-progress` payloads, "terminated by a final `summary` object" — and from 2026-08-12 recorded that no command emitted any. None ever did. What the binary printed instead was not one document either: `install` and `update` printed the `ResolutionReport` and then the `ExecutionSummary`, so `pipdock install x --json | ConvertFrom-Json` failed on the second; `uninstall --force` printed the `GuardReport` before its summary; `snapshot rollback` printed its preview as prose; and `engine`, `env use`, `pin add`, `pin remove`, `snapshot create`, `pip-upgrade` and `self report-bug` ignored `--json` altogether (X5). The rule is now one document per command, and the table above is the contract. `--help` still describes `--json` as "NDJSON for streaming commands"; that line is wrong.
`GuardReport.breaks` maps each package being removed to the installed packages that would break, and each of those carries the specifier that says so: `{"numpy": [{"pkg": "pandas", "version": "2.1.4", "constraint": "<2,>=1.26.0"}]}`. `constraint` is the **bare specifier tail** — the distribution name is the map key, so a caller joins the two halves itself; `version` is omitted when the graph does not know it, and `constraint` is empty for an unconstrained dependency. DATA-FLOW §5's dialog needs the specifier to say *"Removing X breaks Y (requires X>=1)"*, and a bare list of names tells the user what will break but not whether they can live with it.
@@ -88,11 +174,13 @@ requests held back at 2.30.0 (latest 2.32.3) — blocked by apiclient 1.4 (requ
```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
pipdock update --all --env C:\bots\scraper\.venv --yes --json --log-file C:\logs\pd.log > C:\logs\pd-summary.json
# Audit what an upgrade would do without touching anything:
pipdock update pandas numpy --dry-run --json | jq '.held_back'
pipdock update pandas numpy --dry-run --json | jq '.heldBack'
# Refuse-to-break uninstall in CI (exit 2 — plan aborted — if the guard trips):
pipdock uninstall legacylib --json || echo "dependents exist, aborting"
```
The log file holds log lines, not JSON; the summary is the document on stdout. `heldBack` is camelCase, like every key on the wire; this example used to say `.held_back`, which `jq` answers with `null`.
+24 -10
View File
@@ -10,9 +10,9 @@ Code Health answers three questions about a **project folder** (not an environme
|---|---|---|
| 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 |
| Does the code violate common standards, and what can be auto-fixed? | **ruff** (`check`, opt-in `--fix`; an opt-in `format --check` was specified and never built) | 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.
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 check --fix`, gated behind an explicit confirm — `ruff format` is not wired at all (§5 says why); 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
@@ -22,10 +22,11 @@ The three tools are **never installed into the user's environment**. PipDock mai
%LOCALAPPDATA%\PipDock\data\tools\
├─ .venv/ # created with the newest discovered Python (≥3.10), no upper bound
├─ tools-requirements.txt # the resolved three-tool subset actually installed, LF, no comments
├─ tools-constraints.txt # the tools' whole dependency tree, pin lines only, LF — passed as -c (1.4.0)
└─ 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`, with progress in the console drawer. Pin policy: exact `==` pins resolved at PipDock release time (Dependabot PRs bump them, in their own group per RELEASE-CI §2); no floating versions at runtime. Offline: if bootstrap can't reach PyPI, Health reports PD-NET-011 and stays disabled; other tabs unaffected.
Bootstrap: on first Health run (or pin-set change), create/sync the venv from `tools-requirements.txt`, constrained by `tools-constraints.txt`, with progress in the console drawer. Pin policy: exact `==` pins resolved at PipDock release time — for the tools and, since 1.4.0, for everything beneath them (Dependabot PRs bump the tools, in their own group per RELEASE-CI §2); no floating versions at runtime. Offline: if bootstrap can't reach PyPI, Health reports PD-NET-011 and stays disabled; other tabs unaffected.
**Amended by Phase 3 · P2, 2026-08-12** — four corrections, each made against a running bootstrap:
@@ -36,6 +37,18 @@ Bootstrap: on first Health run (or pin-set change), create/sync the venv from `t
`python -m venv` exiting non-zero is **`PD-HLT-004`**, added in the same slice: `PD-NET-011` is `Area::Net` and would exit 6, so a script retrying on network failure would loop forever against a broken interpreter.
**Amended by 1.4.0 — the whole tree is pinned, not just the tools.** The ledger pins four tools and nothing beneath them, so every sync resolved their thirty-odd dependencies against whatever PyPI held that day: a report was reproducible for a build only as far as the top of the tree, and a broken or compromised release of `requests`, `rich` or `msgpack` reached every user on their next sync. `tools/tools-constraints.txt` is that tree, compiled once with
```text
uv pip compile tools/tools-requirements.txt --universal --python-version 3.10 --only-binary :all: --no-emit-package pip -o tools/tools-constraints.txt
```
— the command is in the file's header, which is the copy to run — embedded in the binary beside the ledger (`health::TOOLS_CONSTRAINTS`), written into the tools directory as its pin lines alone, and passed to the bootstrap's `pip install` as `-c`. One file serves both venvs, because a constraint installs nothing. `pip` is left out on purpose: it is the installer, pip-audit depends on it, and constraining it would make pip replace itself half-way through installing pip-audit.
- **Regenerate it whenever `tools/tools-requirements.txt` moves**, a Dependabot bump included. `every_tool_is_constrained_at_the_version_the_ledger_pins` fails `cargo test` on a ledger pin the constraints do not carry, and names the command: a tool installed at one version and constrained at another is something pip refuses, and every user's next Health click would be `PD-NET-011`.
- **The manifest hash still covers the tool pins alone**, so the change forced no existing venv to re-sync. By the same rule, a regeneration that moves only a dependency reaches a venv the next time it is rebuilt for another reason — a tool bump, a missing tool, a cleared cache — and not before.
- **Versions, not hashes.** `--require-hashes` is in ROADMAP's Audit backlog: it needs every wheel's hash across the Pythons and platforms the venvs are built on.
## 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).
@@ -52,14 +65,15 @@ Also amended: the report type is **`HealthReport`**, not the `CheckReport` ARCHI
## 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
deptry . --json-output <tools>\runs\deptry-<pid>.json --no-ansi --ignore-notebooks --extend-exclude ".*<dir>/.*" …
vulture . --min-confidence 80 --exclude "*/<dir>/*,…" # parse text output (stable format)
ruff check . --output-format json --exclude *.ipynb --exclude <dir> …
ruff check . --output-format json --exclude *.ipynb --exclude <dir> … --fix # only from the Fix button / `pipdock health --fix` after confirm
```
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.
Exclusions honored: `.venv`, `venv`, `node_modules`, `build`, `dist`, `.git` (`health::DEFAULT_EXCLUDES`), each in its tool's own dialect — deptry's are anchored regexes, vulture's one comma-separated glob list, ruff's repeated globs — and notebooks (§7) by `*.ipynb` for ruff and `--ignore-notebooks` for deptry. **There are no user globs and no confidence setting**: this paragraph promised "user globs in Settings" and the block above a confidence from `<settings, default 80>`, and neither setting was ever built — `RunOptions` carries both, no head sets them, and the confidence is always 80. Each tool has a watchdog timeout (120 s) → PD-HLT-003 partial report. The list also had `ruff format --check .` as an optional toggle, default off; no toggle exists (§5).
**Amended by 1.4.0 — the fix excludes what the report excluded, by construction.** The fix ran `ruff check . --fix` with none of the read-only run's exclusions (C4). Verified against ruff 0.17.1: it rewrote every `.ipynb` in the tree — which the report never shows — and, in a project whose `pyproject.toml` sets its own `exclude` (which replaces ruff's defaults), the files under `.venv/` as well. The fix's argv is now the report's argv plus `--fix` (`fix_argv` over `run::ruff_argv`, which the pre-write re-check shares too), and `the_fix_excludes_everything_the_preview_excluded` holds it there; re-run against both cases, neither file changes. A fix stopped by its watchdog says that some files may already have been rewritten, because ruff writes as it goes.
## 5. Results model & UI
@@ -72,7 +86,7 @@ Exclusions honored: `.venv`, `venv`, `node_modules`, `build`, `dist`, `.git`, pl
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]`.
**The fix path, as built (Phase 3 · P5).** One dialog with two states, not two dialogs — two confirms break the click budget and the second is the one nobody reads. Cancel is rendered first and focused, so `Enter` without `Tab` cancels. The confirm carries one unconditional sentence — *PipDock cannot undo this; only your own version control can* — and reserves its danger block for a tree that really has uncommitted work, so a folder outside version control is not nagged about. `git --no-optional-locks status --porcelain --untracked-files=no` is asked **twice**: once when the dialog opens, to decide what to render, and again inside `health_fix`, to decide what to allow. Before anything is written, the command re-reads the project (`PD-RES-002` if the counts moved) and checks every target is writable (`PD-PRM-003` if not) — the fix refuses **as a whole** rather than half-rewriting a tree nothing can restore. Only safe fixes are applied; `--unsafe-fixes` is never passed and **`ruff format` is not wired at all**, because formatting a whole project is a far larger blast radius than fixing seventeen lint findings and §7's non-goals are contractual.
**The fix path, as built (Phase 3 · P5).** One dialog with two states, not two dialogs — two confirms break the click budget and the second is the one nobody reads. Cancel is rendered first and focused, so `Enter` without `Tab` cancels. The confirm carries one unconditional sentence — *PipDock cannot undo this; only your own version control can* — and reserves its danger block for a tree that really has uncommitted work, so a folder outside version control is not nagged about. `git -c core.fsmonitor=false --no-optional-locks status --porcelain --untracked-files=no` is asked **twice**: once when the dialog opens, to decide what to render, and again inside `health_fix`, to decide what to allow. The `-c` is 1.4.0's: a repository can name a program for `git status` to run — `core.fsmonitor` in its own `.git/config` — and a project folder downloaded rather than cloned brings that file with it, so asking "is it safe to write here" would have run it (SECURITY §2). A command-line `-c` wins over every config file. Before anything is written, the command re-reads the project (`PD-RES-002` if the counts moved) and checks every target is writable (`PD-PRM-003` if not) — the fix refuses **as a whole** rather than half-rewriting a tree nothing can restore. Only safe fixes are applied; `--unsafe-fixes` is never passed and **`ruff format` is not wired at all**, because formatting a whole project is a far larger blast radius than fixing seventeen lint findings and §7's non-goals are contractual.
## 6. Interpretation guidance (shown as inline help)
+135 -44
View File
@@ -15,20 +15,27 @@
## 2. Shared preamble (all mutating flows)
```text
[Select env] → probe.py -I → env facts (python ver, PEP 668, hidden_user_site, dist metadata)
│
├─ EXTERNALLY-MANAGED detected → BLOCKED banner (PD-ENV-002)
│ └─ explicit override in Settings → proceed with persistent warning chip
[Select env] → probe.py -X utf8 -I → env facts (python ver, PEP 508 markers, PEP 668,
│ hidden_user_site, dist metadata)
│ probed afresh by every mutating flow's start (flow::preamble); the PEP 668
│ answer comes from this probe, never from the PyEnv the caller sent
├─ EXTERNALLY-MANAGED detected → BLOCKED banner (PD-ENV-002), before any engine command
│ └─ explicit override in Settings → proceed with persistent warning chip;
│ SystemPackages::OverrideAllowed → --break-system-packages on every
│ mutating engine call, and on uv's dry run (pip's dry run never);
│ pip 23.0 → still PD-ENV-002 (no flag exists); pip < 23.0 → no flag
├─ hidden_user_site non-null → Installed screen shows the partial-listing note
│ (not a block; see SECURITY §2)
└─ ok → flow continues; reverse-dep graph built from probe data
Every candidate is then screened against the environment's Python version by
pipdock-core (ARCHITECTURE §3): incompatible ones are dropped from the plan with
PD-PKG-001 before any engine command runs, so the preview is identical under pip
and uv even though the engines themselves disagree.
└─ ok → flow continues; reverse-dep graph built from probe data, its markers
evaluated against the probe's marker environment
```
**The gate is decided on a fresh probe** (1.4.0). It read `env.externally_managed` — whatever the caller last cached about the environment — before anything had been probed, and the rollback flow had no gate at all (H12); the Settings override saved and nothing read it, so turning it on changed nothing (H11). `flow::preamble` now probes, gates on that answer, and — only with the override on, the marker present **and** an engine that has the flag — hands the flow `SystemPackages::OverrideAllowed`, which is the one way `--break-system-packages` reaches argv (hard invariant 5). A venv never carries the marker, so the override never applies inside one. The CLI reads the override from the store both heads share, has no flag of its own, and says on stderr every time it applies; the GUI shows a chip wherever it applies. Pip upkeep is not a flow and keeps its own guard (§7).
What a caller decides before a flow starts is `flow::FlowOptions { cancel, clock, allow_externally_managed, releases }`: the cancellation token — the caller's, because the first resolve runs inside `start` and a token made there could only be handed out after the resolve it was needed to stop; a clock, so a test can age a preview without waiting ten minutes; the Settings override as the caller read it; and where a release's `Requires-Python` comes from when the engine does not say (`release::PyPiReleases` in both heads; `None` checks only what the engine itself reported).
**Requires-Python is screened by `pipdock-core`, not the engine** (ARCHITECTURE §3), so the preview is identical under pip and uv even though the engines themselves disagree. Exact pins the user typed and forced pins are checked before the engine sees them; every change the engine planned is checked after the dry run — pip's from its own report, uv's against PyPI's per-release JSON — and a violating release is ruled out as `name!=version` and re-resolved. What is left out is listed in `report.incompatible` (PD-PKG-001's preview row); a request that is nothing but such pins is `PD-PKG-001` outright. A release whose range nobody can tell is never blocked. This applies to the update and install flows; a rollback's restore set is not screened (audit backlog N4).
## 3. Update flow (state machine)
```text
@@ -36,48 +43,67 @@ 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})
│ probe + PEP 668 gate (§2), then
│ engine.resolve(PlanRequest{upgrades, strategy: Compatible}, ResolveCtx)
│ Hold pins restated at their version; Requires-Python screened (§2)
├─ error → Failed(code) catalog-classified; retry available
├─ Stop → Nothing(cancelled) nothing planned, nothing ran
└─ 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
│ · left out for Requires-Python (incompatible), yanked releases,
│ and what each forced package will break (forced)
├─ 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)
│ [Force latest] pin it to latest and release its blockers from the guard set;
│ the preview names what breaks before Confirm
│ any Force/Skip chosen → re-Resolve with overrides → PreviewReady (loop, max 3 rounds,
│ then RoundsExhausted: still confirmable, never re-decided — prevents decision ping-pong)
│ a re-Resolve that fails leaves the previous PreviewReady exactly as it was
└─ [Confirm] → Snapshotting re-probe first: preview > 10 min old or env drifted → PD-RES-002,
│ nothing written; then 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,
Phase A: single batch install of pinned set, the rest held by -c ── ok ──→ PostCheck
Stop or an environment-wide failure → a row for every package, no Phase B
Phase B (on any other A-failure): per-pkg sequential, skip-and-continue,
live stderr → console via plan-progress events
└─ PostCheck engine.check(); findings appended to summary
(a check that could not run: ok false, CheckReport.error)
└─ 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.
**Force latest forces** (1.4.0). The decision was recorded in the request and nothing read it, so the "forced" resolve was the held-back one again (C6). The flow now turns it into the resolve's `GuardAdjust`: the forced package pinned to its latest, and the packages whose constraints held it back released from the guard set. Forcing still failed in the canonical case, because the guard set pins every installed package the plan does not move — the forced package's own dependencies included (httpcore 1.0.9 needs `h11>=0.16`; the guard had `h11==0.12.0`). Which pins collide is resolution, and PipDock does not resolve (invariant 3), but the engine names them in its impossibility: `plan::forced_collisions` releases exactly those, installed and still pinned, and asks again, at most `FORCE_RELEASE_ROUNDS` (3) times. Only a forced pin releases anything — a `Hold` pin's impossibility is shown as it stands. `report.forced` carries each forced package with its blockers, which is what the preview's "Will break" rows and the CLI print.
Cancellation: allowed in Resolving and Executing, through the token the caller hands the flow before its first resolve (`FlowOptions.cancel`). In Resolving it kills the dry run and the flow ends `Nothing(cancelled)` — before 1.4.0 a resolve could not be stopped at all (H13). In Executing it kills the child's whole process tree; completed steps remain, the rest are `Skipped` and `ExecutionSummary.cancelled` is set — `StepStatus` carries no payload, so the `Skipped(UserCancelled)` this line used to name does not exist on the wire. A Stop during Phase A is that summary too, every row skipped; it used to be `PD-INT-001` with no summary and no rollback offer (C5). The snapshot offers full revert.
## 4. Install flow
```text
SearchIdle → (keystrokes) → QueryingIndex (local fuzzy, <50 ms) → Results
│ index still loading → ready: false → the screen asks again
└─ 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
queue kept until the resolve answers
```
A queued version is a PEP 440 specifier set — `==1.0`, `>=5.0,<6`, `~=1.4`, `===legacy`, or a bare version read as `==` — checked by `Spec::parse` on every way in (1.4.0). It was a plain string: `2.0 ; python_version<'0'` reached argv as one token pip read as a requirement whose marker is false, a silent no-op install, and an imported `django>=5.0,<6` failed because the flow split on `==` alone. An install never runs `list --outdated` — a sweep of the index for every installed package that nothing in an install reads (M28) — and its exact pins are screened for Requires-Python before any engine sees them (§2).
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
Selection → [Uninstall] → probe + PEP 668 gate (§2)
→ GuardCheck: reverse-dep graph over full removal set (markers evaluated, §2)
├─ 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]
→ re-probe: env changed since the guard, or guard > 10 min old → PD-RES-002, nothing written
→ Snapshot → sequential engine.uninstall per pkg (skip-and-continue) → Summary
```
@@ -89,56 +115,85 @@ user a set that still breaks something. And the removal itself refuses to run un
clear or the user explicitly accepted the breakage — `flow::GuardAck`, checked in
`UninstallFlow::execute` the way `SnapshotProof` is, so a caller that never looked at the report
cannot proceed by omission. Attempting it anyway is **PD-RES-004**, raised before the snapshot is
written so a plan that will not run leaves nothing behind.
written so a plan that will not run leaves nothing behind — and the GUI keeps the flow parked, so the
dialog's *Force remove* is still a choice rather than a button that answers "no plan".
**The guard is a decision made against a listing**, so it goes stale like a preview (§9.3). Since
1.4.0 `UninstallFlow::take_snapshot` probes again before anything is written: a package installed
after the guard ran may depend on what is about to go (M44).
A removal is blocked on a PEP 668 environment exactly as an update is: §2's preamble is "all mutating
flows", and removing from a system Python is the more dangerous of the two, since no resolver stands
between the user and the damage.
between the user and the damage. With the override on, each `uninstall` is given
`--break-system-packages`, without which pip and uv both refuse to remove from a managed environment.
## 6. Summary model (owner requirement)
```json
{ "planId":"…","phase":"B","results":[
{ "planId":"…","phase":"isolated","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":"…"}],
{"pkg":"oldlib","to":"2.0.0","status":"failed","code":"PD-BLD-002","stderrTail":"…"}],
"check":{"ok":true,"findings":[]},
"counts":{"ok":13,"failed":2,"skipped":1} }
"counts":{"ok":13,"failed":2,"skipped":1},
"cancelled":false }
```
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).
Until 1.4.0 this sample showed two things the wire has never carried. **A row has no `reason`**: the human reason is looked up from `code` in the catalogs, in either language (hard invariant 4), and a Rust-assembled English sentence on the row is exactly what that rule forbids. **`phase` is `batch` or `isolated`**, never `A`/`B`. The rest is as shipped: `from` is absent for a fresh install, and on an update it is taken from the plan's changes — the engines cannot know it, and until 1.4.0 every row carried none, so every upgrade read as a fresh install (M29); `check.error` carries the code when the post-run check could not run, with `ok` false (it said `ok: true`, M30); `cancelled` is set when the user stopped the run; `planId` is the flow's for an update or install, unique per plan and the same id its snapshot records, and the pre-execution snapshot's id for a removal or a rollback.
**A flow that ends before anything runs returns no summary.** Its last step is `{ "step": "nothing", "reason": … }`, and `reason` is one of three:
| `reason` | When | CLI exit |
|---|---|---|
| `nothing-to-do` | the request was empty once pins and `--except` were applied | 0 |
| `everything-skipped` | every candidate was skipped in the decision rounds | 2 |
| `cancelled` | the user stopped the resolve — nothing was planned and nothing ran (1.4.0, when a resolve became stoppable) | 130 |
A request that is nothing but exact pins this interpreter cannot install is not one of these: it is `PD-PKG-001`, with the range and the interpreter (§2).
## 7. Engine command mapping
| Operation | pip (`<py> -m pip …`) | uv (`uv pip … --python <py>`) | Adapter notes |
|---|---|---|---|
| List installed | *(not used — see below)* | *(not used — see below)* | `Engine::list_installed` exists and normalizes both shapes to `Dist`, but only `resolve()` calls it, to build SP-1's guard set |
| 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 — **always runs through the pip adapter**, whatever engine is configured)* | |
| List outdated | `list --outdated --format=json` | `list --outdated --format=json` | uv output pinned in SP-1 fixtures. An update asks; an install does not (M28) |
| Dry-run resolve | `install -U --dry-run --quiet --report - -r <req>` (JSON to stdout) | `uv pip install -U --dry-run -r <req>` (**text plan; no stable JSON report**), plus `--break-system-packages` under the override | uv adapter parses text; exact format frozen via SP-1 fixtures + snapshot tests. Both read the exit status first: 0 is a plan, an impossibility is `report.impossible`, anything else is classified (C3) |
| Install pinned | `install -r <pins> -c <held>` | `uv pip install -r <pins> -c <held>` | `--break-system-packages` only under the override. Phase A: the whole pinned set, everything the plan does not touch held at its current version. Phase B: one pin, the rest of the plan at its planned versions held too. Rollback: one pin, the rest of the restore held |
| Uninstall | `uninstall -y pkg` | `uv pip uninstall pkg` | One package per invocation; `--break-system-packages` only under the override |
| Env check | `check` | `uv pip check` | normalize findings: pip's `requires X, which is not installed` and `has requirement X, but you have Y`, and uv's ``The package `x` requires …`` — only the first was read, and every uv finding was filed under a package called "the" (H18) |
| Freeze (snapshots) | `freeze --all` | `uv pip freeze` | pip's `--all` includes pip/setuptools; record engine in snapshot meta, which a rollback reads (§8) |
| Upgrade pip | `install -U pip`, falling back to `-m ensurepip --upgrade` when pip cannot start | *(n/a — **always runs through the pip adapter**, whatever engine is configured)* | |
`<req>` and `<pins>` are `-r` temp files and `<held>` a `-c` one (ARCHITECTURE §8): every plan restates the installed set (SP-1), and as argv that passed Windows' command-line limit at about 1 300 packages. The `<req>` of a resolve holds three groups — the packages to move as bare names, the installs with their specifiers, and the guard set at `==` (`===` for an installed version that is not PEP 440; one that could be read as more than one token is left out, and so left alone) — plus the flow's `GuardAdjust`: forced and `Hold` pins, and `name!=version` exclusions. Every command runs under the watchdog for its kind of work (ARCHITECTURE §8), and a fired one is `PD-ENG-004`.
**Pip upkeep does not dispatch on the configured engine** (amended by Phase 3 · P1). Upgrading pip is a pip operation by definition; there is no uv way to do it, and `UvEngine::upgrade_pip` exists only to refuse. Dispatching meant `--engine uv` failed at `PD-ENG-001` for a preference that has nothing to do with the operation, on the one command with no resolver between the user and the result — while the surrounding code was already reaching past the abstraction to read pip's version. Both heads now call `PipEngine::upgrade_pip` directly. Same reasoning as the Code Health tools venv (CODE-HEALTH-SPEC §2 as amended by P2): pip is present wherever Python is, and a feature must not go dark over an unrelated setting.
The refusal it replaces is also why `PipEngine::upgrade_pip` carries its own PEP 668 guard: §2's preamble is "all mutating flows", and replacing pip in site-packages is one. `UpdateFlow` has refused since S1 and `UninstallFlow` since S5; this path had no guard at all while its only caller was a CLI command with no button behind it.
The refusal it replaces is also why `PipEngine::upgrade_pip` carries its own PEP 668 guard: §2's preamble is "all mutating flows", and replacing pip in site-packages is one. `UpdateFlow` has refused since S1 and `UninstallFlow` since S5; this path had no guard at all while its only caller was a CLI command with no button behind it. **It is not the preamble**, and 1.4.0 left it so: it reads `externally_managed` from the `PyEnv` it is handed — probed for that command by the CLI, the Environments row's in the GUI — rather than probing again, and the Settings override never reaches it, so pip upkeep on a managed Python is refused whatever the setting.
**Neither head lists installed packages through the engine.** `pipdock list` and `pkg_list` both read `probe.py` instead, because the probe carries `Requires-Dist` — which `list --format=json` does not report, and which the reverse-dependency graph, the uninstall guard and blocker attribution are all built from. Reading the engine here would give the Installed screen a different package set than the guard that protects it. The `-I` trade-off this buys is documented in ARCHITECTURE §4 and surfaced as `hidden_user_site`.
Version floors: pip ≥ 22.2 for `--dry-run --report` (offer in-app pip upgrade when older); uv minimum pinned after SP-1.
Version floors: pip ≥ 22.2 for `--dry-run --report` (offer in-app pip upgrade when older); uv minimum 0.10, pinned by SP-1 (`UV_MIN_VERSION`). Both are declared constants that nothing enforces yet (audit backlog). What a pip below 22.2 actually says is `no such option: --dry-run` — optparse stops at the first option it does not know, and in the planner's argv that is `--dry-run`, not `--report` — and since 1.4.0 that classifies as `PD-ENG-002` too.
## 8. Rollback flow
```text
Snapshot selected → Diff = (current freeze) vs (snapshot freeze)
Snapshot selected → probe + PEP 668 gate (§2)
→ Diff = (current freeze) vs (snapshot freeze); across engines pip, setuptools and wheel
are left out of it, and pip is never in {added}
→ 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
listed explicitly; user may proceed partially) — not implemented, see below
→ freeze again: changed since the preview, or preview > 10 min old → PD-RES-002, nothing written
→ snapshot current state first (rollback is itself reversible)
→ remove {added} one at a time, then restore each pin in isolation, the rest of the restore
held by -c → summary
```
**Across engines a rollback keeps pip** (1.4.0, C7). uv's freeze has no `--all`, so a uv snapshot never lists pip, setuptools or wheel; compared with pip's freeze, which does, every one of them looked added since the snapshot, and the restore uninstalled pip from the environment. `Meta::engine` had been recorded for exactly this and was read by nothing. `snapshot::restorable_diff` leaves those three out of the comparison when the snapshot's engine and the restoring engine differ, and — whichever engine — never plans pip's removal: a snapshot taken before pip arrived would otherwise take away the tool the next plan needs.
**The restore plan is a diff against one freeze**, and applied to anything else it removes and reinstalls the wrong things, so `RollbackFlow::take_snapshot` compares the freeze it is about to write with the one `start` diffed (M44). The restores are not two-phase, as this diagram used to say: `plan::execute_rollback` removes, then installs each pin on its own in `Isolated` mode, because exactness is the whole job and a batch resolve is free to pick another version; a Stop reports the step it interrupted and every one after it as skipped. It no longer runs a `pip check` between the removals and the restores.
**The dry-run resolve step is implemented in neither head**, and S6 deliberately did not add it.
`RollbackFlow::start` diffs, plans, and reports `unrestorable_lines` — the entries no index can
supply, which is what the preview lists as `PD-SNP-002`. What it does *not* do is ask the engine
@@ -146,8 +201,8 @@ whether each restore spec is still fetchable, so a release yanked since the snap
surfaces as a per-package failure at execute time rather than in the preview.
Adding it is a network round trip on an interaction budgeted as instant, and it would resolve
against the *pre-removal* environment — reporting conflicts the two-phase execution never hits,
because the removals happen first. It needs its own design, and it belongs with the engine work in
against the *pre-removal* environment — reporting conflicts the execution never hits, because the
removals happen first. It needs its own design, and it belongs with the engine work in
M3 rather than bolted onto a preview. Until then the preview's promise is precise: it lists what
*cannot* be restored, not everything that might fail.
@@ -163,16 +218,50 @@ M3 rather than bolted onto a preview. Until then the preview's promise is precis
precisely the case the feature exists for, so demanding a report would refuse the only
environments that need it. `pip_upgrade` is one IPC message parking nothing, so it needs no
waiver type either — those exist for a decision made in one message and consumed in another.
**Where:** by type. `plan::execute` takes an `AcceptedPlan`, which only `AcceptedPlan::accept`
builds; `UninstallFlow::execute` demands a `GuardAck` and checks it against the `GuardReport`
it holds (`PD-RES-004`); `RollbackFlow` executes only the `RollbackPlan` its own `start`
produced.
2. No mutating engine call without a successful snapshot write, **except pip upkeep** (added by P1).
A snapshot's only restore path is `pip install pip==X` executed *by pip*, so one taken to protect
against a broken pip has no consumer that could use it. The exemption is **made visible rather
than silent**: the confirm dialog states that no snapshot is taken. That is what keeps it an
exemption rather than an erosion — every other mutating path still writes one, and
`flow::proof_from` still refuses `NotTaken` with `PD-SNP-001`.
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.
6. **A write *outside* an environment needs a `FixConsent` accepted this session and a re-verified count, and takes no snapshot** (added by P5). Invariants 1 and 2 are scoped to a mutating **engine** call and do not reach `ruff check --fix`, which rewrites the user's *source tree*. No snapshot in this application describes one — a snapshot is a freeze, and §8's rollback is *uninstall the added, install the removed at snapshot versions* — so one taken here would have no consumer that could use it. That is invariant 2's own argument for the pip-upkeep exemption, a second time, and like that one it is **made visible rather than silent**: the confirm states that PipDock cannot undo the change and that only the user's own version control can. The safety net is therefore git, which is why `git status --porcelain` is asked twice — once to decide what the dialog *renders*, once inside the command to decide what it *allows* — and why the dirty finding lives inside `FixConsent` rather than beside it.
`flow::proof_from` still refuses `NotTaken` with `PD-SNP-001`. **Where:** `plan::execute`,
`plan::execute_uninstall` and `plan::execute_rollback` each take a `SnapshotProof` — a written
snapshot, or the CLI's named `--no-snapshot` waiver for disposable environments — and the three
flows build it in `proof_from`.
3. **A decision made against a listing of the environment is refused when it is older than 10
minutes (`PLAN_MAX_AGE`) or the environment no longer matches the listing** — `PD-RES-002`,
before any snapshot is written, so a refusal costs nothing. **Unenforced until 1.4.0 while every
test passed** (C1): the flow accepted the plan inside `execute()` with the current time, so its
age was always zero; it passed the resolve-time listing as the "current" one, so the fingerprint
always matched; and `plan::execute` compared the plan's environment hash with itself. **Where:**
`AcceptedPlan::accept` now takes the basis the report was resolved over — the probe's listing
and the resolve time — and `UpdateFlow::take_snapshot` probes the environment again after
Confirm and verifies against it; `plan::execute` verifies once more, against the hash of the
interpreter it is about to change, and acts on the re-probed listing. The rule reaches the two
flows that have no report (M44): `UninstallFlow::take_snapshot` re-probes and checks the guard's
basis (`plan::verify_basis`), since a package installed after the guard ran may depend on what
is about to go, and `RollbackFlow::take_snapshot` compares the freeze it is about to write with
the one the restore plan was diffed against (`plan::verify_age` for the age). `health_fix`
applies the drift half to a source tree (§9.1).
4. Every failure surfaced to UI/CLI carries a catalog code. **Where:** `PdError.code` is not
optional, and the classifiers fall back to `PD-ENG-999`. A *stopped* run is not a failure and is
never shown as one: a stopped step is `Skipped`, a stopped resolve is `nothing`/`cancelled` (§6),
and the typed `PdError.stop` that tells them apart never reaches the wire. A post-run check that
could not run carries its code in `CheckReport.error` rather than reading as a pass.
5. Pinned packages never appear in a `PlanRequest.upgrades` unless the user explicitly unpinned them
this session. **Where:** `pins::filter_upgrades`, inside `flow::build_request`, for a package the
update *names* as much as for one *Select all* sweeps up — the "N pinned excluded" note on screen
is presentation, and the flow's `excluded_pins()` is what a preview shows. `PinMode::Exclude`'s
doc used to promise that a pinned package could still be updated deliberately, one at a time;
nothing implemented that, and this rule was right — 1.4.0 corrected the doc, and unpinning is the
deliberate step. A `Hold` pin is also **restated at its version in every resolve**
(`GuardAdjust.pins`), so it stays put as anyone's dependency too: `pins::hold_requirements`
existed and had no caller, so a held package was only left out of the upgrade list and free to
move under it (H17).
6. **A write *outside* an environment needs a `FixConsent` accepted this session and a re-verified count, and takes no snapshot** (added by P5). Invariants 1 and 2 are scoped to a mutating **engine** call and do not reach `ruff check --fix`, which rewrites the user's *source tree*. No snapshot in this application describes one — a snapshot is a freeze, and §8's rollback is *uninstall the added, install the removed at snapshot versions* — so one taken here would have no consumer that could use it. That is invariant 2's own argument for the pip-upkeep exemption, a second time, and like that one it is **made visible rather than silent**: the confirm states that PipDock cannot undo the change and that only the user's own version control can. The safety net is therefore git, which is why `git status --porcelain` is asked twice — once to decide what the dialog *renders*, once inside the command to decide what it *allows* — and why the dirty finding lives inside `FixConsent` rather than beside it. Both ask with `-c core.fsmonitor=false` (1.4.0): a project folder that carries its own `.git/config` can name a program for `git status` to run, and asking "is it safe to write here" would have run it (M40).
### 9.1 The fix flow
@@ -185,3 +274,5 @@ ReportReady ──Fix──► Confirm(clean | dirty) ──confirm──► Ver
`Verifying` is not decoration and it is not one check. It re-reads the project read-only and refuses with **`PD-RES-002`** when the safely-fixable counts no longer match what the user confirmed — the source-tree analogue of §9's rule 3, for the one thing no snapshot describes — and it refuses with **`PD-PRM-003`** when any target cannot be written. Both happen **before the first byte**: a partial rewrite of a source tree is the worst outcome this flow can produce, because nothing here can undo half of one. ruff can fail to write a file and still exit 1, which the findings-exit rule accepts as a clean run, so the writability check cannot be a classification of the failure afterwards.
`Fixing` is a single `ruff check --fix --output-format json`, which both applies the safe fixes and reports what remains — so `FixReport.remaining` cannot describe a different moment than the fix, and the tab refreshes without a second run. Only **safe** fixes are ever applied; `--unsafe-fixes` is never passed, and `ruff format` is not wired at all (CODE-HEALTH-SPEC §7's non-goals).
**The fix's argv is the read-only run's plus `--fix`** (`health::fix::fix_argv` over `run::ruff_argv`), so it excludes exactly what the preview excluded — notebooks and the default directories (`.venv`, `venv`, `node_modules`, `build`, `dist`, `.git`) — **by construction**. Until 1.4.0 it ran `check . --fix` with none of them (C4): run against real ruff 0.17.1 it rewrote every `.ipynb` in the tree, and in a project whose `pyproject.toml` sets its own `exclude` (which replaces ruff's defaults) the files under `.venv` as well — files nobody had been shown. The fix's failures speak Code Health's codes, and a watchdog that stops it says that some files may already have been rewritten, because ruff writes as it goes (M39).
+35 -32
View File
@@ -10,51 +10,54 @@
| 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-ENG-004 | **Raised by PipDock** — an engine command ran past its watchdog (install 30 min, resolve 10 min, listing and checks 3 min) and was stopped | a very long sdist build, or a hung engine | Retry; install a slow-building package on its own. Before 1.4.0 this surfaced as PD-INT-001 and aborted the whole batch |
| 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-RES-003 | a plan is already resolving or executing | another plan is in flight in this session | Wait for it, or cancel it |
| PD-ENV-001 | interpreter path missing/not executable — checked before the probe, and since 1.4.0 also a failed spawn of an interpreter that is not there (it read as PD-ENG-001, "install the engine") | env deleted or moved | Re-scan environments; remove stale entry |
| PD-ENV-002 | **Raised by PipDock** on the fresh probe every mutating flow starts with (`flow::preamble`, DATA-FLOW §2): the `EXTERNALLY-MANAGED` marker beside the stdlib, never inside a venv — before any engine command. With the Settings override on, a flow raises it only for pip 23.0, which enforces PEP 668 and has no `--break-system-packages` (it arrived in 23.0.1); pip upkeep refuses a managed Python whatever the setting (DATA-FLOW §7). The `externally-managed-environment` stderr rule is a backstop | PEP 668 protected Python | Use a virtual env; system override only via Settings (discouraged) |
| PD-ENV-003 | probe.py non-zero / unparseable; `ModuleNotFoundError` in engine stderr | broken env metadata | Open logs; recreate the venv. A venv under a folder with non-ASCII characters no longer lands here: since 1.4.0 the probe runs under `-X utf8` (ARCHITECTURE §4) |
| PD-ENG-001 | engine binary not found: a program that cannot be started (uv not on PATH), `No module named pip`, or `ensurepip` failing to rebuild pip. A missing *interpreter* is PD-ENV-001 and an over-long command line PD-SYS-001 — both were this code before 1.4.0 | pip/uv missing | Install engine or switch engine in Settings |
| PD-ENG-002 | pip < 22.2 with plan requested: `no such option: --dry-run` (optparse stops at the first unknown option, and the planner's argv puts `--dry-run` before `--report`), `no such option: --report`, or a dry run that wrote no report | no `--dry-run --report` | One-click "Upgrade pip" then retry |
| PD-ENG-003 | uv output shape unrecognized — a plan from a uv run that **exited 0**. A non-zero exit is classified like any engine failure, which before 1.4.0 it was not: a refused connection came through as this code. pip's report in a shape PipDock cannot read is PD-ENG-999, not this — this code's advice is to switch to pip | uv newer than adapter | Update PipDock; temporarily switch engine to pip |
| PD-ENG-004 | **Raised by PipDock** — a command ran past its watchdog and was stopped (`exec::watchdog`: install and uninstall 30 min, resolve and `list --outdated` 10 min, local queries 3 min, `probe.py` 60 s). In Phase A it fails every row with no Phase B, since a hang retried per package is the same hang N times. Code Health and the audit remap it to PD-HLT-003. A stop is recognised by the error's typed `stop`, not its message, so pip's own `Read timed out` — a network failure, PD-NET-001 — is no longer mistaken for a watchdog | a very long sdist build, or a hung engine | Retry; install a slow-building package on its own. Before 1.4.0 this surfaced as PD-INT-001 and aborted the whole batch |
| PD-RES-001 | `ResolutionImpossible` / `conflicting dependencies` / uv's `No solution found when resolving`. A **report**, not an error, under both engines since 1.4.0: pip's `Cannot install A and B …` becomes `report.impossible` as uv's always did, where it used to fail the whole preview | constraints cannot be satisfied | Per-package Skip/Force choices in the preview |
| PD-RES-002 | **Raised by PipDock** after Confirm and before any snapshot: the environment is probed again, and a preview older than 10 minutes or whose installed set no longer matches the one it was resolved over is refused. The same for a removal's guard and a rollback's restore plan, and for a `ruff --fix` whose fixable counts changed. Unreachable until 1.4.0 (DATA-FLOW §9.3) | env changed since preview | Re-run preview |
| PD-RES-003 | a plan is already resolving or executing; also a cache clear while the feature that owns its target runs | another plan is in flight in this session | Wait for it, or cancel it |
| PD-RES-004 | **Raised by PipDock before the engine runs** — the reverse-dependency guard (DATA-FLOW §5) found installed dependents and execution was attempted without the user accepting the breakage | removing these packages would break others | Remove the dependents too, or force the removal knowingly |
| 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 | **Raised by PipDock before the engine runs** — `crates/pipdock-core/src/compat.rs` evaluates the candidate's `Requires-Python` against the env's version. (Engine stderr is not a reliable signal: pip reports it as plain `No matching distribution found`, indistinguishable from PD-PKG-002, and uv does not enforce it at all.) | 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-PRM-003 | a target source file is not writable | read-only attribute or ACL on a file `ruff --fix` would rewrite | Clear the read-only flag (or fix the permissions) and run the fix again. **Raised by PipDock before anything is written**, not classified from stderr: ruff can fail to write and still exit 1, which the findings-exit rule accepts as a clean run, so a stderr-matched code would arrive after the fix had reported success. Nothing is changed — the fix refuses as a whole rather than half-rewriting a source tree nothing can restore |
| PD-PKG-001 | **Raised by PipDock** — `Requires-Python` is checked by `pipdock-core` (`compat.rs` evaluates; `release.rs` supplies a release's range when the engine does not): an exact pin the user typed before any engine runs, and every change the engine planned after the dry run (ARCHITECTURE §3). A request that is nothing but such pins is this error; otherwise the release is left out and listed in `report.incompatible`, a preview row. Never raised before 1.4.0, though this row described it. (Engine stderr is still not the signal: pip ≥ 26 names the versions it ignored for their Python, but ends with `No matching distribution found`, which classifies as PD-PKG-002; uv ignores an upper bound and plans the release.) | package needs different Python | Shows required range vs env version |
| PD-PKG-002 | `No matching distribution found` (plain); uv's `was not found in the package registry` | name/version typo or yanked | Check spelling/version; `pipdock info <pkg>` |
| PD-PKG-003 | **A preview warning, not a failure, and not classified from stderr**: both engines exit 0 and install a yanked release, so the plan parsers detect it — pip's report marks it `is_yanked`, uv prints `warning: … is yanked` — and carry it in `report.yanked`, shown beside the change it belongs to. Both parsers dropped it before 1.4.0, so it never showed | the plan would install a yanked release | Pick a non-yanked version |
| PD-PKG-004 | hash mismatch / `THESE PACKAGES DO NOT MATCH THE HASHES` | corrupted download | Retry; if it repeats, clear the engine's own cache (`pip cache purge`, `uv cache clean`). PipDock has no command for that — this row named an `engine cache purge` that never existed, and the cache manager (PRD P1-4) covers PipDock's own data, not the engine's |
| PD-NET-001 | timeout / `Connection aborted` / DNS failure / uv's `tcp connect error`; `[WinError 53]` (network path not found) and `[WinError 10013]` (a firewall refusing the socket, raised *as* a `PermissionError`) — both ahead of the permission rules, which took them for PD-PRM-001 until 1.4.0 | offline or PyPI unreachable | Offline banner; retry; search stays local |
| PD-NET-002 | TLS/SSL verification failure. For PipDock's own requests — the index, metadata — read from the error's whole `source()` chain, since reqwest's top-level message never mentions the certificate: every such failure was PD-NET-001 until 1.4.0 | proxy/AV interception | Corporate proxy note; never suggests disabling verification |
| PD-NET-010 | index refresh got an answer that is not a usable index: a non-success status, a document that is not PEP 691 JSON, or an empty project list — refused since 1.4.0 rather than ingested over the index. A connection or TLS failure during the fetch is PD-NET-001/002 | PEP 691 fetch error | Retry later; stale index still searchable (staleness shown) |
| PD-NET-011 | tools venv bootstrap fetch failed — Code Health's, or the Security tab's audit venv | offline during Health setup | Health disabled until online |
| PD-PRM-001 | `PermissionError` writing site-packages; `[WinError 5]`, matched with its bracket, so `[WinError 53]` and `[WinError 59]` are not this | admin-owned Python (Program Files) | v1 blocks: use a venv (elevation is P2-3) |
| PD-PRM-002 | file lock (`[WinError 32]`, bracket included); since 1.4.0 also a file the user chose in the GUI that another program holds open (Windows' sharing violation) | package in use by a running process | Close Python processes using the env — or the program holding the file; retry |
| PD-PRM-003 | a target source file is not writable; since 1.4.0 also a file the user chose in the GUI — an export, a saved report, a requirements file to import — that cannot be read or written for lack of permission (U25: every one of those was PD-SYS-002, "not enough free disk space") | read-only attribute or ACL on a file `ruff --fix` would rewrite, or on the chosen file or folder | For the fix: clear the read-only flag (or fix the permissions) and run it again. **Raised by PipDock before anything is written**, not classified from stderr: ruff can fail to write and still exit 1, which the findings-exit rule accepts as a clean run, so a stderr-matched code would arrive after the fix had reported success. Nothing is changed — the fix refuses as a whole rather than half-rewriting a source tree nothing can restore. For a chosen file: pick another location, or fix its permissions |
| 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..004 | tool missing / non-zero / watchdog timeout / venv creation failed | tools venv issue | Re-sync tools env; partial report shown. **PD-HLT-004 is raised by PipDock**, not classified from stderr — `python -m venv` exited non-zero, so the fix is the interpreter, not another re-sync |
| 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) |
| PD-SNP-002 | rollback target release unavailable on PyPI. What raises it is a snapshot that does not exist (or whose freeze file is gone); the rollback preview also lists under it every freeze line no index can supply — editable installs, direct URLs. A release yanked or deleted since the snapshot is **not** detected in the preview (DATA-FLOW §8) and fails as that package's row at execution | deleted/yanked upstream | Partial rollback offered; affected pins listed |
| PD-SYS-001 | `path too long` / `filename or extension is too long`; also Windows error 206 from a spawn or a file PipDock writes — a command line past 32 767 characters, which a large plan reached as argv until 1.4.0 moved requirements into files | MAX_PATH without long-path opt-in | Enable Windows long paths (help link) |
| PD-SYS-002 | disk full (`No space left` / `[WinError 112]`; `ERROR_DISK_FULL` on a file PipDock writes). Until 1.4.0 the GUI answered every file failure with this code | storage | Free space |
| PD-HLT-001..004 | tool missing / non-zero / watchdog timeout / venv creation failed — for the audit venv and pip-audit as for Code Health. One tool whose output cannot be read is that tool's problem, and the other tools still report (1.4.0) | tools venv issue | Re-sync tools env; partial report shown. **PD-HLT-004 is raised by PipDock**, not classified from stderr — `python -m venv` exited non-zero, so the fix is the interpreter, not another re-sync. A PD-HLT-003 from `ruff --fix` says files may already have been rewritten |
| PD-INT-001 | panic/unexpected | PipDock bug | Report-bug deep link prefilled. A panic is written to the log by both heads' panic hook, and the CLI prints the log's path (exit 10) |
| PD-ENG-999 | unclassified engine failure; also pip's dry-run report when it is not JSON, or not version 1 (it was PD-ENG-003, whose advice is to switch to pip) | 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.
`Code::ALL` holds **35** codes; this table has **32** rows because PD-HLT-001..004 share one. `every_variant_is_listed_in_all` and `every_documented_code_has_exactly_one_variant` in `errors/catalog.rs` pin both numbers.
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 — or the code is listed, with the module that raises it, in the `internally_raised` table of `tests/classifier_corpus.rs`, which PD-ENG-004 joined in 1.4.0. **Every WinError needle includes its closing bracket**: Python prints `[WinError N]`, and the bare `winerror 5` also matched 50, 53 and 59, so `[WinError 53] The network path was not found` came out as PD-PRM-001, "use a venv". The corpus runs over `pip/`, `uv/` (uv 0.13's `error:`/`cause:` rendering) and the frozen `uv-0.11/` (miette's `×`/`╰─▶`), and `both_uv_renderings_classify_identically` pins that the two renderings classify alike. Classifying correctly was not enough: `classifier_corpus.rs` passed while uv's adapter never asked the classifier at all (DATA-FLOW §7), so `plan_parsers.rs`'s `every_failed_capture_reaches_the_user_as_the_code_it_was_captured_for` asks the function each resolve actually returns through.
## 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.
GUI: `code · localized one-liner · [Details ⌄ stderr tail ≤ 40 lines] · [Copy full log] · [Report bug]`. CLI: `error[PD-XXX-NNN]: <message>` on stderr, the stderr tail beneath it when there is one, and for an internal error (exit 10) `log: <path>` — the day's `pipdock-cli.<date>.log`. Under `--json` the error envelope is the command's one document on stdout: `{code, message, stderrTail}`, with `stderrTail` null when there is none. **There is no `reason` field**, though this line named one until 1.4.0: `message` is the core's developer-facing detail, in English, because the CLI is English-only (I18N §1), and the GUI receives the same three fields (`WireError`) and looks its one-liner up from `code`. Localization: only the one-liner and action text are localized; codes, messages 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.
1. The GUI keeps a ring buffer (last 64 KB, `LOG_RING_BUFFER_BYTES`) of engine stdout/stderr, cleared when a plan begins. It holds engine output only: PipDock's own log (`data\logs\`, new in 1.4.0) is not in it and not in the URL — Settings' Logs row copies that log's tail on its own (`logs_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").
Given the environment, `python` carries the engine's version too (`Python 3.12.4 · pip 26.2.1`); the GUI asks for it only when the user clicks, which costs a subprocess (U31).
3. URL budget: GitHub rejects very long URLs, so `log-excerpt` is cut, tail-biased, until its **percent-encoded** form fits 6 000 characters (`BUG_REPORT_EXCERPT_CHARS`). The cap was applied before encoding until 1.4.0, and encoding decides what GitHub sees — an accented letter costs up to nine bytes, a path separator three — so a log full of Vietnamese paths built a ~20 KB link and GitHub answered with an error page instead of the form (M51). The full log is not lost: the error row's *Copy full log* puts the whole ring on the clipboard (`BugReportLink.log`), and hides itself when there is nothing to copy.
4. Nothing is ever sent automatically — the user reviews the issue form in their browser. This is the entire "telemetry" story, and the row says so beside the button rather than leaving the user to guess what "Report bug" does.
Built in `pipdock_core::report` and called by both heads, so `pipdock self report-bug` and the GUI's `report_bug_url` cannot drift apart the day the template gains a field. The GUI's ring buffer is fed from **three** places, not one: the `plan-progress` forwarder, and `plan_resolve`'s success *and* failure paths — a resolve emits no progress events at all, and a plan that would not resolve is the commonest thing anyone reports. The CLI has no ring until M3's logging subsystem, so its excerpt is empty and the URL simply omits the parameter.
Built in `pipdock_core::report` and called by both heads, so `pipdock self report-bug` and the GUI's `report_bug_url` cannot drift apart the day the template gains a field. The GUI's ring buffer is fed from **three** places, not one: the progress forwarder — which every streaming command shares, so health- and audit-progress lines land there as well as plan-progress — and `plan_resolve`'s success *and* failure paths: a resolve emits no progress events at all, and a plan that would not resolve is the commonest thing anyone reports. The CLI has no ring, so its excerpt is empty and the URL simply omits the parameter. 1.4.0 gave it a log file (`pipdock-cli.<date>.log`), but `self report-bug` does not read it yet.
+6 -4
View File
@@ -4,16 +4,18 @@
## 1. Mechanics
- **GUI:** i18next + react-i18next; catalogs at `ui/src/locales/{en,vi}/{common,errors}.json`. `en` is the source of truth; `ui/src/i18n.test.ts` fails the build if `vi` is missing keys, and untranslated keys fall back to EN at runtime with a console warning, never raw key names in the UI.
- **GUI:** i18next + react-i18next; catalogs at `ui/src/locales/{en,vi}/{common,errors}.json`. `en` is the source of truth; `ui/src/i18n.test.ts` fails the build if `vi` is missing keys, and untranslated keys fall back to EN at runtime, never raw key names in the UI. **The fallback is silent**, whatever `i18n.ts`'s comment says: i18next calls `missingKeyHandler` only under `saveMissing: true`, which is off, and a key `vi` lacks but `en` has is not missing to i18next at all — so the build-time test is the only thing that notices (audit backlog U59).
**Two files, one namespace — amended in S7.** This section originally named seven namespaces. The app merges its catalogs into a single `common` at init, because a real second namespace means `t('errors:PD-NET-001')` at every call site (i18next's `nsSeparator` is `:`) — churn across every screen, bought with lazy loading a desktop app that bundles both catalogs cannot use. The **error codes still get their own file**, and that part earns itself: there are 34 of them, they are the only keys whose names are a contract with Rust rather than with a screen, and the test checks them against a generated copy of `Code::ALL` rather than against a list someone maintains by hand.
**Two files, one namespace — amended in S7.** This section originally named seven namespaces. The app merges its catalogs into a single `common` at init, because a real second namespace means `t('errors:PD-NET-001')` at every call site (i18next's `nsSeparator` is `:`) — churn across every screen, bought with lazy loading a desktop app that bundles both catalogs cannot use. The **error codes still get their own file**, and that part earns itself: there are 35 of them (PD-ENG-004 made the thirty-fifth in 1.4.0), they are the only keys whose names are a contract with Rust rather than with a screen, and the test checks them against a generated copy of `Code::ALL` rather than against a list someone maintains by hand.
- **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.
**One stated exception, since 1.4.0: the startup-failure dialog.** When the data folder cannot be opened, the GUI says so before Tauri starts — so before any webview exists to load a catalog. `startup_failed` in `src-tauri/src/lib.rs` is therefore the one place GUI copy is written in Rust, and it is written in **both languages at once**, an English sentence and then a Vietnamese one (the stored language choice is in the folder that could not be opened), followed, untranslated, by the catalog code, the error's own message and the log's path. Before 1.4.0 the same failure was a panic inside Tauri's setup hook, and a release build has no console: the user double-clicked and nothing happened. Anything added to that dialog is added in both languages there, because no catalog can reach it.
- **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, error codes, **email addresses, URLs and SPDX identifiers** are **never** translated or reshaped.
Default locale = OS UI language if `vi`, else `en`; switchable in Settings, applied live, and **stored** (since 1.4.0). `settings.locale` holds the user's explicit choice and `null` means "follow the OS"; the two are kept apart so that saving any other setting cannot pin the language the OS happened to resolve to. Until 1.4.0 every save sent `null`, so a choice lasted until the window closed. Settings load at start, before the legal gate, so the gate is shown in the chosen language too. **`<html lang>` follows the UI language**: `index.html` ships `lang="en"` and nothing changed it, so a screen reader read Vietnamese copy as English. Dates via `Intl.DateTimeFormat` with the active locale; file sizes binary (MiB) with locale decimal separators. Not yet everywhere for dates: the snapshot timeline formats its own, but Code Health's and the Security tab's "Checked …" lines print the report's raw timestamp (audit backlog U50). Package names, versions, engine output, error codes, **email addresses, URLs and SPDX identifiers** are **never** translated or reshaped.
The last three live as TypeScript constants beside the component that renders them, not in the catalogs — a catalog entry is a thing a translator is invited to change, and an address they changed would route mail nowhere. They reach JSX as *expressions*, which is also what keeps the `pipdock/no-jsx-literals` rule (§1) correct about them: it examines JSX text and string literals inside expression containers, never an identifier. `PdAbout`'s `CONTACT`, `PdSettings`'s engine ids and `PdEmptyState`'s glyph are the same escape hatch used for the same reason.
@@ -42,4 +44,4 @@ The last three live as TypeScript constants beside the component that renders th
## 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.
Pseudo-locale (`en-XA`-style bracketed expansion) to catch clipping — development only, toggled with `Ctrl+Alt+P` under `npm run dev`, never offered in Settings and never in a release bundle; 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.
+9 -9
View File
@@ -22,7 +22,7 @@ PipDock's thesis: **don't reimplement the resolver — explain it.** Wrap pip/uv
- G4 — Core happy paths complete in **≤ 5 clicks** (see UI-SPEC click budgets).
- G5 — GUI and CLI share **one Rust core**; behavior never diverges.
- G6 — PipDock **never modifies its own runtime** (standalone binary; the managed environments are external).
- G7 — Zero telemetry; **PyPI is the only host PipDock connects to.** It does not update itself, so it never calls home; GitHub, the ruff docs and the author's contact page are only ever handed to the browser as a link the user clicked (SECURITY §4/§5).
- G7 — Zero telemetry; **PyPI is the only host PipDock connects to.** It does not update itself, so it never calls home; GitHub, the ruff docs, OSV's advisory pages and the author's contact page are only ever handed to the browser as a link the user clicked (SECURITY §4/§5).
## 3. Personas
@@ -39,31 +39,31 @@ PipDock's thesis: **don't reimplement the resolver — explain it.** Wrap pip/uv
| # | 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-1 | Environment discovery & switcher | PEP 514 registry + `py -0p` + `uv python list` + known venv dirs + manual browse. Recents persisted. **Manual browse is not built:** `env_add_manual` is the one command still owed (`NOT_YET`), so a venv is found only as a `.venv`, `venv`, `env` or `.env` in the working directory, or named with the CLI's `--env`. **Recents:** the CLI's `env use` default is stored and, since 1.4.0, honoured; the GUI's selection lasts for the session. |
| P0-2 | PEP 668 guard | Detect `EXTERNALLY-MANAGED`; block by default with explanation; explicit opt-in override only. **The override works since 1.4.0.** It saved and nothing read it, so turning it on changed nothing — and the guard decided on whatever the caller last cached, while the rollback flow had no guard at all. Every mutating flow now decides on a fresh probe; turning the override on asks first, and a chip is shown wherever it applies (SECURITY §3). |
| P0-3 | Installed list | Per-env; up-to-date rows dimmed; outdated rows badged and mirrored into Updates tab. |
| P0-4 | Updates flow | Group dry-run resolve → preview diff → 3-way conflict choices → two-phase execution → `pip check` post-verify → summary report. |
| P0-4 | Updates flow | Group dry-run resolve → preview diff → 3-way conflict choices → two-phase execution → `pip check` post-verify → summary report. **Three parts of this worked only from 1.4.0:** *Force latest* was recorded and never read, so a forced resolve was the held-back one again — it now forces, and the preview names what it breaks before anything runs (DISCLAIMER §2); a post-run check that could not run reported `ok`, and now says it could not; and PipDock enforces `Requires-Python` itself (hard invariant 10), where PD-PKG-001 had never been raised. |
| P0-5 | Search & install | Local PEP 691 name-index cache + fuzzy search; per-package metadata on demand (PyPI JSON API); install queue ("dock bay"). |
| P0-6 | Bulk uninstall + reverse-dep guard | Warn "removing X breaks Y, Z" before execution; `--force` override. |
| P0-7 | Pins | Per-env pin list; pinned packages excluded from *Select all*; lock icon in lists. |
| P0-8 | Snapshots & rollback | Auto snapshot (freeze + metadata) before every batch; diff view; minimal-ops rollback. |
| P0-9 | Engine setting (pip / uv) | Auto-detect uv on first run; switch any time in Settings; engine badge in status bar. |
| P0-9 | Engine setting (pip / uv) | Auto-detect uv on first run; switch any time in Settings; engine badge in status bar. **Auto-detect is not implemented, and is owed** (audit backlog X19): a fresh install drives pip (`Settings::default`). `settings.rs` places the detection in Settings, as a choice made where it can be seen, rather than in a read of an empty store — and the CLI follows the stored setting rather than probing `PATH` — but nothing in Settings makes it yet. What exists since 1.4.0 is the half it needs: Settings shows each engine's version for the selected environment beside its radio, *not found* when it is not installed. |
| P0-10 | pip upkeep | Show pip version per env; one-click `python -m pip install --upgrade pip`. |
| P0-11 | Code Health tab | deptry + vulture + ruff from PipDock's isolated tools env; report + safe `ruff --fix`. (Promoted to v1 by owner decision 2026-07.) |
| P0-12 | CLI core parity | env / list / search / install / update / uninstall / pin / snapshot / doctor / health. JSON output. |
| P0-13 | Legal gate | First-run modal: EULA, License, Disclaimer, Privacy, Third-Party → GitHub links; consent stored with docs-version hash. |
| P0-14 | i18n EN + VI | GUI fully localized; CLI English-only in v1. |
| P0-15 | Summary reports | "13 successful, 2 failed" + per-package error-catalog reason; copy log; Report-bug deep link. |
| P0-16 | Structured logging | Rolling local log files (tracing); in-app live console during execution. |
| P0-15 | Summary reports | "13 successful, 2 failed" + per-package error-catalog reason; copy log; Report-bug deep link. Since 1.4.0 each row says what it moved from, and the bug report carries the environment's Python version and the engine's. |
| P0-16 | Structured logging | Rolling local log files (tracing); in-app live console during execution. **Met in 1.4.0.** The live console shipped earlier; the log files did not exist until then — `tracing` was a dependency of three crates and called zero times. Now one file per UTC day under `%LOCALAPPDATA%\PipDock\data\logs\` (`pipdock.<date>.log` for the GUI, `pipdock-cli.<date>.log` for the CLI, so the two never interleave), swept after 14 days: every spawn's argv, exit code and duration, each resolve, snapshot and run outcome, a panic's report, and at DEBUG the engine's own lines. The CLI's `--verbose` and `--log-file` work; Settings shows the folder and copies the recent log; a GUI that cannot open its data folder says so in a dialog naming the log. Nothing in it is sent anywhere. |
### P1 — v1.x
| # | Feature | Notes |
|---|---|---|
| P1-1 | **Shipped 1.2.0.** Security tab | pip-audit (freeze-file mode) listing known advisories per installed package. **Not severity-sorted, because pip-audit has no severity field** — under either vulnerability service its findings carry only `id`, `fix_versions`, `aliases` and `description`, verified against the pinned 2.10.1. Ordered by package, then by whether anything *fixes* it, then by id: the one distinction that changes what the user can do. The CVE is an **alias**; the primary id is a `PYSEC-*`. |
| P1-2 | Pin auto-suggest | **Shipped post-1.0 (P1-A).** Reverse-dependency count ≥ threshold (default 5, configurable in Settings; zero is off) ⇒ suggest pin with reason. Counts in-force edges only — extras and other-Python markers do not qualify a package. |
| P1-2 | Pin auto-suggest | **Shipped post-1.0 (P1-A).** Reverse-dependency count ≥ threshold (default 5, configurable in Settings; zero is off) ⇒ suggest pin with reason. Counts in-force edges only — extras and other-Python markers do not qualify a package, and since 1.4.0, when platform markers began to be read, neither do requirements gated to another platform. |
| P1-3 | **Shipped 1.1.0.** Export / import | `requirements.txt` and `constraints.txt` export; import-as-queue. |
| P1-4 | **Partly shipped, 1.1.0.** Cache manager | Shows and clears **PipDock's own** disk usage: snapshots and the Code Health tools venv. `index.db` is reported but not clearable — it holds settings, pins and the consent record in the same file, so "clear the cache" must never take them. **The engine caches (`pip cache`, `uv cache`) are not covered** and are a separate item: they belong to the engine, live outside `%LOCALAPPDATA%\PipDock\`, and purging them is a subprocess rather than a file delete. |
| P1-4 | **Partly shipped, 1.1.0.** Cache manager | Shows and clears **PipDock's own** disk usage: snapshots, the Code Health tools venv and, since 1.2.0, the Security tab's audit venv. Logs (1.4.0) are not a target — the sweep keeps 14 days and nothing more, and Settings' Logs row says where they are. `index.db` is reported but not clearable — it holds settings, pins and the consent record in the same file, so "clear the cache" must never take them. **The engine caches (`pip cache`, `uv cache`) are not covered** and are a separate item: they belong to the engine, live outside `%LOCALAPPDATA%\PipDock\`, and purging them is a subprocess rather than a file delete. |
| P1-5 | **Shipped 1.1.0.** Command palette | Ctrl+K fuzzy action launcher (terminal-tech signature feature). |
| P1-6 | **Shipped 1.3.0.** Dependency view | "Who holds this back" for a selected package: the focused package between its dependents and its dependencies, each edge carrying the specifier written on it, each neighbour clickable to re-centre, plus the two transitive counts and any requirement nothing installed satisfies. **Not a node-link diagram, and that is a measurement rather than a shortcut** — on a 352-package environment a depth-1 neighbourhood is a median of 7 nodes but depth 2 is a median of 172 and exceeds 60 for 212 of 352 packages, and there are over 2000 distinct paths from `setuptools` to a root. So it is drawn at depth 1, depth is navigated by re-centring, and the transitive answer is a count. Added no runtime dependency. |
| P1-7 | Scheduled check | Optional background outdated-check with toast (no auto-apply, ever). |
+56 -30
View File
@@ -1,48 +1,58 @@
# PipDock — Release & CI
*Version 0.2 · 2026-07-27 · CI reuses the `poli0981/.github` ops repo where a suitable reusable workflow exists, and is project-local where one does not. The ops repo's suite was audited on 2026-07-27 (see §1 note) — do not assume a reusable exists without checking.*
*Version 0.2 · 2026-07-27 · CI reuses the `poli0981/.github` ops repo where a suitable reusable workflow exists, and is project-local where one does not. The ops repo's suite was audited on 2026-07-27, and its CodeQL and notifier reusables re-read on 2026-10-17 (see §1 note) — do not assume a reusable exists without checking.*
## 1. Workflows (`.github/workflows/`)
| Workflow | Kind | Triggers | Jobs |
|---|---|---|---|
| `ci-rust.yml` | **project-local** | PR, push main | `windows-latest`: `cargo fmt --check`, clippy `-D warnings`, `cargo test --locked`, `cargo audit` |
| `ci-node.yml` | caller → ops `reusable-web-react.yml` + one local job | PR, push main | Node 24, `npm ci`, lint / typecheck / Vitest (each runs only if the npm script exists), `vite build`; local job adds `npm audit --audit-level=high` |
| `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` | caller → ops `reusable-codeql.yml` | PR, schedule | `languages: '["javascript-typescript"]'` only |
| `release.yml` | **project-local** | tag `v*` | `windows-latest` build, sign, bundle, publish (see §3) |
| `announce-release.yml` | caller → ops `announce-release.yml` | release published | Discord release announcement |
| `notify-ci-failure.yml` | caller → ops `notify-ci-failure.yml` | `workflow_run` completed | Discord CI-failure notification |
| `ci-rust.yml` | **project-local** | PR, push main | `fmt · clippy · test` (`windows-latest`): `cargo fmt --check`, clippy `-D warnings`, `cargo test --workspace --locked`. `cargo audit` (`ubuntu-latest`): a prebuilt `cargo-audit`, `--deny warnings`. `cargo deny` (`ubuntu-latest`): licences, sources, bans (`deny.toml`) |
| `ci-node.yml` | caller → ops `reusable-web-react.yml` + two local jobs | PR, push main | Node 24, `npm ci`, lint / typecheck / Vitest (each runs only if the npm script exists), `vite build`; local jobs `npm audit --audit-level=high` (after `npm ci --ignore-scripts`) and `tauri lockstep` (`scripts/check-tauri-lockstep.mjs`) |
| `ci-integration.yml` | project-local | PR touching what its end-to-end steps run through (the path list is in the file), nightly, Mondays, dispatch | Windows runner, Python 3.10 and 3.14: the disposable-venv suite (TESTING L2); Mondays and dispatch only, the fixture-drift re-capture against the newest pip and uv |
| `codeql.yml` | caller → ops `reusable-codeql.yml` | PR, push main, weekly | `languages: '["javascript-typescript", "rust", "actions"]'` |
| `security-scan.yml` | **project-local** | daily, dispatch | `cargo audit` and `npm audit` against `main` (SECURITY §7) |
| `release.yml` | **project-local** | tag `v*`; dispatch (`tag`, `dry_run`) | `Build · checksum` (`windows-latest`, read-only) → `Attest · draft` (`ubuntu-latest`); see §3 |
| `announce-release.yml` | caller → ops `announce-release.yml` | release published; dispatch (re-runs) | Discord release announcement |
| `notify-ci-failure.yml` | caller → ops `notify-ci-failure.yml` | `workflow_run` completed for `CI / Rust`, `CI / Node`, `CI / Integration`, `Security scan` — **by name** | Discord CI-failure notification |
**Ops-repo audit (2026-07-27) — why the table looks like this:**
**`notify-ci-failure.yml` names its workflows, and a new workflow is added to it by its exact `name:`.** `workflows: ['*']` — the ops repo's own caller example — is not a wildcard to `workflow_run`: it matched nothing, so `main` stayed red from 2026-09-23 with every failure unreported. The reusable reports only failures on the default branch, and skips by name any workflow that has a dedicated notifier (CodeQL, Dependabot, deploy, Pages, release), which is why `CodeQL` and `Release` are not listed: listing them would only create skipped runs. A failed `Release` run therefore reaches no Discord channel; whoever pushed the tag has to watch it.
- The reusable suite covers assembly, c-cpp, chrome-extension, desktop-csharp, go, jvm, macos-swift, php, python, r, ruby and web-react. **There is no Rust reusable and no Tauri reusable**, and only `reusable-desktop-csharp.yml` uses a Windows runner — hence `ci-rust.yml` and `release.yml` are project-local.
**Ops-repo audit (2026-07-27; CodeQL and the notifier re-read 2026-10-17) — why the table looks like this:**
- The reusable suite covers assembly, c-cpp, chrome-extension, desktop-csharp, go, jvm, macos-swift, php, python, r, ruby and web-react. **There is no Rust reusable and no Tauri reusable**, and only `reusable-desktop-csharp.yml` uses a Windows runner — hence `ci-rust.yml`, `release.yml` and `security-scan.yml` are project-local.
- `reusable-web-react.yml` has **no `working-directory` input** (it runs `npm ci` at the repo root — hence `package.json` lives at the root with Vite's `root: './ui'`, see ARCHITECTURE §2) and **no `npm audit` step**, hence the extra local job.
- `reusable-codeql.yml` supports csharp, python, javascript-typescript, ruby, c-cpp, java-kotlin, go and swift. **CodeQL has no Rust analyzer**, so Rust security coverage comes from clippy `-D warnings` + `cargo audit` in `ci-rust.yml`, not from CodeQL.
- `reusable-codeql.yml` *documents* csharp, python, javascript-typescript, ruby, c-cpp, java-kotlin, go and swift, but hands `languages` straight to `codeql-action`, with `build-mode: none` for anything outside its autobuild list — so `rust` and `actions` run through it unchanged. This bullet said **CodeQL has no Rust analyzer**, so Rust's coverage came from clippy and `cargo audit` alone; the premise stopped being true in 2025, and `codeql.yml` now asks for both. Only the JavaScript/TypeScript analysis is a required check (§2).
- Portfolio notifications are **Discord-only**, driven by the ops repo's `.github/scripts/discord_notify.py`. There is no multi-platform `notify.py`.
**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 }
permissions: { actions: read, contents: read, packages: read, security-events: write }
# announce-release.yml / notify-ci-failure.yml
permissions: { contents: read, actions: read }
# release.yml
permissions: { contents: write } # release assets
# ci-*.yml
# ci-node.yml — the workflow, and the one job that calls the reusable
permissions: { contents: read }
# web: { contents: read, pages: write, id-token: write }
# release.yml — the workflow, then each job (§3)
permissions: { contents: read }
# build: { contents: read }
# publish: { contents: write, id-token: write, attestations: write }
# ci-rust.yml / ci-integration.yml / security-scan.yml
permissions: { contents: read }
```
**The lesson has a converse: a caller must grant at least what the callee's jobs declare, even for a job that will be skipped**, because permissions are validated at startup regardless of `if:`. `reusable-codeql.yml`'s analyze job asks for `packages: read`, and a caller without it got a `startup_failure` with no logs to explain it; `reusable-web-react.yml` declares a Pages-deploy job needing `pages: write` and `id-token: write`, skipped here by `deploy-pages: false` and validated all the same. A write is granted on the job that needs it, never the workflow (SonarCloud S8233), so no other job holds one. This block showed neither of those grants and gave `release.yml` `contents: write` across the board; since 1.4.0 the release's write lives on its publish job alone.
## 2. Branch & version policy
`main` protected (PR + green CI required). SemVer; tags `vX.Y.Z`. Conventional commits feed the changelog generator.
`main` protected (PR + green CI required). SemVer; tags `vX.Y.Z`, and `release.yml` refuses a tag that does not match all five version fields (§3). Commit subjects follow Conventional Commits, but nothing generates a changelog from them — this line said a generator did. `changelog/` is written by hand, for a user, under the rules in `changelog/README.md`; a draft release's notes are GitHub's generated list of merged pull requests.
**Applied 2026-08-14, and it had been false until then** — `/branches/main/protection` returned 404 for four milestones, which is also why `gh pr merge --auto` merged immediately on this repo rather than waiting: with no required checks there is nothing for auto-merge to wait on. Exact settings:
**Protection was applied 2026-08-14, and had been false until then** — `/branches/main/protection` returned 404 for four milestones, which is also why `gh pr merge --auto` merged immediately on this repo rather than waiting: with no required checks there is nothing for auto-merge to wait on. Exact settings:
| Setting | Value | Why |
|---|---|---|
| Required checks | `fmt · clippy · test`, `cargo audit`, `lint · typecheck · test · build / build`, `npm audit`, `analyze / Analyze (javascript-typescript)` | the five that run on **every** PR |
| Required checks | `fmt · clippy · test`, `cargo audit`, `lint · typecheck · test · build / build`, `npm audit`, `analyze / Analyze (javascript-typescript)` | the five that ran on **every** PR when the payload was set; four more do now (below) |
| Check app | pinned to `app_id: 15368` (`github-actions`) | a check from another app cannot satisfy a requirement |
| `enforce_admins` | `true` | the owner is the only contributor; protection that exempts them protects nothing |
| Required approvals | **0** | a solo owner cannot approve their own PR, so 1 would deadlock. A PR is still required |
@@ -50,27 +60,42 @@ permissions: { contents: read }
| Linear history | `true` | matches rebase-merge |
| Force pushes / deletions | `false` | |
**`CI / Integration` is deliberately excluded, and this is the trap worth remembering:** its `pull_request` trigger is `paths:`-filtered, so on a docs-only or UI-only PR it never starts — and a required check that never starts stays *pending forever*. Requiring it would deadlock exactly the PRs it has no opinion about. `Re-capture against the latest engines` is schedule-only and excluded for the same reason. The bare `CodeQL` check belongs to the `github-advanced-security` app rather than Actions and is left out too.
**`CI / Integration` is deliberately excluded, and this is the trap worth remembering:** its `pull_request` trigger is `paths:`-filtered, so on a docs-only or UI-only PR it never starts — and a required check that never starts stays *pending forever*. Requiring it would deadlock exactly the PRs it has no opinion about. `Re-capture against the latest engines` runs on no PR at all (Mondays and dispatch only) and is excluded for the same reason. The bare `CodeQL` check belongs to the `github-advanced-security` app rather than Actions and is left out too.
**Four more run on every PR and are not in the payload** — `cargo deny`, `tauri lockstep`, and CodeQL's `analyze / Analyze (rust)` and `analyze / Analyze (actions)` — all added in 1.4.0, after the five above were set (re-read 2026-10-17; the payload is unchanged). Until they are added, a red one is advice rather than a gate, which matters most for `tauri lockstep`: its whole purpose is to stop one half of a Tauri bump merging alone. `Security scan` runs on no PR and can never be required.
**Two required contexts are named by the ops repo, not by this one.** `analyze / Analyze (javascript-typescript)` and `lint · typecheck · test · build / build` come from `poli0981/.github`'s reusables. If either job is renamed upstream, every PipDock PR deadlocks with no obvious cause and no failing check to point at — the fix is to update the protection payload, not the code.
**If protection wedges**, `PUT` the same endpoint with `enforce_admins: false`, or `DELETE /branches/main/protection`. Worth knowing before it is needed rather than discovering it during an incident.
Dependency updates use **Dependabot** (`.github/dependabot.yml`) — the portfolio standard, as evidenced by the ops repo's `dependabot-summary.yml`; there is no Renovate configuration anywhere in the ops repo. Four ecosystems: `cargo`, `npm`, `github-actions`, and `pip` scoped to `tools-requirements.txt` (the Code Health pins). Weekly schedule with minor/patch grouped per ecosystem; security advisories arrive as **immediate, ungrouped** PRs (Dependabot's default for security updates), and the `pip` ecosystem stays its own group so Code Health pin bumps are reviewable in isolation. Watching `pip`/`uv` releases to trigger the parser-fixture job is the scheduled job in `ci-integration.yml`, not the dependency bot.
Dependency updates use **Dependabot** (`.github/dependabot.yml`) — the portfolio standard, as evidenced by the ops repo's `dependabot-summary.yml`; there is no Renovate configuration anywhere in the ops repo. **Five ecosystems**, weekly on Mondays: `cargo`, `npm`, `github-actions`, `pip` at `/tools` (the Code Health pins) and, since 1.4.0, `rust-toolchain` — the `rust-toolchain.toml` channel, in a PR of its own because a toolchain brings new clippy lints. Minor and patch updates are grouped per ecosystem; security advisories arrive as **immediate, ungrouped** PRs (Dependabot's default for security updates), and the `pip` ecosystem stays its own group so Code Health pin bumps are reviewable in isolation — a bump there also needs `tools/tools-constraints.txt` regenerated (the command is in its header), and `cargo test` fails until it is (CODE-HEALTH-SPEC §2). Watching `pip`/`uv` releases to trigger the parser-fixture job is the scheduled job in `ci-integration.yml`, not the dependency bot. Since 1.4.0:
- **Cooldowns.** A release must be 3 days old before cargo or npm proposes it (14 for a major), and 7 for Actions and the tool pins. Most yanked or compromised releases are pulled inside that window, and nothing here needs a dependency the day it ships.
- **Tauri moves in lockstep.** The `tauri` crate and `@tauri-apps/api` must share a minor or the app refuses to start, and Dependabot bumps Cargo and npm in separate PRs, each green on its own. So each ecosystem groups its Tauri packages (`tauri`, `tauri-*`; `@tauri-apps/*`) ahead of its catch-all group, and `ci-node.yml`'s `tauri lockstep` job fails either PR until its counterpart lands beside it, comparing the core and each plugin with its npm package on `Cargo.lock` and `package-lock.json` — what is built, not what the manifests ask for. **A multi-ecosystem group was considered and not used:** it would put both halves in one PR, but what it does to the dependencies outside its patterns is undocumented, and a wrong guess would silently stop every other update.
- **TypeScript is held below 6.1** (`ignore: typescript >=6.1.0`): typescript-eslint 8.71 peers `typescript >=4.8.4 <6.1.0`, so a 6.1 bump fails `npm ci` with ERESOLVE before a single check runs. Remove it once typescript-eslint widens its range.
- **Labels.** PRs are labelled `dependencies` plus `rust`, `frontend`, `ci` or `code-health`, and the labels must exist in the repository or Dependabot opens its PRs without them (§5).
## 3. Release pipeline (tag `v*`)
1. Windows runner: `npm ci` → **`npm run bundle`**, producing NSIS `.exe` + `.msi`. That one script owns the whole recipe so the workflow cannot drift from what a developer runs locally, and it encodes two things that are easy to get wrong:
Two jobs, so the token that can write a release never runs the build (SECURITY §5).
- **`--locked` goes after `--`.** It is cargo's flag; `tauri build` rejects it as its own with *"unexpected argument"* before a single crate compiles.
- **The CLI sidecar is declared in an overlay** (`src-tauri/tauri.bundle.conf.json`, merged with `--config`), not in `tauri.conf.json`. `tauri-build` validates `externalBin` at build-script time, so declaring it in the base config makes plain `cargo clippy` and `cargo test` fail in a fresh clone with *"resource path … doesn't exist"* — a bundling concern leaking into every compile.
1. **`Build · checksum`** — Windows runner, a read-only token, and no credentials kept in the checkout (`persist-credentials: false`).
- **The tag and all five version fields must agree** — `Cargo.toml`, `Cargo.lock` (`pipdock-core`'s entry), `package.json`, `package-lock.json` and `tauri.conf.json` — or the job stops before building. A tag pushed ahead of its bump commit, or a bump that missed a file, would otherwise build an installer whose About states another version.
- `npm ci` → **`npm run bundle`**, producing NSIS `.exe` + `.msi`. That one script owns the whole recipe so the workflow cannot drift from what a developer runs locally, and it encodes two things that are easy to get wrong:
- **`--locked` goes after `--`.** It is cargo's flag; `tauri build` rejects it as its own with *"unexpected argument"* before a single crate compiles.
- **The CLI sidecar is declared in an overlay** (`src-tauri/tauri.bundle.conf.json`, merged with `--config`), not in `tauri.conf.json`. `tauri-build` validates `externalBin` at build-script time, so declaring it in the base config makes plain `cargo clippy` and `cargo test` fail in a fresh clone with *"resource path … doesn't exist"* — a bundling concern leaking into every compile.
The frontend is built by tauri's `beforeBuildCommand`, so the workflow does not run `vite build` itself.
2. Compute and publish `SHA256SUMS.txt`.
3. Draft GitHub Release with generated changelog; manual publish (owner review) → `announce-release.yml` fires the Discord announcement.
4. Post-release checklist issue auto-opened: verify SmartScreen behavior, spot-check EN/VI in the shipped build.
The frontend is built by tauri's `beforeBuildCommand`, so the workflow does not run `vite build` itself.
- **`SHA256SUMS.txt`**, LF line endings, written byte for byte: `Set-Content` wrote CRLF, and `sha256sum -c` on any other platform reads the CR as part of the file name and reports the file missing.
- The installers and the checksums are uploaded as the `release-artifacts` workflow artifact.
2. **`Attest · draft`** — Ubuntu runner, the only job granted `contents`, `id-token` and `attestations` write. It downloads the build, attests build provenance for the `.exe` and the `.msi` (`actions/attest-build-provenance`, verifiable with `gh attestation verify <file> --repo poli0981/pipdock`), and drafts the GitHub release with GitHub's generated notes and all three files (`softprops/action-gh-release`). Both actions are pinned by commit.
3. **Publishing the draft is a human decision**, taken per release; publishing fires `announce-release.yml`'s Discord announcement. For 1.4.0 the owner approved the plan and instructed the assistant to check the installers against `SHA256SUMS.txt` and then publish — `docs/AI-DISCLOSURE.md` records who did what.
There is no signing step. **PipDock does not update itself** (SECURITY §5), so no `latest.json` is produced, no artifact is signed, and no keypair exists to manage.
**A dry run** — `workflow_dispatch` with `dry_run` — builds and checksums any ref, a branch before it merges included, and attests and drafts nothing, so the release recipe is tested before a tag depends on it. Without `dry_run`, dispatch builds a version tag only (the `tag` input re-runs one); a branch is refused.
This list had a fourth step — a post-release checklist issue, opened automatically, for SmartScreen behaviour and an EN/VI spot-check of the shipped build. No workflow has ever opened one. Those checks belong to the per-release manual charter (TESTING §4).
There is no signing step. **PipDock does not update itself** (SECURITY §5), so no `latest.json` is produced, no artifact is code-signed, and no keypair exists to manage. The attestation is signed through Sigstore with a short-lived certificate bound to the workflow run — which is why the publish job needs `id-token: write` — so it adds no key either.
Secrets bootstrap: set per-repo with `gh secret set` (the ops repo has no `setup-secrets.sh`) — the Discord webhooks the ops-repo notifiers expect (`DISCORD_RELEASES_WEBHOOK`, `DISCORD_REPO_WEBHOOK`, `DISCORD_CI_WEBHOOK`; the callers pass `secrets: inherit`). That is the whole list.
@@ -82,14 +107,15 @@ Two active lines at most: latest release gets features; previous minor gets secu
- [x] 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).
- [x] `.github/ISSUE_TEMPLATE/bug_report.yml` (shipped in this suite) + `config.yml` disabling blank issues.
- [x] `.github/dependabot.yml` covering cargo, npm, github-actions and the Code Health pins.
- [x] `.github/dependabot.yml` covering cargo, npm, github-actions and the Code Health pins — and the Rust toolchain since 1.4.0.
- [x] `rust-toolchain.toml`, `.nvmrc` (24), `Cargo.lock`/`package-lock.json` committed.
- [x] **Repo settings (owner, via the GitHub UI or `gh` — not committable):** branch protection on `main`; disable Advanced Security → CodeQL *Default setup* (the reusable is advanced-setup and is rejected at upload time otherwise); enable Discussions for the issue-template contact links.
- [x] **Secrets via `gh secret set`:** the Discord webhooks (`DISCORD_RELEASES_WEBHOOK`, `DISCORD_REPO_WEBHOOK`, `DISCORD_CI_WEBHOOK`). No signing key — see §3.
- [x] App icon settled (`src-tauri/icons/`). It was called a placeholder because nobody had chosen it; the owner chose it in Phase 4, which is what "a brand decision" needed.
- [x] README badges: CI, CodeQL, release, license.
- [ ] **Labels (owner, repo settings — opened by 1.4.0):** `dependencies`, `rust`, `frontend`, `ci` and `code-health` for Dependabot (§2), and `triage` for `bug_report.yml`. None existed on 2026-10-17, so Dependabot's PRs arrive unlabelled and a bug report gets `bug` alone.
**Closed 2026-08-14, and three of the last four were already true.** CodeQL *Default setup* read
`not-configured` and Discussions were already on — both had been done and never ticked, which is
its own small lesson about a checklist nobody reads back. The Discord secrets were set the same
day. Branch protection was the only genuinely outstanding item; §2's exact settings are below.
day. Branch protection was the only genuinely outstanding item; §2's exact settings are above.
+125 -5
View File
@@ -740,7 +740,7 @@ Three things it settled that outlive it:
## 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. **Five of the seven have shipped** — four in 1.1.0 and the Security tab in 1.2.0; the graph view and the scheduled check remain. Then P2 candidates by demand: macOS/Linux, per-env engine, elevation broker, winget, JP locale.
Security tab (pip-audit), pin auto-suggest, requirements/constraints export-import, cache manager, command palette, dependency graph view, scheduled check. **Six of the seven have shipped** — four in 1.1.0, the Security tab in 1.2.0 and the dependency view in 1.3.0; the scheduled check remains. Then P2 candidates by demand: macOS/Linux, per-env engine, elevation broker, winget, JP locale.
**About shipped early, in Phase 4** — see above. Two smaller items were added to this wave rather
than done at 1.0:
@@ -980,8 +980,9 @@ Nine words of PRD, and **every prerequisite is absent.** Counted against the tre
- **Nothing runs on a timer.** One `tokio::spawn` in the whole Tauri crate, plan-scoped, and zero
occurrences of `tokio::time::interval` or `setInterval` in either head.
- **No surface can report a background failure.** `⚠ n` counts mounted `PdErrorRow`s, the `LogRing`
is cleared per plan, `logs_tail` is still one of the two `NOT_YET` entries, and the console toggle
is disabled while idle. A check that failed at 03:00 has nowhere to say so.
is cleared per plan, and the console toggle is disabled while idle. Since 1.4.0 a failure is at
least *written down* — the daily log in `data\logs\`, which `logs_tail` reads — but a check that
failed at 03:00 still has nowhere to say so on screen.
It is also the item whose users are already served: the PRD's automation persona wants the **CLI in
an external scheduler**, and `docs/CLI-SPEC.md` already ships the Task Scheduler recipe — zero code,
@@ -1275,8 +1276,8 @@ change, which is exactly what a palette should do on dispatch.
#### Adding a command: the ten places
For P1-A and P1-B, which both need new IPC. Three drift tests in `src-tauri/src/lib.rs` police the
first four and fail at `cargo test`:
For P1-A and P1-B, which both need new IPC. Drift tests in `src-tauri/src/lib.rs` — five, since 1.3.0 added the
table check — police the first four and fail at `cargo test`:
1. `crates/pipdock-core/` — the logic. Business logic never goes in `src-tauri` (ARCHITECTURE §1.1).
2. `src-tauri/src/commands.rs` — the `#[tauri::command]`, with a `# Errors` section naming its
@@ -1299,6 +1300,125 @@ first four and fail at `cargo test`:
10. Capability changes → `capabilities/*.json`, and the `description` field is prose explaining
*why*. SECURITY §4 requires the widening be recorded in prose as well.
## 1.4.0 — the audit release — **2026-10-17**
No feature. The owner asked for the whole codebase to be reviewed — logic, configuration,
performance, logging, tests, UI — and for everything found to be either fixed or written down.
Three audit passes and a design pass produced **about 170 findings**, and the heaviest 25 were
checked against the code before any plan was written: all real, several reproduced. The scope the
owner chose was **every Critical and High in 1.4.0**, plus the cheap Medium and Low ones sitting in
code that was being changed anyway; the rest is the **Audit backlog** below, each with a place and
a reason. One PR of about thirty-six commits, each leaving the tree green, and every Critical and
High fix landed with a test that failed first against the code it replaced.
**Where it started.** `main` had been red since 2026-09-23 — `cargo audit` (rustls 0.23.42,
quinn-proto, a yanked chacha20) and `npm audit` (undici, source-map-js, brace-expansion) — with
four Dependabot PRs stuck behind it, and nobody was told: the failure notifier's
`workflows: ['*']` matched nothing. The weekly fixture-drift job had been red for seven weeks, for
two reasons that looked like one.
| Area | What was wrong | What it does now |
|---|---|---|
| **Mutation safety** (DATA-FLOW §9) | The stale-preview and drift checks never fired: `execute` verified the plan's hash against itself (C1). Requires-Python was never enforced, so `PD-PKG-001` was never raised (C2). A uv build failure read as "nothing to change" (C3). Stop or a watchdog in Phase A became `PD-INT-001` with no summary (C5). *Force latest* forced nothing (C6). A rollback with the other engine could uninstall pip (C7) | Re-probed before the snapshot and before execution. PipDock screens Requires-Python itself, uv's through store v4's `release_meta`. uv is read by exit status. A stopped step is a row. Forcing pins latest, releases the blockers, and the preview names what breaks. Cross-engine rollback leaves pip, setuptools and wheel alone |
| **`ruff --fix`** | Rewrote files the report never previewed, `.venv/` and notebooks included (C4) | One argv builder for the report and the fix |
| **Probe** | Crashed on every venv under a folder named in Vietnamese — `-I` ignores `PYTHONUTF8` (H10); parsed METADATA three times per package; dropped interpreter paths with spaces | `-X utf8`; one parse; schema 3 carries the PEP 508 marker environment, so platform-gated requirements stop reading as missing (H25) |
| **PEP 668** | The override was a checkbox nothing read (H11), and the gate trusted the frontend's copy of the environment (H12) | Decided on a fresh probe; `--break-system-packages` only with the override **and** the marker, pip ≥ 23.0.1; a confirm with Cancel focused; a chip wherever it applies |
| **Engines** | A resolve could not be stopped (H13); a watchdog surfaced as a PipDock bug (H14); pip's impossibility was an error where uv's was a report (H15); argv passed 32 767 characters at about 1 300 packages (H20) | `ResolveCtx` carries the token; `PD-ENG-004`; both are reports; requirements and constraints travel as files |
| **Logging** | None. `tracing` was declared in three crates and used nowhere; `--verbose` and `--log-file` did nothing; PRIVACY described a 14-day log that did not exist | Daily files in `data\logs\`, swept at 14 days; `logs_tail` and Settings' Logs row; a failed start says so in a native dialog rather than exiting silently |
| **CLI contract** | `env use` was stored and never read; `--json` printed several documents; Ctrl-C was unhandled | One document per command (CLI-SPEC §6); `--env`, then `env use`, then `.venv`; Ctrl-C stops the process tree and exits 130 |
| **GUI** | Decline did nothing; the language was not kept; a mutation slot could stay claimed until restart; five stores applied answers for an environment the user had already left; Security could not scroll; the window could not maximize, and opened under a laptop's taskbar | Each fixed with a test; `changelog/1.x.md` lists them |
| **Legal** | The documents' hash depended on the checkout's line endings; PRIVACY omitted the log and the tool environments, THIRD-PARTY omitted osv.dev | Normalised before hashing, with a test; both documents updated, so the gate shows once |
| **CI** | As above | Notifier by name; `cargo audit --deny warnings` on a prebuilt binary; a daily `security-scan.yml`; `cargo deny`; CodeQL for Rust and Actions; releases attested, with a dry run; Dependabot cooldowns and groups |
**What running found that reading did not** — the rule this file has recorded since Stage 1, again:
- **The drift job's two causes.** PyPI data — idna's newest release, scipy's list of versions — is
now redacted in `capture.py`. uv 0.13 rewriting its errors from miette's `× … ╰─▶ Caused by:` to
`error: … cause:` is a format change, and got a frozen corpus of its own (`uv-0.11/`) beside the
live one, with a test that both renderings classify alike.
- **Against pip 26.2.1, uv 0.13.1 and Python 3.14.7**, by running each: both engines now report an
impossible set the same way (exit 2); `scipy==1.7.3` on 3.14 is `PD-PKG-001` from both, where pip
said "not found" and uv planned it; forcing `httpcore` past `httpx 0.23` installs httpcore 1.0.9
with h11 0.16.0 and the post-check names what broke; the override sends its flag to a
uv-managed 3.13 and nowhere else; a uv snapshot restored by pip keeps pip; `ruff --fix` leaves
`.venv/` and `.ipynb` alone; every `--json` path parses as exactly one document.
- **Ctrl-Break needed a hang to test.** A blackhole address fails fast on Windows; a silent local
TCP server is what keeps pip waiting long enough to be interrupted. Exit 130, and no orphans.
- **Found while fixing something else**: pip names requirement-file lines `-r <temp> (line N)`, so
messages are rewritten back to the user's own text (`RequirementFiles::humanize`); `PkgName`'s
`Display` ignored width, so the CLI's columns never lined up; `pipdock list` probed twice; a
non-interactive decision skipped impossible packages without saying why; a cache test was flaky on
temp-directory names; and the dev CSP, once moved into a Vite plugin, blocked React Refresh's
inline preamble because it was injected ahead of it.
- **Found by installing it.** The release build was installed and driven before the tag, and two
defects showed up that no suite could: **every dialog opened in the window's top-left corner** —
Tailwind's preflight sets `margin: 0` on everything, which removes the `margin: auto` a modal
`<dialog>` is centred by, so the uninstall guard had been there since it was written — and **Search
never offered to download the index on a fresh profile**: moving the index load into the
background (U35) let a failed load restart on the next keystroke, which reset the slot to
*warming* before the search could say why, and the screen asked again every 150 ms forever. A
test in `state.rs` now holds the second; jsdom computes no layout, so the first is held by a
comment. Also checked there: the strict release CSP renders; the window opens at 1196×799 centred
in the work area and maximizes with the column capped; Decline closes the app; Cancel is focused
in the PEP 668 confirm and focus returns to the checkbox; the language survives a restart; F5 and
Ctrl+R do not reload; `/` lands in the Search field; an update and its rollback run end to end
with `from → to` on the row.
**Deliberately not done**, beyond the backlog: no CLI switch for the PEP 668 override — it stays a
decision made in the GUI, behind a confirm; no multi-ecosystem Dependabot group, because what one
does to the dependencies outside its patterns is undocumented and a wrong guess silently stops every
other update (the `tauri lockstep` job covers the risk instead); the screenshots were not retaken.
### Audit backlog
What 1.4.0 left, as the owner chose — each with where it is and why it waited. Line numbers are as
of the audit (`main` at `02cc17d`); a file 1.4.0 changed may have moved them. **Read this before
starting a slice**: several are cheaper inside a slice that touches the same file.
| ID | Where | What | Why it waited |
|---|---|---|---|
| BL-1 | `engine/mod.rs` `plan_requirements` | The guard set pins every installed package a plan does not move — the *dependencies* of a target updated alone included — so a target whose new release needs a newer dependency is held back with no culprit (pandas alone, over an old numpy). Update-all is unaffected, and *Force latest* works around it | The fix, releasing the targets' dependency closure, is safe under SP-1 but wants uv's `-U` eagerness measured first |
| M46 | `compat.rs:30-51`; `engine/parse.rs` `is_downgrade` | Pre-, post- and dev-releases are not ordered per PEP 440 | Needs a full comparator; no reported case |
| N4 | `flow` rollback | A rollback's restore set is not screened for Requires-Python | A restore re-installs what was there; a mismatch means the interpreter changed under the snapshot |
| H27 | `tools/*-constraints.txt` | Pinned by version, not by hash | `--require-hashes` needs every wheel's hash across the Pythons and platforms CI covers |
| H27-b | `health/mod.rs` `pins_hash` | A venv's manifest hashes its tool pins only, so regenerating the constraints alone — to pick up a patched dependency, say — leaves every existing venv reporting fresh | Hashing the whole constraints file into both venvs would make a pip-audit bump re-sync Code Health, which the hashes are independent to prevent; the precise fix hashes each venv's closure, built from the file's `# via` annotations |
| X19 | first-run engine choice | uv is not detected and offered on first run (PRD P0-9) | A first-run surface the app does not have |
| X17 | `pipdock-cli/src/run.rs:759,1197,1219,1545,1049-1050` | Some refusals carry a code that describes something else | Wants a "confirmation required" code — nine places, its own change |
| X16 (rest) | `pipdock-cli` exit codes | A Code Health failure exits with the generic code rather than its own (`update` with no arguments, the other half, is fixed) | CLI-SPEC §5 change |
| — | `pipdock-cli` `apply_fix`; `health::fix::dirty` | `health --fix --yes` outside a git repository proceeds: `dirty` answers `None` for a clean tree and for no repository alike | Needs a three-way answer from `dirty`, which the GUI's `health_dirty` shares |
| — | `pipdock-cli` | On a terminal, an impossible package is skipped at the prompt without the engine's explanation; `report-bug` points at a log excerpt the CLI never attaches; `uninstall --json --force` warns about "the breakage above", which JSON mode never printed | Small CLI copy fixes |
| X36/U55 | `src-tauri/src/commands.rs:425-467,1189-1214,1350-1377` | Save and export accept any path the webview names, and overwrite a sibling without asking | The picker is the only caller today; defence in depth, not a reachable hole |
| — | `envs/mod.rs:131-138`, `engine/parse.rs:103-108`, `exec.rs:367-375`, `pins/mod.rs:85-89`, `store/mod.rs:253`, `index/mod.rs:144,448` | Failures that are dropped without a log line (a probe error entry, an unreadable pin row, a Job Object that would not attach…) | The log exists now; each wants a `tracing::warn!` and a look at whether it should surface |
| — | `PIP_MIN_VERSION_FOR_REPORT`, `UV_MIN_VERSION`, `probe_supported`, `MIN_PROBE_PYTHON` | Declared floors nothing enforces | Enforcing them is a user-visible refusal and wants its own copy and test |
| L56 | `audit.rs:165-168` | An audit's package count includes skipped packages | Cosmetic |
| L57 | `engine/parse.rs:96-140` | pip's `download_info` is parsed and discarded | Nothing needs it yet |
| L58 | `health/mod.rs:502-504,668` | Progress steps are numbered absolutely, so a sync shows "0..4 of 5" | Cosmetic |
| U16 | `stores/health.ts:104`; `PdHealth.tsx:89-91` | Health's project folder is global rather than per environment | A data-model change: `EnvRow.healthProject` exists and the store does not key on it |
| U19 | `PdEnvironments.tsx:186-196` | Every visit to Environments rescans | Needs a policy — by age, or on request only |
| U27/U28 | `PdConsoleDrawer.tsx:49-52,77`; `plan.ts:196-198,337-350` | The console drawer does not follow the output, and re-renders per line | Wants a long install measured before it is optimised |
| U33 | `PdHealth.tsx:103-105,151-154`, `PdSecurity.tsx:102`, `PdRequirements.tsx:47,64`, `PdErrorRow.tsx:98-100`, `PdAbout.tsx:63-65`, `security.ts:122` | A save, clipboard write or picker that fails says nothing | Needs a toast — P1-7's blocker as well |
| U38 | `index-search.ts:174-177,202` | Metadata errors and a refresh's result are not shown | Same: no surface for a transient message |
| U39 | `PdSettings.tsx:99-116` | The threshold input fights the user mid-edit | Needs a draft-then-commit pattern |
| U40 | `PdPins.tsx:138-139,202-209`; `stores/index.ts:466-472` | The empty state can show before the list has loaded; a reason edit commits on blur with no way to cancel; accepting a suggestion drops it even when the pin write failed | Small, and best done together |
| U41 | `stores/index.ts:526-538`; `PdPalette.tsx:96-103` | No in-flight guard: a double click takes two snapshots, and the palette can dispatch twice | Small |
| U44 | `PdEnvironments.tsx:186-196` | A `scan-progress` listener can outlive the screen | Small; with U19 |
| U45 | `styles.css:156-162` | `forced-colors` misses Remove, Force, rollback, Clear and the active tab | Needs a High Contrast pass, by hand |
| U47 | grids, tabs, radio groups, listbox; `PdHealthReport.tsx:220,321` | ARIA roles are partial | An accessibility pass of its own |
| U48 | `PdPalette.tsx:219` | The palette's selection is not scrolled into view | Small |
| U49 | `App.tsx` Ctrl+K | Ctrl+K reads `e.key`, unlike Ctrl+1..9 | Letter shortcuts by physical key are wrong on Dvorak; needs a decision |
| U50 | `PdHealth.tsx:215`, `PdSecurity.tsx:160`, `PdCacheUsage.tsx:32` | Dates and sizes are not formatted per locale | An `Intl` pass |
| U51 | `PdEnvironments.tsx:55`, `PdEnvDetail.tsx:76`, `PdPackageRow.tsx` | Long paths and names overflow | With U22's container-query work |
| U52 | `PdStatusLine.tsx` | The status line does not show a plan's activity | Small |
| U53 | `PdPackageRow` memo, Health/Pins, *Upgrade pip* | A style object defeats the row's memo; Health and Pins trigger `pkg_outdated`; *Upgrade pip* does not refresh the row's packages | Performance; measure first |
| U59 | i18n tooling | `saveMissing: false`, and holes in the no-literals lint rule | Tooling |
| — | WebView2's context menu | Reload, Back and Print are still offered by right-click in a release build | A decision: removing it also removes Copy and Paste from text fields |
| — | `ui/src/ipc/index.ts` `Settings` | Hand-mirrored rather than generated, against this file's own rule | A `schemars` derive on `settings::Settings` and a re-generated binding |
| — | `plan.confirm` | "Confirm (1 changes)" — the count is not pluralised | Copy, both catalogues |
| — | cache manager | The log folder is not one of its targets | The log is new; worth a row once someone asks |
| X12 | `ci-integration.yml` | The `#[ignore]` tests never run in CI | Each needs a fixture the runner can provide — an index, a hang |
| — | CI | SBOM, an installer smoke test, coverage, `cargo machete`, actionlint/zizmor, dependency review, typos and link checks | Each its own decision; none is free on a Windows runner |
| — | `screenshot/` | The eight screenshots predate About and 1.4.0's window | Retake with a release, by hand |
## Standing risks
| Risk | Mitigation |
+34 -12
View File
@@ -10,31 +10,44 @@ PipDock's job is to run package managers against local environments. The realist
- 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.
- **The version half has been true only since 1.4.0.** Names always went through `PkgName`; versions were plain strings, so a dock-bay entry of `2.0 ; python_version<'0'` reached argv as one token pip read as a requirement whose marker is false — a silent no-op install. `pep440` is now the one place that says what a version and a specifier set may look like, and every way text arrives passes through it: install specs from either head, imported requirements, the IPC types that carry them, and the installed versions the guard set restates.
- **Requirements and constraints reach an engine as files** (`-r <file>`, `-c <file>`) since 1.4.0: restating the installed set one argv entry per package (SP-1) passed Windows' 32,767-character command line at about 1,300 packages. The files hold exactly the tokens argv held — rendered `PinnedSpec`s and validated `Spec`s — and, like `probe.py` and the pins handed to pip-audit, each is an `exec::TempFile`: a fresh random name created with `create_new`, so an existing file is never written through, and deleted on drop.
- 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.
- `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 — and with `-X utf8`, because `-I` implies `-E`, which also discards invariant 7's `PYTHONUTF8`/`PYTHONIOENCODING`: until 1.4.0 a venv under a folder named in Vietnamese crashed the probe.
- **Owner decision 2026-07-27 (spike SP-6): `-I` stays, and the cost is disclosed rather than hidden.** Isolated mode also disables user site-packages, so on a *non-venv* system Python the probe sees fewer distributions than `pip list` does — measured at 352 vs 375 on the reference machine. Virtual environments, the primary target, have no user site and are unaffected. The probe therefore reports `hidden_user_site`: the user-site path when it exists, is off `sys.path`, and is non-empty; `null` otherwise. Only when it is non-null does the Installed screen show a note naming the path (`env.partialListing`), so the disclosure is accurate rather than a permanent disclaimer. Dropping to `-E` was rejected: a package in user site is part of the untrusted surface the isolation exists to exclude.
- 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).
- The Code Health **project folder** is a user file-pick that becomes the working directory of three subprocesses and, with `--fix`, the target of a write. It is canonicalized and existence-checked like an interpreter path, and a folder resolving inside `%LOCALAPPDATA%\PipDock\data\tools` is refused — rewriting the tools venv would break Health itself.
- `git` is the one PATH-resolved program PipDock runs with a **user-controlled** working directory (the dirty-tree check). Windows' legacy `CreateProcess` search order would make a `git.exe` planted in a cloned repository win; **verified by planting one** — Rust's `Command` does its own resolution and does not search the current directory. Re-check if the process layer changes.
- `git` is the one PATH-resolved program PipDock runs with a **user-controlled** working directory (the dirty-tree check). Windows' legacy `CreateProcess` search order would make a `git.exe` planted in a cloned repository win; **verified by planting one** — Rust's `Command` does its own resolution and does not search the current directory. Re-check if the process layer changes. A repository can also name a program for `git status` to run — `core.fsmonitor` in its own `.git/config`, which a project folder downloaded rather than cloned brings with it — so asking "is it safe to write here" would have run it. The check has been `git -c core.fsmonitor=false --no-optional-locks status …` since 1.4.0; a command-line `-c` wins over every config file.
## 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.
**As built in 1.4.0, the first version in which the override did anything.** Until then the checkbox saved and nothing read it, no chip existed anywhere, and the gate trusted whatever copy of the environment the caller had cached — with no gate at all on rollback.
- **Decided on a fresh probe.** Update/install, uninstall and rollback open with one preamble (`flow::preamble`): probe the environment, then decide on what the probe says. Without the override a managed environment is PD-ENV-002 before any engine command runs. A venv is never externally managed, so the override never applies to one.
- **A named value, not a bool.** `SystemPackages::OverrideAllowed` exists only in a flow that probed, found the marker and was told the setting is on — for the reason `SnapshotProof` is a named waiver: invariant 5 says the flag is never passed *implicitly*, and this makes "implicitly" greppable. It reaches both engines' installs and removals, and uv's dry run, which refuses a managed environment without it; pip's `--dry-run --report` never gets it.
- **Per engine** (`engine::system_packages_for`). uv takes the flag throughout its supported range. pip implemented PEP 668 in 23.0 and added the flag in 23.0.1, so pip ≥ 23.0.1 gets it; a pip below 23.0 has nothing to override and is passed nothing; and pip 23.0 itself, which enforces the marker with no way past it, is refused with PD-ENV-002, its message naming 23.0.1.
- ***Upgrade pip* is outside the override.** It refuses a managed environment whatever the setting says, and never passes the flag.
- **Turning it on asks first.** The checkbox opens a confirm with Cancel rendered first and focused, so `Enter` cancels (`PdSettings`); turning it off saves at once. The chip (`PdOverrideChip`) shows on Installed/Updates, Search's dock bay, the plan panel and an environment's detail — and only where the override applies: the setting is on *and* the environment carries the marker. A chip on a venv would claim the flag was being sent.
- **The CLI has no switch of its own.** It reads the setting from the store both heads share — the override stays a decision made in the GUI, behind the confirm — and says on stderr, on every run it applies to, that `--break-system-packages` will be passed.
## 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` |
| `pypi.org` | PEP 691 name index; per-package JSON metadata; since 1.4.0, per-release JSON for `Requires-Python` (invariant 10 — uv's plans and exact pins; `crate::release`, at most eight in flight, each answer cached forever in the store) | HTTPS with certificate verification; redirects restricted to `pypi.org`/`files.pythonhosted.org` |
| — 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) |
`pypi.org` is the **only** host PipDock itself connects to. It does not update itself (§5), so it has no reason to reach `github.com` — the legal gate and the bug-report deep link hand a URL to the user's browser rather than fetching anything. The webview cannot reach either: `connect-src` in `tauri.conf.json` allows only `'self'` and the IPC origin, so all network access goes through Rust.
**Three hosts may be handed to the browser, and the allowlist is the record of why.** `capabilities/external-links.json` scopes `opener:allow-open-url` to `https://github.com/*`; to `https://docs.astral.sh/*` since Phase 3 · P4 — every ruff finding carries its own rule page and CODE-HEALTH-SPEC §6 as amended requires using ruff's `url` rather than constructing one; and to `https://osv.dev/*` since P1-1, where every advisory links to its entry and the alternative was a promise that rejects in silence; and to `https://poli0981.dev/*` since Phase 4, for the one page the About tab links to that lists every other way to reach the author. None is a connection PipDock makes; all three are URLs it asks the OS to open. The widening is recorded here rather than only in `capabilities/` because an allowlist entry is a change to this document's subject matter, not a config detail — and because the failure mode of *not* widening it is silent: the promise rejects, nothing opens, and nothing anywhere says so.
**Four hosts may be handed to the browser, and the allowlist is the record of why.** `capabilities/external-links.json` scopes `opener:allow-open-url` to `https://github.com/*`; to `https://docs.astral.sh/*` since Phase 3 · P4 — every ruff finding carries its own rule page and CODE-HEALTH-SPEC §6 as amended requires using ruff's `url` rather than constructing one; to `https://poli0981.dev/*` since Phase 4, for the one page the About tab links to that lists every other way to reach the author; and to `https://osv.dev/*` since P1-1, where every advisory links to its entry and the alternative was a promise that rejects in silence. None is a connection PipDock makes; all four are URLs it asks the OS to open. This paragraph said "three" from P1-1 until 1.4.0 while listing four — drift no sentence catches and a test does: `the_opener_reaches_four_hosts_and_no_more` (`src-tauri/src/lib.rs`) now fails on a fifth, or on one fewer. The widening is recorded here rather than only in `capabilities/` because an allowlist entry is a change to this document's subject matter, not a config detail — and because the failure mode of *not* widening it is silent: the promise rejects, nothing opens, and nothing anywhere says so.
**What the scope actually defends is narrower than it looks.** Most call sites pass module constants no injected string can reach. Two pass data: `PdErrorRow` hands over a URL built in Rust, and `PdHealthReport` hands over `finding.url` — which comes out of **ruff's own JSON** over the user's source tree, and is the only URL in the application derived from a third-party tool's output. `https://docs.astral.sh/*` is precisely what stops that being anything else. That is also why the contact addresses in About are copied to the clipboard rather than opened: a `mailto:` entry would widen the allowlist by a whole URL *scheme*, and re-open a target class for that one call site, to save a paste.
**What the scope actually defends is narrower than it looks.** Most call sites pass module constants no injected string can reach. Three pass data: `PdErrorRow` hands over a URL built in Rust; `PdAuditReport` an OSV URL that `audit::advisory_url` builds from an advisory id it has checked against a whitelist (ASCII letters, digits and `-`), so the tool chooses the id and never the destination; and `PdHealthReport` hands over `finding.url` — which comes out of **ruff's own JSON** over the user's source tree, and is the only URL in the application taken verbatim from a third-party tool's output. `https://docs.astral.sh/*` is precisely what stops that being anything else. That is also why the contact addresses in About are copied to the clipboard rather than opened: a `mailto:` entry would widen the allowlist by a whole URL *scheme*, and re-open a target class for that one call site, to save a paste.
No telemetry, no crash reporting endpoints, no analytics. TLS failures surface as PD-NET-002 and the app **never** offers to disable verification.
**The webview's reach is narrowed, and its grants are pinned.** Beyond `connect-src`, the Content-Security-Policy is `default-src 'self'` with `object-src`, `base-uri` and `form-action` all `'none'` (since 1.4.0), and a release build's `style-src` is `'self'` alone — React sets styles through CSSOM, which CSP does not govern. The development policy, `devCsp`, adds `'unsafe-inline'` because Vite injects CSS as `<style>` elements. Both live in `tauri.conf.json`, and `vite.config.ts` injects `devCsp` into `vite dev` and nothing else; it used to be a meta tag in `ui/index.html`, which put the weaker policy into every release build beside the stronger one — harmless, since the stricter of two policies wins, and still in the product. The capability set is exact in the same way: `capabilities/*.json` grants the main window the two event permissions the progress streams need, `core:window:allow-close`, the open and save dialogs (each returns a path and grants no file access), clipboard *write* and the scoped opener, and `src-tauri/src/lib.rs` pins that union with a test. `core:default` stood there until 1.4.0 — some sixty core commands nothing called, and not `core:window:allow-close`, so *Decline* on the legal gate did nothing in the installed app while its component test, which mocks `close()`, passed. Widening a grant is now a test change, on purpose; the CSP has no test of its own.
No telemetry, no crash reporting endpoints, no analytics. TLS failures surface as PD-NET-002 and the app **never** offers to disable verification — for PipDock's own requests, since 1.4.0, by reading the error's source chain: reqwest's top-level message never mentions the certificate, so PD-NET-002's guidance never showed.
## 5. Update integrity (PipDock itself)
@@ -42,13 +55,17 @@ No telemetry, no crash reporting endpoints, no analytics. TLS failures surface a
That is a deliberate removal, not an omission. A self-updater is a permanent remote-code-execution path into a tool that already runs subprocesses against the user's interpreters, and it has to be defended for the life of the product: a signing key that must never leak, an endpoint that must never be spoofable, and verification logic that must never be bypassable. For a tool people open occasionally to tidy an environment, that is a large standing liability bought for a small convenience.
What replaces it: SHA-256 checksums published per release (`SHA256SUMS.txt`) for manual verification, which the README tells users to check because SmartScreen warns on first run — the binaries are not EV-code-signed. Installer artifacts are NSIS + MSI from the Tauri bundler.
What replaces it: SHA-256 checksums published per release (`SHA256SUMS.txt`) for manual verification, which the README tells users to check because SmartScreen warns on first run — the binaries are not EV-code-signed. Installer artifacts are NSIS + MSI from the Tauri bundler. Since 1.4.0 the checksum file has LF line endings, written byte for byte: the CRLF one `Set-Content` produced made `sha256sum -c` on any other platform read the CR as part of each file name and report every file missing.
**From 1.4.0, the installers carry a build-provenance attestation.** The release workflow attests the `.exe` and the `.msi` (`actions/attest-build-provenance`), and `gh attestation verify <file> --repo poli0981/pipdock` proves an installer was built by this repository's release workflow at the tagged commit — which a checksum published beside the file cannot, since whoever could replace one could replace both. The attestation is signed through Sigstore with a short-lived certificate bound to the workflow run, so it adds no key to keep.
**The token that can write a release never runs the build.** Building executes third-party code — every crate's build script, every npm package's install script — so the build job holds a read-only token and keeps no credentials in its checkout; a separate job downloads what it produced, attests it and drafts the release, and is the only one granted `contents`, `id-token` and `attestations` write (RELEASE-CI §3).
Consequences worth knowing: there is no signing keypair to generate or rotate, no `TAURI_SIGNING_PRIVATE_KEY` secret, no `latest.json`, and `tauri-plugin-updater` is not a dependency.
## 6. Auditing user environments (P1 Security tab)
pip-audit runs **from a venv of its own** in freeze-file mode: `Engine::freeze` the target env → `pip-audit -r <freeze> --no-deps -f json` → findings joined to installed rows. Flags validated in SP-4 and pinned by a committed capture (`tests/fixtures/audit/`).
pip-audit runs **from a venv of its own** in freeze-file mode: `Engine::freeze` the target env → its pins (`name==version`) in a temp file → `pip-audit -r <pins> --no-deps -f json` → findings joined to installed rows. Flags validated in SP-4 and pinned by a committed capture (`tests/fixtures/audit/`). **Pins, not the raw freeze, since 1.4.0:** an editable install (`-e …`) or a direct reference (`name @ file:///…`) is a line pip-audit cannot look up on an index, and a single one failed the whole audit. Neither is on PyPI, so neither has a PyPI advisory to miss.
**Its own venv, not Code Health's**, and that is a correction rather than a detail. This section said "the tools venv" from the day it was written; the code has refused that since P2, because `pip-audit`'s closure contains `msgpack`, which publishes no universal wheel and would hard-fail the whole sync under `--only-binary=:all:` on a new CPython — taking Code Health down with a feature it does not use. `health::AUDIT_TOOLS` and `health::audit_dir` keep the blast radius inside the Security tab.
@@ -58,11 +75,16 @@ pip-audit runs **from a venv of its own** in freeze-file mode: `Engine::freeze`
## 7. Supply chain of PipDock itself
- CI: `cargo audit` (RustSec) + `npm audit --audit-level=high` gate every PR; Dependabot keeps Rust/npm/actions/tools-requirements pins current (see RELEASE-CI.md §2).
- CI: `cargo audit` (RustSec) + `npm audit --audit-level=high` gate every PR, and since 1.4.0 run again **every day against `main`** (`security-scan.yml`). A PR gate fires only when something changes, so an advisory published against a dependency already merged waited for the next PR to trip over it — which is how `main` went red on 2026-09-23 with no PR open to say so — and, because the failure notifier matched no workflow at all, with nobody told. Dependabot keeps the Rust, npm, Actions and Code Health pins and the Rust toolchain current (see RELEASE-CI.md §2).
- The `cargo audit` gate is on **vulnerabilities** and is never relaxed. `.cargo/audit.toml` ignores a fixed list of *informational* advisories — unmaintained/unsound — on transitive crates PipDock cannot influence, chiefly Tauri's archived GTK3 bindings, which a Windows-only build never compiles. They are listed individually with justification so a **new** advisory still fails CI. Adding macOS/Linux builds (P2-1) is the point at which that block must be re-examined rather than extended.
- **That "still fails CI" has been true only since 1.4.0.** Informational advisories — unmaintained, unsound, yanked — are cargo-audit *warnings*, and `rustsec/audit-check@v2`, which ran the gate until then, let warnings through; on a pull request it failed only on *critical*, which is how September's advisories passed every PR. The gate is now a prebuilt `cargo-audit` (installed by `taiki-e/install-action`, pinned by commit) run with `--deny warnings`.
- `npm audit` installs with `npm ci --ignore-scripts`: it reads the lockfile and builds nothing, so no package's install script has a reason to run.
- **`cargo deny`** checks licences, sources and bans on every PR (`deny.toml`, since 1.4.0). Its licence allowlist — each entry GPL-3.0-compatible — turns THIRD-PARTY-NOTICES' "all bundled licenses are GPL-3.0-compatible" from a sentence into a test for every crate the Windows target resolves, transitive ones included; widening the list is a licensing decision, not a CI fix. Only crates.io may supply a crate — no git dependency, no other registry — and wildcard version requirements are refused. Advisories stay `cargo audit`'s, so there is one ignore list rather than two to keep in step. The npm half of the build has no equivalent licence check.
- `Cargo.lock` and `package-lock.json` committed; builds are `--locked`.
- CodeQL enabled via the ops-repo caller with the established permissions block, scoped to **`javascript-typescript` only** — CodeQL has no Rust analyzer. Rust's static-analysis coverage is clippy `-D warnings` plus `cargo audit`, both blocking in `ci-rust.yml`.
- Third-party licenses tracked in `legal/THIRD-PARTY-NOTICES.md`, which names the **direct** dependencies the manifests declare and is reconciled against them by hand at each release. It is not generated: an earlier revision of both documents claimed `cargo about`/`license-checker` produced it into a `licenses/` directory, and no such config, directory or release step has ever existed. The complete resolved graph is `Cargo.lock` and `package-lock.json`, both committed. Generating the inventory is tracked as a Post-1.0 item; until it lands, the claim here matches what is done.
- **The environments PipDock builds for itself install a pinned tree.** Since 1.4.0 `tools/tools-constraints.txt` pins every package beneath the four tools, for the Code Health and the Security-tab venvs alike, so a broken or compromised release of `requests`, `rich` or `msgpack` no longer reaches every user on their next sync (CODE-HEALTH-SPEC §2). The pins are versions, not hashes; `--require-hashes` is in ROADMAP's Audit backlog.
- **Workflows** pin third-party actions by commit — `taiki-e/install-action`, `softprops/action-gh-release`, and `actions/attest-build-provenance` too — while GitHub's own `actions/*` use major tags and the ops repo's reusables `@main`. A write permission sits on the job that needs it, not on the workflow (RELEASE-CI §1).
- CodeQL enabled via the ops-repo caller with the established permissions block, over **`javascript-typescript`, `rust` and `actions`**. This bullet said `javascript-typescript` only, because "CodeQL has no Rust analyzer" — which stopped being true in 2025, and the reusable hands any language straight to `codeql-action`. `actions` analyses the workflows themselves: write permissions at workflow level and unpinned third-party actions, the class of mistake SonarCloud had been finding by hand. Only the JavaScript/TypeScript analysis is a required check, so Rust's blocking static analysis is still clippy `-D warnings` plus `cargo audit` in `ci-rust.yml`.
- Third-party licenses tracked in `legal/THIRD-PARTY-NOTICES.md`, which names the **direct** dependencies the manifests declare and is reconciled against them by hand at each release. It is not generated: an earlier revision of both documents claimed `cargo about`/`license-checker` produced it into a `licenses/` directory, and no such config, directory or release step has ever existed. The complete resolved graph is `Cargo.lock` and `package-lock.json`, both committed. Generating the inventory is tracked as a Post-1.0 item; until it lands, the claim here matches what is done — and `cargo deny` checks the Rust licences without writing the inventory.
## 8. Data & privacy engineering
@@ -72,7 +94,7 @@ All state PipDock writes is local under `%LOCALAPPDATA%\PipDock\data\`.
**One exception, and it is the only one.** `ruff check --fix` (CODE-HEALTH-SPEC §5, Phase 3 · P5) rewrites files in a project folder the user chose. It is PipDock's sole write outside site-packages and `%LOCALAPPDATA%`, it happens only behind an explicit confirm carrying a `FixConsent` the executing call demands, and it is refused entirely — before the first byte — if any target cannot be written. No snapshot is taken, because no snapshot in this application describes a source tree; the safety net is the user's own version control, which the confirm names and `git status` is consulted about twice. §1's threat model does not otherwise contemplate PipDock writing to user source, so this is the paragraph that says it does.
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 `data\` is a complete reset — and deleting the *parent* uninstalls the program, which is why the distinction is spelled out wherever the advice appears: `legal/PRIVACY-POLICY.md` §2 and the **About** tab. The Privacy Policy carried the pre-move wording for two weeks after the move; that is the failure this paragraph exists to prevent recurring.
Logs contain package names and paths. There was no log until 1.4.0, while the Privacy Policy described one; now each head writes one file per UTC day under `data\logs\` (`pipdock.<date>.log` for the GUI, `pipdock-cli.<date>.log` for the CLI), recording every command PipDock ran with its argv, exit code and duration, kept `LOG_RETENTION_DAYS` (14) by a sweep that touches only files named the way it names them — and the CLI's `--log-file` adds a copy wherever the user says. Nothing sends them anywhere; 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 `data\` is a complete reset — and deleting the *parent* uninstalls the program, which is why the distinction is spelled out wherever the advice appears: `legal/PRIVACY-POLICY.md` §2 and the **About** tab. The Privacy Policy carried the pre-move wording for two weeks after the move; that is the failure this paragraph exists to prevent recurring.
## 9. Vulnerability reporting
+48 -38
View File
@@ -10,65 +10,75 @@
4. Skip-and-continue semantics and summary counts.
5. Reverse-dependency guard correctness — including that it is *enforced*, not merely reported: a removal the user never accepted must be refused (`GuardAck`, PD-RES-004), and widening a removal must re-run the guard rather than proceed.
**A fix lands with a test that failed without it.** 1.4.0 held every Critical and High audit finding to that rule: each fix's test was run against the code it replaced and seen to fail first (ROADMAP's 1.4.0 record). A test that has never failed has not shown that it can.
## 2. Layers
### L1 — Core unit tests (Rust, `cargo test`)
### L1 — Core unit and corpus 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, and the **partition**: every significant freeze line is either parsed into a pin or reported unrestorable, never neither. The second is the one a rollback preview stands on — a line both functions dropped disappeared silently, and the preview then promised a restore it could not perform.
- **Name/spec validation:** PEP 508/440 accept/reject tables.
- **Engine captures:** real pip and uv output under `crates/pipdock-core/tests/fixtures/`, one directory per scenario holding `stdout.txt`, `stderr.txt`, `meta.json` (the exit code, and the catalog code the scenario must produce) and `capture-provenance.json` (engine, interpreter and argv), written by `spikes/capture.py` and seeded by spikes SP-1/SP-2. Ten scenarios per engine — a clean upgrade, held back, held back by a constraint, impossible, not found, yanked, `Requires-Python`, a build-backend failure, an unreachable network, the cp1252 report crash — in **three corpora**, plus one of synthetic stand-ins:
- `pip/` and `uv/` — the current engines (pip 26.2.1 and uv 0.13.1 at 1.4.0), and the bytes the weekly drift job re-captures and compares (L2).
- `uv-0.11/` — **frozen**: a byte-identical copy of uv 0.11.32's captures, the last miette-style rendering (`×`, `╰─▶`, "Caused by:"). uv 0.13.0 rewrote every failure as `error:` / `cause:`, and `UV_MIN_VERSION` is still 0.10, so users run both. `both_uv_renderings_classify_identically` (`classifier_corpus.rs`) holds every scenario to one catalog code under either rendering, and `uv_impossibility_reads_the_same_in_both_renderings` (`plan_parsers.rs`) holds the explanation to the same words.
- `synthetic/` — the eight conditions a capture machine cannot produce (a full disk, a locked file, a hash mismatch…), each flagged, saying why it is synthetic and what would replace it; a test refuses one that does not.
The captures are redacted rather than literal — absolute paths, addresses, progress bars, timings, and data that moves with PyPI rather than with an engine (pip's "from versions" list, its release notice) — so they compare across machines and weeks. Line endings stay byte-exact (`.gitattributes`' `-text`), and a test fails if no fixture keeps a CRLF.
- **Parsers against the corpora** (`plan_parsers.rs`): every capture is replayed through the function each `resolve` returns through — `pip_resolution` / `uv_resolution` — and asserted on *meaning*: a plan is recognised, an upgrade knows what it is upgrading from, an impossibility is a report. Deliberately not snapshotted, because a snapshot would fail on every cosmetic engine change and teach re-blessing without reading; this bullet said `insta` snapshots asserted the normalized `ResolutionReport`, and none does. `every_failed_capture_reaches_the_user_as_the_code_it_was_captured_for` is 1.4.0's: the classifier corpus had proved each stderr classifies correctly while uv's adapter never asked the classifier, so a failed build previewed as "no changes".
- **Error classifiers** (`classifier_corpus.rs`): every catalog code is covered by a fixture that names it or classifies to it, **or** is listed as raised by PipDock itself, with the module that raises it — a watchdog (PD-ENG-004) or a stale preview (PD-RES-002) has no stderr to capture. A code with neither fails CI: "no code without a fixture". This line said every code has a stderr fixture; the table of codes PipDock raises itself has sat beside the captures since the gate was written.
- **Flows, end to end against a scripted engine** (`tests/flows.rs`, 1.4.0). The engine owns a small mutable world — what is installed, what the index offers, whether the interpreter is externally managed — and installs really change it, so a test can move the environment between two calls the way another terminal would; `Engine::probe` and `FlowOptions` (the cancellation token, a clock) are the seams. It exists because everything a flow decides before `plan::execute` — the PEP 668 gate, the drift basis, what reaches the resolver, what a forced package releases — sat behind a free-function probe, so a stale-preview check that could never fire, *Force latest* forcing nothing and a cross-engine rollback removing pip were found by no test. A flow decision without a test here is a regression. `execution.rs` does the same for `plan::execute`: skip-and-continue (thirteen of fifteen apply), the counts against the rows, Phase B isolation, and a stop, a watchdog or an engine that will not start reported per row rather than raised.
- **Graph:** reverse-dep construction and blocker attribution over synthetic metadata sets, including cycles and extras (`pkg[extra]`) markers — and, since probe schema 3, platform markers, so ipython's `pexpect; sys_platform != "win32"` no longer reads as a missing dependency on Windows.
- **Snapshot diff/rollback planner:** the round trip `apply(plan(diff(a,b)), b) == a` over a constructed pair, and, over 400 generated freeze texts, the **partition**: every significant freeze line is either parsed into a pin or reported unrestorable, never neither. The second is the one a rollback preview stands on — a line both functions dropped disappeared silently, and the preview then promised a restore it could not perform. (This bullet said the round trip ran over generated pairs; only the partition does.)
- **Name/spec validation:** PEP 508/440 accept/reject tables — names in `model.rs`, and since 1.4.0 versions and specifier sets in `pep440.rs`, the boundary where text becomes argv (SECURITY §2).
- **What the frontend and the shell depend on** fails `cargo test` too: `generated.ts` and the L3 IPC fixtures when stale (`bindings.rs`, `fixtures.rs`); the webview's exact grants and the opener's four hosts (`src-tauri/src/lib.rs`, SECURITY §4) — a grant is a contract no frontend test can see, and *Decline* on the legal gate did nothing in the installed app while its component test, which mocks `close()`, passed; and the legal-documents hash (`crates/pipdock-core/src/legal_hash.rs`), which `build.rs` includes by `#[path]` and the library compiles only under `cfg(test)`, so the tests run the function that runs at build time. A CRLF document hashes like its LF twin — which failed against the code that took the length before normalising — a changed or moved document changes the hash, and the hand-rolled SHA-256 agrees with `sha2` across block boundaries.
- **Six tests are `#[ignore]`d**, each needing what `cargo test` must not: real PyPI (the tools-venv bootstrap and its repair), a synced audit venv, a real interpreter (the graph), and a populated index in a release build (`search_latency.rs`, which refuses to run in debug). They run by hand with `--ignored`; **no CI job runs them** (ROADMAP's Audit backlog). L2 drives the bootstrap through the CLI instead.
### L2 — Engine integration (disposable venvs, Windows CI runner)
Each test creates a throwaway venv (`python -m venv` and `uv venv`), then exercises real engines:
`ci-integration.yml`'s *Real engines, throwaway venvs* job, on Python 3.10 and 3.14 — the floor and the newest PipDock claims. It runs `cargo test`, builds the CLI and drives it against venvs it creates with `python -m venv`, real pip and real uv on PATH. (This line said `uv venv` as well; nothing creates one.)
Scenario
| Step | Assertion |
|---|---|
| Discovery and inspection | `env list`, `doctor` and `list --json` succeed on a fresh venv |
| The Code Health tools venv | `tools sync` reaches `fresh` with all three tools and without pip-audit; a warm re-sync short-circuits (under 10 s); a deleted `ruff.exe` reads `toolMissing` and a re-sync repairs it; offline, PD-NET-011, exit 6, and no manifest left behind |
| pip upkeep | a venv seeded with pip 22.1.2 is upgraded by `pip-upgrade` and its pip runs afterwards — on 3.14 only through the `ensurepip` fallback |
| PEP 668 | with the marker planted in the base interpreter, a venv built from it is *not* externally managed and the base *is* |
| The SP-1 conflict | over `httpx==0.23.0`, `update httpcore --dry-run` reports httpcore held back and attributes it to httpx |
| Update → snapshot → rollback | after `update --all` and `snapshot rollback <id>`, `snapshot diff <id> --json` reports no drift |
| The uninstall guard | removing `urllib3` from under `requests` exits non-zero |
| Exit codes | a missing environment exits 3; `doctor` on a healthy one exits 0 |
| JSON contracts | `pipdock schema` for four types, and `list --json`, parse |
| An editable install | listed once, and with no size |
Assertion
**What this table used to claim and L2 does not do:** install three wheels and check the summary; take a conflict down the Force path and see `check` report the breakage; isolate a broken sdist in Phase B; `--force` past the guard; and refuse with PD-ENV-002, then pass the flag under the override, against a real engine. Those are proved against scripted engines in L1 — the batch semantics in `execution.rs`, *Force latest* and the PEP 668 gate and override in `flows.rs`, the guard's acknowledgement in `flow`'s unit tests, the flag itself in the adapters' argv tests — and 1.4.0 ran *Force latest* and the override by hand against pip 26.2.1 and uv 0.13.1 (ROADMAP).
Fresh venv + install 3 small pure wheels
**The packages are real PyPI packages, and only some are pinned** — `httpx==0.23.0`, `pip==22.1.2`, the shipped tool pins — while `requests` and `update --all` take whatever is newest that day. This paragraph described a pinned package list in `tests/integration/pins.toml` and a local `pypiserver` mirror for offline runs; neither has ever existed. L2 is network-bound, and only as deterministic as PyPI.
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.
**The drift job** (*Re-capture against the latest engines*, Mondays and on dispatch) re-captures `pip/` and `uv/` with the newest pip and uv on Python 3.12.10 — an exact patch, because pip's report and uv's output both record it — uploads what it captured whether or not it passes (`captured-fixtures`: the fix for a real drift is to review and commit exactly those bytes), fails if any fixture but `capture-provenance.json` moved, and runs `cargo test` over the new captures. It failed seven Mondays running before 1.4.0, mostly for reasons that were not engines — idna's newest release and scipy's growing version list, now pinned and redacted in `capture.py` — and it was blind where it mattered: the capture venv never upgraded pip, so the job meant to see a pip change ran the CPython-bundled 25.0.1 throughout. The one real change, uv 0.13's new rendering, was answered by freezing the old captures as `uv-0.11/`.
### 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 are generated by `cargo run -p xtask -- bindings` over `schemars`, not by tauri-specta as this line once said, so **drift is a test failure rather than a compile error** — which means it fires at `cargo test`, locally as well as in CI. See `crates/pipdock-core/src/bindings.rs`.
Component tests for `PdConflictRow` (3-way state), `PdPreviewDiff` grouping, `PdSummarySheet` counts, dimming/badging rules on `PdPackageTable`, and the design-token contrast test — every text/surface pair ≥ WCAG AA, and since 1.4.0 every badge tint composited over every surface too; it is a test, so it gates every PR. Store tests include `ui/src/stores/races.test.ts` (1.4.0): each holds a command open, moves on — another environment, another timeline entry, Back out of a plan — and only then lets it answer, because five stores wrote whatever came back without asking whether the question was still the one being asked. Six of its seven tests fail on the stores before 1.4.0. `i18n.test.ts` fails on a catalog code that either language has no copy for.
IPC is mocked at the typed wrapper layer (`ui/src/test/ipc.ts`, a factory each test file passes to its own `vi.mock`) with payloads **serialized from the real Rust types** by `cargo run -p xtask -- ipc-fixtures` into `ui/src/test/fixtures/`, and `cargo test` fails when the committed files are stale — which is what guarantees UI and core agree on shapes. Where production computes a value, the fixture is computed by the same function: the guard report and the dependency graph by the real graph over the scenario's rows, the preview's blockers by `blockers_for`, and since 1.4.0 `flow_step_forced.json` by `plan::derive_forced` and `release::mismatch`. A hand-written blocker list that matched the docs while the code had drifted is how the preview shipped a garbled sentence from S3 to 1.1.0 with every suite green. `fixtures.rs` is compiled only under `cfg(test)` or the `fixtures` feature xtask enables, never into a release build. Types are generated by `cargo run -p xtask -- bindings` over `schemars`, not by tauri-specta as this line once said, so **drift is a test failure rather than a compile error** — which means it fires at `cargo test`, locally as well as in CI. See `crates/pipdock-core/src/bindings.rs`.
### 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.
Goldens over the real binary. There is no mocked core — this line promised one, and the CLI has no seam to mock at (`golden.rs` says why) — so what is goldened is everything deterministic without an interpreter: every command's and subcommand's help, which is the flag contract scripts read; the JSON and human error envelope; and `pipdock schema <T>` for every type in `SCHEMA_TYPES`, plus the unknown-type list — **68 snapshots at 1.4.0**. The exit-code table is asserted for the rows reachable without an interpreter (0, 2 and 3); L2 asserts the ones it can reach. A golden diff is a behaviour change: re-bless deliberately, never reflexively.
### L5 — E2E smoke (tauri-driver, P1 gate for release)
**Not covered by a committed test**, though this line claimed both: TTY versus non-TTY prompting, and `--json` payloads checked against `pipdock schema`'s output. CLI-SPEC §6's one-document `--json` rule was verified for 1.4.0 by driving the real binary through every path (ROADMAP), not by a test that stays.
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.
### L5 — E2E smoke — **not built**
The plan was one scripted tauri-driver run on a Windows runner — launch → legal gate → select seeded venv → update-all happy path → summary visible → rollback — as a P1 gate for release. Nothing implements it: no tauri-driver, no WebDriver, no job. What stands in is a person building, installing and driving each release's installer by hand (§4, and ROADMAP Phase 4's "building and installing are their own test tier"). An installer smoke test is in ROADMAP's Audit backlog.
## 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).
**No coverage is measured.** This section set targets — core ≥ 85 % line coverage (`cargo llvm-cov`), classifiers and plan module ≥ 95 % — that nothing has ever measured: `cargo llvm-cov` is not wired anywhere, and coverage is in ROADMAP's Audit backlog. Until it is, the guarantee is §1's rule — a test that failed first — rather than a percentage.
**Required on every PR** (RELEASE-CI §2 has the exact payload): `fmt · clippy · test` — fmt, clippy `-D warnings`, and `cargo test --workspace`, which is L1, L4 and the Tauri crate's tests; `lint · typecheck · test · build / build` — ESLint, `tsc`, L3 and `vite build`; `cargo audit`; `npm audit`; and CodeQL's JavaScript/TypeScript analysis. `cargo deny`, `tauri lockstep` and CodeQL's Rust and Actions analyses run on every PR and are not required.
**L2** runs nightly, on dispatch, and on PRs that touch what its end-to-end steps run through — the path list in `ci-integration.yml`, which 1.4.0 widened to the CLI, `exec.rs`, the audit, release, error, store and index modules, `Cargo.lock` and `rust-toolchain.toml` — each of them something the end-to-end steps run through, whose changes used to reach `main` without this job seeing them. (This line named `engine|plan|snapshot|graph`; the filter had outgrown that before 1.4.0.) It is not a required check: a path-filtered check that never starts stays pending forever.
**The weekly drift job** reports a failure to Discord through `notify-ci-failure.yml`, like any failure on `main`. It does not file an issue, which this section said it did.
## 4. Manual test charter (per release)
+184 -21
View File
@@ -24,7 +24,18 @@ Anti-goals: gradients-everywhere SaaS look, rounded-blob cards, decorative glow.
| `--color-danger` | `#F26A63` | impossible, failures, force actions. `#F0574F` until 1.4.0, which read at 3.92:1 on its own badge tint over a selected row |
| `--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.
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 (**not built**: the status line says nothing of a running plan, only `scanning` or `idle` — audit backlog U52); `prefers-reduced-motion` respected.
**A badge is checked as what it is drawn as, not as its token** (1.4.0). A badge is its text on a tint
of its own colour — `badgeTones.ts`: 20 % for warn, info and accent, 15 % for danger — and the tint
lowers the contrast the plain token has. Danger read **3.92:1** on its own 20 % tint over a selected
row (`surface-2`), under AA, while the token test passed, because it checked tokens on plain surfaces
only. `tokens.test.ts` now composites every tone's tint over every surface and asserts AA on the
result. Both changes were needed: the new `#F26A63` at the old 20 % tint is still 4.29:1 there, and at
15 % it is 4.67:1.
**`--container-content` (87.5rem)** is the content column's widest. It is what stops a table
stretching across a maximized 4K window, now that the window itself is the user's to size (§5).
## 3. Layout
@@ -65,15 +76,28 @@ tabs rather than inside them so the explanation is never reachable only from the
specified against `plan-progress`, and the status line's toggle is disabled unless a plan is
running. Health claims a *separate* session slot by design — a health run and an install can be in
flight at once — so one toggle cannot address two drawers. `PdHealth` renders its own instance
with its own toggle rather than teaching the status line to choose.
with its own toggle rather than teaching the status line to choose. The Security tab does the same,
since 1.2.0 and for the same reason: an audit holds a slot of its own as well.
The log toggle opens the console drawer, and is disabled when no run is in progress. Until M3's
logging subsystem exists the drawer is the only log surface there is, and a toggle that opened an
empty panel would be the same empty gesture the plain-text version was. The **console drawer** slides up over the status line during execution, streaming `plan-progress` lines with per-package section markers; collapsible, never modal.
The log toggle opens the console drawer, and is disabled when no run is in progress: a toggle that
opened an empty panel would be the same empty gesture the plain-text version was. The drawer was once
the only log surface there was. **Since 1.4.0 PipDock also writes its own log** — one file per UTC
day under `data\logs\`, kept 14 days — and Settings' Logs row (§4) says where it is and copies its
recent lines. The toggle still opens the drawer, which streams the run in progress; the file is the
record of what PipDock ran, which outlives the window. 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.
**Environments.** Auto-discovered list (source chip: registry / py launcher / uv / venv / manual) with Python version, package count and pip version; PEP 668 envs carry a red `MANAGED` chip and a line pointing at a virtual environment instead. Actions: *Use*, *Open* (the detail view below), *Rescan*, and *Upgrade pip* when pip is below the planner's floor (§5).
**This line used to promise three things the screen does not have.** A managed environment is not
*disabled*: it can be selected and read, and a change to it is refused with PD-ENV-002 by the flow —
decided on a fresh probe since 1.4.0, not on whatever the row last cached — unless the Settings
override is on. *Browse…* is still owed: `env_add_manual` is the one command left in `NOT_YET`, so an
environment is found only by discovery — the registry, the `py` launcher, `uv python list`, and a
`.venv`, `venv`, `env` or `.env` in the working directory. And there is no star-as-default: the
selection lasts for the session, and a rescan keeps it or falls back to the first usable row. The
CLI's `env use` stores a default, honoured since 1.4.0; the GUI does not read it.
**Installed.** Virtualized table: name (mono) · version · latest · size · chips. When the env's `hidden_user_site` is non-null (non-venv system Pythons only — see SECURITY §2), an inline `--color-info` note above the table says user-account packages are not listed and names the path; it is informational, never a block, and never appears for a venv. 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, and **details**, as three inline buttons rather than a `⋮`
menu. A menu would spend one click opening and one choosing, leaving one of §5's three for a confirm
@@ -91,7 +115,16 @@ its controls are a roving sequence rather than tab stops, and a third is one mor
No button is a tab stop — the row is (see §8). 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: grouped sections — *Will upgrade* (A `1.2 → 2.0`), *Will downgrade*, *Will install*, *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`.
**The header and every row share one set of column widths** (`packageColumns.ts`, 1.4.0). The header
was a hand-written mirror of the row and had drifted: one 2rem slot stood above three action buttons,
so every fixed column's heading sat about 76 px right of its cells. And the fixed widths summed to more
than the table has at the 900 px minimum window, with the name column absorbing the whole deficit — so
at that width it showed no names at all. **A narrow table drops Size first** and tightens the rest, by
container query against the table's own width rather than the window's (Size returns at 48rem): the
plan panel or a split view changes the one without the other. Header and scroller reserve the same
scrollbar gutter, so a scrollbar appearing does not push the cells out from under their headings.
**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: grouped sections — *Will upgrade* (A `1.2 → 2.0`), *Will downgrade*, *Will install*, *New dependencies*, then *Will break*, *Left out — needs a different Python* and *Withdrawn releases* (1.4.0, below), and last *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: `Back`, *Apply choices* while decisions are pending, and `Confirm (n changes)` — `Confirm (n changes, breaks m)`, with the danger treatment, when the plan forces something. The panel's heading names the interpreter it changes, with the PEP 668 chip beside it where that applies: the panel replaces the screen it was started from, so a plan started from Search's dock bay gave no sign of which environment it was for.
*Will downgrade* was added in S3. `ChangeKind` has always had four variants and this section named three, leaving `Downgrade` with nowhere to go — and it is not a rare case: a *compatible* resolve routinely moves a package **down** to satisfy something else's constraint. Folding it in with the upgrades would have been the worst outcome, since a row reading `2.0 → 1.9` under a heading that says "Will upgrade" is actively misleading about the one change most likely to surprise. It carries `--color-warn` for the same reason.
@@ -99,14 +132,57 @@ No button is a tab stop — the row is (see §8). Multi-select via checkboxes; b
**The round counter is visible.** `MAX_CONFLICT_ROUNDS` is 3; when a decision round is applied the preview says how many remain, and the exhausted state keeps the preview on screen with the controls disabled rather than dead-ending. Without it a user hits the cap unwarned.
**Three sections arrived in 1.4.0, each rendering a field `ResolutionReport` had and nothing showed.**
- ***Will break (n)***, in `--color-danger`: each package forced past what held it back, as
`name → latest`, and under it every dependent named with the constraint the forced version
violates. *n* counts broken **dependents**, not forced packages (the heading reads *Forced (n)*
when no blocker names one), and the same count is on Confirm — DISCLAIMER §2 requires what forcing
breaks to be said before it runs, and a section the user has not scrolled to has not said it. There
was nothing to show before 1.4.0: *Force latest* was recorded in the request and never read, so a
"forced" resolve was the held-back one again.
- ***Left out — needs a different Python (n)***, in `--color-warn`: each release left out because its
`Requires-Python` excludes this interpreter, with the range set against the interpreter's version
(hard invariant 10). It is one of three things: an exact pin the user asked for, the latest of a
package they chose to force, or a release the engine planned — uv ignores an upper bound — which is
ruled out by name and the engine asked again. A request that is nothing but such pins is refused
with PD-PKG-001; one with anything else in it plans the rest, and a plan whose only content is a
left-out row is not "nothing to change", because the user asked for something and is owed the
reason it is not happening.
- ***Withdrawn releases (n)***, in `--color-warn`: PD-PKG-003 for each yanked release in the plan,
with the maintainers' reason when the engine printed one. A warning, not a refusal — both engines
install a yanked release (SP-2). Both parsers had always extracted these; the adapters dropped them.
**Back from a preview is not a finished run** (1.4.0). The selection is kept and nothing is
refetched, where it used to be cleared as if something had changed. Leaving work the backend still
holds — Back during a resolve, or out of a parked preview — stops it there (`plan_cancel`), and a late
answer no longer re-opens the panel the user closed. A decision round that fails leaves the preview
usable, because the flow stays parked; its Confirm used to answer "no plan".
**After a run the panel shows the summary** (`PdSummarySheet`): the counts, a row per package, the
snapshot with *Roll back to this*, and what the post-run check found. Since 1.4.0 each row says what
it moved *from* — the engines cannot know it, so every upgrade used to read as a fresh install — and
a check that could not run **says so** ("could not check the environment afterwards", with its code)
instead of rendering nothing, which read as a pass in exactly the case nothing was verified: a run
that broke pip itself.
**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, committed on blur; unpin per row. **Exclude pins only**: a
`Hold` pin is rendered faithfully if one exists, but creating one is not offered, because
`pins::hold_requirements` has no caller and `engine::plan_requirements` restates every package at its
*installed* version — a hold at any other version is a promise nothing keeps, and the CLI cannot
create one either. With no environment selected the screen says so rather than "no pins": pins are
keyed by `env_hash`, so that is not an empty list.
*Install (n)* keeps the queue until the resolve has answered (1.4.0): a plan already in flight, or an
index that could not be reached, used to cost the user the list they had just built. Once there is a
preview, the preview is the list. A search typed while the index is still warming is asked again when
it is ready, rather than waiting for another keystroke. The field's focus on arrival is the shell's
job — see §8's `data-autofocus`.
**Pins.** Pin list with reason field, committed on blur; unpin per row. An `Exclude` pin keeps its
package out of **every** update, a named one included — DATA-FLOW §9.5, enforced by
`pins::filter_upgrades` — not only out of *Select all*. **Exclude pins only**: a `Hold` pin is
rendered faithfully if one exists, but creating one is not offered, here or by the CLI, whose
`pin add` writes `Exclude` and nothing else. The reason this paragraph gave until 1.4.0 has gone:
`pins::hold_requirements` had no caller, so a hold was a promise nothing kept, and since 1.4.0 every
resolve restates a held package at its version. A hold is now honoured if one exists; nothing makes
one. With no environment selected the screen says so rather than "no pins": pins are keyed by
`env_hash`, so that is not an empty list.
**The auto-suggest section** — "`urllib3` — 12 packages depend on it. Pin?" — landed post-1.0 as
P1-A. It sits *above* the pin list, because it is a prompt to act and the list is a record of
@@ -132,6 +208,9 @@ columns — what requires it, and what it requires — each row carrying the spe
edge, and each clickable to re-centre. Below them, the two transitive counts: how many packages a
removal would leave with a missing dependency, and how many the package pulls in itself. A
requirement that nothing installed satisfies is called out; nothing else in PipDock reports one.
Platform markers are read since 1.4.0 — probe schema 3 reports the marker environment — so a
requirement gated to another platform, such as ipython's `pexpect; sys_platform != "win32"`, is no
longer reported missing from every Windows environment.
**Drawn at depth 1, and depth is navigated rather than drawn.** Measured on the 352-package fixture
before the screen was designed: a depth-1 neighbourhood is a median of **7** nodes and a p90 of 25,
@@ -172,7 +251,7 @@ rollback are disabled with a line saying why. The diff's copy names the *directi
in the snapshot — restoring removes it" — because "added" is ambiguous the moment you read it from
the snapshot's side.
**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.
**Health.** Project-folder picker (persisted per env — on disk, through `EnvRow.healthProject`; on screen the folder is taken from the row only while none is set, so after a switch it stays the previous environment's for the rest of the session, audit backlog U16) → run panel with three result tabs (deptry / vulture / ruff) per CODE-HEALTH-SPEC; `Fix with ruff` gated behind explicit confirm listing file count.
**Security.** *Run audit* → advisories grouped by package, each with its id, the versions that fix
it (or **no fix**, stated rather than left blank), its aliases — which is where the CVE lives, since
@@ -184,9 +263,53 @@ no equivalent of: an audit is 18-68 s against Health's 1.3 s. **The body says no
in flight** — not "no audit has run", which is what it said until someone clicked Run against a slow
bridge and read it.
**Settings.** Engine (pip/uv radio + detected versions), locale (EN/VI), **pin auto-suggest count** (P1-A; zero turns suggestions off), snapshot retention, index refresh, PEP 668 override (off by default, scary copy), *Open logs folder*.
**It scrolls** (1.4.0). The screen's root was a bare `<div>` inside a `<main>` that clips, so a report
taller than the window could not be reached at all; it is now one scroll container with its console
drawer pinned beneath, as Health's is. *Cancel* is honoured from the start as well: the cancellation
token used to be registered after the environment's freeze, so a Cancel during it did nothing, and a
run stopped that early now skips the audit venv's sync and reports itself cancelled.
**Disk usage** (P1-C) shows what PipDock has written — snapshots and the Code Health tools venv, each with a *Clear*, and `index.db` reported without one because it holds settings, pins and the consent record in the same file. Three artefacts, not four: there are no log files, `LOG_RETENTION_DAYS` has never had a reader, and a "logs — 0 B" row would invent one.
**Settings.** In screen order: engine (pip/uv radio, each with its version for the selected environment), language (en/vi), **pin auto-suggest count** (P1-A; zero turns suggestions off), PEP 668 override (off by default, scary copy), Disk usage, Logs. Every control saves on change — the override, once its confirm is answered — which is what keeps *Switch engine* at three clicks (§5).
**This line used to list two settings that do not exist.** There is no snapshot retention — snapshots
are kept until cleared under Disk usage — and no index-refresh setting: the index is downloaded from
Search when it is missing, or by `pipdock index refresh`, and its seven-day staleness is reported,
never acted on. *Open logs folder* became the Logs row below.
**Each engine's version is beside its radio** (1.4.0), for the selected environment — pip's comes from
`<python> -m pip --version`, so there is no answer without one — and an engine that is not installed
reads *not found*. `engine_info` had a typed wrapper and no caller, so nothing said uv was missing
until a plan failed for want of it. The answer is keyed by interpreter, so switching environments
never shows one's versions under another. Nothing preselects uv yet: a fresh install drives pip, and
the first-run detection ARCHITECTURE §3 specified is owed (PRD P0-9). `settings.rs` puts it here, as a
choice made where it can be seen, rather than in a read of an empty store.
**The language is stored** (1.4.0) as the user's *choice*, `null` meaning "follow the OS", and applied
at start. `save()` sent `locale: null` every time, so choosing Vietnamese lasted until the window
closed. Settings now load when the app starts, not only when this screen mounts, and before the
legal gate — so the gate is in the chosen language too, and the status line's engine and the PEP 668
chip are right before anyone has opened Settings.
**Turning the PEP 668 override on asks first** (1.4.0, SECURITY §3): a `PdDialog` with Cancel focused,
saying that `--break-system-packages` will be passed for every environment marked
`EXTERNALLY-MANAGED` and that rolling back to a snapshot may not repair what that breaks. Turning it
off saves at once — restoring protection never needs a second thought. Until 1.4.0 the override was
one click on a checkbox that saved and **nothing read**; every mutating flow now probes first, decides
on what the probe says, and carries the override to the engine call only when it is on (hard
invariant 5).
**While the override applies, a chip says so** — `PdOverrideChip`, SECURITY §3's persistent warning —
on Installed and Updates, Search's dock bay, the plan panel and an environment's detail. *Applies*
means the setting is on **and** the environment carries the `EXTERNALLY-MANAGED` marker. A venv never
does, and a chip there would claim the flag is being sent when it is not.
**Disk usage** (P1-C) shows what PipDock has written — snapshots, the Code Health tools venv and, since 1.2.0, the Security tab's audit venv, each with a *Clear*, and `index.db` reported without one because it holds settings, pins and the consent record in the same file. Since 1.4.0 a *Clear* is refused with PD-RES-003 while the feature that owns its target is running — Health for the tools venv, an audit for the audit venv, a plan for the snapshots — rather than deleting the venv a run is executing from; a preview that is merely parked is put back afterwards. **Logs are not a row.** This paragraph once said there were no log files and that a "logs — 0 B" row would invent one. Since 1.4.0 there are, and they look after themselves, so a *Clear* would only take away the record a bug report needs.
**Logs** (1.4.0) shows the log folder as a path — data, never translated (I18N §2) — and *Copy recent
log*, which re-reads the tail at the moment of copying, so the clipboard holds the run that just went
wrong rather than what the log said when the screen opened. The folder is shown rather than opened:
the opener is scoped to four `https` hosts and nothing local, and the copy uses the clipboard
permission *Copy full log* already had, so no capability was widened for the row.
The threshold is the app's **first numeric input**, and it sets the rule for the next one: reject at the boundary, never store junk. `<input type="number">` reports `''` for anything it cannot parse, so coercing the raw value writes `0` — which here is a meaningful setting, "off", that the user did not ask for. Its label avoids the word *threshold* on purpose; see `PdPins.test.tsx`'s Hold assertion, which matches `/hold/i`.
@@ -194,6 +317,16 @@ The threshold is the app's **first numeric input**, and it sets the rule for the
**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.
**Decline has exited the app only since 1.4.0.** The webview was granted `core:default` — some sixty
core commands nothing called — and not `core:window:allow-close`, so in the installed app Decline did
nothing, while its component test, which mocks `close()`, passed. `capabilities/default.json` now
holds exactly what the frontend calls, and a test in `lib.rs` pins the union of every capability
file. **A consent that cannot be read or recorded is shown**, as an error row on the gate; the failure
used to be stored and never rendered, so *Continue* looked like a button that did nothing. And the
hash ignores line endings: a build from a CRLF checkout used to carry a different hash from an LF
build of the same commit, so two builds of one commit could disagree about whether the documents had
changed.
It has a second, **presentational** mode since Phase 4: About re-opens it so the documents can be read again, and in that mode the checkbox and both buttons are replaced by a single *Close*. Consent is neither read nor written. This is a flag of its own (`useLegalStore.review`) rather than setting `accepted = false`, which would have been one line and would have made a review indistinguishable from a revocation — offering Accept and a Decline that closes the application to someone who only wanted to re-read their privacy policy.
**About.** The ninth tab (`Ctrl+9`): what PipDock is; this build — version from `app_info`, the SPDX identifier `GPL-3.0-only`, and the legal-documents hash consent is recorded against; a button that puts the gate back on screen; and contact — two addresses and the author's links page. The addresses are **copied to the clipboard, not opened**: `mailto:` would widen the opener capability by a whole URL scheme, and SECURITY §4 asks for a reason per widening. They are also rendered from a TypeScript constant rather than the catalogs, because an address is data (I18N §2) and a catalog invites a translator to change it. Only `https://poli0981.dev/*` was added to the allowlist, for the links page.
@@ -264,22 +397,52 @@ modal §7's destructive confirms need), `PdUninstallDialog` (§5's three options
including its `PD-SNP-002` list) and `PdAuditReport` (P1-1's advisory list). Three more shipped in
1.1.0 and are named nowhere in this section: `PdCacheUsage`, `PdPalette` and `PdRequirements`.
`PdDepsFocus` (1.3.0, PRD P1-6's focus view) makes **ten** off-list components; it is written here
in the same breath as the count so the two cannot drift apart again.
in the same breath as the count so the two cannot drift apart again. 1.4.0 adds `PdOverrideChip`
(SECURITY §3's chip, §4) and `PdLogs` (Settings' Logs row), which makes **twelve** — and 15 + 12 is
the 27 `Pd*` components in `ui/src/components/`, which is the check to run rather than trusting
either number. Screens (`ui/src/screens/`, `PdPlanPanel` among them) are not counted.
## 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, and — since P5 — `Fix with ruff`, the only one that writes outside an environment) use `--color-danger` primary buttons and require the dialog's default focus to be **Cancel**. Each also carries a `data-action` in `styles.css`'s forced-colors list, because high contrast drops every tint and a destructive primary that looks like Cancel is worse than no colour at all.
- Errors: inline with catalog code, human message (localized), and *Details* expanding stderr tail. Toasts only for background completions. *Report bug* opens a prefilled GitHub issue that nothing sends until the user submits it; since 1.4.0 the link is rebuilt at the click with the selected environment, so the issue carries its Python version and the configured engine's version — one subprocess per report, rather than one per error row mounted, which a summary of many failures would multiply.
- Destructive confirms (`Force latest`, uninstall with breakage, PEP 668 override, and — since P5 — `Fix with ruff`, the only one that writes outside an environment) use `--color-danger` primary buttons and require the dialog's default focus to be **Cancel**. The PEP 668 override was on this list while it was a bare checkbox with no confirm at all; it has been a `PdDialog` since 1.4.0. A `data-action` in `styles.css`'s forced-colors list gives a destructive control a 2 px border, because high contrast drops every tint and a destructive primary that looks like Cancel is worse than no colour at all. **The list is `force` (the guard's *Remove anyway*), `uninstall`, `rollback`, `upgrade-pip` and `fix`, and it is not complete:** the uninstall dialog's plain *Remove* (`remove`), the *Force latest* inline confirm's button, the override's *Allow* (`allow-override`), Disk usage's *Clear* confirm (`confirm-clear-cache`) and the plan panel's danger-treated Confirm (a rollback, or since 1.4.0 a forced plan) are not in it, so in high contrast each is told from the control beside it by its label alone. The active sidebar tab has the same problem by another route: it carries `aria-current="page"`, and the outline rule matches `'true'`. All of it is audit backlog U45, deferred to a High Contrast pass done by hand.
## 8. Keyboard & accessibility
Full keyboard traversal: `Ctrl+1..9` sidebar tabs, **`Ctrl+K` opens the command palette**, `/` focuses search, `Space` toggles row selection, `Ctrl+A` select-all-visible, `Enter` primary action, `Esc` closes drawers, and **`←`/`→` move within a focused row** (P6).
Full keyboard traversal: `Ctrl+1..9` sidebar tabs (by physical key), **`Ctrl+K` opens the command palette**, `/` focuses the Search field, `Space` toggles row selection, `Ctrl+A` select-all-visible, `Enter` primary action, `Esc` closes drawers, and **`←`/`→` move within a focused row** (P6).
**Four rules from 1.4.0:**
- **`Ctrl+1..9` match the physical key** — `e.code`, `Digit1..9` or `Numpad1..9` — not the character
the layout types. On AZERTY, Ctrl+1 reports `&`, so the tab shortcuts did nothing on every French
keyboard. `Ctrl+K` still reads `e.key`, and that is an open question rather than an oversight: for
a letter the physical key is the wrong answer on Dvorak (audit backlog U49).
- **`/` focuses the Search field, from Search itself too.** There `nav` does not change, so the focus
effect did not run and `/` did nothing on the one screen it names. It is ignored while typing in a
text field, so a version specifier can still contain a slash.
- **A screen can name its first focus stop with `data-autofocus`**, and that wins over the heading the
shell otherwise focuses on every tab change. §5's four-click install depends on Search's field
having focus on arrival, and it lost that focus every time to the shell's effect, which runs after
its children's.
- **A release build swallows the browser's own shortcuts** (`browserKeys.ts`): F5 and Ctrl+R
(reload), Ctrl+P (print), Ctrl+F, F3 and Ctrl+G (find), Ctrl+U (source), Ctrl+S (save), Alt+←/→, and
the hardware browser keys for back, forward and refresh. WebView2 is a browser and kept them: a
reload dropped a preview mid-decision along with everything the stores had not persisted, and find
opened over a virtualized table whose off-screen rows are not in the DOM. The listener is in the
capture phase and above the legal gate, so no screen or modal lets one through. Development keeps
them, because a reload is how a developer recovers from a bad hot update. **Right-click is not
covered:** WebView2's context menu still offers Reload, Back and Print in a release build, and
removing it would take Copy and Paste out of every text field with it — a decision, not yet made.
A dialog — `PdDialog`, and the palette — returns focus to whatever opened it when it closes; it used
to fall to `<body>`, and a keyboard user lost their place in a 200-row table. The package grid itself
is focusable but not a tab stop: the row is.
**The arrow keys are not decoration, and the gap they close was real.** Making the row the only tab stop is what keeps 200 rows from becoming 600 — but every control inside one is `tabIndex={-1}`, and that left *Pin* and *Remove* reachable by mouse only: a WCAG 2.1.1 failure, found by tabbing to a row in the running app and discovering there was nowhere further to go. `←`/`→` are the ARIA grid pattern's roving tabindex, `Esc` returns focus to the row, and no tab stops are added.
**`Enter` on a row is the *non-destructive* primary.** On a package row that is pin, never uninstall: a row has one reversible annotation and one irreversible removal, and a destructive operation one keypress from a focused row is an accident waiting rather than a primary action. Everywhere else in the app `Enter` needs no binding at all, because every other primary action is a real `<button>`.
**"Select-all-visible" means the current filtered set, not the rendered window.** Resolved in S2: the package table is virtualized, so only ~25 of a 200-package environment are in the DOM at any moment and "visible" would otherwise mean whatever the scroll position happens to be. `Ctrl+A` selects every *selectable* row in the set the screen is showing — so on Updates that is the outdated rows, and pinned rows are excluded there as they are from the *Select all* button. The row, not its checkbox, is the tab stop and the target of `Space`; tabbing through two controls per row is not traversal at 200 rows. 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.
**"Select-all-visible" means the current filtered set, not the rendered window.** Resolved in S2: the package table is virtualized, so only ~25 of a 200-package environment are in the DOM at any moment and "visible" would otherwise mean whatever the scroll position happens to be. `Ctrl+A` selects every *selectable* row in the set the screen is showing — so on Updates that is the outdated rows, and pinned rows are excluded there as they are from the *Select all* button. The row, not its checkbox, is the tab stop and the target of `Space`; tabbing through two controls per row is not traversal at 200 rows. Contrast: all text tokens meet WCAG AA on their surfaces, and since 1.4.0 so does every badge's text on its own tint over every surface (§2; both 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.
+1 -1
View File
@@ -1,6 +1,6 @@
# PipDock — Privacy Policy
*Version 1.2 · Effective 2026-10-16 · Governing language: English.*
*Version 1.2 · Effective 2026-10-17 · Governing language: English.*
## 1. The short version
+1 -1
View File
@@ -1,6 +1,6 @@
# PipDock — Third-Party Notices
*Version 1.2 · 2026-10-16 · This inventory is maintained by hand and reconciled against the manifests (`Cargo.toml`, `src-tauri/Cargo.toml`, `crates/*/Cargo.toml`, `package.json`) at each release. It names the direct dependencies PipDock declares, not their transitive trees — for the complete resolved graph, read `Cargo.lock` and `package-lock.json`, which are committed. All bundled licenses are GPL-3.0-compatible.*
*Version 1.2 · 2026-10-17 · This inventory is maintained by hand and reconciled against the manifests (`Cargo.toml`, `src-tauri/Cargo.toml`, `crates/*/Cargo.toml`, `package.json`) at each release. It names the direct dependencies PipDock declares, not their transitive trees — for the complete resolved graph, read `Cargo.lock` and `package-lock.json`, which are committed. All bundled licenses are GPL-3.0-compatible.*
## A. Bundled / linked components (distributed with PipDock)