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>
This commit is contained in:
1 parent
2ec698a48c
commit
8ea9b14ba1
3 files changed
+43
-5
No files matched your search
@@ -73,16 +73,32 @@ 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 P2 (the tools venv) is done** — `health::sync_tools_venv` builds
|
||||
**Phase 3 P1 and P2 are done.** P2 built the tools venv — `health::sync_tools_venv` fills
|
||||
`%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
|
||||
wrong; the record says why). P1 closed **P0-10**: pip's version is on every Environments row and
|
||||
*Upgrade pip* is 2 clicks. **Next is P3** (the three runners + `HealthReport`), then P4 (the Health
|
||||
screen) and P5 (the gated `ruff --fix`); `~/.claude/plans/b-n-c-th-b-t-snappy-rabin.md` has all
|
||||
four decomposed, including six corrections to the specs found by running the pinned tools.
|
||||
`src-tauri/src/lib.rs`'s `NOT_YET` is down to **four** — `health_run`, `health_fix`, and
|
||||
`env_add_manual`/`logs_tail` which are M3-general — 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 P1 left behind, all found by running rather than reading:
|
||||
|
||||
- **A venv is never externally managed**, and `sysconfig.get_path("stdlib")` inside one resolves to
|
||||
the *base*. `probe.py` was missing the early return pip's own `check_externally_managed` opens
|
||||
with, so every venv built from a uv-managed, Debian, Homebrew or Fedora Python refused every
|
||||
mutation. Anything reading a path out of `sysconfig` inside a venv is asking about the base.
|
||||
- **`envs::venv_scan` matches exactly `.venv`, `venv`, `env`, `.env`.** A scratch venv named
|
||||
anything else is invisible to `env list` and to the GUI, and `env_add_manual` (*Browse…*) is
|
||||
still owed — so hand-verification of any environment feature needs one of those four names in
|
||||
the working directory.
|
||||
- **Every pip below 22.2 is broken on Python 3.12+** (`distutils`, `pkgutil.ImpImporter`), so the
|
||||
one case *Upgrade pip* exists for is also a pip that cannot run. `upgrade_pip` falls back to
|
||||
`ensurepip`, and decides by asking `pip --version` rather than matching a traceback.
|
||||
|
||||
Three rules from S2/S3 that bind everything after them:
|
||||
|
||||
- **"N pinned excluded" in the table is presentation, not enforcement.** DATA-FLOW §9.5 is enforced
|
||||
|
||||
@@ -405,6 +405,27 @@ 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 · P1 — pip upkeep — **done 2026-08-12**
|
||||
|
||||
Eight commits. **P0-10 is complete in both heads**, and three defects older than the slice went with it.
|
||||
|
||||
| | What landed |
|
||||
|---|---|
|
||||
| **Core** | `PipEngine::upgrade_pip` gains DATA-FLOW §2's PEP 668 guard and an `ensurepip` fallback; both heads call it directly rather than dispatching on the configured engine. `EnvRow.pip_version`, read out of the probe's own distribution list. |
|
||||
| **Bridge** | `pip_upgrade` registered — `NOT_YET` is down to four, two of them M3-general. |
|
||||
| **UI** | pip's version on every Environments row; *Upgrade pip* as a second inline button beside *Use*, below the planner floor only; a confirm that states the snapshot exemption. |
|
||||
| **Docs** | ARCHITECTURE §7's return type corrected; DATA-FLOW §7 (pip unconditionally) and §9.1/§9.2 (a fourth plan shape, and a visible exemption); UI-SPEC §5 gains a row. |
|
||||
|
||||
**Three bugs that were not in the plan, none of them P1's own.**
|
||||
|
||||
1. **A venv was reported externally managed whenever its base was.** A venv has no stdlib, so `sysconfig.get_path("stdlib")` resolves to the base — and every venv built from a Python shipping the marker (uv-managed, Debian, Homebrew, Fedora) refused every mutation with `PD-ENV-002`. pip's own `check_externally_managed` opens with the venv early-return that `probe.py` was missing. Found by making a venv from a uv-managed 3.11 to test P1 and watching `pip-upgrade` refuse it.
|
||||
2. **Every pip below the 22.2 floor is broken on Python 3.12+** — `distutils` and `pkgutil.ImpImporter` are both gone — so the button offered exactly when pip is too old ran a pip that could not start, and the traceback's `ModuleNotFoundError` classified as `PD-ENV-003`, "could not read this environment". Now falls back to `ensurepip`, which is stdlib and offline, chosen by asking `pip --version` rather than matching a traceback that differs by version.
|
||||
3. **Five locale strings were being discarded by the two-file merge.** `common.json` and `errors.json` both carry a top-level `errors` object, and a shallow spread replaced one with the other. `errors.unknown` was among them — `PdErrorRow`'s fallback for an unrecognized code, the thing S7 built so English developer text could never reach a user, rendering as the literal `errors.unknown`. Invisible to both existing i18n tests: one checks `Code::ALL`, the other checks en/vi parity, and both locales lost the same keys.
|
||||
|
||||
**Exit criteria, counted by hand in the running app.** *Upgrade pip* → *Upgrade* is **2 clicks** from the landing screen. The row's version went 22.1.2 → 26.2.1 with exactly `["pip_upgrade", "env_probe"]` crossing the bridge — **no `env_scan`**, which is what "without a rescan" means and the only way to tell the two apart. The button then disappeared, the dialog's default focus was Cancel, and a refused upgrade rendered `PD-ENV-002` with localized copy and incremented `⚠ n`. Against real interpreters: 3.11 with a working pip 22.1.2 upgrades normally; 3.12 with the same pin, which cannot start, is repaired and ends at 26.2.1 running.
|
||||
|
||||
**Deliberately not done:** the *Upgrade pip* button does **not** appear merely because a newer pip exists. That needs `pkg_outdated` — networked, per environment, N calls on the landing screen — to surface something Installed and Updates already offer. What those screens cannot do is upgrade a pip so old the planner behind them refuses to run, which is the only case the button takes.
|
||||
|
||||
### Phase 3 · P2 — the tools venv — **done 2026-08-12**
|
||||
|
||||
Six commits. Code Health has an environment to run in, and `PD-HLT-001`'s shipped copy — *"Re-sync the tools environment"* — now refers to something the user can actually do.
|
||||
|
||||
@@ -123,6 +123,7 @@ app lands. Counted by hand in the running app, never inferred from the markup.
|
||||
| Rollback last snapshot | **4** | Environments → *Open* → timeline entry → *Rollback…* → *Roll back* (2 from a run's summary, via *Roll back to this*) |
|
||||
| Switch engine | **3** | Settings → engine radio → (auto-saved) back |
|
||||
| Run Code Health | **3** | Health → Run (folder persisted) → view |
|
||||
| Upgrade pip | **2** | *Upgrade pip* → *Upgrade* (Environments is the landing screen, so no tab click). The button appears only when pip is below the 22.2 planner floor — the case the ordinary Updates path cannot fix, because the planner it needs will not run. |
|
||||
|
||||
## 6. Component inventory (prefix `Pd`)
|
||||
|
||||
|
||||
Reference in new issue
Block a user