306 Commits
Author SHA1 Message Date
poli0981andClaude Opus 5 08ba978960 docs: the install path, corrected by installing it
I wrote `%LOCALAPPDATA%\Programs\PipDock\` into the README from the Windows convention rather
than from observation. Tauri's NSIS per-user default is `$LOCALAPPDATA\{productName}`, so the
real path is `%LOCALAPPDATA%\PipDock\` — found by running the installer and reading the
uninstall registry entry.

Which surfaces a collision worth deciding about separately: that is **the same directory
`store::default_app_data()` uses**, so `index.db`, `snapshots\` and `tools\` now sit beside
`pipdock-app.exe` and `uninstall.exe`. SECURITY §8 tells users "deleting the app data folder
is a complete reset" — advice that now also deletes the application.

The safety question was answered by testing rather than assumed: **uninstall does not destroy
user data.** It removed its own three binaries, the Start-menu shortcut and the registry
entry, and left `index.db`, `snapshots\` and `tools\` untouched. Verified with a backup taken
first, which turned out not to be needed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 20:59:43 +07:00
poli0981andClaude Opus 5 7aa43cdee1 fix(lint): one build script should not take eslint . down with it
`recommendedTypeChecked` is applied unscoped, so adding `scripts/bundle-cli.mjs` made ESLint
**crash** rather than report a lint: *"You have used a rule which requires type information,
but don't have parserOptions set to generate type information for this file"*. The file is a
plain Node module and is in no tsconfig project, which is correct — the config just had no
place to put it.

Build scripts now join the config files in the `disableTypeChecked` block, with the two Node
globals they actually use. Caught because the commit ran the gates rather than trusting the
previous run — a lint that exits non-zero for a *configuration* reason looks exactly like a
lint that found something, right up until you read it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 20:59:43 +07:00
poli0981andClaude Opus 5 debc05edee fix(bundle): ship the CLI, which the installer had been leaving behind
The first bundle ever built for this project contained exactly one binary. NSIS payload:
`pipdock-app.exe`. MSI `app.cab`: one file. **`pipdock.exe` was not installed at all** — while
PRD P0-12 is "CLI core parity", CLI-SPEC documents the entire surface, `golden.rs` pins 58
snapshots of its output, and the README's own Quick start opens with `pipdock env list`. A
user who installed PipDock had none of it.

Found by listing the installer. `tauri.conf.json` declared no `externalBin` and no
`resources`, so there was nothing to notice in a diff — the config was correct for a
GUI-only app, and nobody had built one to see what came out.

`scripts/bundle-cli.mjs` builds the CLI and stages it as a sidecar under the host triple,
which Tauri strips at bundle time, so it installs as plain `pipdock.exe` beside the GUI. The
triple is asked of `rustc -vV` rather than assumed, since a guess breaks the moment anyone
cross-compiles.

It runs from `beforeBuildCommand`, not only from the release workflow. A locally built
installer and a released one have to be the same artifact; a bundle that differs by who
built it is how "works on my machine" reaches a release. This build proves the clean-checkout
case too — `src-tauri/binaries/` is gitignored and did not exist when the build started.

**`PATH` is deliberately left alone** (owner decision, 2026-08-13). PipDock does not modify
the user's environment, which is the restraint SECURITY §5 already applies to not shipping a
self-updater; the README says where the binary lands and gives the one-liner to add it if
that is what you want.

Verified by rebuilding and listing both installers: NSIS 5.7 → 8.8 MB carrying
`pipdock-app.exe` and `pipdock.exe`; MSI 7.6 → 11.6 MB carrying `Path` and `Bin_pipdock.exe`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 20:59:43 +07:00
poli0981andClaude Opus 5 1aee0bea6b fix(ci): a release workflow that had never been run, and 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; `tauri build` passes
everything after `--` to the runner. No `v*` tag has ever been pushed, so the release job had
never executed and this had never surfaced.

Found by building the bundle on the dev machine for the first time — which is the whole point
of Phase 4, and which took one command to expose a pipeline that would have failed on the
tag that was meant to ship v1.

Also removed a duplicated frontend build: `tauri build` runs `beforeBuildCommand`, which is
already `npm run build`, so vite ran twice per release for no benefit. RELEASE-CI §3.1 now
describes the command that exists rather than `cargo tauri build --locked`, which has the
same flag problem.

**Verified against real artifacts**, not just re-read: the corrected command produces
`PipDock_0.1.0_x64-setup.exe` (5.7 MB) and `PipDock_0.1.0_x64_en-US.msi` (7.6 MB) in 3m48s,
and the workflow's own collect and checksum steps, run verbatim in PowerShell, emit a correct
`SHA256SUMS.txt`.

The README gains the badges RELEASE-CI §5 asks for, loses a status line that still said
*design phase*, and gains the command that makes "verify the SHA-256 checksum" actionable —
tested against the real file, and it reproduces the published sum.

One correction there is not cosmetic: the feature table claimed network traffic goes to
"PyPI (package data) and GitHub (app updates)". **PipDock has no self-updater** — SECURITY §5
removed it deliberately, and the paragraph two lines below the table says so. PyPI is the
only host it connects to; GitHub and the ruff docs are only ever handed to the browser as a
link the user clicked.

ROADMAP records both the build numbers and the blocker the build exposed — see the next
commit's absence: the installer ships no CLI, and fixing that needs an owner decision.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 20:59:43 +07:00
poli0981andClaude Opus 5 4720e1ccb5 docs: close Phase 3, with the numbers it was measured at
The exit criterion was *"CODE-HEALTH flows pass on two real projects (one pyproject, one
requirements-only)"*. Both are recorded in the stage table with times from a release build
rather than ticked: a requirements-only project reports 1 dependency, 3 dead-code and 3 lint
findings in 1.4 s; one declaring nothing reports `ran: [vulture, ruff]` with an empty
`problems` in 1.3 s, because deptry cannot answer its question there and is correctly not
run. The fix path's three refusals were exercised on a seeded repository.

UI-SPEC §8 gains the two rules P6 established and the reason each exists: `←`/`→` are the
ARIA grid pattern's roving tabindex, added because making the row the only tab stop had left
*Pin* and *Remove* reachable by mouse only; and `Enter` on a row is the non-destructive
primary, because a row has one reversible annotation and one irreversible removal.

CLI-SPEC §6's amendment said *"`health` is still the M3 stub"* — stale since P3, and now
carrying the `--fix` output contract instead.

CLAUDE.md records the tab-stop rule beside the other things this project learned by running,
and the status line moves to Phase 4.

**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 actually
works — it fails silently if not), and the fix dialog end to end. All three are named in the
ROADMAP so they are not rediscovered.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 19:48:48 +07:00
poli0981andClaude Opus 5 b083e75505 chore(core): delete the last todo!(), and flip the lint that was waiting on it
`uv::parse_dry_run` had no callers and a `todo!("SP-1: pin uv's text plan format against
captured fixtures before parsing it")` body. The spike it was waiting for happened: the uv
adapter parses `--dry-run` output through `engine::parse`, against captured fixtures, and has
since M1. What was left was a function that would panic if anything ever called it, kept
alive by a comment about work that was already done.

With it gone `clippy::todo` goes from `allow` to `warn`, which its own comment has asked for
since the scaffold ("flip to warn once M1 lands"). Zero `todo!()` in the workspace, and the
next one has to be argued for rather than inherited — a `todo!()` is a panic with a promise
attached, and the promise is the part that expires.

Both were named in P2's stage record as clean follow-ups deliberately kept out of a feature
diff. This is that diff.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 19:48:48 +07:00
poli0981andClaude Opus 5 73a67a6243 feat(ui): reach the row's actions with a keyboard, and stop saying things twice
UI-SPEC §8's remaining keyboard work, and it turned out to be hiding a WCAG 2.1.1 failure.

**Pin and uninstall were unreachable without a mouse.** Every control in a package row is
`tabIndex={-1}` so that 200 rows do not become 600 tab stops — a sound trade for the
checkbox, whose job `Space` already does from the row. Applied to the two action buttons it
removed the actions entirely: the row was the only tab stop, and from it 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.

The ARIA grid pattern's answer is a roving tabindex, so that is what this is: `ArrowRight`
and `ArrowLeft` walk the row's controls, `Escape` comes back out to the row, and no tab stops
are added. Verified in the browser — the focus walk is checkbox → *Pin this package* →
*Remove this package* → row.

**`Enter` is the row's primary action, and it is pin rather than uninstall.** A row has one
reversible annotation and one irreversible removal; a destructive operation one keypress away
from a focused row is not a primary action, it is an accident waiting. `Space` still toggles
selection independently — checked, because a new binding on the same element is exactly how
an old one stops working.

Note what the audit actually found: `Enter` already worked everywhere else in the app,
because every other primary action is a real `<button>` and buttons handle it natively. The
gap was one element that only looks like a control.

**Two live regions folded, and the pair that mattered was not the pair the ROADMAP counted.**
`PdEnvDetail` had two on one screen; they are now one, which is safe because a diff cannot be
loading before a snapshot has been selected from the list. And `PdConsoleDrawer` announced
the same `done/total` as the panel that opens it, so a reader heard every step twice — the
drawer's is gone, because the screen owns the announcement and the drawer may be closed while
a run is going. Ten regions down to eight, with the two genuine conflicts removed rather than
the count merely reduced.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 19:48:48 +07:00
poli0981andClaude Opus 5 6840e0378a docs: the write path, the waiver that gates it, and one claim made true
DATA-FLOW gains **invariant 6** and §9.1's state machine. §9.1 and §9.2 are scoped to a
mutating *engine* call and do not reach `ruff check --fix`, which rewrites the user's source
tree — a thing no snapshot in this application describes, so one taken here would have no
consumer that could use it. That is invariant 2's own argument for the pip-upkeep exemption,
a second time, and like that one the exemption is **made visible rather than silent**: the
confirm states that PipDock cannot undo the change and that only the user's version control
can. The fifth proof shape is a `HealthReport` plus a server-checked `FixConsent`.

**A SECURITY paragraph was ahead of the code, and the code caught up rather than the
paragraph coming back.** §2 now says the project folder is canonicalized, existence-checked,
and refused when it resolves inside PipDock's own tools directory — so `validate_project`
exists, `..` is handled by comparing canonical paths rather than strings, and running Health
against `%LOCALAPPDATA%\PipDock\tools` answers `PD-ENV-003`. ruff would otherwise have
rewritten PipDock's own venv, and that failure would have looked like a corrupted install
rather than like the fix that caused it.

§2 also records the git resolution finding: this is the one place PipDock runs a
PATH-resolved program with a user-controlled working directory, and a planted `git.exe` does
**not** win — verified by planting one, not by reasoning about `CreateProcess`. §8 gains the
one exception to "all state is local".

CODE-HEALTH-SPEC §5 replaces "recommends a clean git tree" with what was built. CLI-SPEC §3
carries the `--yes` rule where someone reading the flag will see it. UI-SPEC §5 gains the fix
row and §7 names the confirm alongside the other three destructive ones, with the
forced-colors requirement each of them shares. ARCHITECTURE §7 gains `health_dirty`.

CLAUDE.md's waiver list goes 2 → 3, and the no-snapshot decision is written where the next
person will look for it rather than left to be re-derived.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 19:30:12 +07:00
poli0981andClaude Opus 5 3e72ecf7c4 feat(ui): Fix N safely fixable issues, and a confirm that says what it cannot undo
**One dialog with two states, not two dialogs.** Two confirms would break the click budget,
and the second is the one nobody reads. `PdDialog` renders Cancel first and focuses it, so
Enter without Tab cancels — UI-SPEC §7's rule for a destructive confirm, inherited rather
than re-implemented. `button[data-action='fix']` joins the forced-colors list in `styles.css`,
because high contrast drops every tint and a destructive primary that looks like Cancel is
worse than no colour at all.

The unconditional line is *PipDock cannot undo this; only your own version control can* —
true whether or not there is a repository. The **danger** block is reserved for a tree that
really has uncommitted work, so a folder outside version control is not nagged about. That is
the same reasoning `fix::dirty` documents for answering `None` rather than warning.

`health_dirty` is a command of its own rather than a field on the report, because the answer
expires: the user can commit, or start editing, between the run and the button. It is asked
when the dialog opens, and `health_fix` asks **again** before writing — this answer decides
what to render, that one decides what to allow.

Every count comes off the report. The button names `fixable`, the dialog names
`fixableFiles`, and neither is derived from the badges rendered beside them — the button, the
CLI prompt and the server's own check all have to name one number, which is what `recount`
exists for.

`fix` is in `NO_HEALTH`, so a second Run closes an open confirm. The server replaces its
parked report on a new run, and a dialog left open would let the user confirm a count that no
longer exists on either side.

On success the tab drops to `remaining` with **no second Run**, which is why the server
re-parks its session rather than releasing it. On failure the dialog closes and the report
stays: nothing was written, so it is still true, and every failure here is one the user has
to act on elsewhere — commit, clear a read-only flag, or re-run.

Six store tests, including the two that would pass silently: that `acknowledgedDirty` is true
only when the tree really is dirty, and that a failed dirty check opens the confirm anyway
rather than blocking the fix for a reason nobody can act on.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 19:30:12 +07:00
poli0981andClaude Opus 5 545ca7fc89 feat(cli): pipdock health --fix, prompting the way the dialog does
Replaces the `PD-INT-001` refusal P3 left in place. CLI-SPEC §1.1 says the two heads share
behaviour, and this is the one operation neither of them can undo, so the CLI refuses in the
same places the dialog will.

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

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

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

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

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

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

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 19:30:12 +07:00
poli0981andClaude Opus 5 d5f02c73d2 feat(app): health_fix, and the last NOT_YET row Phase 3 owed
`NOT_YET` is down to two, both M3-general. Code Health is feature-complete.

The command takes **no project, no environment, no file list and no findings**. All of it
comes from the parked `HealthSession`, which is the point: what is fixed must be what was
reported on — the same reasoning that makes `plan_execute` take nothing. `files` crosses as
an assertion the server checks against its own copy, so a frontend cannot widen the blast
radius past what its own dialog named.

Three gates, in the order that matters, all before the first byte:

1. `files` against the parked report — a mismatch is `PD-INT-001`, because only a frontend
   out of date with its own store can produce it.
2. A **read-only re-read** of the project. Minutes pass between confirming and clicking, and
   a source tree is not PipDock's to assume is still; a change in either count is
   `PD-RES-002`, which is DATA-FLOW §9.3's staleness rule applied to the one thing no
   snapshot describes. It has to be a separate invocation because `--fix` writes as it goes.
3. `git status` asked **again**. The dialog's answer decided what to render; this one decides
   what to allow.

`ruff_argv` is extracted so the re-check and the run cannot drift — a re-check excluding
different files would compare two different questions and refuse a fix the user was correctly
shown. And a note where the next person will read it: if `RunOptions` ever reaches the wire,
this must re-check with the *session's* options rather than the defaults.

The session is re-parked either way, carrying the post-fix ruff state on success. The screen
drops its tab count to `remaining` without a second Run, so the server has to hold the same
thing the user is now looking at — otherwise the next fix is checked against a report nobody
can see. `claim_one` rather than `claim`, so finding nothing leaves the slot idle instead of
wedging every later command with `PD-RES-003` for a session that does not exist.

`FixReport` is the one type on the wire; `FixConsent` never crosses.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 19:30:12 +07:00
poli0981andClaude Opus 5 91ba7bcc19 feat(core): the dirty tree, the third waiver, and PD-PRM-003
`health::fix` — everything that gates PipDock's **first write outside site-packages and
`%LOCALAPPDATA%`**.

DATA-FLOW §9.1 and §9.2 do not reach it. Both are scoped to a mutating **engine** call, and
ruff is a tool run from PipDock's own venv; more to the point, a fix rewrites the user's
*source tree*, which no snapshot in this application describes. A snapshot is a freeze and
§8's rollback is uninstall-the-added/install-the-removed, so one taken to protect source
files would have no consumer that could use it — invariant 2's own argument for the pip
upkeep exemption, a second time. The safety net CODE-HEALTH-SPEC §5 names is the user's own
version control, which is why the dirty finding lives *inside* `FixConsent` rather than
beside it.

`consent_ok` builds the waiver from what the **server** observed, so a frontend claiming a
clean tree against one the server just found dirty is refused. Same shape as `ack_ok`
checking a `GuardAck` against the guard that produced it. A tree that *was* dirty and is
clean by the time the fix runs needs no acknowledgement — the thing waived no longer exists,
and refusing there would cost the user the fix for having committed.

`git --no-optional-locks status --porcelain --untracked-files=no`, and neither flag is
decoration. Plain `git status` refreshes and **writes `.git/index`** on a stat-dirty tree —
writing into the user's repository while checking whether it is safe to write would be a
poor first act for the write path. Untracked files are excluded because `git checkout .`
restores tracked files regardless, so warning about a scratch file is how a warning stops
being read. `None` covers no-repo, no-git, git-failed and timed-out, because all four leave
the caller with the same options.

**A security question answered by running it.** This is the one place PipDock runs a
PATH-resolved program with a user-controlled working directory, so a `git.exe` planted in a
cloned repository would matter if Windows' legacy `CreateProcess` search order applied. I
planted one and watched which ran: the real git. Rust's `Command` does its own resolution and
does not include the current directory. Recorded on the function, with a note to re-check if
the process layer ever changes.

**`PD-PRM-003`, not a reused `PD-PRM-001`.** That code is scoped to site-packages and its
catalogued action is "use a venv", which is nonsense for a read-only `util.py` — the same
class of wrong answer P3 removed when a corrupted `ruff.exe` reported "install the engine".
Raised internally, so it needs no classifier, only a corpus entry.

And the real hazard is worse than mis-coding: **ruff can fail to write a file and still exit
1**, which `is_findings_exit` accepts as a clean run — so the failure can be *silent*, with
the fix reporting success over a file it never touched. `ensure_writable` therefore refuses
the whole fix before the first byte, checking both the read-only attribute and an append
probe for the ACL case. A partial rewrite of a source tree is the worst thing this design can
produce, because nothing here can undo half of one.

The checklist is **nine** places and CLAUDE.md said eight: `HealthReport` embeds `Code`
through `ToolProblem`, so a new code re-blesses four schema goldens, not three. Corrected
there, along with the count in I18N §1 that was already stale.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 19:30:12 +07:00
poli0981andClaude Opus 5 484d1a4693 docs: the fifteenth component, and the decision that was open for three slices
**The deptry question is closed.** ROADMAP has flagged it since P3 as the one decision in
three slices the owner had not made themselves: deptry cannot be told which environment to
compare against, so §2's isolation and §3's comparison conflict. Chosen 2026-08-13 — 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, because that file is read away from both.

UI-SPEC §6 goes 14 → **15 of 16**; only `PdEnvSwitcher` is left. §5's Health row gains the
parenthetical the Uninstall row already has: 3 clicks holds once the folder is remembered,
and the first run in a project is 4. §3 gains two rulings it was silent on — that a failed
tool's error row counts into `⚠ n` (three separable tools are three problems, where
forty-seven failed packages are one run), and that Health owns its own console drawer,
because it claims a separate session slot by design and one toggle cannot address two.

