From 4720e1ccb5ebcc4f7637da362f9cbcd920a7ac14 Mon Sep 17 00:00:00 2001 From: poli0981 <127664709+poli0981@users.noreply.github.com> Date: Thu, 13 Aug 2026 19:40:24 +0700 Subject: [PATCH] docs: close Phase 3, with the numbers it was measured at MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- CLAUDE.md | 10 ++++++++-- docs/CLI-SPEC.md | 2 +- docs/ROADMAP.md | 46 +++++++++++++++++++++++++++++++++++++++++----- docs/UI-SPEC.md | 6 +++++- 4 files changed, 55 insertions(+), 9 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 439bee1..be3c4c9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,7 +1,7 @@ # PipDock — working notes for Claude Windows GUI + CLI for bulk-managing Python packages. Tauri 2 + Rust core + React 19. -Repo `poli0981/pipdock` · GPL-3.0 · **Status: M1 and M2 complete; Phase 3's five slices done, the tail next**. +Repo `poli0981/pipdock` · GPL-3.0 · **Status: M1, M2 and Phase 3 complete; Phase 4 (RC → v1.0) next**. ## Read the docs before changing anything @@ -74,7 +74,7 @@ summarises and installs over real commands. **"Update everything" is 4 clicks an against a 50 ms budget. All 16 of UI-SPEC §6's components exist. `docs/ROADMAP.md` Phase 2 has a table per stage and says where to pick up; read it before starting a slice. -**Phase 3's five slices are done.** P4 put Code Health on screen: `PdHealthReport` is UI-SPEC §6's +**Phase 3 is complete** — six slices, exit criteria met and recorded. P4 put Code Health on screen: `PdHealthReport` is UI-SPEC §6's fifteenth of sixteen, `EnvRow.healthProject` remembers the folder per environment, and `health_save_report` writes Markdown + JSON. **`NOT_YET` is down to two**, both M3-general — P5 landed the gated `ruff --fix`, PipDock's first write outside site-packages and `%LOCALAPPDATA%`. P4 *did* need new commands, contrary to the earlier claim — one shipped, and @@ -164,6 +164,12 @@ Things worth knowing before you change any of it: They are what made the `core::flow` refactor provably behaviour-preserving. - **Two tests hold the wire format**: `Code::ALL` must serialize as `as_str()`, and no `SCHEMA_TYPES` property may contain `_`. Both fail at `cargo test`. +- **A control that is not a tab stop is a control a keyboard user does not have.** Making the + package row the only tab stop is right — 200 rows would otherwise be 600 — but every button + inside one was `tabIndex={-1}`, so *Pin* and *Remove* were mouse-only, which is a WCAG 2.1.1 + failure. The ARIA grid answer is a roving tabindex (`←`/`→`, `Esc` back out), and P6 added it. + `Enter` on a row is the **non-destructive** primary — pin, never uninstall. + - **Run it, don't just test it.** Every unplanned bug in Stage 1 *and* Stage 2 came from executing against a real environment, a real runner or a real browser — never from reading code or from a passing suite. Stage 1: the watchdog that never killed anything, `--json` that never parsed, diff --git a/docs/CLI-SPEC.md b/docs/CLI-SPEC.md index 31ff527..4acc29c 100644 --- a/docs/CLI-SPEC.md +++ b/docs/CLI-SPEC.md @@ -77,7 +77,7 @@ requests held back at 2.30.0 (latest 2.32.3) — blocked by apiclient 1.4 (requ `--json` payloads are the serde-serialized core types (`Dist`, `OutdatedDist`, `ResolutionReport`, `ExecutionSummary`, `CheckReport`, `GuardReport`, `HealthReport`) — schema documented by `pipdock schema ` which prints the JSON Schema generated from the Rust types, so scripts can pin against it. Streaming commands (`update`, `install`, `health`) with `--json` emit NDJSON events matching the GUI's `plan-progress` payloads, terminated by a final `summary` object. -> **Not implemented, recorded 2026-08-12 (Phase 3 · P2).** No command in the binary emits NDJSON. `update`, `install`, `uninstall` and `tools sync` all stream engine output as plain lines to **stderr** and print a single final object to stdout; `health` is still the M3 stub. Either this paragraph or four commands are wrong, and closing it means changing the output shape of every streaming command at once — so it is its own slice, not a thing to half-do while adding a fifth. `tools sync` matches the existing behaviour deliberately rather than becoming the one command that is inconsistent with the other four. +> **Not implemented, recorded 2026-08-12 (Phase 3 · P2).** No command in the binary emits NDJSON. `update`, `install`, `uninstall` and `tools sync` all stream engine output as plain lines to **stderr** and print a single final object to stdout; `health` does the same since P3, and `health --fix` prints one document — the `FixReport`, not the pre-fix report, which describes a state that no longer exists by the time the command returns. Either this paragraph or four commands are wrong, and closing it means changing the output shape of every streaming command at once — so it is its own slice, not a thing to half-do while adding a fifth. `tools sync` matches the existing behaviour deliberately rather than becoming the one command that is inconsistent with the other four. `GuardReport.breaks` maps each package being removed to the installed packages that would break, and each of those carries the specifier that says so: `{"numpy": [{"pkg": "pandas", "version": "2.1.4", "constraint": "<2,>=1.26.0"}]}`. `constraint` is the **bare specifier tail** — the distribution name is the map key, so a caller joins the two halves itself; `version` is omitted when the graph does not know it, and `constraint` is empty for an unconstrained dependency. DATA-FLOW §5's dialog needs the specifier to say *"Removing X breaks Y (requires X>=1)"*, and a bare list of names tells the user what will break but not whether they can live with it. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 36ef154..ffc5fb9 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -383,11 +383,17 @@ against the slice that owes it. ### Where to pick up -**Phase 3's five slices are done.** P1 (pip upkeep), P2 (the tools venv), P3 (the runners and -`HealthReport`), P4 (the Health screen) and P5 (the gated `ruff --fix`) are merged, each with a -stage table above. **What remains is the tail:** `Enter` as primary action, folding the `aria-live` regions -(there are ten now, not the six this file used to claim), the doc reconciliation, and the two dead-code -follow-ups P2 deferred. `~/.claude/plans/b-n-b-t-u-ph-n-tranquil-anchor.md` decomposes all of it. +**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. +**Next is Phase 4** — the release pipeline, the manual charter, and a clean install of the RC on a +machine that has never run PipDock. + +`NOT_YET` is down to **two**, both M3-general: `env_add_manual` (*Browse…* has no surface) and +`logs_tail` (needs the logging subsystem). 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. `NOT_YET` is down to three and **only `health_fix` is Phase 3's**. P4 did add two commands after all — `health_save_report` and, had it been taken, `health_cancel` — so the earlier claim that it @@ -413,6 +419,36 @@ Tools venv, deptry/vulture/ruff runners + report UI + gated fix, pip upkeep, bug 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 `