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>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-08-13 19:30:12 +07:00
1 parent 3e72ecf7c4
commit 6840e0378a
11 files changed
+141 -14

No files matched your search

+16 -7
View File
@@ -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 P1–P4 done, P5 and the tail next**.
Repo `poli0981/pipdock` · GPL-3.0 · **Status: M1 and M2 complete; Phase 3's five slices done, the tail next**.
## Read the docs before changing anything
@@ -74,10 +74,10 @@ 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 P1–P4 are done.** P4 put Code Health on screen: `PdHealthReport` is UI-SPEC §6's
**Phase 3's five slices are done.** 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. **Only `health_fix` (P5) is still Phase 3's in
`NOT_YET`.** P4 *did* need new commands, contrary to the earlier claim — one shipped, 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
cancellation was deferred on a measurement (a warm three-tool run is 1.3 s in release).
Four P4 defects worth not repeating, all found by running: an empty state that said *no issues
@@ -137,9 +137,18 @@ Three rules from S2/S3 that bind everything after them:
- **A dialog is not an enforcement point.** DATA-FLOW §5's three options are what the user *sees*;
what stops a removal is `GuardAck` inside `UninstallFlow::execute`, beside `SnapshotProof`. The
same shape twice: the report and the proof are produced in one call and consumed in another, so
the only way "somebody forgot to look" cannot happen is a value the executing call demands. Any
future flow with a decision between two IPC messages needs its own.
same shape three times now — `SnapshotProof`, `GuardAck`, and P5's `FixConsent`: the report and
the proof are produced in one call and consumed in another, so the only way "somebody forgot to
look" cannot happen is a value the executing call demands. Any future flow with a decision
between two IPC messages needs its own.
- **`ruff --fix` takes no snapshot, and that is the reasoned answer rather than an oversight.**
DATA-FLOW §9.1/§9.2 are scoped to a mutating *engine* call; a fix rewrites the user's source
tree, which no snapshot in this application describes, so one taken here would have no consumer
that could use it — invariant 2's own argument for the pip-upkeep exemption, a second time. The
safety net is the user's own git, asked about **twice** (once to decide what the dialog renders,
once inside `health_fix` to decide what it allows), and the exemption is stated in the confirm
rather than left silent. DATA-FLOW invariant 6 is where this lives.
- **Measure in `--release`, and say which build a number came from.** A debug build measures bounds
checks: the same index load is 572 ms in debug and 140 ms in release, and the same keystroke is
+1 -1
View File
@@ -17,7 +17,7 @@ pub mod vulture;
pub use run::run as run_tools;
pub use run::{RunOptions, has_findings, run_steps};
pub use project::{DeclaredSource, declared_source};
pub use project::{DeclaredSource, declared_source, validate_project};
pub use report::{
DeptryIssue, FixApplicability, HealthReport, RuffFinding, RuffFindings, SourceLocation,
ToolProblem, VultureFinding, markdown,
+67 -1
View File
@@ -3,7 +3,7 @@
//! CODE-HEALTH-SPEC §3: the folder is persisted per environment, and the detection order for
//! declared dependencies is `pyproject.toml` → `requirements*.txt` → none.
use std::path::Path;
use std::path::{Path, PathBuf};
use crate::errors::{Code, PdError, Result};
@@ -45,6 +45,45 @@ impl DeclaredSource {
/// # Errors
/// `PD-ENV-003` when the folder cannot be read at all — a path that is not a directory, or one the
/// user cannot list. Health has nothing to run against in either case.
/// Refuse a project folder Code Health must not run in.
///
/// SECURITY §2 validates package names, versions and interpreter paths; the project folder is the
/// fourth user-supplied path that reaches a subprocess, and with `--fix` it is a **write target**.
///
/// The one refusal that is not merely hygiene: a folder inside the tools directory. ruff would
/// happily rewrite PipDock's own venv, and the failure mode is Code Health breaking itself in a
/// way that looks like a corrupted install.
///
/// # Errors
/// `PD-ENV-003` when the path is not a readable directory, or is inside `tools_dir`.
pub fn validate_project(project: &Path, tools_dir: &Path) -> Result<PathBuf> {
let canonical = project.canonicalize().map_err(|e| {
PdError::new(
Code::EnvProbeFailed,
format!("cannot read {}: {e}", project.display()),
)
})?;
if !canonical.is_dir() {
return Err(PdError::new(
Code::EnvProbeFailed,
format!("{} is not a folder", project.display()),
));
}
// Compared against the canonical tools path, or `..` walks straight past this.
if let Ok(tools) = tools_dir.canonicalize()
&& canonical.starts_with(&tools)
{
return Err(PdError::new(
Code::EnvProbeFailed,
format!(
"{} is inside PipDock's own tools environment; Code Health will not run there",
project.display()
),
));
}
Ok(canonical)
}
pub fn declared_source(project: &Path) -> Result<DeclaredSource> {
let unreadable = |e: &dyn std::fmt::Display| {
PdError::new(
@@ -93,6 +132,33 @@ mod tests {
use super::*;
use std::path::PathBuf;
#[test]
fn code_health_refuses_to_run_inside_its_own_tools_directory() {
// ruff would rewrite PipDock's own venv, and the failure looks like a corrupted install
// rather than like the fix that caused it.
let tools = std::env::temp_dir().join(format!("pd-tools-{}", std::process::id()));
let inside = tools.join(".venv").join("Lib");
std::fs::create_dir_all(&inside).expect("scratch");
let err = validate_project(&inside, &tools).expect_err("must refuse");
assert_eq!(err.code, Code::EnvProbeFailed);
assert!(err.message.contains("tools environment"), "{}", err.message);
// And the escape that a plain string comparison would miss.
let sneaky = inside.join("..").join("..").join(".venv");
assert!(
validate_project(&sneaky, &tools).is_err(),
"`..` must not walk out and back in"
);
let elsewhere = std::env::temp_dir().join(format!("pd-proj-{}", std::process::id()));
std::fs::create_dir_all(&elsewhere).expect("scratch");
assert!(validate_project(&elsewhere, &tools).is_ok());
let _ = std::fs::remove_dir_all(&tools);
let _ = std::fs::remove_dir_all(&elsewhere);
}
#[test]
fn pyproject_wins_over_requirements_beside_it() {
// deptry's own precedence. Reporting both would invite the UI to explain a distinction
+2
View File
@@ -117,6 +117,8 @@ pub async fn run(
opts: &RunOptions,
sink: &ProgressSink,
) -> Result<HealthReport> {
// Refused before any subprocess is spawned in it, and before `--fix` could write to it.
let project = &super::project::validate_project(project, tools_dir)?;
let declared = super::declared_source(project)?;
// **deptry cannot answer its question about a project that declares nothing, and says so by
// failing.** `DependencySpecificationNotFoundError` exits non-zero and writes no report, which
+1
View File
@@ -137,6 +137,7 @@ This table is the surface. A command that is not listed here does not exist; add
| `snapshot_rollback` | `ExecutionOutcome` | Restore the parked snapshot — itself snapshotted first, per DATA-FLOW §8, which is why the outcome always carries one. |
| `health_run` | `HealthReport` | Run the Code Health tools against a project folder. **Not `CheckReport`** — that name is taken by `engine.check()` and is already a published `pipdock schema` contract, so two unrelated shapes would have shared one name on the wire. |
| `health_fix` | `FixReport` | Apply the gated `ruff` fix (P5). **Not `ExecutionSummary`** — there is no plan, no phase and no per-package counts in a fix, and inventing them would be four lies for one operation. Same correction §7 needed for `pip_upgrade`. |
| `health_dirty` | `number \| null` | Uncommitted entries in the parked report's project, so the fix confirm can name one. `null` means no repository, no git, or git failed — a courtesy, not a precondition. Asked again inside `health_fix`: this decides what to render, that decides what to allow. |
| `health_save_report` | `string[]` | Write a finished report as Markdown **and** JSON beside a user-chosen path, returning both. Rust-side rather than a filesystem capability: `dialog:allow-save` lets the webview ask for a path and nothing more. |
| `engine_info` | `EngineInfo[]` | Detected version and availability per engine. Settings shows both, so this returns both. |
| `pip_upgrade` | `StepResult` | Upgrade pip itself in the selected environment. **Not `ExecutionSummary`** — there is no plan, no phase and no per-package counts, and inventing them would be four lies for one step. Carries no versions either (`from`/`to` are always absent): the caller re-probes, which it must do anyway to refresh the row. |
+2
View File
@@ -38,6 +38,8 @@ pipdock pin add|remove <pkg> [--reason "…"] | pin list
pipdock snapshot list | create | diff <id> | rollback <id|latest>
pipdock doctor # engine check + env sanity + (P1) audit summary
pipdock health [--path <dir>] [--tool deptry|vulture|ruff] [--fix] # --fix = ruff only, prompts
# --yes: proceeds on a clean tree,
# REFUSES on a dirty one (exit 2)
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
+2
View File
@@ -72,6 +72,8 @@ Exclusions honored: `.venv`, `venv`, `node_modules`, `build`, `dist`, `.git`, pl
UI (Health tab): run header (folder picker · env chip · Run) → three result tabs with counts; deptry unused-dep rows offer **"Review in Uninstall…"** (jumps to the guarded flow); ruff tab shows `Fix 17 safely fixable issues` → confirm dialog states file count and recommends a clean git tree (PipDock checks `git status --porcelain` if a repo is detected and warns on dirty). Export: `Save report` writes Markdown + JSON to a user-chosen path. CLI mirror: `pipdock health [--tool …] [--fix] [--json]`.
**The fix path, as built (Phase 3 · P5).** One dialog with two states, not two dialogs — two confirms break the click budget and the second is the one nobody reads. Cancel is rendered first and focused, so `Enter` without `Tab` cancels. The confirm carries one unconditional sentence — *PipDock cannot undo this; only your own version control can* — and reserves its danger block for a tree that really has uncommitted work, so a folder outside version control is not nagged about. `git --no-optional-locks status --porcelain --untracked-files=no` is asked **twice**: once when the dialog opens, to decide what to render, and again inside `health_fix`, to decide what to allow. Before anything is written, the command re-reads the project (`PD-RES-002` if the counts moved) and checks every target is writable (`PD-PRM-003` if not) — the fix refuses **as a whole** rather than half-rewriting a tree nothing can restore. Only safe fixes are applied; `--unsafe-fixes` is never passed and **`ruff format` is not wired at all**, because formatting a whole project is a far larger blast radius than fixing seventeen lint findings and §7's non-goals are contractual.
## 6. Interpretation guidance (shown as inline help)
- deptry `DEP001` (missing) often means a dep used but undeclared — the fix is declaring it, which PipDock does **not** automate; copy suggests the exact line to add.
+13
View File
@@ -172,3 +172,16 @@ M3 rather than bolted onto a preview. Until then the preview's promise is precis
3. `plan_execute` refuses a report older than 10 minutes or if the env's probe hash changed (env drifted → re-resolve).
4. Every failure surfaced to UI/CLI carries a catalog code.
5. Pinned packages never appear in a `PlanRequest.upgrades` unless the user explicitly unpinned them this session.
6. **A write *outside* an environment needs a `FixConsent` accepted this session and a re-verified count, and takes no snapshot** (added by P5). Invariants 1 and 2 are scoped to a mutating **engine** call and do not reach `ruff check --fix`, which rewrites the user's *source tree*. No snapshot in this application describes one — a snapshot is a freeze, and §8's rollback is *uninstall the added, install the removed at snapshot versions* — 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 it is **made visible rather than silent**: the confirm states that PipDock cannot undo the change and that only the user's own version control can. The safety net is therefore git, which is why `git status --porcelain` is asked twice — once to decide what the dialog *renders*, once inside the command to decide what it *allows* — and why the dirty finding lives inside `FixConsent` rather than beside it.
### 9.1 The fix flow
```
ReportReady ──Fix──► Confirm(clean | dirty) ──confirm──► Verifying ──► Fixing ──► FixSummary
│ │
└──cancel──► ReportReady └── PD-RES-002 / PD-PRM-003 ──► ReportReady
```
`Verifying` is not decoration and it is not one check. It re-reads the project read-only and refuses with **`PD-RES-002`** when the safely-fixable counts no longer match what the user confirmed — the source-tree analogue of §9's rule 3, for the one thing no snapshot describes — and it refuses with **`PD-PRM-003`** when any target cannot be written. Both happen **before the first byte**: a partial rewrite of a source tree is the worst outcome this flow can produce, because nothing here can undo half of one. ruff can fail to write a file and still exit 1, which the findings-exit rule accepts as a clean run, so the writability check cannot be a classification of the failure afterwards.
`Fixing` is a single `ruff check --fix --output-format json`, which both applies the safe fixes and reports what remains — so `FixReport.remaining` cannot describe a different moment than the fix, and the tab refreshes without a second run. Only **safe** fixes are ever applied; `--unsafe-fixes` is never passed, and `ruff format` is not wired at all (CODE-HEALTH-SPEC §7's non-goals).
+28 -3
View File
@@ -383,9 +383,9 @@ against the slice that owes it.
### Where to pick up
**Phase 3 is four-fifths done.** P1 (pip upkeep), P2 (the tools venv), P3 (the runners and
`HealthReport`) and P4 (the Health screen) are merged, each with a stage table above. **Next is P5,
the gated `ruff --fix`**, then the tail: `Enter` as primary action, folding the `aria-live` regions
**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.
@@ -413,6 +413,31 @@ 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 · P5 — the gated `ruff --fix` — **done 2026-08-13**
Five commits. **`NOT_YET` is down to two, both M3-general**, and PipDock has its first write outside site-packages and `%LOCALAPPDATA%`.
| | What landed |
|---|---|
| **Core** | `health::fix` — `dirty`, `FixConsent`, `consent_ok`, `ensure_writable`, `recheck`, `apply`, `FixReport`; `project::validate_project`; `run::ruff_argv` extracted so the re-check cannot drift |
| **Errors** | `PD-PRM-003`, internally raised. `Code::ALL` 33 → 34, and the checklist is **nine** places, not eight |
| **Bridge** | `health_fix` (the last Phase-3 `NOT_YET` row) and `health_dirty` |
| **CLI** | `pipdock health --fix`, with the `--yes` rule, the usage error, and a one-document `--json` |
| **UI** | the Fix button, one dialog with two states, `data-action="fix"` in the forced-colors list |
| **Docs** | DATA-FLOW gains **invariant 6** and §9.1's state machine; SECURITY §2 and §8; CODE-HEALTH-SPEC §5; CLI-SPEC §3; UI-SPEC §5 and §7 |
**The invariant question, answered rather than dodged.** DATA-FLOW §9.1 and §9.2 are scoped to a mutating *engine* call, and a ruff fix rewrites a source tree, which no snapshot describes. A snapshot taken here would have no consumer that could use it — invariant 2's own argument for the pip-upkeep exemption, a second time. So: **no snapshot**, a fifth proof shape (`HealthReport` + a server-checked `FixConsent`), and the exemption made *visible* the way P1's is, in the confirm's own copy.
**Three things found by running.**
1. **`--json --fix` printed two documents** — the pre-fix report and the `FixReport`. The first describes a state that no longer exists by the time the command returns, and CLI-SPEC §6 states the contract as one document. Found by reading stdout rather than asserting on it.
2. **A planted `git.exe` does not win.** This is the one place PipDock runs a PATH-resolved program with a user-controlled working directory. Windows' legacy search order would make a binary in a cloned repository run; Rust's `Command` does its own resolution and skips the current directory. Verified by planting one, not by reasoning about `CreateProcess`.
3. **The SECURITY paragraph was ahead of the code.** Writing "the project folder is validated and a folder inside the tools directory is refused" made it true rather than aspirational: `validate_project` now refuses it, `..` included, and running Health against `%LOCALAPPDATA%\PipDock ools` answers `PD-ENV-003`.
**Verification, release build, against a seeded repository.** 6 fixable across 2 files with an unfixable `E722` in a third: after `--fix`, `git diff --stat` lists **exactly those two files** — the third untouched, which is what rules out a stray `ruff format` — and the run exits 1 with one finding remaining. Non-TTY without `--yes` refuses (exit 2). A dirty tree with `--yes` refuses naming the entry count (exit 2) and writes nothing. `attrib +R` on one target produces `PD-PRM-003` naming that file, and the **other**, perfectly writable, is not written either: the fix refuses as a whole rather than half-rewriting a tree nothing can restore.
**Deliberately not done:** `ruff format`. §4's `--check` toggle stays read-only and default-off; formatting a whole project is a far larger blast radius than fixing seventeen lint findings, and §7's non-goals are contractual.
### Phase 3 · P4 — the Health screen — **done 2026-08-13**
Ten commits, plus a Slice 0 that got the tool pins to their final version first. **Code Health is on screen**, `PdHealthReport` is UI-SPEC §6's fifteenth of sixteen, and both halves of Phase 3's exit criterion pass.
+7 -1
View File
@@ -14,6 +14,8 @@ PipDock's job is to run package managers against local environments. The realist
- `probe.py` is stdlib-only, written to a temp file with a random name, executed with `-I` (isolated mode: ignores `PYTHONPATH`, user site) so a poisoned env cannot inject code into the probe.
- **Owner decision 2026-07-27 (spike SP-6): `-I` stays, and the cost is disclosed rather than hidden.** Isolated mode also disables user site-packages, so on a *non-venv* system Python the probe sees fewer distributions than `pip list` does — measured at 352 vs 375 on the reference machine. Virtual environments, the primary target, have no user site and are unaffected. The probe therefore reports `hidden_user_site`: the user-site path when it exists, is off `sys.path`, and is non-empty; `null` otherwise. Only when it is non-null does the Installed screen show a note naming the path (`env.partialListing`), so the disclosure is accurate rather than a permanent disclaimer. Dropping to `-E` was rejected: a package in user site is part of the untrusted surface the isolation exists to exclude.
- Child processes run with inherited user privileges only; PipDock never elevates in v1 (PD-PRM-001 blocks instead — elevation broker is P2 with its own review).
- The Code Health **project folder** is a user file-pick that becomes the working directory of three subprocesses and, with `--fix`, the target of a write. It is canonicalized and existence-checked like an interpreter path, and a folder resolving inside `%LOCALAPPDATA%\PipDock ools` is refused — rewriting the tools venv would break Health itself.
- `git` is the one PATH-resolved program PipDock runs with a **user-controlled** working directory (the dirty-tree check). Windows' legacy `CreateProcess` search order would make a `git.exe` planted in a cloned repository win; **verified by planting one** — Rust's `Command` does its own resolution and does not search the current directory. Re-check if the process layer changes.
## 3. PEP 668 policy (protecting the system Python)
@@ -56,7 +58,11 @@ pip-audit runs **from the tools venv** in freeze-file mode: snapshot-freeze the
## 8. Data & privacy engineering
All state is local under `%LOCALAPPDATA%\PipDock\`. Logs may contain package names and paths — the bug-report flow shows the user exactly what will be prefilled and requires manual submission (ERROR-CATALOG §4). No identifiers are generated or stored beyond the random consent record. Deleting the app data folder is a complete reset (documented in Settings → Legal & About).
All state is local under `%LOCALAPPDATA%\PipDock\`.
**One exception, and it is the only one.** `ruff check --fix` (CODE-HEALTH-SPEC §5, Phase 3 · P5) rewrites files in a project folder the user chose. It is PipDock's sole write outside site-packages and `%LOCALAPPDATA%`, it happens only behind an explicit confirm carrying a `FixConsent` the executing call demands, and it is refused entirely — before the first byte — if any target cannot be written. No snapshot is taken, because no snapshot in this application describes a source tree; the safety net is the user's own version control, which the confirm names and `git status` is consulted about twice. §1's threat model does not otherwise contemplate PipDock writing to user source, so this is the paragraph that says it does.
Logs may contain package names and paths — the bug-report flow shows the user exactly what will be prefilled and requires manual submission (ERROR-CATALOG §4). No identifiers are generated or stored beyond the random consent record. Deleting the app data folder is a complete reset (documented in Settings → Legal & About).
## 9. Vulnerability reporting
+2 -1
View File
@@ -135,6 +135,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 (**4** the first time in a project: Health → *Choose folder…* → the OS dialog, which is not PipDock's click → Run → view. The folder is remembered per environment from then on.) |
| Fix ruff findings | **3** | ruff tab → *Fix N…* → *Fix* (from a report already on screen; **5** from the landing screen with a folder remembered, which is the owner's ceiling). Cancel holds default focus, so `Enter` without `Tab` cancels. |
| 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`)
@@ -158,7 +159,7 @@ table and the Pins screen) and `PdRollbackPreview` (DATA-FLOW §8's preview, inc
- Empty states: one mono glyph + one sentence + one action (e.g. Updates empty: `▸ all packages up to date`).
- Offline: banner chip in top bar; search works (local index), metadata panel shows cached-at timestamp.
- Errors: inline with catalog code, human message (localized), and *Details* expanding stderr tail. Toasts only for background completions.
- Destructive confirms (`Force latest`, uninstall with breakage, PEP 668 override) use `--color-danger` primary buttons and require the dialog's default focus to be **Cancel**.
- Destructive confirms (`Force latest`, uninstall with breakage, PEP 668 override, and — since P5 — `Fix with ruff`, the only one that writes outside an environment) use `--color-danger` primary buttons and require the dialog's default focus to be **Cancel**. Each also carries a `data-action` in `styles.css`'s forced-colors list, because high contrast drops every tint and a destructive primary that looks like Cancel is worse than no colour at all.
## 8. Keyboard & accessibility