CODE-HEALTH-SPEC §6's third bullet is corrected in place rather than left as a known-dead
line: the rule page is keyed by name, `.../rules/<code>` 404s, and the allowlist had to be
widened or every link failed silently.

ARCHITECTURE §7 gains `health_save_report` and corrects `health_fix` to `FixReport` —
`ExecutionSummary` was wrong for the same reason it was wrong for `pip_upgrade`: no plan, no
phase, no per-package counts. Both `EnvRow` rows now say that every per-row field has to be
filled by *both* probe paths, since `upgradePip` replaces the row wholesale.

The ROADMAP stage table records what the plan did not predict: four defects, all found by
running, and the cancellation deferral with the measurement behind it rather than a shrug.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 18:49:59 +07:00
poli0981andClaude Opus 5 6f09d5f060 fix(core): a project that declares nothing is not a deptry failure
deptry raises `DependencySpecificationNotFoundError`, exits non-zero and writes no report
when there is no `pyproject.toml` and no `requirements*.txt`. `collect` then read that as
`PD-HLT-002` — "the tool exited non-zero" — so Code Health detected the state, told the user
in the header that results would be limited, ran a tool that cannot run in it, and reported
the consequence as a failure of Code Health.

CODE-HEALTH-SPEC §3 already calls this the "limited-mode notice". It is a property of the
project, not a fault, so deptry is left out of `ran` instead: the tab reads *not run*, and
the declared-source line directly above it says why. Recording it in `problems` claimed
something had gone wrong when nothing had.

