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:
1 parent
3e72ecf7c4
commit
6840e0378a
11 files changed
+141
-14
No files matched your search
@@ -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
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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. |
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
@@ -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
@@ -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
@@ -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
|
||||
|
||||
|
||||
Reference in new issue
Block a user