One run in five on #120 reported "Unused crate: sha2", the crate env_hash is built on, on a commit that changed only a Markdown file. Every run's sanity check finds the Cargo project only partly loaded in the linter's container, and the inspection sometimes concludes from that. A baseline entry would not hold, because its fingerprint hashes neighbouring lines that Dependabot rewrites weekly. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1805 lines
161 KiB
Markdown
1805 lines
161 KiB
Markdown
# PipDock — Roadmap
|
||
|
||
*Version 0.1 · 2026-07-17*
|
||
|
||
## Phase 0 — Spike week (before any feature code) — **RUN 2026-07-27**
|
||
|
||
The entire architecture stands on assumptions that must be verified on a real machine first (the FrameLedger/QuoteAtlas discipline). Each spike is a small script + captured fixtures committed to `crates/pipdock-core/tests/fixtures/`.
|
||
|
||
**Outcomes — full write-up in [`spikes/README.md`](../spikes/README.md).**
|
||
|
||
| Spike | Verdict | The one thing that changed |
|
||
|---|---|---|
|
||
| SP-1 | **GO — ship both engines** | Neither engine holds packages back on `install -U <pkg>`; both silently break installed dependents. **Every plan must restate the full installed set as explicit requirements.** uv's conflict attribution is *better* than pip's; uv writes its plan to **stderr**, not stdout. uv minimum pinned at 0.10.0. |
|
||
| SP-2 | Corpus captured; **blocker found and fixed** | `pip install --dry-run --report -` crashes with `UnicodeEncodeError` on Windows/cp1252 (pip 25 **and** 26). Every pip invocation must set `PYTHONIOENCODING=utf-8` + `PYTHONUTF8=1`. Also: yanked releases exit 0 (a preview warning, not a failure), and pip/uv disagree on Requires-Python enforcement. |
|
||
| SP-3 | **PASS** | 858 k projects; cold refresh 2.95 s (budget 60 s); worst keystroke 42.1 ms (budget 50 ms) — but only **in memory**: scanning SQLite per keystroke costs 218 ms. Margin is thin on fast hardware, and raw nucleo ranking puts `requests-ntlm` above `requests`. |
|
||
| SP-4 | Answered | `--path` cannot be combined with `--no-deps`; freeze-file mode (`-r <freeze> --no-deps -f json`) is the only option. SECURITY §6 confirmed. Findings arrive with duplicate advisory ids. |
|
||
| SP-5 | Answered by SP-1 | **No engine reports held-back items at all.** Resolved version, latest version and blocker must all be derived by PipDock — for pip as much as for uv, contrary to ARCHITECTURE §3's implication. |
|
||
| SP-6 | Answered | `uv python list` returns downloadable entries and duplicate shims; `env_hash` **must lowercase** the interpreter path on Windows or pins and snapshots split in two. `probe.py -I` hides 24 user-site packages on a system Python — open decision. Microsoft Store Python still unverified. |
|
||
|
||
**Both adapter-behaviour questions were decided 2026-07-27** and are implemented: PipDock enforces `Requires-Python` itself so the preview is engine-independent (`crates/pipdock-core/src/compat.rs`, ARCHITECTURE §3), and `probe.py` keeps `-I` while reporting `hidden_user_site` so the Installed screen can disclose the gap accurately (SECURITY §2). Two non-blocking questions remain at the end of `spikes/README.md`: search ranking scope, and how to obtain the five error fixtures this machine cannot produce.
|
||
|
||
| # | Spike | Question to answer | Exit criterion |
|
||
|---|---|---|---|
|
||
| SP-1 | **uv dry-run shape** | Exact stdout of `uv pip install -U --dry-run` (current + previous uv) across: clean upgrade, held-back, impossible. Is held-back attribution derivable, or does uv only show the resolved set? | Fixture set committed; adapter parsing strategy written; uv minimum version pinned. **Go/no-go for launching with both engines** — if uv's plan output is too lossy, v1.0 ships pip-primary with uv behind a "beta engine" flag. |
|
||
| SP-2 | **pip report & stderr corpus** | Capture `--dry-run --report` JSON + real stderr for every ERROR-CATALOG build/network/permission case (broken sdist, MSVC-missing, PEP 668, locked file, yanked, hash mismatch). | ≥ 1 fixture per launch catalog code. |
|
||
| SP-3 | **PEP 691 index economics** | Full name-index size, download time on VN broadband, SQLite ingest time, fuzzy-search latency on ~600 k names. | < 60 s cold refresh, < 50 ms search on the i7-14700KF and on a low-end reference VM; else design delta/compression fallback. |
|
||
| SP-4 | **pip-audit foreign-env mode** | Correct invocation for auditing an env the tool isn't installed in (freeze-file `--no-deps` vs newer options). | Command line + JSON fixture pinned (P1 feature, but flags decided now). |
|
||
| SP-5 | **Held-back attribution accuracy** | On a real numpy/scipy/pandas pin tangle: does graph-based blocker attribution match reality? | Preview sentences verified by hand against the tangle; ambiguity fallback path exercised. |
|
||
| SP-6 | **Windows env discovery sweep** | PEP 514 registry + `py -0p` + Microsoft Store Python + uv-managed on a real machine; Store-Python aliasing quirks. | Discovery module design note updated; Store Python either supported or explicitly detected-and-explained. |
|
||
|
||
## Phase 1 — M1 "Core + CLI" — **substantially complete 2026-07-27**
|
||
|
||
Engine trait + both adapters (per SP-1 outcome), probe.py, discovery, index cache + search, plan/resolve/execute two-phase, snapshots, pins, guard graph, error catalog, CLI over all of it. **Exit:** TESTING L1+L2+L4 green in CI; `pipdock update --all` survives the SP-5 tangle env with correct summary; dogfood on Kokone's own bot venvs begins.
|
||
|
||
### What works
|
||
|
||
Every P0 CLI command except `health`: `env list|use`, `list [--outdated]`, `search`, `info`, `install`, `update`, `uninstall`, `pin add|remove|list`, `snapshot list|create|diff|rollback`, `doctor`, `pip-upgrade`, `engine [pip|uv]`, `index refresh`, `schema`, `self report-bug`. 173 tests; `cargo fmt`, `clippy -D warnings` and `npm audit` clean.
|
||
|
||
Verified against real environments, not only unit tests:
|
||
|
||
- the held-back conflict from SP-1 is reported and attributed — `httpcore 0.15.0 (latest 1.0.9)` / `httpx 0.23.0 requires httpcore <0.16.0,>=0.15.0` — which **no engine produces**;
|
||
- `update --all` resolves the same tangle to latest, applies it, and leaves `pip check` clean;
|
||
- `snapshot rollback` restores an environment exactly (PRD §6's "env diff vs snapshot = ∅");
|
||
- the uninstall guard refuses to break `requests` and exits non-zero, per CLI-SPEC §7;
|
||
- exit codes match CLI-SPEC §5.
|
||
|
||
### Findings that changed the design
|
||
|
||
| | |
|
||
|---|---|
|
||
| `plan_requirements` | Every resolve restates the installed set, or both engines break installed dependents at exit 0 (SP-1). |
|
||
| `-U` in the dry-run argv | Without it pip plans nothing and every package looks held back for no reason. The unit test had encoded the omission instead of the document. |
|
||
| Search ranking | Tiered, not score-ordered, and ranked by selection rather than a full sort: 90.5 ms → 16.5 ms against a 50 ms budget. |
|
||
| `SnapshotProof` | `--no-snapshot` is a named waiver, not an `Option`, so forgetting a snapshot cannot look like deliberately waiving one. |
|
||
|
||
### Not yet done
|
||
|
||
- **`health`** — belongs to M3 with the tools venv (CODE-HEALTH-SPEC).
|
||
- ~~**TESTING L2 in CI**~~ — **done 2026-07-29.** It had run nightly on 07-28 and 07-29 and failed both times; five causes were found and fixed (see *L2's first runs* below). Run `30460248664` on `main` is green on all three jobs, including the fixture-drift re-capture that had never passed.
|
||
- **TESTING L4** — `assert_cmd` is a dependency and the clap surface is covered, but the golden-output tests per command are not written.
|
||
- ~~**The SP-5 tangle env**~~ — **done 2026-07-29.** A 38-package numpy/scipy/pandas/matplotlib/scikit-learn/statsmodels environment on Python 3.12, with scipy pinned so numpy had to be held back. `update --all` reported *15 successful, 0 failed, 0 skipped*, exited 0, and left `pip check` clean; numpy stayed at 1.26.4, the scipy pin held (invariant 5), and the snapshot was written before any mutation (invariant 2). See *What the dogfood found* below — the answer to SP-5's question was "yes, but the explanation was wrong".
|
||
- **Settings beyond engine choice** — locale, thresholds and the PEP 668 override land with the GUI in M2.
|
||
|
||
### L2's first runs — what actually failed (2026-07-29)
|
||
|
||
The job ran and failed three times. **No cause was a product bug** — all five were in the test harness, and all are fixed. Worth reading before touching `capture.py` or the workflow, because most of them look like the product misbehaving.
|
||
|
||
**1. The rollback assertion targeted the wrong snapshot.** The step did `snapshot create` → `update --all` → `snapshot rollback latest` → `snapshot diff latest`, asserting the prose `matches snapshot`. But `latest` moves twice during that flow: `update --all` writes a `Trigger::Plan` snapshot before mutating, and `snapshot rollback` writes a `Trigger::Rollback` one before restoring (DATA-FLOW §8 — rollback is itself reversible). So the final `diff latest` compared the restored environment against the *pre-rollback* state and correctly reported every package as changed. The rollback itself had worked. Fixed by pinning the id from `snapshot list --json` immediately after `create`, and asserting structurally on `diff --json` rather than on prose.
|
||
|
||
**2. `fixture-drift` could never have gone green.** `spikes/capture.py` built each scenario in a `mkdtemp` directory whose name carries a random suffix, and `redact()` replaced only the temp *root* — so the suffix survived into every committed sidecar, and every re-capture differed. Four further sources of churn were found underneath it: pip's `[notice] To update, run: <venv>\Scripts\python.exe` (which also leaked the capturing user's home directory into a public repo), CPython object addresses in urllib3 retry warnings, pip's download progress bar with its transfer rate, and uv's per-phase timings (`Resolved 3 packages in 775ms`). Fixed by redacting all of them in `capture.py`, splitting the sidecar into `meta.json` (contract, gated) and `capture-provenance.json` (versions and argv, excluded from the gate), and capturing cache-free so a warm dev machine and a cold runner agree.
|
||
|
||
**3. The guard step failed on the outcome it was asserting.** Fixing the rollback let the job reach the uninstall-guard step, which requires `pipdock uninstall urllib3` to exit non-zero (CLI-SPEC §7). The guard did exactly that — but the runner ends a `pwsh` step with `exit $LASTEXITCODE`, and nothing had reset it. The other seven end-to-end steps were audited; each ends on a command that legitimately exits 0.
|
||
|
||
**4. The redaction regex ate prose.** With the drift diff finally readable, it showed `Some things HTTP Core does d<PATH>` — pip's `--report` embeds package descriptions, and `does do:\n\n* Sending…` reads as drive `o:` followed by `\n` path segments. A lookbehind requiring a non-alphanumeric before the drive letter is what distinguishes a path from prose.
|
||
|
||
**5. `report-encoding-crash` cannot be re-captured on CI.** The SP-2 `UnicodeEncodeError` needs a cp1252 console and a runner's is already UTF-8, so re-capturing there recorded an ordinary successful report and destroyed the evidence. Scenarios now carry a `reproducible` flag; host-dependent ones are skipped in bulk runs and stay capturable with `--only`. pip's report also echoes the PEP 508 environment markers, which carry the host OS — normalized, while the *interpreter* version markers are deliberately left alone, since those can change a resolution.
|
||
|
||
Verified two ways: locally, both engines' captures run twice back to back differ in **0 of 96 files**; on CI, run `30460248664` re-captured against the newest pip and uv and matched the committed fixtures byte for byte.
|
||
|
||
Two things worth keeping in mind, both recorded in `.gitattributes` and `CLAUDE.md`: `-text` is what preserves the CRLF bytes the fixtures need, and `-diff` — which was also set — only suppressed the textual diff, so the drift job's own diagnostics could report nothing but "Binary files differ". Faults 3–5 were all found *because* that was fixed. And the weekly drift job's `if:` matched the *nightly* cron, so the PyPI-heavy job the comment says would be "rude" to run daily was running daily; it now has its own `'17 4 * * 1'` entry.
|
||
|
||
### What the dogfood found (2026-07-29)
|
||
|
||
SP-5 asked whether graph-based blocker attribution matches reality on a real tangle. It does — and at scale it was also **saying things that were not true**. The held-back numpy came with eight constraints, four of which do not apply to Python 3.12:
|
||
|
||
```text
|
||
numpy 1.26.4 (latest 2.5.1)
|
||
pandas 2.1.4 requires numpy <2,>=1.22.4 <- python_version < "3.11"
|
||
pandas 2.1.4 requires numpy <2,>=1.23.2 <- python_version == "3.11"
|
||
pandas 2.1.4 requires numpy <2,>=1.26.0 <- the only pandas branch in force
|
||
statsmodels 0.14.1 requires numpy <2,>=1.22.3 <- python_version == "3.10" and Windows
|
||
```
|
||
|
||
`Requirement` has always carried its marker, but only `extra ==` was honoured, so every marker-gated branch of a dependency was reported as though it were in force. That is not just noise — telling someone on 3.12 that "pandas requires numpy >=1.22.4" is false, and ERROR-CATALOG's premise is that what PipDock says about a failure can be trusted. The same bug sat under the **uninstall guard**, which would refuse a removal on the strength of a dependent that only needs the package on another Python.
|
||
|
||
Fixed in `graph/markers.rs`: `python_version` and `python_full_version` are evaluated, with `and`/`or`/parentheses. Platform markers are left alone — they are constants for a Windows-only v1 and reading them would mean plumbing more out of `probe.py` for no present gain. **An unrecognised marker keeps the requirement**, because over-reporting a constraint is noise while dropping one hides the reason a package is stuck. The same environment now reports five constraints, one per package, each genuinely in force.
|
||
|
||
One thing deliberately *not* changed: blockers are still derived from the installed set, so a package being upgraded by the very same plan can still be named. Here that meant matplotlib, pandas, scikit-learn and statsmodels appeared even though the plan moves all four to numpy-2-compatible versions, leaving pinned scipy as the only real blocker. Narrowing that needs post-plan metadata the preview does not have, and it makes the sentence over-broad rather than false. Worth revisiting when `PdConflictRow` is built.
|
||
|
||
### Where to pick up
|
||
|
||
Pushed to `main` and green: **CI / Rust, CI / Node and CodeQL all pass** on the published commit. Three configuration bugs were fixed getting there, each recorded in its own commit message: caller workflows must grant *at least* what the callee declares (a `startup_failure` with no logs), `cargo audit` was pinned to a toolchain too old to build itself, and its informational advisories needed scoping rather than silencing.
|
||
|
||
Done 2026-07-29, closing out M1's CI debt:
|
||
|
||
- ~~Dependabot triage~~ — six PRs resolved. #3 (TypeScript 7) and #4 (rusqlite 0.40) closed per ARCHITECTURE §10; #1, #2, #5, #6 merged. **No PRs are open.**
|
||
- ~~L2 green~~ — all three jobs, both matrix legs, on `main`.
|
||
- ~~TESTING L4~~ — `tests/golden.rs`, 46 snapshots. See *What L4 covers and what it does not* below.
|
||
|
||
Immediate, in rough order:
|
||
|
||
1. **Repo settings** — branch protection, the Discord webhook secrets, and CodeQL/Discussions, per RELEASE-CI §5. None of these are committable and all are owner-only. The updater keypair that used to be on this list is gone: PipDock no longer updates itself (SECURITY §5).
|
||
|
||
**M1 is otherwise closed.** Everything else on this list is done, and Stage 1 of M2 — the IPC bridge — is the next piece of work.
|
||
|
||
### What L4 covers and what it does not
|
||
|
||
TESTING §2 asks for goldens "against a mocked core". There is no seam to mock at — `run.rs` builds its engine from the global options and drives a real interpreter, and `print_preview` / `print_summary` are private functions that `println!` rather than return. So `tests/golden.rs` covers what is deterministic without an environment: the clap surface, the exit-code table, the `--json` error envelope, and `schema <T>` for all fifteen `SCHEMA_TYPES`. Preview and summary rendering stays with L2.
|
||
|
||
Those schema snapshots are also the review surface for M2's wire-format change. They pin two contract bugs as they stand today:
|
||
|
||
- `ExecutionSummary` serializes `plan_id` / `stderr_tail`, where DATA-FLOW §6 documents `planId` / `stderrTail`
|
||
- `Code` serializes as its Rust variant name (`"EnvInterpreterMissing"`), where ERROR-CATALOG documents `PD-ENV-001`
|
||
|
||
The error envelope, which `main.rs` hand-builds rather than deriving, already has the documented shape — so the binary currently disagrees with itself across its two `--json` paths. Fixing that is Stage 1 work, and the goldens make it a reviewable diff.
|
||
|
||
When the flow refactor moves rendering out of the CLI ("the flow never prints"), the preview and summary renderers become pure functions of core types and should gain their own snapshots there.
|
||
|
||
Then M2. The core carries everything the GUI needs; `ui/src/ipc` fixes the command names, the design tokens and EN/VI catalogs are scaffolded, and the shell renders.
|
||
|
||
## Phase 2 — M2 "GUI shell + core flows" (~7–8 weeks)
|
||
|
||
Tauri app, design tokens, Environments/Installed/Updates/Search/Pins screens, preview + 3-way conflict UX, console drawer, summary sheet, snapshots UI, legal gate, EN/VI catalogs, settings. **Exit:** all UI-SPEC click budgets met by manual count; L3 green; VI sweep clean.
|
||
|
||
The estimate was 3–4 weeks until 2026-07-29, when surveying the code for M2 showed the bridge was scaffolding rather than substance: 26 command **names** with zero wrappers, one registered Tauri command, 2 of 16 `Pd*` components, 1 of 5 stores. Scope is unchanged; the estimate moved to match it.
|
||
|
||
### Stage 1 — the IPC bridge — **done 2026-07-30**
|
||
|
||
Ten commits, `0ccee04..a553bf7`. Everything M2's screens stand on now exists, and there is a running app.
|
||
|
||
| | What landed |
|
||
|---|---|
|
||
| **Wire format** | `#[serde(rename)]` on all 30 `Code` variants so they serialize as `PD-*`, and `rename_all = "camelCase"` on every IPC-crossing struct. `--json` had never matched DATA-FLOW §6 or ERROR-CATALOG §3 — and the two `--json` paths in the binary disagreed with each other. Held by a `Code::ALL` round-trip test and a test that walks every `SCHEMA_TYPES` schema rejecting any property containing `_`. |
|
||
| **Codegen** | `ui/src/ipc/generated.ts` from schemars via `cargo run -p xtask -- bindings`. Deviates from ARCHITECTURE §9's specta; reasoning and the revisit condition are in `crates/pipdock-core/src/bindings.rs`. Drift is a **test** failure, so it fires locally as well as in CI. |
|
||
| **`core::flow`** | `UpdateFlow`, `UninstallFlow`, `RollbackFlow` — resumable state machines, because the GUI's two decision points are IPC round trips with a render in between. `plan::execute_rollback` is new: core had `rollback_plan()` and nothing to run it, so the CLI hand-assembled an `ExecutionSummary`. **The flow never prints.** |
|
||
| **Cancellation** | `CancellationToken` through `exec.rs`, plus `kill_on_drop(true)` — the 600 s watchdog had never killed anything. A cancelled Phase A does **not** fall through to Phase B, and a step killed by us is `Skipped`, not `Failed`. |
|
||
| **Progress** | `ProgressSink` carries `step`/`total`; `scan-progress` finally has a producer and a payload (`ScanProgress`). |
|
||
| **Vertical slice** | Legal gate, Environments, Settings. `core::settings`, `docsHash` computed in `build.rs`, capabilities split and scoped. |
|
||
|
||
**Four bugs turned up that were not in the plan**, all found by running things rather than reading them: the watchdog leak; `--json` unparseable because `snapshot … written` went to stdout; blocker attribution naming constraints from other Pythons (the SP-5 dogfood); and `updater:default` granted to a plugin whose pubkey was a placeholder.
|
||
|
||
### Stage 2 — Installed + Updates (read-only) — **done 2026-08-04**
|
||
|
||
Three PRs, `d7da4d7..`. Both screens render from a real environment, and the slice's exit criteria
|
||
are met.
|
||
|
||
| | What landed |
|
||
|---|---|
|
||
| **Docs** | ARCHITECTURE §7's command list rewritten as a table of **32** — it was prose with `a\|b\|c` groupings, ambiguous enough that Stage 1 added `app_info` and `plan_decide` without amending it. Closes open owner decision #1. DATA-FLOW §7's "List installed" row corrected: it claimed an engine command **neither head has ever called**. |
|
||
| **Core** | `engine::for_id` — the CLI held the only copy of engine selection plus a duplicate `KEY_ENGINE` and a byte-for-byte copy of `store::default_app_data`. `Dist.sizeBytes`, summed from RECORD. `PkgName` validates on deserialize. |
|
||
| **Bridge** | `pkg_list`, `pkg_outdated`, `pin_list\|add\|remove`, registered and wrapped. `pkg_list` reads the probe, not the engine; both take a `PyEnv` so the outdated path never probes. |
|
||
| **UI** | `PdBadge`, `PdEmptyState`, `PdPackageRow`, `PdPackageTable` (virtualized) — 8 of 16 components now exist. One screen serving both tabs, `useEnvStore` grown, EN+VI catalogs, `Space`/`Ctrl+A`. |
|
||
| **L3** | The repo's first rendered-component tests, fed from fixtures generated out of the real Rust types by `cargo run -p xtask -- ipc-fixtures` and held current by a staleness test. |
|
||
|
||
**Four bugs turned up that were not in the plan, three of them found by running:**
|
||
|
||
1. **`Distribution.files` is a 10× trap.** The obvious way to sum RECORD took the probe from 551 ms
|
||
to **5,492 ms** on a 352-package environment — on the path the Installed screen runs on every
|
||
environment open. Parsing RECORD text directly costs 79 ms.
|
||
2. **The naive size is wrong for editables, not merely missing.** A PEP 660 install has a *valid*
|
||
RECORD listing only its import shim: **240 bytes for a package whose sources are 8.1 MiB**.
|
||
Detected via `direct_url.json` and reported as absent, because a wrong number is worse than none.
|
||
3. **A distribution could be listed twice.** An editable puts its own `.egg-info` on `sys.path`, so
|
||
`importlib.metadata` finds it there *and* at the venv's `.dist-info`. `pip list` shows it once.
|
||
For the table it is an ambiguous join key and two rows a user cannot tell apart.
|
||
4. **Every screen fetched twice on mount.** React runs effects twice in development and the
|
||
`loadedFor` guard is set only *after* the await, so both runs proceed. `env_scan` had done this
|
||
since Stage 1, invisibly, because both scans return the same rows.
|
||
|
||
**Two decisions worth knowing before S3:**
|
||
|
||
- **Row state is three-valued, not two.** `pkg_list` is local, `pkg_outdated` is networked, so there
|
||
is a window where outdatedness is unknown. Treating it as "up to date" dims all 200 rows and
|
||
un-dims a handful a second later — visibly wrong, and untrue while it lasts.
|
||
- **"N pinned excluded" is presentation, not enforcement.** DATA-FLOW §9.5 is enforced by
|
||
`pins::filter_upgrades` at the plan boundary. **S3's preview must report the flow's
|
||
`excluded_pins()`, not the number the table computed.**
|
||
|
||
Also resolved: UI-SPEC §8's "select-all-visible", which has no meaning under virtualization. It is
|
||
the current filtered set, and §8 now says so.
|
||
|
||
### Stage 3 — the mutation spine — **done 2026-08-04**
|
||
|
||
Two PRs. The app now previews, decides, executes, streams and summarises — PRD G1's promise that
|
||
every mutating operation is previewed before it runs is real for the first time in the GUI.
|
||
|
||
| | What landed |
|
||
|---|---|
|
||
| **Cancellation** | A Windows Job Object, so a cancel reaches the build backends `python -m pip` spawns and not only pip. `win32job` is a safe wrapper, so `unsafe_code = "forbid"` stays absolute. |
|
||
| **`plan-progress`** | A tagged lifecycle (`stepStarted` / `line` / `stepFinished`) instead of a bare line, plus `stream`. ARCHITECTURE §7 amended. |
|
||
| **Wire types** | `FlowStep`, `Intent`, `Decision` and `ProgressEvent` cross IPC; `roundsRemaining` makes `MAX_CONFLICT_ROUNDS` visible for the first time. |
|
||
| **Plan session** | `PlanSlot` in `AppState` holds the resumable flow between the four calls that drive it; `PD-RES-003` refuses a second plan. |
|
||
| **UI** | `usePlanStore`, `PdPreviewDiff`, `PdConflictRow`, `PdConsoleDrawer`, `PdSummarySheet` — 13 of UI-SPEC §6's 16 components now exist. |
|
||
| **L3** | The last three of TESTING §2's five obligations, so the list is complete and §3's PR gate means something. |
|
||
|
||
**Exit criteria, counted and measured in a running app:** "update everything" is **exactly 4
|
||
clicks** — Updates → Select all → Update → Confirm — and it is still 4 with a conflict left at its
|
||
default, which is §5's second row. Cancelling mid-execution yields a coherent summary with
|
||
`Skipped` rows and the cancelled banner. The live region reads "2 of 4 complete" and the drawer
|
||
groups output by package, both of which were unimplementable before the lifecycle enum existed.
|
||
|
||
**Three specification gaps closed, each recorded in UI-SPEC §4:**
|
||
|
||
1. **`Will downgrade` has a section.** `ChangeKind` has four variants and §4 named three groups. A
|
||
*compatible* resolve routinely moves a package down, and `2.0 → 1.9` under a heading reading
|
||
"Will upgrade" is misleading about the change most likely to surprise.
|
||
2. **`Keep compatible` is disabled on impossible rows.** §4 said every needs-decision row hosts the
|
||
full 3-way control, but `default_decision(is_impossible = true, …)` returns `Skip` — there is no
|
||
compatible version to keep. The UI mirrors the core rather than offering a choice it would
|
||
refuse.
|
||
3. **The round counter is visible.** `MAX_CONFLICT_ROUNDS` had been in core since M1 with nothing
|
||
surfacing it, so a user could hit the cap unwarned.
|
||
|
||
**And the third Stage 1 deferral, `ExecutionSummary.cancelled` copy**, which had no specified
|
||
wording: the summary now says the run stopped part-way, that a package may have been left
|
||
half-written, and points at the snapshot.
|
||
|
||
**One design change forced by the compiler, worth knowing.** `UpdateFlow::start` took a `&Store`;
|
||
`Store` wraps a `rusqlite::Connection` and is `Send` but **not `Sync`**, so a future holding one
|
||
across an await is not `Send` and a Tauri command cannot return it. It takes the pins instead —
|
||
one synchronous read at each call site, and the flow no longer touches a database at all.
|
||
|
||
### Stage 4 — search, the dock bay and install — **done 2026-08-04**
|
||
|
||
Five commits. Both exit criteria met and measured in the running app. *(The "16 of 16 components"
|
||
claim recorded here was wrong: the count had folded in components that are not on UI-SPEC §6's list.
|
||
It was 13 of 16 then and after S5 — see §6, which now says so.)*
|
||
|
||
| | What landed |
|
||
|---|---|
|
||
| **Index** | `IndexSlot` in `AppState` holds the 864k-name index; warmed on first Search open, never blocking a search. `index_search`, `index_refresh`, `pkg_metadata`. |
|
||
| **UI** | `useIndexStore`, `PdSearch`, `PdDockBay`, `PdOfflineBanner`, the metadata panel, `/` to focus. |
|
||
| **Install** | The dock bay resolves through `Intent::Install`, into the same preview and summary S3 built. |
|
||
|
||
**The keystroke budget, measured rather than assumed — and it was being missed.**
|
||
|
||
| | Median | p95 | Over 50 ms |
|
||
|---|---|---|---|
|
||
| First measurement | 57.4 ms | 79.8 ms | 18 of 19 |
|
||
| After two fixes | **22 ms** | **24.5 ms** | **0 of 19** |
|
||
|
||
The two fixes were a **leading-edge debounce** — it was trailing-only, spending 16 ms of a 50 ms
|
||
budget doing nothing on every keystroke, while the comment above it had claimed leading-edge
|
||
behaviour since the day it was written — and **`SEARCH_LIMIT` 50 → 20**, because React commits
|
||
every row on every keystroke and the row count is the largest lever on the render half.
|
||
|
||
**A number I reported was wrong, and it mattered.** The 613 ms index load was a *debug* build; in
|
||
release it is 140 ms, and the worst keystroke is 16 ms rather than 176 ms. The design — hold the
|
||
index, warm on demand — is unchanged and still right at 140 ms, but it had been justified with a
|
||
figure four times too large. `crates/pipdock-core/tests/search_latency.rs` now **refuses to run in
|
||
debug** rather than printing a number that means nothing.
|
||
|
||
**Two bugs found by counting clicks**, neither reachable by any test written for them:
|
||
|
||
1. **A plan started from Search resolved into nowhere.** `PdPlanPanel` was owned by `PdPackages`,
|
||
so the command ran, the flow parked, and the user saw unchanged search results. A plan belongs
|
||
to the app — there is one at a time, and which tab is showing is not part of that.
|
||
2. **Every result offered [Add], including installed packages**, because only `PdPackages` ever
|
||
loaded the installed set. That is exactly the mistake DATA-FLOW §4's chips exist to prevent.
|
||
|
||
### Stage 5 — uninstall, the guard dialog and the Pins screen — **done 2026-08-09**
|
||
|
||
Twelve commits. Every mutating command in ARCHITECTURE §7 now exists, and removal is the first flow
|
||
whose *whole* value is refusing to do what was asked.
|
||
|
||
| | What landed |
|
||
|---|---|
|
||
| **Core** | `GuardReport.breaks` carries `BrokenDependent { pkg, version, constraint }` — the specifier, not just the name. `GuardAck` makes the guard an enforcement point rather than a dialog. PEP 668 refused on removal. New code **PD-RES-004**. |
|
||
| **Execution** | `execute_uninstall` emits the `stepStarted`/`stepFinished` lifecycle it never had, checks the cancellation token in its loop, takes a `base` step index shared with `execute_rollback`, and honours `--no-snapshot`. |
|
||
| **Bridge** | One `Session` enum for all four flows, with typed claims; `uninstall_guard`, `uninstall_execute`; `plan_cancel` async, and now discarding a parked session. |
|
||
| **UI** | `PdDialog` (the repo's first modal), `PdUninstallDialog`, `PdPinChip`, the Pins screen, the row's ✕, and the `failed` phase. |
|
||
| **L3** | The first mocked `@/ipc`, the first store test, the first screen test. 6 files → 9; 59 tests → 79. |
|
||
|
||
**Exit criteria, counted and verified in a running app** (driven in the Browser pane against a
|
||
stubbed bridge, per the recipe that found Stage 2's double fetch): uninstall is **exactly 3 clicks**
|
||
— Installed → row ✕ → *Remove* — and 4 when the guard trips, by design. The dialog reads
|
||
`pandas 2.1.4 requires numpy<2,>=1.26.0`, naming the dependent **and** its constraint. *Remove
|
||
dependents too* issues a **second** `uninstall_guard` over the widened set with **no**
|
||
`uninstall_execute` in between. At the CLI, against a real venv, the guard refuses and exits 2 with
|
||
every package still installed.
|
||
|
||
**Five live bugs came out of it, none of them S5 features:**
|
||
|
||
1. **A claim that found nothing wedged the slot.** `plan_decide`/`plan_execute` wrote `Busy` before
|
||
discovering there was no plan, and never released — so one out-of-order call from the UI made
|
||
every later command answer `PD-RES-003` for a plan that had never existed.
|
||
2. **`execute_uninstall` emitted no lifecycle markers**, and every line carried `step: 0`. The CLI
|
||
never noticed because it prints `event.line()` and nothing else; the console drawer groups on
|
||
`stepStarted` and the live region counts `stepFinished`, so the GUI would have shown an empty
|
||
drawer against a green suite.
|
||
3. **A cancelled removal removed everything, then reported `cancelled: true`.** The loop had no
|
||
token check at all.
|
||
4. **`--no-snapshot` was parsed and ignored on the uninstall path** — the same waiver meant "waive"
|
||
for an update and nothing for a removal, the one operation with no way back.
|
||
5. **The pin button was a tab stop**, so Space on it toggled the row's *selection* instead of
|
||
pinning. The rule was enforced on the checkbox and forgotten one element later.
|
||
|
||
**And one specification gap closed:** DATA-FLOW §9.1 required "a `ResolutionReport` accepted in this
|
||
session", which the uninstall path cannot produce — there is nothing to resolve. It now names the
|
||
proof per plan shape, so the one flow with no preview is no longer the one flow the invariant did not
|
||
describe.
|
||
|
||
### Stage 6 — snapshots, the env detail and rollback — **done 2026-08-09**
|
||
|
||
Eight commits. Every snapshot the app has been writing since S1 is now reachable from it, and P0-8
|
||
is complete in both heads.
|
||
|
||
| | What landed |
|
||
|---|---|
|
||
| **Core** | `RollbackPreview` and `RollbackPlan` cross IPC; `snapshot::Meta` gains a schema rename so embedding it does not mint a second interface. `parse_freeze` and `unrestorable_lines` rebuilt on one classifier. |
|
||
| **Bridge** | `snapshot_list\|create\|diff\|rollback_preview\|rollback`. ARCHITECTURE §7's single rollback row becomes two, 32 → 33. |
|
||
| **UI** | `PdSnapshotTimeline`, `PdRollbackPreview`, the env detail as a *mode* of the Environments tab, the diff viewer, and the rollback the summary's copy has promised since S3. |
|
||
| **L3** | Two more generated fixtures; 9 → 11 test files, 79 → 91 tests. Goldens 52 → 54. |
|
||
|
||
**Exit criteria, verified by running.** At the CLI against a real venv: create → mutate → `snapshot
|
||
rollback <id>` → `snapshot diff <id>` prints *environment matches snapshot* — PRD §6's metric, and
|
||
the timeline afterwards shows the `rollback of …` entry above the one it restored, which is
|
||
`latest` moving twice, live. In the app: **rollback = 4 clicks** (Open → entry → *Rollback…* →
|
||
*Roll back*), 2 from a run's summary; the preview lists `PD-SNP-002` with the verbatim freeze line
|
||
**before** the confirm.
|
||
|
||
**Four bugs, three of which no test would have found:**
|
||
|
||
1. **A cancelled rollback killed the package in flight and installed the rest.** The restore loop
|
||
had no token check — S5 gave one to the removal half and not to the install half. Found by
|
||
writing the cancellation test the plan asked for.
|
||
2. **`parse_freeze` and `unrestorable_lines` did not partition their input.** Two independent
|
||
filters that disagreed: a line like `Foo Bar==1.0` was dropped by both and vanished. In a
|
||
rollback preview, whose whole job is saying what it cannot put back, that silence is the worst
|
||
possible failure.
|
||
3. **`snapshot_list` fired twice on open** — Stage 2's double fetch, reintroduced exactly, because
|
||
the guard is written after the await. Invisible in the UI, since both calls return the same rows.
|
||
4. **A rollback left the timeline empty.** The refetch and the rescan race, and the rescan wiped the
|
||
result: the snapshot fields were inside `NO_PACKAGES`, whose reset is keyed to the *package*
|
||
slice's environment. The two slices key on different things and now reset separately.
|
||
|
||
**Deliberately not done:** DATA-FLOW §8's dry-run resolve of the restore set, which is implemented
|
||
in **neither** head. 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. §8 now says so, and the preview's promise is precise instead: it lists what *cannot* be
|
||
restored, not everything that might fail. Snapshot retention (`snapshot::delete` + keep-N) also
|
||
stays out; a destructive command against the user's only way back needs its own confirm.
|
||
|
||
### Stage 7 — the shell — **done 2026-08-09**
|
||
|
||
Eight commits. What the shell was missing was rarely a feature — it was a promise the docs had made
|
||
and nothing had kept.
|
||
|
||
| | What landed |
|
||
|---|---|
|
||
| **Fonts** | Inter and JetBrains Mono vendored. `--font-sans`/`--font-mono` had named them since the tokens were written and both fell through to a system fallback, because no `@font-face` was ever registered. |
|
||
| **i18n** | **26 of 32 catalog codes had no copy in either locale.** All 32 now do, in `locales/*/errors.json`, asserted against a generated `codes.json` — both directions, plus I18N §4's ≤ 90-char cap. |
|
||
| **Bug report** | `pipdock_core::report` shared by both heads; `LogRing` in `AppState` fed by three writers; `report_bug_url`; the error row's *Copy full log* and *Report bug*. |
|
||
| **a11y** | Every `--color-*` rebound under `forced-colors`, with borders on the destructive controls whose tint the UA erases. The pseudo-locale, dev-only and verified absent from a production build. |
|
||
| **Status line** | The log toggle does something, and `⚠ n` means something. |
|
||
|
||
| **Bridge** | `engine_info`, and three tests that make `COMMANDS` mean something. It listed **32 names while 19 were registered** — a wrapper for any of the other 13 typechecked and would have failed at runtime, on a command that looked implemented. |
|
||
| **Keyboard** | Focus follows the tab: `Ctrl+3` changed the screen and left focus behind, so the next Tab resumed inside the screen the user had just left. |
|
||
|
||
**Deliberately left for later, and named:** the `Enter` primary-action map and folding the six
|
||
`aria-live` regions into one — both are cross-screen behaviour that wants the VI sweep and a real
|
||
screen reader to verify, not a passing test. S7b (Settings' remaining controls) was always a
|
||
follow-up PR. `PdEmptyState` now covers every surface that renders a list.
|
||
|
||
**One thing worth keeping:** i18next's `nsSeparator` is `:`, so I18N §1's seven namespaces would
|
||
have meant `t('errors:PD-NET-001')` at every call site — churn across every screen, bought with lazy
|
||
loading a desktop app that bundles both catalogs cannot use. The app ships **one** namespace and two
|
||
files per locale; §1 is amended to say so rather than left describing something that was never built.
|
||
|
||
**M2 is complete.** Every P0 feature except Code Health (P0-11) is in both heads, all seven UI-SPEC
|
||
click budgets are met by hand count, and `NOT_YET` names the five commands that remain — each
|
||
against the slice that owes it.
|
||
|
||
### Where to pick up
|
||
|
||
**Phase 3 is complete.** P1 (pip upkeep), P2 (the tools venv), P3 (the runners and `HealthReport`),
|
||
P4 (the Health screen), P5 (the gated `ruff --fix`) and P6 (the tail) are all merged, each with a
|
||
stage table above, and the exit criteria are recorded with the numbers they were measured at.
|
||
**Phase 4 is complete too** — see its section below. `1.0.0` is tagged.
|
||
|
||
`NOT_YET` is down to **two**, both M3-general: `env_add_manual` (*Browse…* has no surface) and
|
||
`logs_tail` (needs the logging subsystem). `src-tauri/src/lib.rs:25-28` and the three tests that
|
||
police it in both directions are the authority; a paragraph here used to say "three" and was
|
||
describing the state before P5 merged. The M3 debt list is otherwise unchanged: dead
|
||
`pins::hold_requirements`, unread `allow_externally_managed`, DATA-FLOW §8's dry-run resolve,
|
||
snapshot retention, `PdEnvSwitcher`, CLI-SPEC §6's NDJSON gap, and `RunOptions`/the confidence floor
|
||
reaching Settings.
|
||
|
||
The four things P4 was warned it would otherwise rediscover all held: `@tauri-apps/plugin-dialog`
|
||
really was absent from `package.json`, the opener really was scoped to GitHub only, UI-SPEC §6
|
||
really said 14, and deptry really does name a module rather than a distribution. What the warnings
|
||
did not cover were the four defects in P4's stage table above, every one of which came from running
|
||
the thing.
|
||
|
||
**The one open decision is now closed.** deptry cannot be told which environment to compare against;
|
||
the owner chose on 2026-08-13 to keep all four DEP codes and disclose the limitation where findings
|
||
are shown, rather than `--ignore DEP003` (which turns a mislabelled finding into a missing one) or
|
||
dropping deptry from v1. The screen carries the note under the same condition the CLI does, and the
|
||
saved Markdown carries it too.
|
||
|
||
**All three Stage 1 deferrals are closed**, each in S3 as planned — the `plan-progress` lifecycle enum, the Windows Job Object, and the `ExecutionSummary.cancelled` copy. Deferring them to the slice that could verify them worked: each was finished against a running UI or a real process tree rather than against a guess.
|
||
|
||
## Phase 3 — M3 "Health + polish" (~2 weeks)
|
||
|
||
Tools venv, deptry/vulture/ruff runners + report UI + gated fix, pip upkeep, bug-report deep link, offline states, keyboard map, icon/branding pass. **Exit:** CODE-HEALTH flows pass on two real projects (one pyproject, one requirements-only).
|
||
|
||
Decomposed **P1** pip upkeep · **P2** the tools venv · **P3** the runners + `HealthReport` · **P4** the Health screen · **P5** the gated `ruff --fix`. Three of the sentence's items are already spent: the bug-report deep link landed in S7, `PdOfflineBanner` in S4, and the keyboard map's `Ctrl+1..8` in S7 — what remains of "keyboard map" is `Enter` as primary action and folding the six `aria-live` regions. The icon/branding pass belongs with Phase 4's release slice; it churns binaries that must not sit inside a feature diff.
|
||
|
||
### Phase 3 · P6 — the tail — **done 2026-08-13**
|
||
|
||
Three commits, and **Phase 3 is closed**. The keyboard item turned out to be hiding a WCAG failure; the rest was owed bookkeeping.
|
||
|
||
| | What landed |
|
||
|---|---|
|
||
| **UI** | roving tabindex in `PdPackageRow` (`←`/`→`/`Esc`), `Enter` as the non-destructive primary, two live regions folded |
|
||
| **Core** | `uv::parse_dry_run` deleted — the last `todo!()` in the workspace — and `clippy::todo` flipped `allow` → `warn` |
|
||
| **Docs** | UI-SPEC §8's keyboard map and the two rules behind it; CLI-SPEC §6's stale "`health` is still the M3 stub" |
|
||
|
||
**Pin and Remove were unreachable without a mouse.** Every control in a package row is `tabIndex={-1}`, which is a sound trade for the checkbox — `Space` does its job from the row — but applied to the two action buttons it removed the actions entirely. The row was the only tab stop and there was nowhere further to go. Found by tabbing to a row in the running app and pressing every key that should have done something; invisible to a suite that clicks.
|
||
|
||
The audit's other finding is worth keeping: **`Enter` already worked everywhere else**, because every other primary action in the app is a real `<button>` and buttons handle it natively. "Zero `Enter` handlers" was true and misleading. The gap was one element that only looks like a control.
|
||
|
||
**The live-region pair that mattered was not the one being counted.** ROADMAP had said "six regions" for two slices; there were ten. But the duplication that actually reached a user was `PdConsoleDrawer` and the panel that opens it announcing the same `done/total`, so a screen reader heard every step twice. Eight now, with both genuine conflicts removed rather than the number merely reduced.
|
||
|
||
### Phase 3 exit criteria — **met 2026-08-13**
|
||
|
||
*"CODE-HEALTH flows pass on two real projects (one pyproject, one requirements-only)."* Run in `--release` against a warm tools venv:
|
||
|
||
| Project | Result | Time |
|
||
|---|---|---|
|
||
| requirements-only | 1 dependency, 3 dead-code, 3 lint (3 fixable in 1 file) | 1.4 s |
|
||
| declares nothing | `ran: [vulture, ruff]`, `problems: []` — deptry correctly not run | 1.3 s |
|
||
| seeded git repo | 6 fixable across 2 files; `--fix` changed **exactly** those two | — |
|
||
|
||
The fix path's refusals were exercised on the same repository: non-TTY without `--yes`, `--yes` over a dirty tree, and `attrib +R` on one target — the last confirming the fix refuses **as a whole**, leaving the other, writable file untouched.
|
||
|
||
**Still owed, and it needs the real Tauri runtime rather than the stubbed bridge:** the OS folder picker, a ruff rule link (to confirm the `docs.astral.sh` allowlist entry works), and the fix dialog end to end. All three are reachable only from `npm run tauri dev`.
|
||
|
||
### Phase 3 · P5 — the gated `ruff --fix` — **done 2026-08-13**
|
||
|
||
Five commits. **`NOT_YET` is down to two, both M3-general**, and PipDock has its first write outside site-packages and `%LOCALAPPDATA%`.
|
||
|
||
| | What landed |
|
||
|---|---|
|
||
| **Core** | `health::fix` — `dirty`, `FixConsent`, `consent_ok`, `ensure_writable`, `recheck`, `apply`, `FixReport`; `project::validate_project`; `run::ruff_argv` extracted so the re-check cannot drift |
|
||
| **Errors** | `PD-PRM-003`, internally raised. `Code::ALL` 33 → 34, and the checklist is **nine** places, not eight |
|
||
| **Bridge** | `health_fix` (the last Phase-3 `NOT_YET` row) and `health_dirty` |
|
||
| **CLI** | `pipdock health --fix`, with the `--yes` rule, the usage error, and a one-document `--json` |
|
||
| **UI** | the Fix button, one dialog with two states, `data-action="fix"` in the forced-colors list |
|
||
| **Docs** | DATA-FLOW gains **invariant 6** and §9.1's state machine; SECURITY §2 and §8; CODE-HEALTH-SPEC §5; CLI-SPEC §3; UI-SPEC §5 and §7 |
|
||
|
||
**The invariant question, answered rather than dodged.** DATA-FLOW §9.1 and §9.2 are scoped to a mutating *engine* call, and a ruff fix rewrites a source tree, which no snapshot describes. A snapshot taken here would have no consumer that could use it — invariant 2's own argument for the pip-upkeep exemption, a second time. So: **no snapshot**, a fifth proof shape (`HealthReport` + a server-checked `FixConsent`), and the exemption made *visible* the way P1's is, in the confirm's own copy.
|
||
|
||
**Three things found by running.**
|
||
|
||
1. **`--json --fix` printed two documents** — the pre-fix report and the `FixReport`. The first describes a state that no longer exists by the time the command returns, and CLI-SPEC §6 states the contract as one document. Found by reading stdout rather than asserting on it.
|
||
2. **A planted `git.exe` does not win.** This is the one place PipDock runs a PATH-resolved program with a user-controlled working directory. Windows' legacy search order would make a binary in a cloned repository run; Rust's `Command` does its own resolution and skips the current directory. Verified by planting one, not by reasoning about `CreateProcess`.
|
||
3. **The SECURITY paragraph was ahead of the code.** Writing "the project folder is validated and a folder inside the tools directory is refused" made it true rather than aspirational: `validate_project` now refuses it, `..` included, and running Health against `%LOCALAPPDATA%\PipDock\data\tools` answers `PD-ENV-003`.
|
||
|
||
**Verification, release build, against a seeded repository.** 6 fixable across 2 files with an unfixable `E722` in a third: after `--fix`, `git diff --stat` lists **exactly those two files** — the third untouched, which is what rules out a stray `ruff format` — and the run exits 1 with one finding remaining. Non-TTY without `--yes` refuses (exit 2). A dirty tree with `--yes` refuses naming the entry count (exit 2) and writes nothing. `attrib +R` on one target produces `PD-PRM-003` naming that file, and the **other**, perfectly writable, is not written either: the fix refuses as a whole rather than half-rewriting a tree nothing can restore.
|
||
|
||
**Deliberately not done:** `ruff format`. §4's `--check` toggle stays read-only and default-off; formatting a whole project is a far larger blast radius than fixing seventeen lint findings, and §7's non-goals are contractual.
|
||
|
||
### Phase 3 · P4 — the Health screen — **done 2026-08-13**
|
||
|
||
Ten commits, plus a Slice 0 that got the tool pins to their final version first. **Code Health is on screen**, `PdHealthReport` is UI-SPEC §6's fifteenth of sixteen, and both halves of Phase 3's exit criterion pass.
|
||
|
||
| | What landed |
|
||
|---|---|
|
||
| **Core** | `health::markdown`; `reporting()`, which keeps deptry out of `ran` for a project that declares nothing; `fixtures::{health_report, health_partial}` |
|
||
| **Bridge** | `EnvRow.healthProject` filled by `env_scan` **and** `env_probe`; `health_run` persists the folder; `health_save_report`; `env_probe` gains a `source` parameter |
|
||
| **UI** | `useHealthStore` (a third reset key, and the first that is a pair), `PdHealthReport`, `screens/PdHealth`, `pickProjectFolder`/`pickSavePath`, `apply` generalized so two stores share one console reducer |
|
||
| **Capabilities** | `docs.astral.sh` added to the opener allowlist, `dialog:allow-save` granted; both recorded in SECURITY §4 and the grant's own description |
|
||
| **Copy** | a `health` block in both locales, ~30 keys |
|
||
|
||
**Four defects found by running, none of them in the plan.**
|
||
|
||
1. **The screen said "no issues found" before anything had run.** With a folder remembered and no report yet — the identical lie a tab keyed on `ran` alone tells about a failed tool, one level up, written by someone who had just spent a commit preventing it. Empty states are the easiest place in this app to claim a result nobody produced.
|
||
2. **A project that declares nothing was reported as a deptry failure.** deptry raises `DependencySpecificationNotFoundError` and exits non-zero, which read as `PD-HLT-002`. PipDock had already detected the state and already told the user results would be limited — then ran a tool that cannot run in it and blamed the tool. Now skipped, and outside `ran`.
|
||
3. **`env_probe` hardcoded `EnvSource::Manual`.** So *Upgrade pip* on a registry-discovered interpreter relabelled it *Added manually* in the chip, and handed that relabelled `PyEnv` to every later `pkg_list`. A P1-era defect in the function P4 had to touch anyway.
|
||
4. **A test asserted a version Dependabot owns**, so merging the ruff bump broke `main`. Its CI had gone green on a base predating the health module.
|
||
|
||
**Deliberately not done: health-run cancellation.** Measured rather than assumed, which is what the plan asked for: a warm three-tool run is **1.3 s** and a cold one is that plus the ~15 s tools-venv bootstrap, both far under the 30 s threshold set before the number was known. It is also more than the bridge one-liner it looks like — `run_one` never passes the sink's token to `Command`, so wiring `set_cancel` alone would cancel only the sync, and `watchdog()` maps a cancel to `PD-INT-001`, so a cancelled run would render three "PipDock hit an internal error" rows. Worst case remains watchdog-bound at 3 × 120 s; revisit if a real project hits it.
|
||
|
||
**Exit criteria, release build, warm tools venv.** A requirements-only project reports 1 dependency, 3 dead-code and 3 lint findings (3 fixable in 1 file) in **1.4 s**; a project declaring nothing reports `ran: [vulture, ruff]` with an empty `problems` in **1.3 s**. In the running app against a stubbed bridge: `Ctrl+6` reaches Health, the `<h1>` takes focus, the remembered folder arrives on the row so the button reads *Change folder…*, `plugin:event|listen` crosses before `health_run`, the three tab counts are 4/3/6 against a fixture carrying 4/3/6, and on the partial report the ruff tab reads *did not finish* while vulture reads *not run* and the status line reads `⚠ 1`.
|
||
|
||
### Phase 3 · P3 — the runners and `HealthReport` — **done 2026-08-12**
|
||
|
||
Six commits. `pipdock health` runs deptry, vulture and ruff out of P2's tools venv and reports; `health_run` streams the same thing over `health-progress`. **`NOT_YET` is down to three, and only `health_fix` is still Phase 3's.**
|
||
|
||
| | What landed |
|
||
|---|---|
|
||
| **Core** | `health::{project,deptry,vulture,ruff,report,run}`; `HealthReport` and its six sub-types; `is_findings_exit`; the project folder in `health_projects`, keyed by `env_hash` |
|
||
| **Bridge** | `health_run`, its own `Sessions<HealthSession>` slot, and `forward_progress` taking the channel as a `&'static str` |
|
||
| **CLI** | `pipdock health [--path] [--tool …] [--json]`, exit 1 on findings; `--fix` refused until P5 |
|
||
| **Wire format** | `HealthReport` in `SCHEMA_TYPES` — one registration, seven TS declarations, because the generator hoists `$defs` |
|
||
| **Fixtures** | eight captured documents under `tests/fixtures/health/`, redacted and `-text` |
|
||
|
||
**Five things the specs had wrong, all found by running the pinned tools.**
|
||
|
||
1. **All three exit non-zero on findings, and disagree about how** — deptry 1, ruff 1, **vulture 3**, with vulture's 1 and 2 being real failures. A plain `!out.ok()` reports every successful run over a real project as `PD-HLT-002`, and a suite that only runs them over a clean directory agrees with it.
|
||
2. **deptry cannot be told about an environment.** §3 said the env is "passed to deptry"; there is no such flag, `VIRTUAL_ENV` is ignored, and it reads whatever its own interpreter imports. §2's isolation and §3's comparison conflict, isolation wins, and the cost is disclosed rather than papered over.
|
||
3. **deptry's `--json-output` is a file path, not a stream.** `-` would have created a file called `-` inside the user's project — the exact §1 boundary the flag was chosen to respect.
|
||
4. **ruff's docs URL is keyed by rule name**, so §6's `.../rules/<code>` 404s; and it writes findings to stdout with warnings on stderr, which corrupted the first fixture capture.
|
||
5. **A tool present but unrunnable reported `PD-ENG-001`** — "install the engine, or switch engine in Settings", for a corrupted `ruff.exe`. Now `PD-HLT-001`, which says re-sync the tools environment, which is the fix.
|
||
|
||
**Exit criteria, run against real projects.** `pipdock health` over a pyproject project reports 1 dependency, 3 dead-code and 3 lint findings and exits **1**; over a clean one it exits **0**; `--tool ruff` runs one tool and leaves `ran` naming only it, so an empty deptry tab is "not run" rather than "clean". Replacing `ruff.exe` with a text file of the same name — present, so the sync check says Fresh — produced the **partial report**: deptry and vulture reported normally, ruff landed in `problems` as `PD-HLT-001`, and the run still returned a report. Deleting `ruff.exe` outright instead triggers the implicit sync and repairs it.
|
||
|
||
**Deliberately not done:** `RunOptions` stays off the wire. §4 says the confidence floor comes "from settings", but `Settings` has three fields and none is this; adding them is a golden, a bindings regeneration and a Settings screen, which is its own slice.
|
||
|
||
### Phase 3 · P1 — pip upkeep — **done 2026-08-12**
|
||
|
||
Eight commits. **P0-10 is complete in both heads**, and three defects older than the slice went with it.
|
||
|
||
| | What landed |
|
||
|---|---|
|
||
| **Core** | `PipEngine::upgrade_pip` gains DATA-FLOW §2's PEP 668 guard and an `ensurepip` fallback; both heads call it directly rather than dispatching on the configured engine. `EnvRow.pip_version`, read out of the probe's own distribution list. |
|
||
| **Bridge** | `pip_upgrade` registered — `NOT_YET` is down to four, two of them M3-general. |
|
||
| **UI** | pip's version on every Environments row; *Upgrade pip* as a second inline button beside *Use*, below the planner floor only; a confirm that states the snapshot exemption. |
|
||
| **Docs** | ARCHITECTURE §7's return type corrected; DATA-FLOW §7 (pip unconditionally) and §9.1/§9.2 (a fourth plan shape, and a visible exemption); UI-SPEC §5 gains a row. |
|
||
|
||
**Three bugs that were not in the plan, none of them P1's own.**
|
||
|
||
1. **A venv was reported externally managed whenever its base was.** A venv has no stdlib, so `sysconfig.get_path("stdlib")` resolves to the base — and every venv built from a Python shipping the marker (uv-managed, Debian, Homebrew, Fedora) refused every mutation with `PD-ENV-002`. pip's own `check_externally_managed` opens with the venv early-return that `probe.py` was missing. Found by making a venv from a uv-managed 3.11 to test P1 and watching `pip-upgrade` refuse it.
|
||
2. **Every pip below the 22.2 floor is broken on Python 3.12+** — `distutils` and `pkgutil.ImpImporter` are both gone — so the button offered exactly when pip is too old ran a pip that could not start, and the traceback's `ModuleNotFoundError` classified as `PD-ENV-003`, "could not read this environment". Now falls back to `ensurepip`, which is stdlib and offline, chosen by asking `pip --version` rather than matching a traceback that differs by version.
|
||
3. **Five locale strings were being discarded by the two-file merge.** `common.json` and `errors.json` both carry a top-level `errors` object, and a shallow spread replaced one with the other. `errors.unknown` was among them — `PdErrorRow`'s fallback for an unrecognized code, the thing S7 built so English developer text could never reach a user, rendering as the literal `errors.unknown`. Invisible to both existing i18n tests: one checks `Code::ALL`, the other checks en/vi parity, and both locales lost the same keys.
|
||
|
||
**Exit criteria, counted by hand in the running app.** *Upgrade pip* → *Upgrade* is **2 clicks** from the landing screen. The row's version went 22.1.2 → 26.2.1 with exactly `["pip_upgrade", "env_probe"]` crossing the bridge — **no `env_scan`**, which is what "without a rescan" means and the only way to tell the two apart. The button then disappeared, the dialog's default focus was Cancel, and a refused upgrade rendered `PD-ENV-002` with localized copy and incremented `⚠ n`. Against real interpreters: 3.11 with a working pip 22.1.2 upgrades normally; 3.12 with the same pin, which cannot start, is repaired and ends at 26.2.1 running.
|
||
|
||
**Deliberately not done:** the *Upgrade pip* button does **not** appear merely because a newer pip exists. That needs `pkg_outdated` — networked, per environment, N calls on the landing screen — to surface something Installed and Updates already offer. What those screens cannot do is upgrade a pip so old the planner behind them refuses to run, which is the only case the button takes.
|
||
|
||
### Phase 3 · P2 — the tools venv — **done 2026-08-12**
|
||
|
||
Six commits. Code Health has an environment to run in, and `PD-HLT-001`'s shipped copy — *"Re-sync the tools environment"* — now refers to something the user can actually do.
|
||
|
||
| | What landed |
|
||
|---|---|
|
||
| **Core** | `health::pins`/`pins_hash`/`requirements_body` over `tools/tools-requirements.txt`, which had existed since the first scaffold commit and which nothing read. `sync_tools_venv(tools_dir, base_python, sink)` replaces the module's `todo!()`: create, install, verify. `ToolsManifest` + `SyncNeed` + `needs_sync`, `choose_tools_python`. |
|
||
| **Errors** | `PD-HLT-004` (`HltVenvCreateFailed`), the eight-place checklist in one commit. `Code::ALL` 32 → 33. |
|
||
| **CLI** | `pipdock tools sync [--force] [--python]` and `tools status`; `doctor` reports whether Health can run at all, without folding it into its exit rule. |
|
||
| **Wire format** | None. No Tauri command, no `NOT_YET` edit, no `COMMANDS` entry, no new `SCHEMA_TYPES`. P2 ships the `health-progress` **producer**; P3 ships the channel, when `health_run` exists to emit on it. |
|
||
| **Docs** | CODE-HEALTH-SPEC §2 amended on four points; CLI-SPEC §3 gains the commands and §6 gains a recorded, unclosed NDJSON gap. |
|
||
|
||
**Five findings that were not in the plan.**
|
||
|
||
1. **`TOOLS_PYTHON_MAX` should not exist, and the premise for it was wrong.** ROADMAP called it "the top unknown in all of M3" on the grounds that deptry ships compiled wheels with no cp314 build. deptry ships a Rust extension built against CPython's **stable ABI** — one `cp310-abi3` wheel, installed here on both 3.12.10 and 3.14.6. No ceiling was added; `--only-binary=:all:` makes a future gap a clean `PD-NET-011` instead of an sdist build.
|
||
2. **`tools/tools-requirements.txt` already existed and was already Dependabot-wired.** P2 consumes it rather than creating it, which deleted about half a day of the estimate.
|
||
3. **A re-sync could not repair the one state it exists to repair.** `pip install -r` over satisfied pins is a no-op, so replacing a deleted `ruff.exe` installed nothing and then failed verification with `PD-HLT-001` — and wedged, because the manifest had already been deleted. The venv is rebuilt now, not repaired. Found by deleting `ruff.exe`; invisible to a suite that only ever synced into an empty directory.
|
||
4. **`SyncNeed::ToolMissing(String)` could not be serialized.** `#[serde(tag = "state")]` is internal tagging and serde cannot represent a tagged newtype. It passed every unit test that constructed it and panicked the first time `tools status --json` met a missing tool. Now a struct variant, with a test that serializes all five states.
|
||
5. **The pin closure is not ABI-free, and the reason to exclude `pip-audit` is narrower than assumed.** deptry pulls `tomli`, which ships per-CPython wheels — but also a `py3-none-any` fallback, so a missing `cpXXX` build degrades to pure Python. `pip-audit`'s closure contains `msgpack`, which publishes **no** universal fallback and would hard-fail under `--only-binary=:all:`. That, not "exposure is zero", is why the ledger's fourth pin stays out of the venv.
|
||
|
||
**Exit criteria, measured by running it** (debug build, i7-14700KF, Python 3.14.6): cold bootstrap **15.2 s**, warm re-run **31 ms**, repair-after-quarantine **13.3 s**. `PIP_NO_INDEX=1` gives `error[PD-NET-011]`, exit **6**, an empty venv and — the thing that matters — **no `manifest.json` left behind**, so the next online run does not believe it is fresh. A forced `--python` onto 3.12.10 installs the same abi3 wheel. A sync killed mid-download leaves **zero orphan `pip.exe`** and no manifest.
|
||
|
||
**Deliberately not done:** deleting the dead `engine::uv::parse_dry_run` and flipping `clippy::todo` from `allow` to `warn`. After this slice that function holds the last `todo!()` in the workspace, so the flip is a clean two-line follow-up — but not inside a feature diff. `sync_tools_venv` also takes no `--break-system-packages` path and needs none: the tools venv is PipDock's own and is never PEP 668 managed.
|
||
|
||
## Phase 4 — RC → v1.0 (~1–2 weeks)
|
||
|
||
Release pipeline live (bundling, checksums), manual charter executed, docs/README screenshots, legal files public, a clean install of the RC verified on a machine that has never run PipDock. **Exit:** RELEASE-CI §5 checklist fully checked; v1.0.0 published + notify fan-out.
|
||
|
||
### First bundle built locally — 2026-08-13
|
||
|
||
`npx tauri build --bundles nsis,msi -- --locked` on the dev machine, 3m48s, producing
|
||
`PipDock_0.1.0_x64-setup.exe` (5.7 MB) and `PipDock_0.1.0_x64_en-US.msi` (7.6 MB). The workflow's
|
||
collect and checksum steps were then run verbatim against those artifacts and produce a correct
|
||
`SHA256SUMS.txt`; the README's verification one-liner reproduces the published sum.
|
||
|
||
**Two defects, both invisible until something was actually built.**
|
||
|
||
1. **`release.yml` could not have worked.** `npx tauri build --locked --bundles nsis,msi` fails with
|
||
*"unexpected argument '--locked' found"* before a single crate compiles — `--locked` is cargo's
|
||
flag and everything after `--` is what reaches the runner. No `v*` tag has ever been pushed, so
|
||
the release job had never run. Fixed, along with a duplicated frontend build step (`tauri build`
|
||
already runs `beforeBuildCommand`).
|
||
2. **The installers ship the GUI only.** `tauri.conf.json` declares no `externalBin` and no
|
||
`resources`, so the NSIS payload is exactly `pipdock-app.exe` and the MSI's `app.cab` holds one
|
||
file. **`pipdock.exe` is not installed at all** — while PRD P0-12 is "CLI core parity", CLI-SPEC
|
||
documents the whole surface, and the README's own Quick start tells the user to run
|
||
`pipdock env list`. A real install leaves none of that on the machine. **This is a v1 blocker**
|
||
and the fix needs an owner decision, because the options differ in how much they touch the
|
||
user's system: ship the CLI beside the GUI and leave `PATH` alone; ship it and have NSIS extend
|
||
`PATH`; or publish it as a separate archive on the release.
|
||
|
||
**The installer was then run for real, and it found a third defect.** Tauri's NSIS per-user
|
||
installer writes to `$LOCALAPPDATA\{productName}` — the same folder `store::default_app_data()`
|
||
used — so `pipdock-app.exe`, `pipdock.exe` and `uninstall.exe` landed beside `index.db`,
|
||
`snapshots\` and `tools\`. SECURITY §8 tells users that deleting the app data folder is a
|
||
complete reset; collided, that advice uninstalled the application. The data root moved to
|
||
`%LOCALAPPDATA%\PipDock\data\`, which was free to change because no release has ever been
|
||
published — and therefore carries **no migration code**, which would have been dead from its first
|
||
commit.
|
||
|
||
**Uninstall was tested rather than assumed**, with a backup taken first that turned out not to be
|
||
needed: it removes its own three binaries, the Start-menu shortcut and the registry entry, and
|
||
leaves the data directory untouched.
|
||
|
||
**Verified after reinstalling:** the install root holds `data\` plus three binaries; the installed
|
||
`pipdock.exe --version` answers, `env list` works, and `tools status` resolves
|
||
`…\PipDock\data\tools`. First-run behaviour had already been checked against a throwaway
|
||
app-data root, where the app creates its store from nothing and spawns a WebView2 host.
|
||
|
||
**Honest limits.** This machine has run PipDock before, so isolating the app-data root approximates
|
||
the "never run PipDock" criterion rather than meeting it — a genuinely clean machine is still owed.
|
||
SmartScreen was **not** exercised: the installer was run scripted, and SmartScreen is an Explorer
|
||
behaviour. And the three click-through items P4/P5 left owed — the OS folder picker, a ruff rule
|
||
link, the fix dialog — are **still owed**: the screenshot tooling resolves the installed app to a
|
||
virtualized sandbox path and masks its window, so it could not be driven here. All four need a
|
||
human at the keyboard.
|
||
|
||
**Charter progress (TESTING §4).** Non-ASCII project path (`E:\sp5\dự án tiếng việt`) runs all
|
||
three Code Health tools with the path intact. Scale, release build: `pipdock list` is **1.1 s**
|
||
over a 145-package venv and **1.5 s** over a 352-package system Python. Still to do: the VI locale
|
||
sweep of the mutation dialogs, corporate-proxy simulation, and cancel mid-Phase-B.
|
||
|
||
### Shell polish from the first click-through — 2026-08-13
|
||
|
||
The owner drove the **installed** build as a user. That cleared every item P4/P5 had left owed —
|
||
folder picker, both locales, ruff over a real project, install/rollback/upgrade, bilingual error
|
||
copy, and the bug-report deep link — and found two bugs and two improvements that only appear when
|
||
someone actually uses the thing.
|
||
|
||
| | Found |
|
||
|---|---|
|
||
| **Duplicate *Back to packages*** | `PdSummarySheet` renders `plan.done` from `onDone`; the panel rendered a second beneath it. The panel's now shows only when there is no sheet, because a run that fails before producing an `ExecutionSummary` would otherwise be a dead end |
|
||
| **No single instance** | five launches, five windows — five `AppState`s over one machine, each certain it owned the mutation in flight |
|
||
| **Sidebar navigable mid-plan** | left the plan parked in Rust with nothing driving it; the next Update answered `PD-RES-003` about a plan the user could no longer see |
|
||
| **Window unbounded** | a fixed sidebar plus one scrolling column, stretched across a 4K panel |
|
||
|
||
**The duplicate button is the interesting one.** `PdSummarySheet` had tests and `PdPlanPanel` had
|
||
none, so the two had never been rendered together — the bug lived exactly in the seam between a
|
||
tested component and its untested parent. The new `PdPlanPanel.test.tsx` was checked *against* the
|
||
bug (revert the panel change, it fails `expected 2 to have length 1`), and adding it exposed a
|
||
second gap: `ipcMock` had no `reportBugUrl`, which `PdErrorRow` requests on mount, so **any screen
|
||
containing an error row was untestable**.
|
||
|
||
Verified against the installed build rather than the config: five launches → one process and one
|
||
window; the real `HWND` style carries no `WS_MAXIMIZEBOX` and still carries `WS_THICKFRAME`.
|
||
|
||
### Phase 4 — where it stands
|
||
|
||
**Done:** the release pipeline builds, checksums and drafts correctly (proven by running its own
|
||
steps against real artifacts); the installer ships both binaries; program and data no longer share
|
||
a directory; the shell bugs above are fixed; README carries the badges RELEASE-CI §5 asks for.
|
||
|
||
### Phase 4 closed — 2026-08-14
|
||
|
||
All six of the items above are done. What actually happened, item by item, because "we ran the
|
||
charter" ages into nothing:
|
||
|
||
1. **A genuinely clean machine.** The RC was installed and driven on a real Windows 11 machine
|
||
that had never run PipDock, plus **Windows Sandbox** and a **Windows 10 VM under VirtualBox**.
|
||
Three installs, three uninstalls, no failures.
|
||
2. **SmartScreen produced no prompt** on any of the three. Worth knowing *why* that is not a
|
||
guarantee: SmartScreen's reputation check is per-file-hash and per-publisher, and the binaries
|
||
are still not EV-code-signed, so a warning on some future user's first download remains
|
||
possible. The README's checksum instructions are the answer either way, and they stay.
|
||
3. **The manual charter is complete** (TESTING §4). The three that were owed — the VI locale sweep
|
||
of the mutation dialogs, cancel mid-Phase-B, and corporate-proxy simulation for `PD-NET-002` —
|
||
were all executed, as was a **non-ASCII Windows username**, which is a different case from the
|
||
non-ASCII *path* already covered by `E:\sp5\dự án tiếng việt`: the username is in
|
||
`%LOCALAPPDATA%`, so it is in the data root, the log paths and the tools venv.
|
||
4. **The icon is decided, not deferred.** The green triangle stays. It was called a placeholder
|
||
because nobody had chosen it; the owner has now chosen it, which is what "a brand decision"
|
||
needed. `bundle.icon` still names only `icons/icon.ico` — correct for a Windows-only build; the
|
||
Square*.png set is Microsoft Store furniture nothing reads.
|
||
5. **Version is `1.0.0`** in all five places (`Cargo.toml`, `Cargo.lock`, `package.json`,
|
||
`package-lock.json`, `tauri.conf.json`). The `v1.0.0` tag is the first real run of
|
||
`release.yml`.
|
||
6. **Seven screenshots** are in `screenshot/` and referenced from the README. They predate the
|
||
About tab, so their sidebar has eight entries where 1.0 has nine.
|
||
|
||
**Repo scaffolding (RELEASE-CI §5) is complete**, and three of its items turned out to be already
|
||
done and undocumented: the Discord webhook secrets were set 2026-08-14, CodeQL *Default setup* was
|
||
already `not-configured` (which is what the advanced-setup caller requires), and Discussions were
|
||
already on. **Branch protection** was the only genuinely outstanding one and is now applied over
|
||
the API — five required checks, `enforce_admins: true`, PR required, linear history. RELEASE-CI §2
|
||
has claimed `main` was protected since it was written; that claim is true for the first time.
|
||
|
||
`CI / Integration` is deliberately **not** a required check: its `pull_request` trigger is
|
||
`paths:`-filtered, and a required check that never starts leaves a PR pending forever — so
|
||
requiring it would deadlock every docs-only and UI-only PR.
|
||
|
||
### What Phase 4 found that was not on its list
|
||
|
||
Four things, three of them defects that had been shipping.
|
||
|
||
**`main` was red and nobody knew.** `Cargo.lock` at `3eeda05` carried a dependency edge to
|
||
`thiserror 2.0.19` while its package entry said `2.0.20` — a lockfile cargo wants to repair and
|
||
`--locked` forbids repairing, so every cargo job in every workflow died before compiling a crate.
|
||
Same shape as the ruff-pin defect in P4: a Dependabot bump whose base predated the code that would
|
||
have caught it. The lesson is the one already written — **check `gh run list` before believing a
|
||
green badge**, because the badge is per-workflow-file and shows the last run, not the last commit.
|
||
|
||
**The privacy policy described a self-updater deleted two weeks earlier**, and told users to delete
|
||
`%LOCALAPPDATA%\PipDock\` for "a complete reset" — the folder the program installs into. Following
|
||
the shipped privacy policy uninstalled the application. `d829c4f` had updated
|
||
THIRD-PARTY-NOTICES and not PRIVACY-POLICY; SECURITY §8 recorded the data-root move and the legal
|
||
document never got it. **A `docs/` fix and a `legal/` fix are two different changes**, and the
|
||
second is the one a user reads.
|
||
|
||
**Four documents credited `specta`/`tauri-specta`,** which `bindings.rs` has recorded since M1 that
|
||
the project deliberately does not use. One of them was `legal/THIRD-PARTY-NOTICES.md`, i.e. a
|
||
licence attribution for a dependency that does not exist, beside eleven that do and were unlisted.
|
||
|
||
**`Ctrl+N` never refused while a plan owned the screen,** despite UI-SPEC §8 asserting it did since
|
||
S3. `App.tsx` guarded on `guardOpen`, and `PANEL_PHASES` excludes `guard` on purpose — the two sets
|
||
are disjoint, so guarding on one guarded neither. Invisible, because the sidebar was disabled and
|
||
the panel kept rendering, until the plan finished and dropped the user on a tab they never chose.
|
||
**A spec sentence is not a test.** Found by reading `App.tsx` to add a ninth tab.
|
||
|
||
### The About tab (early out of the Post-1.0 wave)
|
||
|
||
UI-SPEC §4 has specified *Legal & About* since the spec was written, as a section inside Settings,
|
||
and four milestones shipped without it — so after acceptance there was no in-app path back to the
|
||
documents at all. It is the ninth tab instead, because a read-only surface folded into a screen of
|
||
controls is the thing that never gets built.
|
||
|
||
Three things it settled that outlive it:
|
||
|
||
- **Appending to `NAV_KEYS` is free; inserting is not.** `Ctrl+9` cost one array entry and one
|
||
label. Every comment saying "a ninth entry would renumber `Ctrl+1..8`" was wrong about the
|
||
reason: Snapshots stays a mode of Environments because it would have to sit *beside*
|
||
Environments, which is an insert.
|
||
- **A review is not a revocation.** Re-opening the gate by setting `accepted = false` was one line
|
||
and would have offered Accept and a Decline-that-quits to someone re-reading their privacy
|
||
policy. `useLegalStore.review` is its own flag and the gate takes a presentational prop.
|
||
- **`app_info` fired twice per mount, and only the running app said so.** StrictMode's doubling is
|
||
dev-only, but it exposed the real one: `key={nav}` remounts `<main>`, so every visit re-fetched a
|
||
value baked in at compile time. `PdAbout.test.tsx` asserted one call and passed, because Testing
|
||
Library does not use StrictMode. **Run it, don't just test it** — the twenty-fifth time.
|
||
|
||
## 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. **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 is **not planned**, decided with the move to maintenance mode in 1.6.0 (*Maintenance mode*, below). 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:
|
||
|
||
- **Generate `legal/THIRD-PARTY-NOTICES.md`.** Both it and SECURITY §7 claimed `cargo about` +
|
||
`license-checker` regenerated it at release into a `licenses/` directory; no `about.toml`, no
|
||
such directory and no such release step have ever existed. The claim now describes what is
|
||
actually done — a hand-maintained inventory of the *direct* dependencies, reconciled against the
|
||
manifests at each release. Making it true is the item. Doing it at 1.0 would have meant
|
||
complicating `release.yml` on the first run it had ever had.
|
||
- **Re-capture the screenshots** once anything visible changes. `screenshot/` holds **eight**;
|
||
seven of them predate the About tab and show an **eight**-entry sidebar, while `about.png` shows
|
||
nine and a *This build* panel reading `1.0.0`. So every one of them is now stale in at least one
|
||
way, and the count is worth stating because the sentence here used to read as though there were
|
||
seven files.
|
||
|
||
~~Also worth doing when the Security tab lands: an OSV host in
|
||
`capabilities/external-links.json`.~~ **Done in P1-1**, along with the prose §4 requires — and the
|
||
entry records what makes it different from `docs.astral.sh`: `advisory_url` *builds* the URL from a
|
||
validated id, so the tool chooses the id and never the destination.
|
||
|
||
### The P1 wave, closed — 1.1.0, 2026-08-14
|
||
|
||
All four items shipped, in one afternoon after 1.0.0. **The estimate's central claim held for
|
||
three of them and was wrong about the fourth in a useful direction:** P1-A was mostly already
|
||
written, P1-B's export needed no code at all, P1-D touched no Rust — and P1-C turned out to have a
|
||
scope error rather than an effort error.
|
||
|
||
| Slice | What it cost |
|
||
|---|---|
|
||
| **P1-A** pin auto-suggest | 6 commits. `dependent_count` finally has a caller. |
|
||
| **P1-B** requirements | 1 commit. Export is `Engine::freeze` and a path; import is a parser. |
|
||
| **P1-C** cache manager | 1 commit. Three artefacts, not four, and the first delete-a-tree. |
|
||
| **P1-D** command palette | 1 commit. Frontend only, exactly as estimated. |
|
||
|
||
**Four things running it said that reading could not.**
|
||
|
||
1. **94 suggestions** on a 352-package environment at the default threshold — a quarter of the
|
||
install list. Fixed by bounding the view, not by raising the default: a deep tree is where a
|
||
bulk update is most dangerous.
|
||
2. **`graph::Requirement::parse` accepts prose.** It splits the name at the first space, so
|
||
`this is not a requirement` parses as package `this` with constraint `is not a requirement` —
|
||
correct for `Requires-Dist`, which never looks like that, and a spec containing spaces heading
|
||
for argv when the input is a file a person typed. P1-B shape-checks the constraint, which is
|
||
the obligation SECURITY §2 already places on every other user-supplied version.
|
||
3. **There are no log files.** `LOG_RETENTION_DAYS` has never had a reader. P1-C reports three
|
||
artefacts; a "logs — 0 B" row would have invented one.
|
||
4. **The palette's first ranking put an action above the screen it belongs to.** Matching one flat
|
||
`"${group} ${label}"` string ranked *Download the index* above the Search tab. Label matches now
|
||
outrank group matches by a margin wider than any tier.
|
||
|
||
**Two corrections to the process, both from P1-A and both now in the checklist below.** Adding a
|
||
command touches **six** places, not five — `golden.rs` keeps its own copy of `SCHEMA_TYPES`. And
|
||
a generated type must be added to the `import type` list in `ui/src/ipc/index.ts`; `export type *`
|
||
does not bring it into scope for a wrapper's own signature.
|
||
|
||
**What P1 did not do.** No `pipdock pin suggest`, no CLI surface for export/import or the cache —
|
||
all four are GUI-only, and `pins::suggest`, `requirements::parse` and `cache::usage` are in core
|
||
precisely so a subcommand is later trivial. No dismissal for a rejected pin suggestion. `index.db`
|
||
is not a clearable target and will not become one while it holds settings, pins and the consent
|
||
record in the same file.
|
||
|
||
**Still open from the original P1 list:** the Security tab (pip-audit), the dependency-graph view,
|
||
the scheduled check — and the half of P1-4 this did not do. PRD P1-4 also asked for the *engine*
|
||
caches (`pip cache`, `uv cache`); those belong to the engine, live outside
|
||
`%LOCALAPPDATA%\PipDock\`, and purging them is a subprocess rather than a file delete, so they are
|
||
a different feature wearing the same word. The PRD row now says so rather than reading as done. The Security tab remains the one that needs an OSV host added to
|
||
`capabilities/external-links.json` — DISCLAIMER §4 and SECURITY §6 both say findings link there,
|
||
and the allowlist would reject it silently.
|
||
|
||
### Slice 0 — preflight before the Security tab — **done 2026-08-18**
|
||
|
||
Three commits. Nothing here is a feature; all three are things `main` was already carrying, found
|
||
while surveying what is left of Post-1.0 (P1-1 Security tab, P1-6 dependency graph, P1-7 scheduled
|
||
check). Two of the three had to happen before a 39th command could land anyway.
|
||
|
||
| | What landed |
|
||
|---|---|
|
||
| **Fixtures** | `redact()` covers pip's `[notice] A new release of pip is available:` version pair; nine pip fixtures re-blessed; one byte re-blessed in uv's `build-backend-failure` |
|
||
| **Core + UI** | `plan::Blocker` becomes `by` / `version` / bare requirement; `run.rs` gains `blocker_line`; `PdConflictRow` composes; `fixtures::numpy_blockers` is **computed**; `PdConflictRow.test.tsx` is new |
|
||
| **Docs** | ARCHITECTURE §7's five missing rows, a fourth drift test that reads the table, two stale counts |
|
||
|
||
**The drift gate could not have stayed green.** pip's upgrade notice states the version that is on
|
||
PyPI *today*, so it moves with every pip release — and `redact()` stripped the disposable venv path
|
||
out of the line *below* it while leaving this one alone. pip 26.2.1 shipped on 2026-08-17 and the
|
||
weekly re-capture failed across all nine pip fixtures carrying the line. The same shape as the five
|
||
faults in *L2's first runs*: a gate that fires for a reason unrelated to engine behaviour means
|
||
nothing, and this one was going to fire every Monday.
|
||
|
||
**The preview named the dependent twice, and had since S3.** It rendered `scipy requires scipy
|
||
1.11.4 requires numpy <1.28.0,>=1.21.6`, because `graph::blockers_for` built an English sentence
|
||
into `Blocker.constraint` while also setting `by`, and `PdConflictRow` passed both to
|
||
`plan.blocker`, whose template is `{{by}} requires {{constraint}}`. Hard invariant 4 the wrong way
|
||
round — and the reason it was written that way is instructive: the **CLI** prints that field alone,
|
||
so the one head it looked right in was the one with no catalog. Each head composes now, exactly as
|
||
`BrokenDependent` and `PdUninstallDialog` already did.
|
||
|
||
**Why every suite was green, which is the part worth keeping.** `PdPreviewDiff.test.tsx` *did*
|
||
assert this sentence, and asserted the **correct** one — because the fixture's blockers were
|
||
hand-written to the shape `Blocker`'s own doc describes, while the producer had drifted away from
|
||
it. `fixtures.rs` says in its own module doc that hand-writing the JSON "would defeat the
|
||
guarantee", and `guard_report()` is computed for precisely that reason; the plan fixture's blockers
|
||
were the single exception, and the bug lived in it. They are computed now — which is also why there
|
||
are two of them: `pandas 2.1.4` and `scipy 1.11.4` both exclude 2.5.1, and only one had ever been
|
||
written down. **A hand-written fixture that agrees with the documentation while the code disagrees
|
||
with both is worse than no fixture**: it makes a test that asserts the right thing prove the wrong
|
||
one.
|
||
|
||
**Three process notes.**
|
||
|
||
1. **`sed -i` under Git Bash rewrites in text mode and strips CR.** It flattened every CRLF in ten
|
||
engine fixtures in one command — exactly the byte-exactness `.gitattributes`' `-text` exists to
|
||
protect, and `git diff --stat` reported 160 changed lines where one was intended. Anything
|
||
touching `tests/fixtures/**/*.txt` has to go through a binary-mode read/write, asserting the
|
||
CRLF count per file.
|
||
2. **ARCHITECTURE §7 now has a test.** Its opening sentence has claimed since M2 that a command not
|
||
in the table does not exist; the three drift tests never read it, and `every_registered_command_
|
||
is_declared`'s failure message claimed §7 coverage it did not have. *A spec sentence is not a
|
||
test* — the fourth time this exact lesson has been recorded here, and the first time on a
|
||
sentence about the document itself.
|
||
3. **A count was called stale that was not.** ROADMAP's screenshot note says "the seven in
|
||
`screenshot/` show an eight-entry sidebar". `screenshot/` holds eight files, so a reader counting
|
||
files concludes the sentence is wrong. Opening two of the images settles it: seven predate the
|
||
About tab and do show eight entries, and `about.png` shows nine. Reworded rather than
|
||
"corrected", because correcting it would have introduced the error.
|
||
|
||
### Post-1.0 · P1-1 — the Security tab — **done 2026-08-18**
|
||
|
||
Eight commits, and **1.2.0**. The last major P1 item; PRD P1-1 has been on the list since the PRD
|
||
was written and had a spike behind it from Phase 0.
|
||
|
||
| | What landed |
|
||
|---|---|
|
||
| **Core** | `health::pins_for`/`sync_steps`/`needs_sync`/`sync_tools_venv` take a tool list; `AUDIT_TOOLS`, `audit_dir`; the whole `audit` module — `Advisory`, `AuditReport`, `parse`, `dedupe`, `sort_advisories`, `advisory_url`, `run`, `markdown`; `cache::Target::Audit` |
|
||
| **Bridge** | `audit_run`, `audit_cancel`, `audit_save_report`; `AppState.audit` as `Sessions<()>`; the `audit-progress` channel |
|
||
| **CLI** | `pipdock audit`, exit 1 on findings |
|
||
| **UI** | `PdSecurity`, `PdAuditReport`, `useSecurityStore` — and `PdSidebar`'s `NOT_YET` is **empty** for the first time |
|
||
| **Fixtures** | the pip-audit capture SP-4 asked for in Phase 0 and never got, plus a **computed** `audit_report.json` |
|
||
| **Docs & legal** | PRD P1-1, SECURITY §4/§6, UI-SPEC §4/§5/§6, CLI-SPEC §3, CODE-HEALTH-SPEC §2, `capabilities/external-links.json`, and three `legal/` documents |
|
||
|
||
**Three decisions the owner closed before any code**, each of which would have been expensive to
|
||
reverse:
|
||
|
||
1. **pip-audit gets its own venv.** `HEALTH_TOOLS` gave two reasons for excluding it and only one
|
||
survives the tab existing — "a feature they cannot reach" stops being true, but `msgpack` still
|
||
publishes no universal wheel, and `--only-binary=:all:` is load-bearing. A fourth entry in
|
||
Code Health's venv would let a new CPython take Code Health down with the Security tab.
|
||
2. **The default PyPI vulnerability service, linking out to OSV.** This is what keeps
|
||
`legal/PRIVACY-POLICY.md` §3's "exactly one destination" **true**, and measuring showed it costs
|
||
nothing: the same environment under `--vulnerability-service osv` returns the *same eight*
|
||
advisories, set difference empty in both directions. The 10-vs-16 row difference is pure
|
||
duplication.
|
||
3. **The specs get corrected rather than the tool worked around** — see below.
|
||
|
||
**Two spec claims were not stale but unimplementable.** SECURITY §6 said pip-audit "runs from the
|
||
tools venv"; the code had refused that since P2 with three tests enforcing the refusal. And §6 and
|
||
PRD P1-1 both promised a **severity** — "(CVE/GHSA id, severity, fixed-in)", "severity-sorted" —
|
||
against a field pip-audit has never had under *either* service. A finding carries `id`,
|
||
`fix_versions`, `aliases` and `description`, full stop. The order that shipped is package →
|
||
fixable → id, which is the one distinction that changes what a user can do; a severity derived
|
||
from the id's year or the prose would be a number PipDock invented, shown beside real ones.
|
||
|
||
**SP-4's exit criterion is finally met.** It asked for "command line + JSON fixture pinned" in
|
||
Phase 0. The command line was pinned in prose; the fixture never was, so every claim about
|
||
pip-audit's output had gone unchecked for a year of development. Both are committed now, with
|
||
provenance.
|
||
|
||
**Four things found by running, none of them visible in a diff.**
|
||
|
||
1. **The watchdog was a linter's.** Written against Code Health's 120 s `TOOL_TIMEOUT`, the first
|
||
real run hit it and reported `PD-HLT-003` for a tool that was working. Measured afterwards:
|
||
**68 s cold** for one package, 18.6 s warm for one, **20.0 s warm for twelve**. Twelve cost
|
||
1.4 s more than one, so the cost is a one-off advisory-database fetch and a 352-package
|
||
environment is not the risk — a cold fetch on a slow link is. `AUDIT_TIMEOUT` is 600 s,
|
||
matching `exec::DEFAULT_TIMEOUT`.
|
||
2. **That number reopened cancellation.** P4 deferred it for Code Health on a measurement of
|
||
**1.3 s**; 18-68 s is a different answer to the same question. Wired *and* mapped, because P4
|
||
also recorded that wiring the token alone renders a cancel as "PipDock hit an internal error" —
|
||
`exec` reports a cancel and a crash through the same `IntUnexpected`. `AuditReport.cancelled` is
|
||
a state, the step ends `Skipped`, and nothing lands in `problems`.
|
||
3. **The screen lied while running.** Mid-run the body read *"No audit has run for this
|
||
environment"* — while an audit was running. The report is cleared before the command, so `shown`
|
||
is legitimately null during a run and the un-run empty state rendered on that basis. That is
|
||
P4's "no issues found before anything had run" **inverted**: a true-looking sentence derived
|
||
from a state the screen had not loaded. Found by clicking Run against a deliberately slow
|
||
bridge; no test saw it, because every other test renders this screen settled.
|
||
4. **`total_bytes` under-reported by a whole venv.** Adding `Target::Audit` gave `Usage` a fourth
|
||
entry and the sum still added three — with every existing cache test passing. A wrong total with
|
||
nothing to say so is worse than a missing row, so the guard now asserts on distinct powers of
|
||
two: a missing term shows up as its own bit rather than as a plausible number.
|
||
|
||
**The engine changes what is audited, and the tab does not hide it.** `Engine::freeze` passes
|
||
`--all` on pip and uv has no such flag, so auditing the SP-4 environment reports **five advisories
|
||
in pip 25.0.1 itself** alongside urllib3's eight. A uv-engine audit of the same environment sees
|
||
fewer packages.
|
||
|
||
**Verified by running, at every level.** `pipdock audit` cold against a real vulnerable environment
|
||
with an isolated `LOCALAPPDATA`: the audit venv bootstrapped, wrote its manifest, reported 13
|
||
advisories across 2 packages, `--json` emitted one camelCase document, exit **1**. The second run
|
||
did no bootstrap, which is `needs_sync` returning `Fresh` for `AUDIT_TOOLS`. The runner and the
|
||
cancel path were each run against the real tool (`--ignored`, `PIPDOCK_AUDIT_DIR`) and each
|
||
mutation-checked. The screen was driven in the browser against a stubbed bridge: `audit_run`
|
||
crosses **once**, all three listens precede it, both package groups render, and Cancel reaches
|
||
`audit_cancel`.
|
||
|
||
**The legal gate re-shows once** for every existing user. `legal/EULA.md`,
|
||
`THIRD-PARTY-NOTICES.md` and `DISCLAIMER.md` all described pip-audit as planned-and-not-invoked,
|
||
and all three are in `build.rs`'s `DOCUMENTS`. That is the mechanism working, and it was decided
|
||
before the work rather than discovered after it.
|
||
|
||
**Still owner-verifiable only**, because the stubbed bridge cannot reach them: the save dialog, and
|
||
clicking an OSV link to confirm the widened allowlist actually opens — which is the one failure
|
||
mode that is *silent*, and the reason SECURITY §4 requires the widening in prose.
|
||
|
||
**Deliberately not done:** no `pipdock audit --fix`, and no auto-upgrade from a finding. SECURITY §6
|
||
has always said audit never applies anything; "update to fixed version" is the ordinary Update flow,
|
||
reached by the user.
|
||
|
||
**Nothing is left of Post-1.0.** The scheduled check (PRD P1-7) was the last item, and on
|
||
2026-11-21 the owner closed it as not planned, for the reasons the survey below gives; the
|
||
dependency view shipped as 1.3.0, and its record is below.
|
||
|
||
*This paragraph used to point at "the analysis above" for what blocked each of two items. There was
|
||
no such analysis anywhere in this document* — the survey existed only outside the repository, and
|
||
the sentence had been repeated into `CLAUDE.md`. What actually separated P1-1 from the other two was
|
||
that it had a Phase-0 spike behind it (SP-4) and they did not; P1-6 has one now, in the shape of
|
||
measurements taken before the screen was designed. The P1-7 half of the missing survey is below, so
|
||
that the pointer finally has something to point at.
|
||
|
||
#### What blocks P1-7 — the scheduled check
|
||
|
||
Nine words of PRD, and **every prerequisite is absent.** Counted against the tree on 2026-08-20:
|
||
|
||
- **No toast.** `ui/src/components/` has none. UI-SPEC states a policy for a mechanism that has
|
||
never been built.
|
||
- **No plugin.** `src-tauri/Cargo.toml` carries no notification, autostart or tray dependency, and
|
||
each would need a capability entry with SECURITY §4's prose justification.
|
||
- **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, 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,
|
||
zero dependencies, zero legal edit, no toast. Whoever picks this up should first say what the GUI
|
||
version gives that the recipe does not, because the honest answer may be "a notification", and that
|
||
is one plugin and a permanent background process for one line of text.
|
||
|
||
### Post-1.0 · P1-6 — the dependency view — **done 2026-08-20**
|
||
|
||
Six commits, and **1.3.0**. PRD P1-6 was twelve words and had no UI-SPEC screen, no §6 component,
|
||
no nav slot, no CLI command and no decomposition here.
|
||
|
||
| | What landed |
|
||
|---|---|
|
||
| **Preflight** | ARCHITECTURE §7's `audit_run` row regains its trailing pipe; `the_architecture_table_is_well_formed`; `catalog.rs`'s stale 33/30 comment; CLAUDE.md's three-named-as-four schema list |
|
||
| **Core** | `ReverseDeps.forward`; `requires_of`, `edges_to`, `unsatisfied`, `reach`, `view`; `DepEdge`, `DepsNode`, `DepsGraph`; nine tests plus an opt-in live one |
|
||
| **Wire** | `DepsGraph` in `schema_for!`, `SCHEMA_TYPES` and `golden.rs`'s own copy. 32 types, 67 goldens |
|
||
| **Bridge** | `deps_graph` — `pin_suggestions`' shape, not `audit_run`'s. `NOT_YET` unchanged at two |
|
||
| **UI** | `PdDeps` (a mode of the package screen), `PdDepsFocus`, `stores/deps.ts`, a third row button, both catalogues |
|
||
| **Docs** | UI-SPEC §4/§5/§6, ARCHITECTURE §4, PRD P1-6, this section |
|
||
|
||
**The measurements decided the design, and they were taken first.** Against `C:\Python314` — 352
|
||
packages, the scale fixture — and a 29-package venv, by running `probe.py` directly:
|
||
|
||
| | 352-pkg | 29-pkg |
|
||
|---|---|---|
|
||
| Depth-1 neighbourhood | median **7**, p90 25, max 151 | median 2, max 11 |
|
||
| Depth-2 neighbourhood | median **172**, p90 209 | max 25 |
|
||
| Over 60 nodes at depth 2 | **212 of 352** | 0 of 29 |
|
||
| Transitive reverse closure | median 20, p90 111, max 178 | — |
|
||
| Distinct paths to a root, `setuptools` | **>2000** | — |
|
||
|
||
So: **depth 1 is drawable and depth 2 is a hairball**, and paths cannot be enumerated at all. The
|
||
view is drawn at depth 1, depth is navigated by re-centring, and the transitive question is answered
|
||
by two numbers. A graph library would have been the eleventh runtime dependency, a
|
||
`THIRD-PARTY-NOTICES.md` edit that re-shows the legal gate, an npm-audit surface and a CSP argument
|
||
— and would not have made 172 nodes readable. **Zero new dependencies.**
|
||
|
||
**Rust's answer differed from the prototype's, which is the argument for where this lives.** The
|
||
throwaway Python that took the measurements skipped only extra-gated edges. Rust, evaluating
|
||
`python_version` as well, reports **1858** in-force edges rather than 1893 — and **one** unsatisfied
|
||
requirement rather than seven. The other six are backports gated on a Python this environment is
|
||
not. Counting raw `Requires-Dist` names would have shipped a healthy environment described as
|
||
broken.
|
||
|
||
**Measured in `--release`** on that environment: probe 605 ms, graph build **1.8 ms**, whole-view
|
||
computation **43 ms**, payload **249 KB**. Having `reach` walk `forward` itself takes the view to
|
||
31.4 ms — 11 ms, or **1.8% of a probe the user is already waiting for**, in exchange for a second
|
||
copy of the in-force-and-installed rule. Declined; the number is in `reach`'s doc so it is not
|
||
re-litigated.
|
||
|
||
**UI-SPEC §4 was corrected rather than followed.** It said the third row action would fold
|
||
pin/uninstall/details into a `⋮` menu "with the budget intact". It does not: a menu makes uninstall
|
||
four clicks where §5's table records three, hand-counted, for the second most destructive action in
|
||
the app. Four is under the ceiling of five, which is precisely why the ceiling alone would have
|
||
allowed it — **a ceiling is not a ratchet, and a table of measured counts is.** Three inline buttons
|
||
cost nothing, because the row is the only tab stop and its controls are a roving sequence.
|
||
|
||
**Three defects found by mutation rather than by writing tests.** A column helper keyed on copy
|
||
matched nothing once the heading pluralised — "2 packages *require* this", not "requires" — and the
|
||
test passed by finding the singular case. A name-only comparison of the dependents column survived
|
||
a mutation that dropped the version and the specifier from every row. And the App-level test's
|
||
first draft asserted against a **licence agreement**: `App` calls `checkConsent()` on mount and
|
||
`useLegalStore.check` fails closed, so `accepted: true` in the store is undone a tick later and the
|
||
gate replaces the whole shell. The store had reached `phase: 'ready'` with the graph in hand the
|
||
entire time. That is the browser recipe's own warning, met in its jsdom form.
|
||
|
||
**The invalidation this slice was warned about, and hit.** `freshGraph` keys on `envHash`, which a
|
||
mutation does not change, so an install would have left last-hour's edges on screen looking correct.
|
||
`App.tsx` resets the slice in `onFinished`. Health and Security guard and never reset because
|
||
nothing they read is altered by an install; edges are exactly what an install alters.
|
||
|
||
**Deliberately not done.** No `pipdock deps` — the P1-A..D precedent, and the core functions are in
|
||
`graph/` so a subcommand is later trivial. No tree widget: re-centring already navigates depth. No
|
||
node-link diagram at any depth. No graph for packages that are not installed — there is no
|
||
`Requires-Dist` to read.
|
||
|
||
**Still owner-verifiable only.** The browser pane could not reach `localhost` in this session, so
|
||
the live drive was replaced by an App-level test against a logging bridge. That reaches everything
|
||
except the Rust side of the command and the real window; `deps_graph`'s argument name is the usual
|
||
runtime-only risk, and it is the same `{ env }` shape `pkg_list` has shipped since M2.
|
||
|
||
### Four items decomposed, easiest first
|
||
|
||
Surveyed 2026-08-14 against the real tree. Ordered by how much already exists, not by value — each
|
||
is a slice in the M2/Phase-3 shape: one PR, split commits, ending in a `docs:` commit.
|
||
|
||
**The reusable-surface rule this survey confirmed:** three of the four are mostly *wiring*, and the
|
||
fourth introduces the first delete-a-tree primitive in the codebase. Read the per-item notes before
|
||
estimating; the interesting work is rarely where it looks.
|
||
|
||
---
|
||
|
||
#### P1-A · Pin auto-suggest — PRD P1-2, UI-SPEC §4 — **done 2026-08-14**
|
||
|
||
Five commits. The estimate below held: **most of it was already written and had never been
|
||
called.**
|
||
|
||
| | What landed |
|
||
|---|---|
|
||
| **Core** | `pins::suggest` — the first caller `graph::dependent_count` has ever had. `PinSuggestion { pkg, dependents }`. `Settings.pin_suggest_threshold`, defaulting to `graph::PIN_SUGGEST_THRESHOLD` rather than a second literal. |
|
||
| **Bridge** | `pin_suggestions(env)` — store read, guard dropped, then probe. `NOT_YET` unchanged at two. |
|
||
| **UI** | The suggestion section on Pins, above the list; `useEnvStore.suggestions` keyed on its own `suggestionsFor`; the app's first `type="number"` in Settings. |
|
||
| **Docs** | UI-SPEC §4 (the section, and the Settings threshold), PRD P1-2 marked shipped. |
|
||
|
||
**The one thing only a real environment could say: 94 suggestions.**
|
||
|
||
Against `C:\Python314` — 352 packages, the scale fixture — the default threshold of 5 qualifies
|
||
**94 packages**, a quarter of the environment. The top of the list is right (`setuptools` at 150
|
||
dependents, then `zope` at 93, `zope-interface` at 86) but a "Worth pinning" section with 94 rows
|
||
is not a suggestion, it is a second package list.
|
||
|
||
Raising the default was the wrong fix: a deep dependency tree is exactly where a bulk update is
|
||
most dangerous, so it is exactly where the feature has to work. The screen shows the top
|
||
`SUGGESTIONS_SHOWN = 8` and says how many more qualify — the `RUFF_ROWS_SHOWN` pattern, and for
|
||
the same reason: the count comes from the **full** list, so a capped view never misreports a total.
|
||
`pins::suggest` still returns everything at or above the threshold, which is what makes it
|
||
composable.
|
||
|
||
Measured while there, in `--release`: the probe is **605 ms** and the graph build plus the whole
|
||
suggest pass is **1 ms**. The plan's worry that `dependent_count` looping over 350 packages would
|
||
be O(n·m) enough to matter was unfounded — the subprocess dominates completely, and there is no
|
||
case for a batched counts method.
|
||
|
||
**Three things the plan had wrong, all found by doing it.**
|
||
|
||
1. **A six-place checklist, not five.** `crates/pipdock-cli/tests/golden.rs` keeps its *own* copy of
|
||
`SCHEMA_TYPES`, and `schema_lists_exactly_the_documented_types` reads the real list back out of
|
||
the binary to compare — so the copy cannot silently fall behind. It failed exactly as designed
|
||
and is now in the checklist below.
|
||
2. **The `/hold/i` trap.** `PdPins.test.tsx` asserts `queryByText(/hold/i)` is absent, to prove the
|
||
screen offers no way to create a `Hold` pin — and **"threshold" matches that pattern.** Any
|
||
copy on this screen containing the substring "hold" breaks a test whose subject is something
|
||
else entirely. The Settings label is worded "Suggest pinning at" for that reason.
|
||
3. **`ReverseDeps::build`'s doc contradicted `dependent_count`.** It said the guard ignores
|
||
extra-gated edges "while pin auto-suggest may still count them" — describing an intent nothing
|
||
implemented, since `dependent_count` delegates to `dependents_of` and always filtered. Settled
|
||
in favour of what shipped, and the comment now says why: two features disagreeing about one
|
||
edge rule is exactly the failure that argues for computing this in Rust rather than looping over
|
||
`requiresDist` in the frontend, which already holds it.
|
||
|
||
**Exit criteria, driven in the browser against a stubbed bridge.** The section renders with
|
||
UI-SPEC §4's sentence and pluralises at 1 and at 12 in both locales; accepting moves the package
|
||
into the pin list with `12 packages depended on it` already in its reason field, and it does not
|
||
reappear; `pin_suggestions` crosses the bridge **once** per visit, not twice. The threshold field
|
||
refuses `abc`, `-1` and `9999` without a write and accepts `3` with exactly one.
|
||
|
||
Two mutation checks rather than trusting green: swapping `build_for` for `build` fails the marker
|
||
case, and `>=` for `>` fails the inclusive-threshold case.
|
||
|
||
**Known rough edge, deliberately not fixed:** nothing records a *rejected* suggestion, so unpinning
|
||
a package re-offers it. A dismissal needs persistence, and both the suggestion and the pin are on
|
||
the same screen, so it is visible rather than mysterious.
|
||
|
||
**Deliberately not done:** no `pipdock pin suggest`. `pins::suggest` is in core so the subcommand
|
||
is trivial later, but adding one now means a new help golden plus a churned `golden__help-pin.snap`
|
||
for an advisory feature nothing scripts against yet.
|
||
|
||
---
|
||
|
||
##### The original estimate, kept for comparison
|
||
|
||
**Most of this was built in M2 and never called.** `graph::dependent_count(&pkg) -> usize`
|
||
(`graph/mod.rs:242`) exists, is documented *"for pin auto-suggest (PRD P1-2)"*, and has no caller
|
||
outside its own test. So does `graph::PIN_SUGGEST_THRESHOLD = 5` (`:29`), documented *"default …
|
||
Configurable"* and read by nothing. The graph module's own doc names auto-suggest as one of its
|
||
three intended consumers.
|
||
|
||
| Step | |
|
||
|---|---|
|
||
| 1 | `settings.rs` gains `pin_suggest_threshold: usize`. Five places: the `KEY_*` const, the struct field, `load`, `save`, and a test. `Settings` is **not** in `SCHEMA_TYPES` — its TS mirror at `ui/src/ipc/index.ts:160` is hand-written, so no bindings regeneration. Then `useSettingsStore`, `PdSettings.tsx`, and both catalogues. |
|
||
| 2 | New command `pin_suggestions(envHash) -> Vec<PinSuggestion>` where `PinSuggestion { pkg, dependents }`. Probes once, `ReverseDeps::build_for(&dists, python_version)`, filters `dependent_count >= threshold`, drops already-pinned. Follow the ten-step IPC checklist below. |
|
||
| 3 | A suggestion section on `PdPins`: UI-SPEC §4 specifies the copy shape — *"`urllib3` — 12 packages depend on it. Pin?"* — so it is `t()` with an interpolated name and a plural count. Accepting writes `{ pkg, mode: 'exclude' }` through the existing `togglePin`. |
|
||
|
||
**Do not compute this in JavaScript**, even though the frontend already holds `dists` with
|
||
`requiresDist` from `pkg_list`. The counts depend on PEP 508 marker evaluation and extra-gated edge
|
||
exclusion, both of which live in `graph/markers.rs` and `Requirement::applies_in`. A JS
|
||
reimplementation would drift from the guard that uses the same edges — and the guard is the one
|
||
that stops people breaking their environments.
|
||
|
||
**Do not touch `pins::hold_requirements`.** It is dead, it is on the M3 debt list, and it concerns
|
||
`Hold` pins. Auto-suggest creates `Exclude` pins, which `togglePin` already writes.
|
||
|
||
Cost: one probe per invocation, on a screen the user opened deliberately. `dependent_count` is
|
||
`dependents_of().len()`, so a loop over 350 packages is O(n·m) — measure it before adding a batched
|
||
method that may not be needed.
|
||
|
||
---
|
||
|
||
#### P1-B · Requirements / constraints export–import — PRD P1-3 — **done 2026-08-14**
|
||
|
||
**A snapshot's freeze document already *is* a `requirements.txt`** — verbatim `pip freeze --all` /
|
||
`uv pip freeze` from `Engine::freeze` (`engine/mod.rs:245`). Export is therefore mostly file I/O,
|
||
and `health_save_report` (`commands.rs:1065`) is the shape to copy: the webview gets a path from
|
||
the picker and **Rust does the write**, because `default.json` grants `dialog:allow-open` and
|
||
`dialog:allow-save` and deliberately no `fs` permission at all.
|
||
|
||
*Export* is the easy half:
|
||
|
||
- `env_export(env, path, kind: Requirements | Constraints)`. Constraints is the same body — the
|
||
difference is how the file is used, not what it contains.
|
||
- `snapshot::unrestorable_lines` (`:183`) already names what a freeze cannot express: editable
|
||
installs, direct URLs, VCS requirements. Report them the way the rollback preview does rather
|
||
than writing a file that silently loses them.
|
||
|
||
*Import* is where the work is, and it is **parsing**:
|
||
|
||
- `snapshot::parse_freeze` (`:144`) handles exactly `name==version` and nothing else, by design —
|
||
`pin_of` (`:165`) is deliberately narrow because it feeds rollback. **Do not widen it**; its
|
||
narrowness is what makes it the exact complement of `unrestorable_lines`, an invariant TESTING §2
|
||
calls out.
|
||
- A real requirements file has `-r`/`-c` includes, `--hash`, extras (`pkg[extra]`), environment
|
||
markers, and comments after the spec. `graph::Requirement::parse` (`graph/mod.rs:71`) already
|
||
parses `name[extras] (spec); marker` and is exercised against real metadata — it is the closest
|
||
thing to a PEP 508 line parser in the tree and the right starting point.
|
||
- Decide up front what an unsupported line does. Refusing the file is defensible; silently skipping
|
||
`-r requirements-dev.txt` is not.
|
||
|
||
Once parsed, **the install flow already exists**: `Intent::Install { specs }` (`flow/mod.rs:59`),
|
||
which `PdSearch` already drives at `:224`. An import can also fill the dock bay through
|
||
`useIndexStore.enqueue`, giving the user the existing preview → snapshot → execute path for free.
|
||
|
||
Missing plumbing: a file-*open* wrapper. `pickProjectFolder` passes `directory: true`; an import
|
||
needs `open({ directory: false, filters: [...] })`. The `dialog:allow-open` permission already
|
||
covers it.
|
||
|
||
---
|
||
|
||
#### P1-C · Cache manager — PRD P1-4 — **done 2026-08-14**
|
||
|
||
**Scope it honestly first: there are no log files.** `LOG_RETENTION_DAYS` (`lib.rs:70`) has no
|
||
reader anywhere. The only "log" that exists is the in-memory ring buffer at `state.rs:373`, and
|
||
`logs_tail` is one of the two `NOT_YET` commands. `actions.openLogs` is an orphan string in both
|
||
catalogues. So this covers **three** artefacts, not four:
|
||
|
||
| Artefact | Path | Deletable? |
|
||
|---|---|---|
|
||
| Package index + settings + pins | `data\index.db` | **No** — it holds settings and pins too. Offer *refresh*, not *delete*. |
|
||
| Snapshots | `data\snapshots\<env_hash>\` | Yes, per environment or per snapshot |
|
||
| Tools venv | `data\tools\.venv\` | Yes — `tools sync` rebuilds it |
|
||
|
||
**This introduces the first delete-a-tree primitive in production code.** Today the only deletion
|
||
anywhere outside test scaffolding is one `remove_file` in `snapshot::create`'s failure path. That
|
||
makes the safety design the actual work, not the UI:
|
||
|
||
- Every path must be **asserted to be under `app_data`** before removal — canonicalised, not string-prefixed.
|
||
- Deleting `index.db` must be refused outright, or it takes settings and pins with it.
|
||
- SECURITY §8 and `legal/PRIVACY-POLICY.md` §2 both describe deleting `data\` as the complete
|
||
reset, and both now spell out that deleting the *parent* uninstalls the program. If this feature
|
||
offers a "reset everything" button, those two documents are part of the change — and a `legal/`
|
||
edit bumps `PIPDOCK_LEGAL_DOCS_HASH` and re-shows the gate.
|
||
|
||
The easy parts: a recursive size walker (none exists — `probe.py`'s `_size_bytes` is per-package),
|
||
and `formatBytes` in `ui/src/screens/rows.ts:126`, which is already the binary-units formatter
|
||
I18N §2 requires. `pipdock tools status` (`run.rs:1174`) already reports the tools venv's path and
|
||
sync state and would gain sizes for free.
|
||
|
||
---
|
||
|
||
#### P1-D · Command palette, `Ctrl+K` — PRD P1-5, UI-SPEC §1 — **done 2026-08-14**
|
||
|
||
Frontend only. No new IPC command, no new Rust, no capability change — **every dispatch target
|
||
already exists** as a store action.
|
||
|
||
`Ctrl+K` collides with nothing. Verified against all ten existing bindings, including
|
||
`Ctrl+Alt+P`'s separate listener in `i18n.ts:93`. Today it is a silent no-op:
|
||
`App.tsx:114` does `Number.parseInt(e.key, 10) - 1`, so `'k'` becomes `NaN` and `NAV_KEYS[NaN]` is
|
||
`undefined`. The branch goes **before** line 113's `if (!e.ctrlKey …) return`.
|
||
|
||
**Write a matcher; do not route palette queries through `index_search`.** `nucleo` is a
|
||
`pipdock-core` dependency and there is no JS fuzzy library. `PdSearch` does zero matching in JS —
|
||
every keystroke is an IPC call into an index of 864,000 *PyPI package names*, which is the wrong
|
||
corpus and the wrong cost for a 30-item action list. `index/mod.rs:78`'s `is_subsequence` is the
|
||
algorithm to copy, and the tiering rationale at `:181` is worth reading first: nucleo ranks
|
||
`requests-ntlm` above `requests`, which is why that module tiers rather than sorting by score.
|
||
|
||
**Two rules the palette must honour or it reintroduces solved bugs:**
|
||
|
||
1. **Refuse while a plan owns the screen.** `App.tsx:101` bails on `guardOpen || PANEL_PHASES.has(planPhase)`, and `PdSidebar` disables every tab for the same reason. A palette that can navigate during an execution is the same defect through a different door — and the Phase 4 record is explicit that guarding on one of those two conditions guards neither.
|
||
2. **Refuse while the legal gate is up**, including the About tab's review mode (`App.tsx:91`).
|
||
|
||
`PdDialog` is the wrong base — it hardcodes a Cancel-first button row and a heading — but its
|
||
`showModal()` pattern (`PdDialog.tsx:51`) is the focus trap to lift, and the `if (!el.open)` guard
|
||
there is there because StrictMode double-invokes the effect. The legal gate is **not** a model for
|
||
this: it does not trap focus, and gets away with it only by replacing the entire shell.
|
||
|
||
Setting `nav` from the palette gets `<h1>` focus for free — `App.tsx:78` moves focus on every nav
|
||
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. 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
|
||
catalog codes. **Never hold the store guard across an `await`.**
|
||
3. `src-tauri/src/lib.rs` — `generate_handler![…]`.
|
||
4. `ui/src/ipc/index.ts` — the name in `COMMANDS` **and** a hand-written typed wrapper. A generated
|
||
type also needs adding to the `import type { … } from './generated'` list; `export type *` does
|
||
not bring it into scope for the wrapper's own signature.
|
||
5. New wire type → `serde` + `schemars::JsonSchema` + `rename_all = "camelCase"`, register in
|
||
**both** `schema_for!` and `SCHEMA_TYPES`, `cargo run -p xtask -- bindings`, and bless a new
|
||
`golden__schema-<T>.snap` plus every schema that embeds it.
|
||
**And `crates/pipdock-cli/tests/golden.rs`'s own copy of `SCHEMA_TYPES`** — a deliberate second
|
||
list, guarded by `schema_lists_exactly_the_documented_types`, which reads the real one back out
|
||
of the binary. Blessing `golden__schema-unknown-type.snap` is expected here: its error message
|
||
enumerates every known type, so one more schema is a real behaviour change.
|
||
6. New error code → nine places; CLAUDE.md enumerates them.
|
||
7. New event channel → `EVENTS` plus a `listen<T>` wrapper.
|
||
8. `ui/src/test/ipc.ts` — the mock.
|
||
9. Locale keys in **both** catalogues; `i18n.test.ts` fails on either direction.
|
||
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 |
|
||
| X36-b | `src-tauri/src/commands.rs` — every command taking a `PyEnv` (`pkg_list`, `pip_upgrade`, `deps_graph`, `plan_resolve`, `health_run`, `audit_run`, `engine_info`…) and `env_probe` | The interpreter a `PyEnv` names is run as the webview hands it back, and `env_probe` validates only a path the webview calls `manual` | Found by 1.6.0's independent review; predates it. The paths come from `env_scan`, which checks added entries itself, so this is defence in depth against a compromised webview — a `validate_interpreter` per command, its own change |
|
||
| — | `exec.rs:633` `canonical_interpreter` | An interpreter on a share hashes as `unc\server\share\…`: the verbatim prefix `\\?\` is stripped, `\\?\UNC\` is not | Correcting it changes the identity — and orphans the pins and snapshots — of every interpreter on a share |
|
||
| — | `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~~, ~~U47~~, ~~U48~~ | — | Closed by 1.5.0, the accessibility pass (below) | — |
|
||
| A1 | `PdPackageTable.tsx`, `PdPackageRow.tsx` | The package grid is one tab stop per row with no `↑`/`↓` between rows, so passing 200 rows is 200 Tabs | Changes the tab model the owner had just tested by hand on 1.4.0; wants a decision and a Narrator pass of its own, and a virtualizer that scrolls ahead of focus |
|
||
| A2 | `PdPackages.tsx:197`, `PdEnvironments.tsx:222`, `PdUninstallDialog.tsx:130`, `PdSummarySheet.tsx:83` | A live region that mounts together with its text may never be announced | Only a screen reader can answer it; Search's region was rebuilt in 1.5.0 because its fix did not depend on the answer |
|
||
| A3 | `PdErrorRow.tsx:68`; `PdStatusLine.tsx:41` with `PdEnvironments.tsx:223` | Every error row is `role="alert"`, so a failed batch may fire one assertive alert per package; "scanning" is announced by two regions | Same: needs Narrator, and a decision about which region owns it |
|
||
| A4 | `PdConflictRow.tsx`, `PdDockBay.tsx` | Why a control is disabled is only in a `title`, which a disabled control cannot be focused to show | Wants visible text beside the control, in both catalogues |
|
||
| A5 | `packageColumns.ts`, `PdSidebar.tsx`, `tauri.conf.json` | No in-app zoom: at 200 % in the default window the name column (`min-w-0 flex-1`) collapses to zero and the sidebar cuts off its last tabs | With U51 — a minimum for the name column, an overflow for the sidebar, then `zoomHotkeysEnabled` |
|
||
| A6 | `PdDialog.tsx`, `PdUninstallDialog.tsx`, `PdCacheUsage.tsx`, `PdHealth.tsx` | A dialog's buttons still go `disabled` while its work runs, so focus drops inside the modal until it closes | The shell's lost-focus rule recovers it when the dialog closes; inside one, `aria-disabled` needs the dialog's own busy handling rethought |
|
||
| A7 | — | Narrator on 1.5.0, NVDA and JAWS at all, each Windows contrast theme by hand, the installers | The owner's hands; `ACCESSIBILITY.md` says none of it has been done and must be updated by whoever does it |
|
||
| 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, `cargo machete`, actionlint/zizmor, dependency review, typos and link checks | Each its own decision; none is free on a Windows runner. Coverage left this row on 2026-10-25 (below) |
|
||
| — | `pipdock-cli/src/run.rs` (4 %), `src-tauri/src/commands.rs` (0 %) | The two large coverage holes `sonar.yml` measured: the CLI driving a real interpreter, and the IPC surface. L2 exercises the first and only a running app the second, so neither is measured | Each needs a seam — an engine `run.rs` can be handed, a `tauri::test` harness — and is its own slice. The gate asks 80 % of *new* lines, so neither blocks anything until it is touched |
|
||
| — | `screenshot/` | The eight screenshots predate About and 1.4.0's window | Retake with a release, by hand |
|
||
|
||
## After 1.4.0 — SonarQube Cloud from CI — **2026-10-25**
|
||
|
||
No version. The owner switched automatic analysis off, set `SONAR_TOKEN`, and asked for CI-based
|
||
analysis on the newest scanner, with Dependabot, the audits and the code scanners brought up to
|
||
date on the way.
|
||
|
||
**Where it started.** Automatic analysis had measured 11 602 lines — CSS, JS, Python, TypeScript,
|
||
YAML — and **not one of Rust**: it cannot build, so two thirds of the code had never been analysed
|
||
and no coverage could be imported. It had also never sent a project version, so the *previous
|
||
version* new-code period was still the first analysis (2026-09-27) and grew with every merge.
|
||
Separately, `Security scan` had been red on `main` every day since 2026-10-21 — rustls-webpki
|
||
(RUSTSEC-2026-0382), webpki-root-certs (-0383), a yanked clipboard-win, and zod
|
||
(GHSA-mrhx-c7xc-m3w5, through eslint-plugin-react-hooks) — and since `cargo audit` and `npm audit`
|
||
are required, every PR would have been red as well. Dependabot opened a PR for none of the four.
|
||
|
||
| What | Now |
|
||
|---|---|
|
||
| Analysis | `sonar.yml`: one Windows job — vitest and `cargo llvm-cov` LCOV, clippy's JSON, `sonarqube-scan-action` v8.3.0 pinned by commit, `sonar.qualitygate.wait` so a red gate on `main` reaches Discord |
|
||
| Scope | `sonar-project.properties`: everything tracked, tests split out, fixtures and binaries excluded, coverage excluded only where no test here can execute the code, with the reason beside each |
|
||
| New code | `sonar.projectVersion` from `package.json`, which the previous-version period keys on — one analysis late (below) |
|
||
| The token | In the scanner step's environment alone; a job with no token (Dependabot, forks) is skipped, not failed |
|
||
| Audits | The four bumps above, and nothing ignored |
|
||
| Dependabot | A `vitest` group, because `@vitest/coverage-v8` peers vitest exactly; the `rfd` and `typescript` ignores re-checked and both still needed |
|
||
|
||
**What running found that reading did not:**
|
||
|
||
- **Coverage, measured for the first time:** Rust 71.6 % of 15 364 lines, TypeScript 68.4 % of
|
||
1 569; SonarQube Cloud's combined figure is **71.3 % of 16 327**. TESTING §3 had promised
|
||
thresholds since the first draft that nothing had measured. The two big holes are a backlog row.
|
||
- **The plan analyses `main` and pull requests, and nothing else.** A dispatch on the branch, to see
|
||
every Rust finding before merging, uploaded its report and then failed the gate check with
|
||
"Organization is not allowed to access data from non main branches". A PR analysis reports only
|
||
the lines it changes, so the full Rust picture exists only once `main` is analysed; the dispatch
|
||
is now refused off `main`.
|
||
- **Every tracked image and font was read as UTF-8 text** by the secrets sensor, one warning each,
|
||
once `sonar.sources=.` replaced automatic analysis's own scoping.
|
||
- **The scanner's signature check works on a Windows runner.** v8 verifies the CLI's OpenPGP
|
||
signature by default, and Git for Windows' `gpg.exe` does it; no `skipSignatureVerification`.
|
||
- **The first analysis of `main` failed its gate**, on the two things automatic analysis could
|
||
never have seen. **Sixteen Rust findings**, every one a bug by Sonar's classification: three
|
||
`rust:S6677` — `message = %e.message` beside a format string records two fields called
|
||
`message`, and the log line read `failed code=PD-ENV-001 no interpreter at …` with the error's
|
||
words indistinguishable from the event's (now `error = …`, as every other failure logs it, and
|
||
`golden.rs` reads the CLI's log to hold it) — and thirteen `rust:S7493`, `std::fs` inside an
|
||
`async fn`: the tools-venv sync, Code Health's deptry report, and the four commands that write or
|
||
read a file the user chose, on what may be a network drive. They go through `tokio::fs` now.
|
||
And **new-code coverage 78.3 %** against 80 %.
|
||
- **Sending a version moves the baseline one analysis late.** The analysis that first sent
|
||
`1.4.0` still measured new code from 2026-09-27, so "new" was all of 1.4.0's audit — 4 037
|
||
lines, 849 of them uncovered; the one after it measured from the last analysis of the version
|
||
before (2026-10-20). Waiting a merge would have turned the gate green by itself, and that was
|
||
not the answer: the lines were untested either way, and a release bump will gate the next
|
||
merge on its whole period exactly like this. The answer was tests: the restore half of `execute_rollback`, a
|
||
force the environment's Python cannot run, PEP 691 parsing (split out of `index::refresh`, with
|
||
L55's empty list finally under test), `user_file_error` (U25), a plan verified against another
|
||
environment, the cached half of `release::PyPiReleases`, and the store paths no test had driven
|
||
— a resolve that succeeds, a round of decisions, a rollback preview, and late answers on the
|
||
error paths. `InstallSet::only` had no caller and went. Estimated against Sonar's own per-line
|
||
data before pushing, by a script that reproduced its 78.28 % exactly: 81.2 %. Measured on
|
||
`main` after #91: **81.2 %, gate passed, 0 open issues, every rating A**, overall 72.3 %.
|
||
- **Cost:** eight to eleven minutes on a Windows runner beside the required checks, three of them restoring
|
||
ci-rust.yml's cache read-only. Saving a cache of its own was rejected: the repository is at 8.6 of
|
||
its 10 GB, and a fourth Windows cargo cache would evict the ones the required checks restore.
|
||
|
||
## After 1.4.0 — dependencies to latest, and pip 26.3 — **2026-11-04**
|
||
|
||
No version. The owner asked for every dependency, action and toolchain brought to its newest
|
||
release, code fixed where that needed it, and a version only if one was needed. One PR superseded
|
||
the five open Dependabot PRs (#97–#101).
|
||
|
||
**Where it started.** `cargo audit --deny warnings` had been red since 2026-11-03 on the daily scan
|
||
and on all five bot PRs: `async-executor 1.14.0` was yanked. It is Linux-only (zbus), so no shipped
|
||
binary ever carried it — the same shape as 2026-10-20's informational advisories, every gate red
|
||
for something the product never contained.
|
||
|
||
| What | Now |
|
||
|---|---|
|
||
| Cargo | `cargo update` (~60 bumps, 627 crates → 616); rusqlite 0.41.1 (SQLite 3.54.1), no code change; rfd 0.17 **with** tauri-plugin-dialog 2.8.4, which moved to rfd ^0.17 — the condition the `rfd` ignore was waiting for, so it went |
|
||
| npm | Thirteen packages to latest; TypeScript still held at 6.0.3, typescript-eslint 8.72.1 still peering `<6.1.0` |
|
||
| Tools | ruff 0.17.3 and three transitive pins, regenerated by the header's own command |
|
||
| Actions / Node | taiki-e/install-action v2.87.32, sonarqube-scan-action v8.4.0; Node 24 → 26, Active LTS since 2026-10-28 |
|
||
| "Latest" | The newest release **past each ecosystem's cooldown**, not the newest published: v2.87.33+, v8.4.1, filelock 4.2.5+ and platformdirs 4.13.7+ were days old and wait for Dependabot |
|
||
|
||
**What running found that reading did not:**
|
||
|
||
- **pip 26.3 had re-rendered a build failure, and the classifier read it as the wrong code.**
|
||
Found by dispatching the drift job on the branch, two days after pip 26.3 and five before the
|
||
Monday run would have. An unloadable build backend was a `BackendUnavailable` traceback (exit 2);
|
||
26.3 prints `error: backend-unavailable` and ends with `Failed to build '<name>' when calling
|
||
build backend hook …` (exit 1). The traceback was the only needle PD-BLD-002 had for it, so the
|
||
failure fell through to `failed to build` — PD-BLD-003. Both codes give the same advice, so the
|
||
cost to a user was the headline sentence, not the remedy; that, and no advisory reaching the
|
||
shipped binary, is why this is not 1.4.1. *Upgrade pip* installs 26.3, so every user who presses
|
||
it would have met it. The 26.2.1 capture is frozen as `pip-26.2/` — only that scenario moved —
|
||
and a test holds the two renderings to one code; it failed against the old classifier first.
|
||
- **A dependency ignore has an exit condition, and somebody has to notice it was met.**
|
||
tauri-plugin-dialog 2.8.4 moved to rfd 0.17 the same week; Dependabot's #100 took the plugin and
|
||
would have put a second rfd in the binary, because the ignore still blocked the matching bump.
|
||
- **`npm audit` now lists a moderate advisory it cannot fix**: minimatch GHSA-g3hv-75wg-m249,
|
||
patched only in 11.x, which ESLint 10.14 and typescript-eslint 8.72 do not accept. Dev-only, the
|
||
gate is `high`, and ARCHITECTURE §10 says why it is tolerated rather than forced by `overrides`.
|
||
|
||
## 1.5.0 — the accessibility pass — **2026-11-10**
|
||
|
||
One slice: audit backlog U45, U47 and U48, taken as "an accessibility pass of its own", plus the
|
||
statement that says what the pass did and did not establish. It began from GitHub's community
|
||
profile — five things missing, `ACCESSIBILITY.md` among them — and from the owner's report that
|
||
1.4.0 had been driven end to end with the mouse unplugged and with Narrator, and nothing blocked.
|
||
Both were true. The code agreed with the owner: nothing was unreachable. What a survey of the code
|
||
found was eleven places where it worked and made a user work for it.
|
||
|
||
**What shipped** (the changelog has it by reader): focus on every screen replacement, not only on a
|
||
tab change; the tabs, radio group and listbox patterns finished; names that contain the visible
|
||
text; a well-formed grid; a status region for Search; `data-destructive` in place of a hand-kept
|
||
list; axe-core over every screen; `ACCESSIBILITY.md`, `CONTRIBUTING.md`, a code of conduct, a pull
|
||
request template and an accessibility issue form; and About's Accessibility section.
|
||
|
||
| Decision | Why |
|
||
|---|---|
|
||
| axe-core called directly, no `eslint-plugin-jsx-a11y` | The plugin peers ESLint 9 at most and this repository is on 10 — the same wall `react/jsx-no-literals` hit. The matcher packages wrap axe and pin a runner's major. axe-core has no dependencies |
|
||
| The radio group's arrows move focus and choose nothing | The pattern says arrows check what they land on; here that would open *Force latest*'s destructive confirm from an arrow key |
|
||
| `data-destructive`, and a test that reads the source | Forced-colors cannot be rendered under jsdom, and the stylesheet's list of five `data-action` names had been wrong for as long as it existed |
|
||
| WCAG 2.2 AA as a *target* | Nobody independent has audited it, Narrator was not re-run on 1.5.0, and a statement that claims more than its last test is the thing it exists to prevent |
|
||
| An answer in 7 days and no fix date | One maintainer. The toolkit's template promises 30/60/90 days; a date that slips is worse than none |
|
||
| Zoom built, measured, and taken out | Below |
|
||
| `legal/` untouched | The five hashed documents did not need to change, so the gate does not re-show. A dev-only dependency is not a third-party notice |
|
||
|
||
**What running found that reading did not** — the installed bundle, WebView2's remote-debugging
|
||
port (`WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=…`, which a release build
|
||
honours), real key presses through `Input.dispatchKeyEvent`, and `document.activeElement` and the
|
||
accessibility tree read back after each one. Every item below was in code whose tests were green:
|
||
|
||
- **The high-contrast border on destructive buttons had never been drawn — not for the five the old
|
||
list named either.** The rule was in `@layer base`; every button carries Tailwind's `border`
|
||
utility; a later layer wins whatever the selectors say. UI-SPEC §7 described that border for two
|
||
milestones, and U45 was filed as "the list is incomplete" when the list did nothing at all. Seen
|
||
by emulating `forced-colors: active` and enlarging a screenshot of *Cancel* beside *Allow*: the
|
||
same border. The rule is unlayered now, a test counts the braces, and it is a double border
|
||
because 2 px beside 1 px is not a difference anyone sees.
|
||
- **A button that disables itself when pressed drops focus to `<body>`.** A browser takes focus
|
||
from a control that becomes `disabled`; jsdom does not, so no test could fail. Found by pressing
|
||
*Download the index*. Nine buttons were doing it — *Use*, *Rescan*, *Run*, *Run audit*, *Add*,
|
||
*Stop* among them — which is to say most of the app's primary actions lost a keyboard user's
|
||
place on the keypress that started the work. Busy is `aria-disabled` now; `disabled` is for
|
||
unavailable.
|
||
- **Accepting the legal gate left focus on nothing.** The fix for "focus is lost when the screen is
|
||
replaced" had been written and tested an hour earlier and did not cover it, because the gate is
|
||
rendered *instead of* the shell: a fifth way to replace the screen, and the first thing a new
|
||
user does.
|
||
- **A dialog's name read "Remove packages : certifi".** A browser puts a space before
|
||
visually-hidden text; jsdom's name computation does not.
|
||
- **The Updates tab's name read "Updates(5)"** — inline spans are joined without a space.
|
||
- **Zoom broke the table.** `zoomHotkeysEnabled` is one line and needs no permission on Windows.
|
||
At 200 % in the default 1180 px window — a 590 px viewport, emulated with a device-metrics
|
||
override — the name column collapsed to zero width and the sidebar cut off *Settings* and
|
||
*About*. It holds at a maximised 1920 px window, which is the layout's own 900 px floor. Taken
|
||
out; backlog A5.
|
||
|
||
And one thing running confirmed rather than found. The survey suspected a package row's focus ring
|
||
was clipped, and it was — on three sides, in normal mode, fixed here. The forced-colors block had
|
||
carried that exact fix since M2, with a comment saying why: the knowledge was in the stylesheet,
|
||
scoped to the one mode someone had looked at.
|
||
|
||
**And what a second reader found**, in the diff, after the smoke had passed — an independent review
|
||
run while CI was going:
|
||
|
||
- **`sr-only` text needs a positioned parent.** It is `position: absolute`; with no positioned
|
||
ancestor it is laid out against the viewport and escapes every scroller above it. A pin chip's
|
||
new hidden sentence did exactly that on Pins, where nothing between the chip and `<html>` is
|
||
positioned: a long list made the whole window scroll and took the header with it. Package rows
|
||
hid it, because a row is `absolute`. Every parent of hidden text is `relative` now.
|
||
- **An error-only summary had no `<h1>`**, so the new focus rule had nothing to land on — on the
|
||
one screen where a run had just failed.
|
||
- **A drawer that mounts already open has no opener.** `consoleOpen` outlives a run; closing the
|
||
drawer in the next one dropped focus as it had before the fix. It falls back to the *Console*
|
||
button.
|
||
- Under forced-colors, the selection outline followed the focus ring at equal specificity, so a
|
||
focused current tab got a 1 px line in place of its 2 px ring.
|
||
|
||
**What it did not establish.** The assistant cannot run a screen reader. Everything above about
|
||
what assistive technology receives is the accessibility tree, which is what is *exposed*, not what
|
||
is *said*. Narrator on 1.5.0, NVDA, JAWS and each contrast theme by hand are backlog A7 and are
|
||
listed as untested in `ACCESSIBILITY.md`. ROADMAP's own count of live regions — "eight now", Phase
|
||
3 · P6 — was ten when this slice counted them, plus two `role="status"`.
|
||
|
||
**Dependencies, the same day, no version of their own** (#106, superseding #103–#105): the npm,
|
||
actions and tools bumps that were past their cooldown, with `tools-constraints.txt` regenerated by
|
||
the header's command rather than edited (the result was byte-identical to Dependabot's edit, which
|
||
is the check the edit had lacked) and the drift job dispatched on the branch first. Held back and
|
||
said so in the PR: i18next 27 with react-i18next 18, and jsdom 31 — majors inside the 14-day
|
||
window, the first with new defaults and stricter `t()` types that want a session of their own —
|
||
and rfd 0.18, which tauri-plugin-dialog 2.8.4 still pins below.
|
||
|
||
## After 1.5.0 — the move to poli0981org — **2026-11-21**
|
||
|
||
No version of its own; it ships inside 1.6.0. The owner moved the repository from `poli0981/pipdock`
|
||
to the **poli0981org** organization, to keep the projects maintained seriously apart from the ones
|
||
made for fun, and asked for everything that move touches: the alerts and the open Dependabot PRs,
|
||
Qodana on the owner's Ultimate plan, a licence check for the dependencies, CI that lives in the
|
||
repository ("mono repo"), and proof that the repository works in its new home. One PR,
|
||
[#119](https://github.com/poli0981org/pipdock/pull/119), superseding #113–#118.
|
||
|
||
**Where it started.** `main` had been red every day since 2026-11-18, and so had `cargo audit` on
|
||
all four of the week's Dependabot PRs: **RUSTSEC-2026-0543, chrono unmaintained** — in `Cargo.lock`,
|
||
and compiled into nothing.
|
||
|
||
| What | Now |
|
||
|---|---|
|
||
| chrono | Listed only because serde_with 3.24's `std` feature carries the weak features `chrono_0_4?/clock` and `chrono_0_4?/std`, which Cargo's lock resolution records even when nothing enables them; `cargo tree -i chrono --target all` prints nothing. Ignored in `.cargo/audit.toml` with that reason and its exit condition |
|
||
| Dependencies | #113–#118 cherry-picked (Rust 1.100.0, rusqlite 0.42.0, Tauri 2.12.6 with its npm half, the code-health pins, three actions, eleven npm packages) plus jsdom 31.0.1. No new clippy lint fired; neither rusqlite nor jsdom needed a code change; `tools-constraints.txt` regenerated by its header's command came out byte-identical to Dependabot's edit; the drift job, dispatched on the branch, found no engine output moved |
|
||
| minimatch | GHSA-g3hv-75wg-m249, tolerated since 2026-11-04, is gone: ESLint 10.15 and typescript-eslint 8.73 moved to minimatch 11 (11.0.9 throughout) |
|
||
| rfd 0.18 (#112) | Not taken. tauri-plugin-dialog 2.8.4 is still the newest and still requires `^0.17`; the ignore is back, with its exit condition |
|
||
| CI | Every workflow is local and every action pinned by commit (RELEASE-CI §1). Branch protection's payload changed with it: the two names the ops repo owned are renamed, and `cargo deny`, `npm licences` and `tauri lockstep` are required — eight checks |
|
||
| Licences | `npm licences`: 18 production packages, all MIT, Apache-2.0 or both. Proved to fail on a lockfile with one licence changed to CC-BY-4.0 |
|
||
| Qodana | Two Qodana Cloud projects, two configs, two tokens; full scans; a Rust baseline; `--fail-threshold 0` |
|
||
| SonarQube Cloud | `poli0981org_pipdock`, empty until this branch's first analysis; the old project keeps the history to 1.5.0 |
|
||
|
||
**What running found that reading did not:**
|
||
|
||
- **Dependabot's groups had never worked as written.** It gives a dependency to the *most specific*
|
||
group, and counts one with `update-types` as more specific than one with patterns alone — its own
|
||
log: "Skipping tauri-plugin-dialog for group 'tauri' - belongs to more specific group
|
||
'cargo-minor-patch'". The `tauri` groups caught nothing, while `dependabot.yml` said their order
|
||
kept Tauri out of the catch-alls. `exclude-patterns` on each catch-all now does.
|
||
- **Qodana's first Rust result was 0 problems, from 0 files analysed** — the same shape as 1.4.0's
|
||
"a check that cannot run must not report a pass". The linter container runs as the runner's
|
||
user, so rustup could not install the toolchain `rust-toolchain.toml` pins (it writes under
|
||
`/usr/local/rustup`, root's), `cargo metadata` failed, and RustRover loaded no Cargo project and
|
||
inspected nothing. Fixing that exposed the second half: `CARGO_HOME` was root's too, and the
|
||
registry download failed with "Permission denied". The bootstrap now points the job's own checkout
|
||
at the image's toolchain (1.94.0), and `CARGO_HOME` lives in the action's cache mount. The third
|
||
run analysed the workspace and found 62.
|
||
- **Of the 62, two are Critical and both are RustRover misreading code rustc compiles**: "value
|
||
used after being moved" on a `std::io::ErrorKind`, which is `Copy` (`exec.rs`, a test), and
|
||
"takes 2 parameters, 1 supplied" on an `async_trait` method called through `Box<dyn Engine>`
|
||
(`commands.rs`). The other 60 are Moderate style: 49 unnecessary path qualifications, 10
|
||
duplicated fragments, 1 trait-member order in a test fake. All 62 are the baseline; anything
|
||
new fails the run. Qodana for JS found six and all were fixed: five `React.*` types reached
|
||
through the UMD global rather than imported, and one High, `step` "possibly null" in
|
||
`PdPlanPanel` — which TypeScript narrows through an aliased condition and an optional chain, and
|
||
WebStorm's engine through neither, so it took an explicit `step !== null`.
|
||
- **SonarQube Cloud's first gate on the branch failed on code it had never seen**: `npm ci` running
|
||
lifecycle scripts in the web and Qodana jobs (githubactions:S6505). It ran the same way inside the
|
||
ops repo's reusable, where nothing analysed it. The one package with an install script is
|
||
fsevents, macOS-only; every `npm ci` in the workflows passes `--ignore-scripts` now.
|
||
- **An attestation stays with the account that made it.** After the transfer, README's own command
|
||
— `gh attestation verify <file> --repo poli0981/pipdock` — answered 404 for 1.5.0, and so does
|
||
`--repo poli0981org/pipdock`: the attestations of 1.4.0 and 1.5.0 are reachable only through the
|
||
user account that owned the repository when they were made. `--owner poli0981 --signer-repo
|
||
poli0981/pipdock` verifies them, checked against the real 1.5.0 installer. A user following
|
||
README to the letter would have been told not to run a genuine build.
|
||
- **A flaky runner, recorded so it is not chased again.** One integration job failed before any
|
||
test: rustup on the Windows image reported "detected conflict: `bin\cargo-clippy.exe`" while
|
||
installing Rust 1.100.0's components. The same toolchain installed cleanly on every other Windows
|
||
job, and the same job passed on the branch's next run.
|
||
|
||
**Kept as it was, on purpose**: `package.json` at the repository root — its original reason (the
|
||
reusable's missing `working-directory`) is gone, but SonarQube Cloud, Qodana, the scripts and
|
||
Tauri's configuration all assume the root now. And `pr-mode` is off in `qodana.yml`, where the plan
|
||
had put it back on: a whole scan is two to three minutes a part, so analysing only a pull
|
||
request's files would save little and make a result depend on which files changed.
|
||
|
||
## 1.6.0 — *Add interpreter…* — **2026-11-21**
|
||
|
||
One slice: PRD P0-1's manual browse, the last command `NOT_YET` held, shipped as **Add
|
||
interpreter…** on Environments and `pipdock env add` / `env remove` in the CLI, over one new table.
|
||
With it the project moved to maintenance mode (the next section), and the org move above ships in
|
||
the same version. [#120](https://github.com/poli0981org/pipdock/pull/120).
|
||
|
||
**What shipped** (the changelog has it by reader):
|
||
|
||
| Piece | What |
|
||
|---|---|
|
||
| Core | `envs::validate_interpreter`, the one check a person's path passes: an existing file named like Python (`python3.14t.exe` included), leading to one, and not inside PipDock's own venvs — run and stored as given, made absolute. `envs::probe_listed` checks an added entry again before every listing probes it |
|
||
| Store | Schema v5, `manual_envs(env_hash, interpreter, added_at)` — apart from the CLI's `envs` recents, which has no source column. Adding again keeps an entry's place |
|
||
| Discovery | Added entries come after discovery's own and never shadow it. One whose file is gone is still listed, with `PD-ENV-001`, because that is the row a person needs in order to remove it |
|
||
| IPC | `env_add_manual`, `env_remove_manual`; `NOT_YET` is empty |
|
||
| GUI | *Add interpreter…* beside *Rescan*, as the empty state's one action and in `Ctrl+K`; *Remove from list* on added rows; a status line mounted before its words; focus to the heading when the focused row goes |
|
||
| CLI | `env add`, `env remove`; `env list` shows what was added; `--env`, `env use` and the stored default are validated |
|
||
| Maintenance | `triage.yml` over a tested `.github/scripts/triage.cjs`, the wording issue form, CONTRIBUTING's scope |
|
||
|
||
**What running found:**
|
||
|
||
- The first name rule refused the free-threaded `python3.14t.exe`, which the python.org installer
|
||
puts beside `python.exe` and the registry lists — found by running `env list` against the owner's
|
||
own Pythons, not by any test.
|
||
- `env remove <dir>` answered "not on the list" for a deleted venv — the one case it exists for —
|
||
because `interpreter_in` resolves only what is there. Found by its own test.
|
||
- Qodana for JS flagged a non-ASCII identifier in `triage.cjs`; renamed.
|
||
- Qodana for Rust failed one run in five on #120 — the last on a commit that changed only this
|
||
file — with "Unused crate: sha2", the crate `env_hash` is built on. Every run's sanity check finds
|
||
the Cargo project only partly loaded in its container, and the unused-crate inspection sometimes
|
||
draws its conclusion from that. A baseline entry would not have held, since its fingerprint
|
||
hashes neighbouring lines Dependabot rewrites, so the inspection is excluded in
|
||
`qodana-rust.yaml`, with the reason.
|
||
- The installed build — the release dry run's NSIS installer, a scratch `LOCALAPPDATA`, driven over
|
||
CDP: the legal gate once on a fresh profile; an interpreter added, rescanned, updated and rolled
|
||
back in a scratch venv named `myproj-env` outside the working directory; the entry kept across a
|
||
restart; the venv deleted and its `PD-ENV-001` row removed from the keyboard, focus to the
|
||
heading; `env list` and `env remove` agreeing with the screen. **Windows' own file picker was not
|
||
driven**: screen control was declined, and a release build's `__TAURI_INTERNALS__` cannot be
|
||
patched to stub it, so every add went through `envAddManual` with a path — the call the picker's
|
||
result makes.
|
||
- The review's fixes (below) were smoke-tested the same way on a second dry-run installer, against
|
||
a real `--symlinks` venv made from the registry's Python 3.14: added as itself, with its own
|
||
prefix and its own identity, listed beside its base, its own one package against the base's 64,
|
||
removed and not brought back by a scan; a deleted venv's broken row removed for good; and the
|
||
installed CLI's `env add`, `env list` and `env remove` agreeing.
|
||
|
||
**What an independent review found** once the suites and that smoke were green, reading the diff
|
||
cold and reproducing with a scratch `LOCALAPPDATA` and the debug CLI. Every fix has a test that was
|
||
seen to fail first:
|
||
|
||
| # | Severity | Found | Now |
|
||
|---|---|---|---|
|
||
| 1 | High | `validate_interpreter` returned the canonical path, and every caller ran and stored it. A `--symlinks` venv's `python.exe` is a link to its base, so `env use <venv>` stored `C:\Python315\python.exe` (reproduced) and `--env .venv update --all --yes` would have changed the system Python; the GUI merged the added venv into the registry row by `envHash` and selected that. The name check looked at the link while the target was stored, so a `python.exe` linking to `notepad.exe` stored `notepad.exe` | The path made absolute is run and stored, links left alone; canonicalizing only decides where a link leads and whether it is PipDock's own. The UI merges and removes by path. **Fixing it exposed the identity beneath**: `env_hash` followed the same link, so the venv, listed now beside its base, would have shared the base's pins, snapshots and cached graph, report and audit — a rollback of one offered the other's snapshots. `canonical_interpreter` resolves a venv's own interpreter (recognised by `pyvenv.cfg`) only up to its folder; no other path's identity changed, and a linked venv's earlier pins stay with the base they were filed under. Seen on this machine's real `--symlinks` venv |
|
||
| 2 | Medium | A Microsoft Store Python was refused: an app-execution alias reports `is_file()` and fails `canonicalize()` with os error 1920, so `--env` and `env use`, which worked in 1.5.0, would have exited 3 | Judged by its own path when it cannot be resolved, as `canonical_interpreter` always fell back |
|
||
| 3 | Medium | Not an enforcement point over IPC, while SECURITY §2 and `env_probe`'s doc said it was: `env_probe` checks only a path the webview calls `manual`, and every `PyEnv` command runs `env.interpreter` unchecked. Stored entries, and the CLI's default from 1.5.0, were probed unchecked too | Both sentences corrected. Added entries are checked again on every listing (`probe_listed`, both heads), the stored default when it is used. The IPC exposure predates 1.6.0: backlog X36-b |
|
||
| 4 | Low–Medium | *Remove from list* announced success while the entry stayed, for an entry on a share whose file was gone: the row's `envHash` was recomputed from the stored text, while the identity it was added under had been hashed from `UNC\server\share\…` | Removed by the path the row shows; the store matches either |
|
||
| 5 | Low–Medium | Re-adding a venv deleted and made again kept the broken row and selected it — a row with no `env`, which nothing loads packages for | The fresh row replaces it and is selected |
|
||
| 6 | Low | Removing during a scan: the scan had read the list first, so its result brought the row back while the status line said it was gone | Each waits for the other; *Remove from list* is busy while a scan runs |
|
||
| 7 | Low | `env remove .venv` never matched what `env add .venv` stored | The typed path is made absolute first |
|
||
| — | — | `env add --json` was documented as printing the entry "exactly as" `env list` would, untrue when discovery also finds it; a Triage failure on a pull request reached no channel | Wording; `notify.yml` reports Triage's `pull_request_target` runs |
|
||
|
||
Reviewed and found sound: `triage.yml`'s handling of a stranger's pull request (the base branch's
|
||
scripts only, no expression reaching a shell, writes that start no runs), who it can close, the
|
||
v4→v5 migration, the store guard, and the copy in both catalogues.
|
||
|
||
**Left, in the backlog with a reason each:** X36-b, the `PyEnv` commands' trust in the webview's
|
||
path, and the identity of an interpreter on a share.
|
||
|
||
## Maintenance mode — from 1.6.0
|
||
|
||
**PipDock is maintained rather than developed from 1.6.0 on** (owner decision, 2026-11-21, with the
|
||
move to the poli0981org organization). 1.6.0 closed the last P0 gap, *Browse…*; nothing else on
|
||
this page will be built unless it qualifies below. CONTRIBUTING.md, "Scope in maintenance mode",
|
||
is the public version of this section, and `.github/workflows/triage.yml` enforces its edge.
|
||
|
||
**What the work is now:**
|
||
|
||
| Kind | What qualifies |
|
||
|---|---|
|
||
| Dependencies | Dependabot's weekly proposals, past their cooldowns, one PR superseding the bot's (the 2026-11-04 shape) |
|
||
| Security | A dependency advisory of High or Critical, or a serious security problem in a runtime or toolchain the program is built with (Node, Rust, WebView2) — fixed promptly, and released when it reaches the shipped binary |
|
||
| Majors | Language, runtime and framework upgrades — Node, TypeScript, a Rust edition, Tauri — once stable. The held-back i18next 27 + react-i18next 18 pair is the next one, and wants a session of its own |
|
||
| Defects | Bugs, UI/UX problems and accessibility barriers. **The Audit backlog above is this list**: every row that is a defect is in scope, every row that is a feature (X19, the engine caches) is not |
|
||
| Wording | English or Vietnamese that is wrong, misleading, or not how people speak; `.github/ISSUE_TEMPLATE/wording.yml` |
|
||
|
||
**What is not planned, and why** — each one decided, not dropped:
|
||
|
||
| Item | Why not |
|
||
|---|---|
|
||
| P1-7, the scheduled check | Every prerequisite is absent (the survey above), and its persona is served by the CLI in Task Scheduler. One plugin and a permanent background process for one line of text |
|
||
| P0-9's first-run uv detection (backlog X19) | Settings already shows both engines and their versions and switches with one click; a first-run prompt is a new surface, not a fix |
|
||
| P1-4's engine caches (`pip cache`, `uv cache`) | A different feature wearing the same word (P1 wave, above) |
|
||
| P2 — macOS/Linux, per-env engine, elevation broker, conda, portable mode, a Japanese locale | Each is a feature, and most a test matrix |
|
||
| Generating THIRD-PARTY-NOTICES | The licence checks (`cargo deny`, `npm licences`) now hold the claim the inventory makes; the inventory itself stays hand-kept |
|
||
| Retaking `screenshot/` | The owner's hands, when something visible changes enough to mislead |
|
||
|
||
**How the edge is held.** A feature request — titled as one, a `feat:` pull request, or labelled
|
||
`enhancement` — is labelled `out-of-scope` and closed by `triage.yml` with a bilingual answer that
|
||
links CONTRIBUTING. Only unmistakable signals count, because closing a real bug report would be
|
||
worse than leaving a request open; maintainers, bots and anything labelled `policy-exception` are
|
||
never closed. `workflow_dispatch` on it is a dry run that classifies a title without touching
|
||
anything.
|
||
|
||
## Standing risks
|
||
|
||
| Risk | Mitigation |
|
||
|---|---|
|
||
| uv output churn between releases | weekly latest-engine parser CI job (TESTING L1) + PD-ENG-003 graceful degrade + "switch to pip" escape hatch |
|
||
| pip UX flags deprecations (e.g. report format changes) | same job covers pip; adapter version-gates per engine version |
|
||
| Index size growth | SP-3 fallback design kept in the drawer |
|
||
| Scope creep from Health into a linter IDE | CODE-HEALTH §7 non-goals are contractual |
|