It stays in the step loop as a **skipped** step. `run_steps` sizes the caller's progress bar
before the project has been read, so a deptry that vanished from the loop rather than being
skipped would leave every such run ending at "2 of 3" — and skipped is what the console
should show anyway, since the tool was considered.

Found by running, not by reading: three tools over a folder with no `pyproject.toml`, which
is half of Phase 3's own exit criterion and invisible to a suite whose fixtures all declare
something.

Both halves now pass, release build, warm tools venv:

- requirements-only: 1 dependency, 3 dead-code, 3 lint (3 fixable in 1 file), 1.4 s
- declares nothing: `ran` is `[vulture, ruff]`, `problems` empty, 1.3 s

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 18:49:59 +07:00
poli0981andClaude Opus 5 fc74edfc0c feat(app): health_save_report, Markdown and JSON where the user asked
CODE-HEALTH-SPEC §5's *Save report*, and §7's argument for it: the JSON export is what lets
users wire their own CI annotations, which is why "no CI annotations in v1" is a non-goal
rather than a gap. Two files from one prompt, because asking twice for what is conceptually
one action spends a click on nothing.

**Written in Rust, not through `tauri-plugin-fs`.** A general `fs:allow-write-text-file` is a
write-anywhere primitive granted to the webview of a tool that already runs subprocesses
against the user's interpreters. `dialog:allow-save` only lets the webview *ask* for a path;
it still has no permission to read or write a single file. The grant says so where the next
person will look for it.

`markdown()` lives in `health/report.rs` rather than in the bridge, so a future
`pipdock health --format md` reuses it instead of growing a second renderer that drifts. That
flag is deliberately not built now — one consumer is not a reason to design for two.

The renderer makes the same three-way distinction the tabs do, and for a sharper reason: a
saved report is read months later, away from the screen that produced it. An empty section
says `_Not run._`, `_Did not finish — see Problems above._` or `_No findings._`, because a
document claiming "no findings" about a ruff that could not be spawned would be read as proof
the code was fine. The deptry caveat travels with the findings it qualifies for the same
reason — the saved file is the one place it cannot be left implicit.

Both names are derived from the chosen path's stem rather than from what was typed, so the
pair always matches even if the user names the file `report` or `report.txt`.

Read the rendered document rather than only asserting on fragments of it: headings, the
per-file grouping, the whole-file location with no dangling colon, and "3 of 6 carry a safe
fix, across 2 file(s)" against a fixture carrying exactly that.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 18:49:59 +07:00
poli0981andClaude Opus 5 aa839545c2 feat(ui): the Health screen, and a tab that stops being dimmed
`SCREENS.health`, `PdSidebar`'s `NOT_YET` down to `['security']`, and a screen that owns the
folder, the run, the progress and the errors while `PdHealthReport` owns the tabs.

**A bug found by opening the screen, not by any test.** With a folder remembered and no run
yet, it said *no issues found* — nothing had run, so there was nothing to have found. That
is the identical lie a tab keyed on `ran` alone tells about a failed tool, one level up and
in code written by someone who had just spent a commit preventing it. It now says *not
checked yet · Press Run to check this folder*, which is a state rather than a claim.

Driven against a stubbed bridge in a real browser, which is how the above surfaced and how
the rest was confirmed rather than assumed:

* `Ctrl+6` reaches Health and the `<h1>` takes focus, so the next Tab resumes in the new
  screen.
* The remembered folder arrives on `EnvRow.healthProject` — the button reads *Change
  folder…* rather than *Choose folder…* on a first visit, which is the whole read path
  end to end.
* `plugin:event|listen` crosses the bridge **before** `health_run`, so the tools-venv
  bootstrap is not emitted into nothing.
* The three tab counts are 4/3/6 against a fixture carrying 4/3/6. Nothing is recomputed.
* `requests` — unused *and* installed — offers *Review in Uninstall…*; `httpx`, unused and
  not installed here, does not; `yaml`, a DEP001, does not either.
* On the partial report: the ruff tab reads *did not finish*, vulture reads *not run*,
  deptry still reports its four findings, `PdErrorRow` carries `PD-HLT-001` with its
  localized one-liner above the tabs, and the status line reads `⚠ 1`.

`useEnvPackages` rather than a fourth copy of that effect, and rather than the `loadPackages`
-only variant an earlier draft of the plan called for: the hook's own doc comment explains
that `loadedFor` is one flag covering two calls, so a screen loading only `pkg_list` would
set it and leave every row's badge permanently `unknown`. One networked `pkg_outdated` this
screen does not use is the price of not reintroducing that.

`asError` converts a `ToolProblem` for `PdErrorRow`. The two are the same shape by design but
not the same type: `exactOptionalPropertyTypes` is on and the generator emits `?: T | null`,
so an absent `stderrTail` and a null one are different and neither is `string`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 18:49:59 +07:00
poli0981andClaude Opus 5 1b909deb33 feat(ui): PdHealthReport, the fifteenth of UI-SPEC §6's sixteen
Prop-driven and store-free, split from its screen the way `PdPreviewDiff` and
`PdRollbackPreview` are. That split is what lets it be tested against the two committed
fixtures with nothing mocked but the URL opener.

**A tab has three states, not two, and this is where getting it wrong would have shipped.**
`health::run` fills `ran` from the selection before the tool loop, so a tool that failed is
in `ran`, in `problems`, and reports nothing. Keying on `ran.includes(tool)` renders a
quarantined `ruff.exe` as *no issues found* — P3's own exit-criterion scenario, shown as a
lie, and green in any suite that only ever feeds it a successful run. `health_partial.json`
is the subject, and the test asserts the absence of "no issues found" as well as the
presence of "did not finish".

The deptry handoff has two gates and the first is the one every draft of this dropped. Only
`DEP002` may offer *Review in Uninstall…*: `DEP001` is a *missing* dependency, so a button
there tells the user to uninstall something the project does not have, and `DEP003` is
transitive where removing it is actively wrong. CODE-HEALTH-SPEC §5 says "unused-dep rows"
and the qualifier is load-bearing. The second gate is the module-versus-distribution one —
`yaml` is `PyYAML` — resolved by matching against what is actually installed and rendering
no button when nothing matches, rather than by an alias table PipDock does not own.

Counts come off the report. Not one is recomputed here, because a tab that counted its own
rows could disagree with `pipdock health --json` over the same run, and that is the one
difference nobody would think to check. The same rule makes the `fixable` badge count only
safe fixes: `unsafe` and `display` are what `--unsafe-fixes` exists to opt into and PipDock
never passes it, so badging them would promise a fix the fix will not deliver.

