diff --git a/CLAUDE.md b/CLAUDE.md index 37d133e..dc6b097 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 complete; M2 Stages 1–4 done, S5 next**. +Repo `poli0981/pipdock` · GPL-3.0 · **Status: M1 and M2 complete; Phase 3 P2 done, P1 and P3 next**. ## Read the docs before changing anything @@ -73,10 +73,15 @@ 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. -Next is **Phase 3 — Code Health**, and its first slice (P1, pip upkeep) needs only `pip_upgrade`: -`Engine::upgrade_pip`, the CLI command and `engine_info` all exist. `src-tauri/src/lib.rs`'s -`NOT_YET` names the five commands still owed, each against its slice, and three tests keep that -list honest in both directions. +**Phase 3 P2 (the tools venv) is done** — `health::sync_tools_venv` builds +`%LOCALAPPDATA%\PipDock\tools\.venv` from the shipped pins over `pipdock tools sync`, and there is +no `TOOLS_PYTHON_MAX` because deptry ships an abi3 wheel (ROADMAP's premise for that const was +wrong; the record says why). Next are **P1** (pip upkeep — `pip_upgrade` is the only command it +needs, and `Engine::upgrade_pip`, the CLI command and `engine_info` all exist) and **P3** (the three +runners + `HealthReport`, which P2 unblocked). `src-tauri/src/lib.rs`'s `NOT_YET` names the five +commands still owed, each against its slice, and three tests keep that list honest in both +directions. P2 touched none of them: it is CLI-only on purpose, so P3's `health_run` owns the +implicit sync rather than the frontend getting two ways to reach one operation. Three rules from S2/S3 that bind everything after them: @@ -112,7 +117,7 @@ Things worth knowing before you change any of it: - **`cargo test` fails when `ui/src/ipc/generated.ts` is stale.** Fix with `cargo run -p xtask -- bindings`; the failure names that command and the first differing line. -- **The L4 goldens (`crates/pipdock-cli/tests/golden.rs`, 54 snapshots) are the CLI's output +- **The L4 goldens (`crates/pipdock-cli/tests/golden.rs`, 58 snapshots) are the CLI's output contract.** A diff there is a real behaviour change — re-bless deliberately, never reflexively. They are what made the `core::flow` refactor provably behaviour-preserving. - **Two tests hold the wire format**: `Code::ALL` must serialize as `as_str()`, and no diff --git a/docs/CLI-SPEC.md b/docs/CLI-SPEC.md index ac19dd3..0b7e1f8 100644 --- a/docs/CLI-SPEC.md +++ b/docs/CLI-SPEC.md @@ -41,6 +41,8 @@ pipdock health [--path ] [--tool deptry|vulture|ruff] [--fix] # --fix = r pipdock pip-upgrade # upgrade pip inside --env (pip engine paths only) pipdock engine [pip|uv] # show or set configured engine pipdock index refresh # re-pull PEP 691 name index +pipdock tools sync [--force] [--python ] # build/re-sync the Code Health tools venv +pipdock tools status # where it is, and whether it matches the shipped pins pipdock self report-bug # prints prefilled GitHub issue URL (ERROR-CATALOG §4) ``` @@ -73,6 +75,8 @@ 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`) — 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. + `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. `Dist.sizeBytes` is present only when it can be known: it is summed from the distribution's RECORD manifest, which `.egg-info` distributions do not have and which a PEP 660 editable install fills with its import shim rather than its sources. The field is **omitted** in those cases rather than reported as `0`, and it is always omitted on a `Dist` that came from ` list` — neither engine reports a size. Where present it is a lower bound: uncompressed bytes as recorded at install time, excluding `__pycache__` written afterwards. `pipdock list`'s human table does not show it, as it already omits `requiresDist` and `requiresPython`. diff --git a/docs/CODE-HEALTH-SPEC.md b/docs/CODE-HEALTH-SPEC.md index 56c845f..6aa776a 100644 --- a/docs/CODE-HEALTH-SPEC.md +++ b/docs/CODE-HEALTH-SPEC.md @@ -20,12 +20,21 @@ The three tools are **never installed into the user's environment**. PipDock mai ```text %LOCALAPPDATA%\PipDock\tools\ -├─ .venv/ # created with the newest discovered Python (≥3.10) -├─ tools-requirements.txt # exact pins, shipped with the app, updated per release via Dependabot +├─ .venv/ # created with the newest discovered Python (≥3.10), no upper bound +├─ tools-requirements.txt # the resolved three-tool subset actually installed, LF, no comments └─ manifest.json # installed pin set + hash; mismatch with shipped pins ⇒ re-sync ``` -Bootstrap: on first Health run (or pin-set change), create/sync the venv from `tools-requirements.txt` using the configured engine, with progress in the console drawer. Pin policy: exact `==` pins resolved at PipDock release time (Dependabot PRs bump them, in their own group per RELEASE-CI §2); no floating versions at runtime. Offline: if bootstrap can't reach PyPI, Health reports PD-NET-011 and stays disabled; other tabs unaffected. +Bootstrap: on first Health run (or pin-set change), create/sync the venv from `tools-requirements.txt`, with progress in the console drawer. Pin policy: exact `==` pins resolved at PipDock release time (Dependabot PRs bump them, in their own group per RELEASE-CI §2); no floating versions at runtime. Offline: if bootstrap can't reach PyPI, Health reports PD-NET-011 and stays disabled; other tabs unaffected. + +**Amended by Phase 3 · P2, 2026-08-12** — four corrections, each made against a running bootstrap: + +- **pip unconditionally, not "the configured engine".** The venv is created with `python -m venv` and populated with pip whatever the user selected. uv is a preference about the *user's* environments; Health going dark with `PD-ENG-001` because uv is not on PATH would be a failure with no relation to what was asked for, and pip is present wherever Python is. +- **No upper Python bound, and no `TOOLS_PYTHON_MAX`.** ROADMAP assumed "deptry ships compiled wheels; no cp314 wheel means an sdist build". deptry does ship a Rust extension but builds it against CPython's **stable ABI** (`deptry-0.25.1-cp310-abi3-win_amd64.whl`), verified installing on 3.12.10 and 3.14.6 from the same file; vulture and ruff are `py3-none-*`. The one version-tagged member of the closure, `tomli`, also publishes a `py3-none-any` fallback. The install passes `--only-binary=:all:`, so a future gap is a clean `PD-NET-011` rather than an sdist build ending at `PD-BLD-001` — which would tell someone who clicked *Health* to install Visual Studio Build Tools. +- **The repo's `tools/tools-requirements.txt` is the release-time ledger; the file written into `%LOCALAPPDATA%` is a rendering of it.** The ledger carries a fourth pin, `pip-audit`, for the post-1.0 Security tab (PRD P1-1). Health installs three. Rendering rather than copying is also what keeps the build machine's line endings out of the pin hash, which is taken over the *parsed* pin set for that reason. +- **A sync rebuilds the venv rather than repairing it, and deletes `manifest.json` first.** `pip install -r` over satisfied pins is a no-op, so repairing a deleted `ruff.exe` installed nothing and then failed verification with `PD-HLT-001` — the state the code tells the user to re-sync out of. Deleting the manifest first means a torn sync reads as "never synced" rather than as a manifest claiming tools that are half-replaced. + +`python -m venv` exiting non-zero is **`PD-HLT-004`**, added in the same slice: `PD-NET-011` is `Area::Net` and would exit 6, so a script retrying on network failure would loop forever against a broken interpreter. ## 3. Inputs diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 1dcceb9..da24d7d 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -403,6 +403,32 @@ cp314 wheel means an sdist build and PD-BLD-001 with no user action. That answer Tools venv, deptry/vulture/ruff runners + report UI + gated fix, pip upkeep, bug-report deep link, offline states, keyboard map, icon/branding pass. **Exit:** CODE-HEALTH flows pass on two real projects (one pyproject, one requirements-only). +Decomposed **P1** pip upkeep · **P2** the tools venv · **P3** the runners + `HealthReport` · **P4** the Health screen · **P5** the gated `ruff --fix`. Three of the sentence's items are already spent: the bug-report deep link landed in S7, `PdOfflineBanner` in S4, and the keyboard map's `Ctrl+1..8` in S7 — what remains of "keyboard map" is `Enter` as primary action and folding the six `aria-live` regions. The icon/branding pass belongs with Phase 4's release slice; it churns binaries that must not sit inside a feature diff. + +### Phase 3 · P2 — the tools venv — **done 2026-08-12** + +Six commits. Code Health has an environment to run in, and `PD-HLT-001`'s shipped copy — *"Re-sync the tools environment"* — now refers to something the user can actually do. + +| | What landed | +|---|---| +| **Core** | `health::pins`/`pins_hash`/`requirements_body` over `tools/tools-requirements.txt`, which had existed since the first scaffold commit and which nothing read. `sync_tools_venv(tools_dir, base_python, sink)` replaces the module's `todo!()`: create, install, verify. `ToolsManifest` + `SyncNeed` + `needs_sync`, `choose_tools_python`. | +| **Errors** | `PD-HLT-004` (`HltVenvCreateFailed`), the eight-place checklist in one commit. `Code::ALL` 32 → 33. | +| **CLI** | `pipdock tools sync [--force] [--python]` and `tools status`; `doctor` reports whether Health can run at all, without folding it into its exit rule. | +| **Wire format** | None. No Tauri command, no `NOT_YET` edit, no `COMMANDS` entry, no new `SCHEMA_TYPES`. P2 ships the `health-progress` **producer**; P3 ships the channel, when `health_run` exists to emit on it. | +| **Docs** | CODE-HEALTH-SPEC §2 amended on four points; CLI-SPEC §3 gains the commands and §6 gains a recorded, unclosed NDJSON gap. | + +**Five findings that were not in the plan.** + +1. **`TOOLS_PYTHON_MAX` should not exist, and the premise for it was wrong.** ROADMAP called it "the top unknown in all of M3" on the grounds that deptry ships compiled wheels with no cp314 build. deptry ships a Rust extension built against CPython's **stable ABI** — one `cp310-abi3` wheel, installed here on both 3.12.10 and 3.14.6. No ceiling was added; `--only-binary=:all:` makes a future gap a clean `PD-NET-011` instead of an sdist build. +2. **`tools/tools-requirements.txt` already existed and was already Dependabot-wired.** P2 consumes it rather than creating it, which deleted about half a day of the estimate. +3. **A re-sync could not repair the one state it exists to repair.** `pip install -r` over satisfied pins is a no-op, so replacing a deleted `ruff.exe` installed nothing and then failed verification with `PD-HLT-001` — and wedged, because the manifest had already been deleted. The venv is rebuilt now, not repaired. Found by deleting `ruff.exe`; invisible to a suite that only ever synced into an empty directory. +4. **`SyncNeed::ToolMissing(String)` could not be serialized.** `#[serde(tag = "state")]` is internal tagging and serde cannot represent a tagged newtype. It passed every unit test that constructed it and panicked the first time `tools status --json` met a missing tool. Now a struct variant, with a test that serializes all five states. +5. **The pin closure is not ABI-free, and the reason to exclude `pip-audit` is narrower than assumed.** deptry pulls `tomli`, which ships per-CPython wheels — but also a `py3-none-any` fallback, so a missing `cpXXX` build degrades to pure Python. `pip-audit`'s closure contains `msgpack`, which publishes **no** universal fallback and would hard-fail under `--only-binary=:all:`. That, not "exposure is zero", is why the ledger's fourth pin stays out of the venv. + +**Exit criteria, measured by running it** (debug build, i7-14700KF, Python 3.14.6): cold bootstrap **15.2 s**, warm re-run **31 ms**, repair-after-quarantine **13.3 s**. `PIP_NO_INDEX=1` gives `error[PD-NET-011]`, exit **6**, an empty venv and — the thing that matters — **no `manifest.json` left behind**, so the next online run does not believe it is fresh. A forced `--python` onto 3.12.10 installs the same abi3 wheel. A sync killed mid-download leaves **zero orphan `pip.exe`** and no manifest. + +**Deliberately not done:** deleting the dead `engine::uv::parse_dry_run` and flipping `clippy::todo` from `allow` to `warn`. After this slice that function holds the last `todo!()` in the workspace, so the flip is a clean two-line follow-up — but not inside a feature diff. `sync_tools_venv` also takes no `--break-system-packages` path and needs none: the tools venv is PipDock's own and is never PEP 668 managed. + ## Phase 4 — RC → v1.0 (~1–2 weeks) Release pipeline live (bundling, checksums), manual charter executed, docs/README screenshots, legal files public, a clean install of the RC verified on a machine that has never run PipDock. **Exit:** RELEASE-CI §5 checklist fully checked; v1.0.0 published + notify fan-out.