Bounded at 500 ruff rows rather than virtualized. ruff's built-in defaults are far wider than
`E4,E7,E9,F` — with no config at all it reports flake8-bandit rules — so a large tree is
thousands of findings, while `PdPackageTable` is a fixed-column ARIA grid typed to
`PackageRow` and generalizing it over three row shapes is a bigger change than the problem.
The counts are unaffected, so a capped list never misreports a total.

The visible tab label is the tool's own name; the accessible name is what says which
question the tab answers. Tool names, codes, messages, paths and versions are data and are
never translated (I18N §2) — and there is deliberately no PipDock copy per `DEP` code, which
would be a mapping maintained in two languages against a tool on someone else's release
schedule.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 18:49:59 +07:00
poli0981andClaude Opus 5 2d1b261625 feat(app): docs.astral.sh, or every ruff link does nothing
`opener:allow-open-url` was scoped to `https://github.com/*`. Every `RuffFinding.url` points
at `https://docs.astral.sh/ruff/rules/<name>`, so the ruff tab's links would have failed —
the promise rejects, nothing opens, and nothing in the console, the tests or a review says
so. Invisible in dev, which is why it goes in before the screen that needs it rather than
after, and why it has its own line on the click-through list.

Still scoped. Two hosts is not the same as any host: an unscoped opener is a
launch-anything primitive reachable from any injected string, which is the reasoning
SECURITY §2 already applies to argv arrays. The second entry is there because a feature
failed silently without it, not to make room for future ones.

Recorded in SECURITY §4 beside the GitHub precedent rather than only in `capabilities/`. An
allowlist entry is a change to that document's subject matter — what PipDock will hand to
the user's browser — not a config detail.

Note the two hosts cover more than the ruff tab needs: vulture's whitelist help, which
CODE-HEALTH-SPEC §6 wants linked from the dead-code tab, is already on github.com.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 18:49:59 +07:00
poli0981andClaude Opus 5 e4f1596d95 chore(ui): the folder picker Tauri already had permission for
`tauri-plugin-dialog` has been registered in Rust since the shell was scaffolded and
`dialog:allow-open` has been granted in `default.json` since then too — but
`@tauri-apps/plugin-dialog` was never in `package.json`, so there was no JS binding to call.
A permission with no way to exercise it, which is invisible until something tries.

`pickProjectFolder` lives in `@/ipc` rather than in the component that calls it. `PdErrorRow`
imports `plugin-opener` directly and that is fine, because `openUrl` is fire-and-forget and a
test has nothing to assert about it. Here the return value *is* the interaction — which
folder the user chose is what every screen test has to script — and TESTING §2 requires
mocking at the typed wrapper layer. A component-level import would lint clean and be
unmockable, which is the worst combination.

`ipcMock` gains it, resolving to `null`: cancelled is the honest default, and a picker that
silently produced a folder would let a test assert a run it never asked for.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 18:49:59 +07:00
poli0981andClaude Opus 5 33e41f4a9f feat(ui): useHealthStore, keyed to an environment *and* a folder
The third reset key in this app, and the first that is a pair. `NO_PACKAGES` is keyed to
`selected` and `NO_SNAPSHOTS` to `openFor` — those two were folded together once, and a
rescan wiped a freshly-loaded timeline. A report is keyed to `(envHash, folder)`: the folder
is remembered per environment, and two environments can legitimately name the same one, so
neither half is the key alone. `folder` is deliberately outside `NO_HEALTH`, because it is
half of what the reset is keyed on.

`tabState` is the rule the screen cannot get right by itself. `health::run` fills `ran` from
the selection *before* the tool loop, so a tool that failed is in `ran`, in `problems`, and
reports nothing — and a tab keyed on `ran.includes(tool)` renders a quarantined `ruff.exe`
as *no lint findings*. That is P3's own exit-criterion scenario shown as a lie, so it is
three states, not two, and `health_partial.json` is a committed subject for each.

`ruffByFile` is grouped once, when the report lands, and held as state. A selector calling
`groupRuff` returns a fresh array on every `getSnapshot`, which zustand v5 on
`useSyncExternalStore` turns into a caching warning or an endless re-render — the same rule
`packages` is held as state for, second application.

`run` subscribes to `health-progress` before invoking, because on a cold install the
tools-venv bootstrap is the slowest part of the run and is emitted first; subscribing after
loses exactly the progress the user is waiting on. It clears before subscribing too, so a
second Run cannot paint the previous findings under a new `ranAt`. `phase: 'failed'` exists
for `PlanPhase.failed`'s reason: returning to `idle` unmounts whatever reads `error`, and
the user presses Run and sees nothing happen.

Sixteen tests, including the two that would otherwise pass silently: that a failed tool's
tab is not "clean", and that `subscribe` really does precede `invoke`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 18:49:59 +07:00
poli0981andClaude Opus 5 7b393c12c6 feat(ui): a console reducer two stores can share
`health-progress` carries the identical `ProgressEvent` payload as `plan-progress` — same
`stepStarted`/`line`/`stepFinished` lifecycle, same `step`/`total`, same streams. So the
Health store either reuses this reducer or gets a second one with its own `CONSOLE_LIMIT`,
its own drop-from-the-front rule, and its own opportunity to count `done` differently from
the drawer that renders it.

`apply` is now generic over a `ConsoleState` slice and returns `Partial<ConsoleState>`.
`PlanState` satisfies it structurally, so `usePlanStore` and `plan.test.ts` are untouched —
which is the point: the change costs one signature and buys the guarantee that the two
progress surfaces cannot drift.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 18:49:59 +07:00
poli0981andClaude Opus 5 f3059d4328 feat(core): two health fixtures, and a subject for every branch the tabs implement
`health_report.json` and `health_partial.json`, serialized from the real types the way
every other IPC fixture is, so a component test cannot pass against a shape the app does
not send.

**Two documents, because one cannot express both states of the same tool.** A populated
ruff tab and a ruff `ToolProblem` are contradictory; a single fixture leaves either the ruff
tab or the partial-report branch with no subject.

The partial one is the more interesting half. `ran` is filled from the selection *before*
the tool loop, so a tool that failed is in `ran`, in `problems`, and reports nothing — which
means `ran.includes(tool)` alone cannot tell "clean" from "did not finish". A screen keyed
on `ran` alone renders a quarantined `ruff.exe` as *no lint findings*, which is P3's own
exit-criterion scenario rendered as a lie. So `health_partial` carries all three states at
once: deptry reported, ruff failed, vulture was never asked.

The deptry rows are chosen against `pkg_list()` rather than invented, because the *Review in
Uninstall…* button has two gates and each needs both answers: a `DEP002` naming an installed
distribution (the button), a `DEP002` naming one that is not installed (no button), and a
`DEP001` for `yaml` — a module name that is not a distribution, and the wrong code for the
button twice over. Plus a row with no location at all, one with two, and a location with no
line, since deptry names no position for a finding about the manifest.

ruff carries safe, unsafe and no-fix findings across two files, so `fixable` and
`fixableFiles` are 3 and 2 — deliberately unequal, because equal counts let a UI confuse
findings with files and still pass. The syntax error is the subject for the absent-link
branch, and it carries `invalid-syntax` as its code rather than null, which is the opposite
of what CODE-HEALTH-SPEC §6 assumed.

`the_health_fixtures_still_cover_every_branch_the_tabs_implement` asserts every one of those
by construction, including that the committed counts still agree with `recount()`. Editing
the scenario without reading it is how a component test quietly stops covering the case its
name claims.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 18:49:59 +07:00
poli0981andClaude Opus 5 eec926862d feat(app): the project folder, on the row that already carries per-env data
`EnvRow` gains `healthProject`, read out of the `health_projects` table P3 added and the
CLI has been writing since. P4's screen needs to know where Health last ran without asking
for a command whose whole job is to return one string, which is the trade `pipVersion`
already makes on this struct.

`env_scan` reads every folder in one pass before the probe loop and joins afterwards. Not
tidiness: `Store` is not `Sync`, so holding the guard across `envs::probe` does not compile
at the command boundary — the hazard CLAUDE.md says has bitten twice, enforced this time by
the type system rather than by remembering.

`health_run` now writes the folder, so the GUI stops being the head that reads a table only
the CLI fills. Not with `?`: the report is in hand and P5 depends on it being parked, so a
failed bookkeeping write must not discard findings that cost three subprocesses.

Two things `env_probe` was getting wrong, both of the same shape, and both because
`upgradePip` replaces the row **wholesale**:

Its own doc comment warned that a refresh path omitting `pip_version` would blank the field
it was refreshed to update. `healthProject` is the second field to need that warning applied
— without it, upgrading pip made the Health screen forget where it was pointed.

`source` was hardcoded `EnvSource::Manual` for both of the function's uses. So refreshing a
registry-discovered interpreter relabelled it *Added manually* in the chip at
`PdEnvironments.tsx:31` — and, because `PyEnv` carries the source too, handed that
relabelled environment to every subsequent `pkg_list`. It is a parameter now: `None` means
*Browse…*, which really is manual, and a refresh passes back the source the row had.

The join the whole feature rests on gets a test rather than an argument.
`a_probed_env_hashes_the_same_as_the_path_it_was_discovered_at` pins that the write key
(`PyEnv.interpreter`, round-tripped through the frontend) and the read key (the discovered
candidate path, before any probe) hash to the same string. If they ever diverge the folder
is written under one key and read under another, and the only symptom is a screen that
keeps asking where the project is.

Verified by running: `pipdock health --path <sample>` then, from an unrelated working
directory, `pipdock health` with no `--path` — same project, out of the store.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 18:49:59 +07:00
poli0981andClaude Opus 5 9c9a46e6aa test(core): commit the sample the ruff fixtures are captured from
The four documents under `tests/fixtures/health/ruff/` were captured from a synthetic
project that lived only on the capturing machine. Re-deriving it is most of the cost of a
tool bump, and getting it subtly wrong is indistinguishable from the tool having changed.

Both of those happened during 0.16.2. An `except:` body of `pass` rather than `return None`
pulled in an `S110` alongside the `E722`, and a one-line `def parse(` produced "unexpected
EOF while parsing" where the real sample produces two errors including "Expected `)`, found
newline". Both read as ruff regressions. What settled it was installing 0.16.0 beside 0.16.2
and running both against the same input — a diff between versions on one interpreter cannot
separate "the tool changed" from "the sample changed", and neither can a diff against a
fixture whose input you no longer have.

So the input is committed, with a README saying what each file exists to produce and which
property of it is load-bearing, and `capture.py` beside it. Running it now reports all four
documents unchanged, which is the sample proving itself.

Kept out of `spikes/capture.py`: that one redacts object addresses and progress bars and is
what the weekly drift job watches. This is four invocations and a path substitution, and
folding it in would hand the drift job a fifth engine it does not have.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 17:42:33 +07:00
poli0981andClaude Opus 5 d7d3e5f685 chore(core): re-capture the ruff fixtures at 0.16.2, and record what did not move
The bump landed as one line in the ledger; this is the part that has to be checked by
running. Both versions were installed side by side and pointed at identical input.

**Nothing changed.** findings.json, nofix.json and syntax-error.json are byte-identical at
0.16.0 and 0.16.2, and over two real packages out of the tools venv (vulture, deptry:
124 and 78 findings) the full finding sets — code, location, message, fix applicability —
compare equal. The doc comments that named 0.16.0 as the verified version now name 0.16.2,
because that claim was re-established rather than assumed.

Only clean.json moves, and not because of ruff: it was three bytes where ruff emits two.
`[]` has no trailing newline, and its three siblings all end in `]`. It had been typed
rather than captured, inside the one directory `.gitattributes` marks `-text` specifically
so captures stay byte-exact.

Two things worth knowing before the next bump, both found by running:

`spikes/capture.py` does not capture these. It knows pip and uv; the health fixtures come
from a synthetic sample with paths normalized to `C:\proj`, and reconstructing that sample
is most of the work. Two of my first attempts differed from the committed documents, and
running 0.16.0 against them is what proved the difference was mine and not ruff's — a
version-to-version diff on one interpreter would have called both a regression.

ruff's built-in default rule set is much wider than `E4,E7,E9,F`: `--isolated`, with no
config anywhere on this machine, still reports S110 from flake8-bandit. Whatever the Health
screen renders, it is not the small default a reader would assume.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 17:42:33 +07:00
poli0981andClaude Opus 5 dbd362fd4d fix(core): a pin bump should not fail a test about serialization
`a_manifest_round_trips_through_its_on_disk_form` asserted `Some("0.16.0")` against a
manifest whose tool versions `write_manifest` derives from the real ledger — so bumping the
one pin Dependabot exists to bump broke a test that is about neither ruff nor versions.

It broke on `main`, not in the PR. Dependabot opened the ruff bump on 2026-08-10 and its CI
went green there; the health module landed on 08-12. A merge whose checks predate the code
they would have caught is a shape worth naming: green on the PR is a statement about the
base it was cut from.

Now read out of `pins()`, which is where the number lives. What the test pins is that the
tools map survives the round trip — the value it carries is the ledger's business.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 17:42:33 +07:00
dependabot[bot] 0c1457639a build(deps): Bump ruff from 0.16.0 to 0.16.2 in /tools
Bumps [ruff](https://github.com/astral-sh/ruff) from 0.16.0 to 0.16.2.
- [Release notes](https://github.com/astral-sh/ruff/releases)
- [Changelog](https://github.com/astral-sh/ruff/blob/main/CHANGELOG.md)
- [Commits](https://github.com/astral-sh/ruff/compare/0.16.0...0.16.2)

---
updated-dependencies:
- dependency-name: ruff
  dependency-version: 0.16.2
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
2026-08-13 17:16:07 +07:00
poli0981andClaude Opus 5 00621be739 docs: where P4 picks up, and the four things it would otherwise rediscover
"Where to pick up" still described P1 as the next slice and pointed at the plan file that
covered S5-S7. Three slices later that sends the next session to the wrong document.

It also still carried the ten-minute TOOLS_PYTHON_MAX probe, whose premise P2 disproved —
deptry ships an abi3 wheel, so there is no cp314 gap and no const. Leaving instructions to
investigate a settled non-question is worse than leaving nothing.

The four notes are things P4 will hit and cannot see coming: plugin-dialog is registered in
Rust but absent from package.json; the opener capability is scoped to github.com so ruff's
rule links fail *silently*; UI-SPEC §6 says 14 of 16, not 15; and deptry reports module
names, so the uninstall handoff has to reconcile yaml/PyYAML or the guard rejects it.

And the open deptry decision is named where the next person will look, rather than only in
a merged PR body.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-12 23:38:30 +07:00
poli0981andClaude Opus 5 3ae4b25331 docs: what the tools actually emit, and what CheckReport was never going to be
CODE-HEALTH-SPEC §3 said the environment is "passed to deptry so installed vs declared vs
imported compares against reality". deptry 0.25.1 has no such option, ignores VIRTUAL_ENV,
and reads whatever its own interpreter can import — so §2's isolation and §3's comparison
are in conflict and isolation wins. §3 now says that, names the bounded cost, and says why
DEP003 is kept rather than suppressed.

§3 also gains what the tools actually emit, since §5's sketch predates anyone running them:
deptry's flat list keyed by module and written to a file *path*, vulture having no
machine-readable output and one message shape with no identifier, ruff's URL keyed by rule
name, and all three exiting non-zero on findings with vulture using 3.

ARCHITECTURE §7 and CLI-SPEC §6 both typed the report CheckReport, which engine.check()
already owns and which is a published `pipdock schema` contract — two unrelated shapes
sharing one name on the wire. It is HealthReport.

CLI-SPEC §5's code 1 now covers "health found something", which is the behaviour a
pre-commit hook needs and the one doctor already had.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-12 23:31:37 +07:00
poli0981andClaude Opus 5 01426b97a8 feat(app): health_run, and a progress forwarder that knows its own channel
NOT_YET is down to three, and only health_fix is still Phase 3's.

forward_progress hardcoded "plan-progress". It now takes the channel as a `&'static str`
rather than a String, because the names are the closed set in EVENTS — a literal typo
becomes a compile error instead of an event nobody is listening for, which is the failure
that leaves a progress bar at zero while the work runs to completion behind it.

The health slot is its own, not Sessions<Session>. A run mutates nothing, so refusing it
while an install streams would be a lock with no invariant behind it — and S5 bug 1 is the
standing warning about claims that wedge. But two Run clicks would put six subprocesses
over one folder, so it needs *a* slot. Sessions<T> was already generic and already tested
with a u32.

It is typed Sessions<HealthSession> rather than Sessions<()> deliberately: P5's health_fix
has to check the user's consent against a report the *server* holds — a count arriving from
the frontend proves nothing about what the frontend displayed — which is the same shape
ack_ok checks a GuardAck against the guard that produced it. Typing it now means P5 does
not redo the slot.

The implicit tools-venv sync runs on the same channel, so a first run on a fresh install
shows the ~15 s bootstrap rather than an unexplained pause, and the total is decided before
the first event because whether a sync is owed is exactly what changes it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-12 23:31:37 +07:00
poli0981andClaude Opus 5 2673da05e5 feat(cli): pipdock health, the last unimplemented command
The M3 stub is gone. `pipdock health` runs the three tools out of the tools venv, syncing
it first when one is owed, and prints a report or emits it as JSON.

Exit 1 when any tool reported a finding, 0 when all were clean. A linter that exits 0 on
findings is useless in a pre-commit hook, and doctor already returns PartialFailure for
"found real problems" — CLI-SPEC §5's description of code 1 is amended to cover it. Real
failures still map through exit_for, so a tools venv that will not build stays
distinguishable from a project with lint.

--tool is a ValueEnum now, so a typo is refused before a subprocess runs and --help lists
the three values CLI-SPEC §3 always documented. That re-blesses golden__help-health.snap;
the diff is the review artefact and it is deliberate. --fix is refused rather than
half-shipped: the write path needs a confirm, a dirty-tree check and a named waiver, none
of which exist, and all of which a user would reasonably assume were there.

The progress total is decided before the first event, because whether a sync is owed is
exactly what changes it and a progress bar cannot learn its own total halfway.

One bug found by running, and it is the same class as P2's: a tool that is *present but
unrunnable* — antivirus damage, a truncated download — reported PD-ENG-001, whose shipped
copy tells the user to install an engine or change it in Settings. exec speaks the engine's
vocabulary and this path is not the engine's. It now reads as PD-HLT-001, "re-sync the
tools environment", which is the thing that actually fixes it. Found by replacing ruff.exe
with a text file of the same name: present, so the sync check said Fresh, and unrunnable,
so the run reached the spawn failure.

That same experiment is what verified the partial report end to end — deptry and vulture
reported normally, ruff landed in problems[], and the run still exited with a report rather
than an error.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-12 23:31:37 +07:00
poli0981andClaude Opus 5 a9d57cf8fb feat(core): HealthReport, and the runner that fills it
The report joins SCHEMA_TYPES; its seven sub-types do not, and do not need to — the
bindings generator hoists every $defs entry into its own TS declaration, so DeptryIssue,
VultureFinding, RuffFinding, RuffFindings, SourceLocation, ToolProblem, DeclaredSource and
FixApplicability all arrive from one registration. Listing them would emit each twice.

Skip-and-continue is the shape. PD-HLT-003 promises a "partial report shown", so a tool
that fails lands in problems[] and the other two still report — the same rule plan::execute
follows for a failed package, and the thing most likely to be built as a whole-run failure
by accident. ToolProblem is deliberately PdError-shaped so the UI hands it to PdErrorRow
rather than inventing a second error presentation. `ran` is what makes an empty tab
readable: without it "no findings" and "never ran" are the same empty array.

Two argv corrections found by reading `deptry --help` after asserting otherwise:

--json-output takes a *location*, not a stream. `-` would have created a file literally
named `-` in the CWD, which is the user's project — the exact §1 boundary the flag was
chosen to respect. It now writes under the tools directory and is deleted on both paths.

**deptry has no environment flag at all.** CODE-HEALTH-SPEC §3 says the env is "passed to
deptry so 'installed vs declared vs imported' compares against reality"; deptry 0.25.1
ignores VIRTUAL_ENV and reads whatever its own interpreter can import. Verified by watching
it report `click` — which exists only in the tools venv — as DEP003 transitive. Putting the
tools venv on a user interpreter's PYTHONPATH does not help either: deptry's own deps come
along. §2's isolation and §3's comparison are in conflict at this version.

Kept all four codes rather than suppressing DEP003: deptry classifies an undeclared import
as DEP003 *instead of* DEP001 when it can see the package, so --ignore DEP003 would turn a
mislabelled finding into a missing one. The cost is bounded and named — the nine packages
the tools venv holds — and both codes mean "you imported something you did not declare",
which §6 already tells the user to fix the same way. A test pins the absence so a future
deptry gaining the flag is noticed.

Excludes are translated per tool, which is not cosmetic: deptry's are anchored regexes, so
`.venv` unescaped also matches `avenv`; vulture takes one comma-separated glob list, not
repeated flags.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-12 23:31:37 +07:00
poli0981andClaude Opus 5 93285ad262 feat(core): three parsers, against captured output rather than a guess
The commit that earns the slice. Parsing is where P3's risk lives — three formats PipDock
does not control, bumped by Dependabot on its own schedule — and all of it is testable
without ever spawning a subprocess. Runners come next; if these are wrong nothing after
them can be right.

CODE-HEALTH-SPEC §5 is amended on three points, each because the tools were run:

deptry emits a **flat list**, one object per (code, module, location), keyed by `module`.
§5 sketched a per-dependency object with a `locations` array; that shape does not exist.
Grouping is therefore PipDock's job, done on (code, module) rather than module alone — one
dependency can be both DEP001 and DEP003, and merging those yields a row whose message
describes only one of them. `dep` is a **module** name: yaml is PyYAML, cv2 is
opencv-python, so anything handing it to a package operation must reconcile it first.

vulture has no machine-readable output at all. Its eighth message shape, `unreachable code
after '<token>'`, quotes the token the code follows rather than a dead identifier — so
`name` is optional and quoting alone cannot decide it. The line number is found by
splitting from the right, because `C:\proj\a.py:12:` has three colons and a left-to-right
split would ship broken on every Windows machine.

ruff's docs URL is keyed by rule **name**: I001 lives at .../rules/unsorted-imports, so
§6's .../rules/<code> 404s. Carried, never constructed. A syntax error arrives as
`invalid-syntax` with a null url — not a null code, which is what §6 assumed.

The exit-code table is the sharpest thing here. All three exit non-zero on findings and
they 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 the tools over a clean directory agrees with it.

Fixtures are captured from the pinned versions and redacted: ruff's `filename` is absolute
and carried this machine's home directory, which is the exact failure CLAUDE.md records pip
shipping to a public repo. They are also `-text` in .gitattributes, as an exception to the
rule above them — under health/ the JSON *is* the tool's output, not a sidecar of ours, and
normalising a captured document's line endings makes it something no tool ever emitted.

One of these fixtures was captured with `2>&1` first and every parse failed: ruff writes
findings to stdout and its warnings to stderr. A test now says so.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-12 23:31:37 +07:00
poli0981andClaude Opus 5 15b5ed292f feat(core): the project folder, remembered per environment
CODE-HEALTH-SPEC §3 persists the folder Health runs in per environment, and gives the
detection order for declared dependencies. Both land here, ahead of anything that runs a
tool.

Per environment rather than globally because deptry's question is "declared versus
installed" — the same folder against a different env is a different answer, so one
remembered folder would make the second env's report quietly wrong.

Its own table rather than a `kv` row: `kv` is documented for scalars that do not deserve
one, and this is keyed and carries a second column. The upsert is the mechanism, not a
detail — env_hash is the primary key, so a plain INSERT would fail the second time the user
picked a folder and their choice would silently not stick. SCHEMA_VERSION 2 -> 3, which is
bookkeeping: migrate() is one idempotent CREATE TABLE IF NOT EXISTS batch and nothing reads
user_version back.

pyproject.toml wins outright over a requirements.txt beside it rather than merging with it,
because that is deptry's own precedence and reporting both would invite the UI to explain a
distinction deptry did not make. Requirements matching is case-insensitive: Windows
filesystems are, and a case-sensitive check would report "nothing declared" for a project
that plainly declares things.

Declaring nothing is a state, not a failure — §3's limited-mode notice. Only a folder that
cannot be read at all is an error.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-12 23:31:37 +07:00
poli0981andClaude Opus 5 90863d8459 ci: name the base interpreter instead of asking PATH for it
The PEP 668 step failed on both legs against a fix that was working. `Get-Command python`
resolves through PATH, and the "Install uv" step earlier in this job puts .uvtools\Scripts
on it — a venv Scripts directory, which holds a python.exe. So the "base" being asked was
that venv, which is correctly not externally managed, and the assertion fired exactly as
designed.

Both interpreters are now named rather than looked up: the marker is planted relative to
$env:pythonLocation's python and the same one is asked about, and .pep668 is created from
it so it is a venv rather than a venv of a venv. The step also ends with an explicit
exit 0, since the runner appends `exit $LASTEXITCODE` to every pwsh step.

The pip upkeep step passed on both legs: pip 22.1.2 -> 26.2.1 on 3.10 where the old pip
runs, and on 3.14 where it cannot and only the ensurepip fallback gets out of it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-12 22:45:02 +07:00
poli0981andClaude Opus 5 8ea9b14ba1 docs: record P1, and the three older defects it surfaced
The stage record in the house format, plus UI-SPEC §5's new row (2 clicks, counted by hand
from the landing screen) and CLAUDE.md's where-to-pick-up.

Three rules worth not re-deriving are written into CLAUDE.md rather than left in the
ROADMAP body, because each is a trap the next slice can walk into: sysconfig inside a venv
answers about the base; venv_scan matches exactly four directory names, which is what makes
hand-verification of any environment feature need one of them; and every pip below the
planner floor is broken on 3.12+, so the case the button exists for is also a pip that
cannot run.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-12 22:45:02 +07:00
poli0981andClaude Opus 5 2ec698a48c fix(ui): five strings that the two-file merge was throwing away
`errors.logPrivacy` rendered as its own key in the error row — spotted by making a
pip-upgrade fail in the running app and reading what came back.

`common.json` and `errors.json` both have a top-level `errors` object: the catalog codes in
one, the row's own furniture in the other. `{ ...common, ...errors }` is a shallow spread,
so the second replaced the first outright and five strings vanished in both languages —
`title`, `retry`, `unknown`, `logPrivacy`, `logCopied`.

`errors.unknown` is the one that matters. PdErrorRow falls back to it deliberately rather
than leaking PdError.message, which is English developer text — so the single thing
standing between a user and an untranslated internal string was itself rendering as the
literal `errors.unknown`.

Neither existing test could see it. The catalog test only asks about Code::ALL, and the
parity test compares en against vi — which agreed perfectly, because both locales lost
exactly the same keys. The new test compares the merge against its own inputs, which is the
only comparison that catches a merge discarding one of them; checked by reverting the fix
and watching it name all five.

The i18n.ts comment already claimed the keys "land exactly where common.json used to hold
them". They did not.

Also gitignores `.claude/`, which holds worktrees and a local launch config.

Found while verifying P1 and fixed here rather than filed: it is five lines, and one of
them is an error path that S7 built specifically so this could not happen.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-12 22:45:02 +07:00
poli0981andClaude Opus 5 f447902257 ci: pip upkeep and PEP 668, against real interpreters
Two steps and a paths entry, all covering things no unit test can reach.

probe.py was not in the filter at all. It sits at src/probe.py rather than under envs/, and
its only tests parse a canned document — so its behaviour against a real interpreter was
never exercised anywhere, which is how the venv/EXTERNALLY-MANAGED bug survived.

The pip upkeep step gets both outcomes out of one matrix: on 3.10 an old pip runs and
upgrades normally, on 3.14 the same pin cannot start and only the ensurepip fallback gets
out of it. It runs with --engine uv, which is meaningful rather than incidental here since
uv is on PATH in this job.

The PEP 668 step plants the marker rather than hoping a runner ships one, and asserts both
directions: a venv must not report managed, and its base must — a fix that simply stopped
looking would pass the first and silently break the code that protects system Pythons.

Both assert through `--env` rather than discovery. envs::venv_scan matches exactly
.venv/venv/env/.env, so a suffixed scratch venv is invisible to `env list` — which the
first draft of these steps got wrong, and which the local dry-run caught.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-12 22:45:02 +07:00
poli0981andClaude Opus 5 2fb2a27593 feat(ui): pip's version where the user is already looking, and one click to fix it
Closes P0-10's GUI half. Every Environments row now shows its pip beside the Python
version and package count, and a row whose pip is below the planner floor offers to fix it.

A second inline button beside Use, not a `⋮` menu: there is no row overflow menu anywhere
in the app, and the first one should not arrive to hold a single action.

Shown only below 22.2, deliberately — not "or when an upgrade exists". That would need
pkg_outdated, which is networked and per-environment, so it would put N network calls on
the landing screen to surface something Installed and Updates already offer. What those
screens cannot do is upgrade a pip so old that the planner behind them refuses to run,
which is exactly this case and the whole reason the button earns its place.

The rule lives in a pure module with its own tests rather than inline in the row, because
the interesting cases are all off-screen: absence is not "old" (a --without-pip venv has
nothing to upgrade), an unreadable version declines rather than guesses, and 22.10 is
newer than 22.2 — which a string comparison gets backwards, putting a mutating button on
an environment eight releases past the floor.

The dialog says no snapshot is taken. DATA-FLOW §9.2's exemption is defensible — a
snapshot restored by pip is no use when pip is what broke — but an unannounced exception
to "every mutation is snapshotted" is how an exemption becomes an erosion.

The row refreshes through envProbe rather than a rescan: one subprocess instead of one per
discovered interpreter, and a rescan can move the selection. It writes a new array rather
than mutating the row, or zustand's reference comparison would leave the old number on
screen until some unrelated field happened to change.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-12 22:45:02 +07:00
poli0981andClaude Opus 5 cc1597bd1f fix(core): a pip too broken to upgrade itself
Every pip below the 22.2 planner floor is broken on Python 3.12+: distutils was removed in
3.12 and pkgutil.ImpImporter with it, so pip cannot import itself. Which means the button
P0-10 exists to offer — shown precisely when pip is below that floor — ran
`pip install -U pip` against a pip that could not start, and the user got a traceback whose
ModuleNotFoundError the classifier reads as PD-ENV-003, "PipDock could not read this
environment". Nothing probed, nothing actionable, on the one path whose whole purpose is
fixing the thing that is broken.

ensurepip is the documented recovery and it is stdlib and offline: the wheel ships with
CPython, so it repairs an environment that has no working installer without needing one.
What it lands is whatever that Python bundles — always at or above the floor for any Python
new enough to have broken the old pip — and the normal upgrade then takes it to latest.

The fallback is driven by asking `pip --version`, not by matching the traceback. A pip that
cannot answer that cannot do anything; one that can had a real install failure worth
reporting as-is. The tracebacks differ by Python version and by pip version, and a rule
matching them would go stale silently. One extra process, only after something already
failed.

Verified against both: 3.11 with a working pip 22.1.2 upgrades normally, and 3.12 with the
same pin — which cannot start — is repaired and ends at 26.2.1 running.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-12 22:45:02 +07:00
poli0981andClaude Opus 5 1e1c868e5f fix(core): a venv is never externally managed
Found while building a below-floor pip to verify P0-10: `pipdock pip-upgrade` refused a
freshly created virtual environment with PD-ENV-002, the code that exists to protect
system Pythons from being mutated.

A venv has no stdlib of its own. `sysconfig.get_path("stdlib")` resolves to the *base*
installation, so `_externally_managed()` was finding the base's marker and reporting it as
the venv's. Every venv created from a Python that ships EXTERNALLY-MANAGED — uv-managed
builds, Debian, Homebrew, Fedora — declared itself unmutable, and PipDock refused to
update, install into, uninstall from or upgrade pip in the one kind of environment PEP 668
tells users to create. uv-managed Pythons are the case that found it, and PipDock ships uv
support.

pip's own check_externally_managed opens with exactly this early return before it looks for
the file; the probe was missing the first half of the rule and keeping the second. The
information was already three functions away — `_hidden_user_site` tests the same
expression, and the probe reports it as `is_venv`.

Wider than P1, and fixed here because P1 is what made it reachable and because a mutation
tool that will not mutate anything is not a bug to route around. The CI gate lands with the
rest of P1's; it plants a marker rather than hoping for one, and asserts both directions —
a fix that simply stopped looking would pass the venv half and silently break PD-ENV-002.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-12 22:45:02 +07:00
poli0981andClaude Opus 5 3ccd93e9f1 feat(core): the environment's pip version, out of a probe that already knew it
P0-10 wants pip's version on every Environments row. The obvious source is engine_info —
and it is the wrong one: it spawns two subprocesses per call, pip's --version and uv's, so
per row that is 2N spawns added to the landing screen on top of the N probe.py runs already
happening there.

The data was already computed and thrown away. pip is an ordinary distribution in
site-packages, `probe_row` holds `probed.dists`, and `packages` is that same list's length.
Reading one more field off it costs nothing and needs no probe.py change, so CLAUDE.md's
hot-path warning does not apply.

env_probe carries it too, and that is load-bearing rather than tidy: refreshing one row
after an upgrade is exactly what that command is for in the next commit, and a refresh
through a path that omitted the field would blank the thing it was refreshing to update.
The compiler caught it, which is the argument for the field not being Option-defaulted.

`pipdock env list --json` grows the same field off the same list, so the two heads cannot
disagree about which pip is installed.

Absent means the probe found no pip — a --without-pip venv, or -I hiding a user-site
install — which is a real state, not "not yet known".

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-12 22:45:02 +07:00
poli0981andClaude Opus 5 5bd21de203 feat(app): pip_upgrade, the command P0-10 needs
P0-10 is a ship blocker that has had an Engine method, a CLI command and no way to reach it
from the app. This is the bridge, and NOT_YET is one shorter.

Returns StepResult. ARCHITECTURE §7 typed it ExecutionSummary, which would need an invented
plan_id, phase, CheckReport and counts — four lies for one step. It carries no versions
either; the caller re-probes, which it must do anyway to refresh the row.

Two DATA-FLOW §9 amendments, both narrow and both written down rather than assumed.

§9.1 gains a fourth plan shape: pip upkeep, which is not resolver-planned and cannot be.
This is S5's lesson a second time — the invariant named the shapes that could produce a
proof and left out the one that structurally cannot. pip below 22.2 cannot emit
--dry-run --report at all, which is exactly the case the feature exists for, so demanding
a report would refuse the only environments that need it. One IPC message parking nothing,
so no waiver type: those exist for a decision made in one message and consumed in another.

§9.2 gains an exemption: no snapshot. A snapshot's only restore path is
`pip install pip==X` executed by pip, so one taken to protect against a broken pip has no
consumer that could use it. Made visible rather than silent — the dialog will say so — which
is what keeps it an exemption instead of an erosion.

The slot is claimed and released on both paths. Two pip invocations against one
site-packages would interleave, and a claim that is never released leaves every later
command answering PD-RES-003 for a plan that never existed (S5 bug 1).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-12 22:45:02 +07:00
poli0981andClaude Opus 5 c281d054c0 fix(core): pip upkeep runs pip, whatever engine is configured
`pipdock pip-upgrade --engine uv` failed at PD-ENG-001 — while the line immediately below
had already reached past the abstraction to call PipEngine.info directly for the version.

Upgrading pip is a pip operation by definition. There is no uv way to do it, which is why
UvEngine::upgrade_pip exists only to refuse, and the engine setting is a preference about
the *user's* environments. Dispatching on it meant the one command with no resolver
between the user and the result was also the one that could be blocked by an unrelated
choice. Same reasoning P2 applied to the tools venv: pip is present wherever Python is.

Both heads now call PipEngine::upgrade_pip directly. The uv refusal stays rather than
becoming an unreachable!() — the trait is public and for_id can still hand a caller that
adapter, where a catalog code beats a panic.

That refusal was also the only thing standing in front of this path, so PipEngine now
carries its own PEP 668 guard, copied verbatim from UninstallFlow::start rather than
reworded so the three cannot drift. DATA-FLOW §2's preamble is "all mutating flows" and
replacing pip in site-packages is one; UpdateFlow has refused since S1 and UninstallFlow
since S5, and this had no guard at all. It stayed harmless only while nothing but a CLI
command could reach it — the next commit gives it a button.

Verified by running: `pip-upgrade --engine uv` on a 3.12 venv reports pip 25.0.1 -> 26.2.1
and exits 0, and a second run is idempotent.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-12 22:45:02 +07:00
poli0981andClaude Opus 5 ef5a1ec805 ci: the tools-venv bootstrap runs against real PyPI on 3.10 and 3.14
health/ was not in the integration job's paths filter, so nothing about the tools venv
would have run on a PR that changed it. tools/ is there too: a Dependabot pin bump has to
re-run the bootstrap, because whether the new pin set still resolves to wheels on both ends
of the supported range is exactly what this job can answer and a unit test cannot.

Four assertions, each one a bug this slice actually had or nearly had: a just-synced venv
reports fresh with all three tools and no pip-audit; a second sync short-circuits in under
10 s; a quarantined ruff.exe reports toolMissing and is repaired by a re-sync; and an
unreachable index gives PD-NET-011, exit 6, and leaves no manifest claiming the venv is
good.

LOCALAPPDATA is overridden to redirect the whole app-data root, so the job never touches a
runner's profile and PipDock needs no test-only configuration knob. Verified locally rather
than assumed, along with the whole script — which is how the `exit 0` at the end was found:
the runner appends `exit $LASTEXITCODE` to every pwsh step and the last command
deliberately exits 6, so without it the step failed with every assertion passing.

.gitignore gains the three scratch directories this job builds in the workspace. Only the
new one is P2's, but ignoring one of three would be odder than ignoring none.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-12 21:31:22 +07:00
poli0981andClaude Opus 5 49deac680c docs: amend CODE-HEALTH §2 to what P2 actually built, and record the slice
CODE-HEALTH-SPEC §2 said the venv is populated "using the configured engine" and left the
Python range open-ended; both are now written as built, with the evidence.

The ROADMAP record carries what a later reader would otherwise re-derive: why there is no
TOOLS_PYTHON_MAX (deptry is abi3, verified on 3.12 and 3.14 from one wheel), why pip-audit
is in the ledger and not the venv (msgpack has no py3-none-any fallback — the earlier
"exposure is zero" reasoning was simply wrong), why the hash covers parsed pins rather than
bytes, why the manifest is deleted first, and that P2 shipped the health-progress producer
while P3 ships the channel.

CLI-SPEC §6's NDJSON paragraph is flagged, not quietly satisfied: no command emits NDJSON
today, and making tools sync the only one that does would be worse than the gap.

CLAUDE.md had M2 as "Stages 1-4 done, S5 next" while its own body said M2 was complete,
and 54 goldens where there are now 58.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-12 21:31:22 +07:00
poli0981andClaude Opus 5 eb51e870dd feat(cli): pipdock tools sync, the re-sync PD-HLT-001 already tells users to run
PD-HLT-001 has shipped copy in both locales saying "Re-sync the tools environment", and
until now there was no way to re-sync anything. This is the missing referent of text the
app already shows, not new surface invented for P2's convenience.

`tools sync` builds or rebuilds; `tools status` reports without triggering one. --force
skips the freshness check, --python skips discovery — the latter looks like a nicety but
is what makes CI deterministic and what proved deptry's cp310-abi3 wheel installs on 3.12
and 3.14 alike.

No Tauri command. NOT_YET, COMMANDS and generated.ts are all untouched, so lib.rs's three
registration tests need no edit. P3's health_run owns the implicit sync CODE-HEALTH-SPEC §2
describes; exposing tools_sync over IPC too would give the frontend two ways to reach one
operation and a race between them.

No NDJSON, despite CLI-SPEC §6. No command in this binary emits it today — they all stream
lines to stderr and a final object to stdout — and adding it for one command would make the
CLI inconsistent with itself. The spec gap is recorded rather than half-closed.

doctor gains a code-health line in both output modes, and deliberately does not fold it
into its exit rule: Health is optional, and a fresh install exiting 1 because it has not
built a tools venv would make doctor useless as a check on everything else.

CancellationToken is re-exported from pipdock_core::engine so a head that builds a
ProgressSink does not need its own tokio-util — two versions of that type would not be the
same token.

Counted by running: cold 15.2 s, warm 31 ms, repair 13.3 s (debug build). Killing a sync
mid-download leaves no orphan pip and no manifest.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-12 21:31:22 +07:00
poli0981andClaude Opus 5 766359083f fix(core): a re-sync that could not repair the state it exists to repair
Both found by running `pipdock tools status --json` and `tools sync` against a real
machine; both passed the whole unit suite.

`pip install -r` over a venv whose pins are already satisfied is a no-op. So deleting
ruff.exe and re-syncing installed nothing, then failed its own verification with
PD-HLT-001 — the exact state PD-HLT-001's shipped copy tells the user to re-sync out of.
And it wedged: the manifest is deleted at the start of a sync, so every later run took the
same path and failed identically, with no way out but deleting the folder by hand.

The venv is now rebuilt rather than repaired. A sync means "make this directory match the
pins", and the only way to guarantee that from an arbitrary broken state is to start from
nothing. The cost lands only where a sync was needed anyway — needs_sync short-circuits
the common case in ~30 ms. A locked file during the teardown gets PD-PRM-002, which says
what to do, rather than a generic "could not build".

SyncNeed::ToolMissing was a newtype variant, and #[serde(tag = "state")] is internal
tagging, which serde cannot use to represent one. It serialized fine in every unit test
that constructed it and panicked the first time `tools status --json` reached a missing
tool. Now a struct variant, with a test that serializes all five states.

Verified: quarantine ruff.exe, `tools status --json` emits
{"state":"toolMissing","tool":"ruff"}, and `tools sync` repairs it in 13.3 s.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-12 21:31:22 +07:00
poli0981andClaude Opus 5 5b9b47fa8a feat(core): sync_tools_venv, over pip and the newest Python that has wheels
Replaces health/mod.rs's todo!() with the three-step bootstrap CODE-HEALTH-SPEC §2
describes: create the venv, install the pin set, verify each tool answers.

Amends CODE-HEALTH-SPEC §2 on the engine. The spec says "using the configured engine";
this uses `python -m venv` and pip unconditionally. uv is a preference about the *user's*
environments, and Health going dark with PD-ENG-001 because uv is not on PATH would be a
failure with no relation to what the user asked for. pip is present wherever Python is.

Three things are load-bearing and would each ship silently broken.

manifest.json is deleted *before* anything is touched, inverting snapshot::create's
data-then-metadata order. A snapshot writes a sidecar that did not exist; a re-sync
replaces a manifest describing the *old* pin set, so a sync that dies half-way would leave
one claiming tools that were just part-replaced. Gone, a torn sync reads as NeverSynced.

--only-binary=:all: turns "a pin has no wheel" from an sdist build ending at PD-BLD-001 —
telling someone who clicked Health to install Visual Studio Build Tools — into a clean
resolution failure mapped to PD-NET-011. It never fires today, which is when to add it.

exec::Command::stopped raises PD-INT-001 for both its watchdog and cancellation, so every
timeout in PipDock currently reads as "PipDock hit an internal error". That defect is
pre-existing and wider than this module, but it is not inherited here: each step remaps its
own timeout, and a cancel is deliberately not caught by the same test.

choose_tools_python excludes EnvSource::VenvScan. That source finds whatever is below the
current working directory, and building PipDock's permanent tools env on a project venv the
user deletes tomorrow breaks Health for a reason nobody could trace back.

Verified by running: 14.6 s cold on 3.14.6, picked over 3.12 by version; manifest carries
the three pins and their reported versions; pip list shows no pip-audit and no
charset-normalizer; a second needs_sync says Fresh.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-12 21:31:22 +07:00
poli0981andClaude Opus 5 1748ea06f5 feat(errors): PD-HLT-004, for a Python that cannot make a venv
`python -m venv` spawning fine and exiting non-zero had no honest code. The tools venv
bootstrap (next commit) is the first thing that can hit it, so the code lands before the
error path that raises it rather than being retrofitted onto one.

None of the three candidates worked. PD-NET-011 is Area::Net, and run::exit_for derives
the exit code from the area — so `tools sync || wait-for-network && retry` would loop
forever on a stripped Python, and both locales' shipped copy is explicitly about
downloading. PD-HLT-001 tells the user to re-sync the tools environment, which is the
operation that just failed. PD-INT-001 is "a PipDock bug", and a Python built without the
venv module is not one. Area::Hlt already maps to exit 1, which is right.

All eight places from CLAUDE.md in one commit, because seven of them are a broken build:
the variant, Code::ALL, both count assertions (32 -> 33), classifier_corpus's
internally_raised table without which the no-code-without-a-fixture gate fails, en+vi copy
under the 90-char cap, regenerated codes.json and bindings, and the catalog doc. Three
goldens re-blessed — Code plus the two schemas that embed it, StepResult and
ExecutionSummary. ResolutionReport does not embed it and did not move.

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