From bee85dcdc2b53cfd21373470e9a97d1300123de2 Mon Sep 17 00:00:00 2001 From: poli0981 <127664709+poli0981@users.noreply.github.com> Date: Tue, 18 Aug 2026 10:43:57 +0700 Subject: [PATCH] chore(release): 1.2.0, and the Security tab recorded MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Version in all five places — `Cargo.toml`, `Cargo.lock`, `package.json`, `package-lock.json`, `tauri.conf.json` — and `cargo metadata --locked` verified after, which is the one-command check that would have caught the `thiserror` lockfile breakage that had `main` red for a day in Phase 4. The ROADMAP stage record, and three rules in CLAUDE.md that the diff does not show: - **A spec can promise a field that has never existed.** SECURITY §6 and PRD P1-1 both asked for a severity pip-audit publishes under neither vulnerability service, and §6 named a venv the code had refused since P2. Found by running the tool and reading its JSON, not by reading the specs against each other. When a spec describes an external tool, the tool is the authority. - **A watchdog is a unit, not a number.** Borrowing Code Health's 120 s gave an audit a linter's budget for a network fetch, and it fired on the first real run. A borrowed constant carries its original units with it. - **Adding a field to a struct that is summed is a bug the suite will not see.** `total_bytes` kept adding three entries after a fourth arrived, with every cache test green. Post-1.0 is down to two items: the dependency-graph view and the scheduled check. Co-Authored-By: Claude Opus 5 --- CLAUDE.md | 24 ++++++++- Cargo.lock | 8 +-- Cargo.toml | 2 +- docs/ROADMAP.md | 105 ++++++++++++++++++++++++++++++++++++-- package-lock.json | 4 +- package.json | 2 +- src-tauri/tauri.conf.json | 2 +- 7 files changed, 133 insertions(+), 14 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 2e5259d..a4f55e5 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-only · **Status: 1.1.0. M1, M2, Phase 3, Phase 4 and the P1 wave are all complete.** 1.0.0 shipped the release pipeline, a protected `main`, the manual charter and legal documents that match the code; 1.1.0 added pin auto-suggest, requirements export/import, the cache manager and the `Ctrl+K` palette. What is left of Post-1.0 is the Security tab, the dependency-graph view and the scheduled check — see `docs/ROADMAP.md`. +Repo `poli0981/pipdock` · GPL-3.0-only · **Status: 1.2.0. M1, M2, Phase 3, Phase 4, the P1 wave and the Security tab are all complete.** 1.0.0 shipped the release pipeline, a protected `main`, the manual charter and legal documents that match the code; 1.1.0 added pin auto-suggest, requirements export/import, the cache manager and the `Ctrl+K` palette; 1.2.0 added the Security tab (PRD P1-1), which was the last major P1 item. **What is left of Post-1.0 is two things** — the dependency-graph view (P1-6) and the scheduled check (P1-7) — and neither is near P1-1's readiness; see `docs/ROADMAP.md`. ## Read the docs before changing anything @@ -142,6 +142,28 @@ Three rules from S2/S3 that bind everything after them: the package slice happened to be stale. After a rollback that is exactly the case. A shared reset constant is only correct for fields with a shared key. +- **A spec can promise a field that has never existed.** SECURITY §6 asked for a *severity* per + finding and PRD P1-1 for "severity-sorted"; pip-audit publishes no severity under **either** + vulnerability service, and never has. §6 also said pip-audit runs from the Code Health tools venv, + which the code had refused since P2 with three tests enforcing the refusal. Both were found by + *running the pinned tool and reading its JSON*, not by reading the specs against each other. When + a spec sentence describes an external tool, the tool is the authority — and the correction belongs + in the spec, not in a workaround that invents the missing field. + +- **A watchdog is a unit, not a number.** `audit::run` inherited Code Health's 120 s `TOOL_TIMEOUT` + and hit it on the first real run, reporting `PD-HLT-003` for a tool that was working. Code Health + is a linter walking a source tree; an audit is a network fetch. Measured: **68 s cold** for one + package, 20.0 s warm for *twelve* — twelve cost 1.4 s more than one, so the cost is a one-off + database fetch and package count is not the risk. The same measurement reopened cancellation, + which P4 had deferred on Code Health's 1.3 s. **A borrowed constant carries its original units + with it.** + +- **Adding a field to a struct that is summed is a bug the suite will not see.** `Target::Audit` + gave `cache::Usage` a fourth entry and `total_bytes` still added three — every cache test passed + and the number on screen was wrong with nothing to say so. The guard asserts on distinct powers + of two so a missing term appears as its own bit rather than as a plausible total. Same shape as + the `entryOf` ternary whose last branch was a hand-maintained negation of every case above it. + - **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 three times now — `SnapshotProof`, `GuardAck`, and P5's `FixConsent`: the report and diff --git a/Cargo.lock b/Cargo.lock index 366cb52..0112088 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3168,7 +3168,7 @@ checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" [[package]] name = "pipdock-app" -version = "1.1.0" +version = "1.2.0" dependencies = [ "jiff", "pipdock-core", @@ -3188,7 +3188,7 @@ dependencies = [ [[package]] name = "pipdock-cli" -version = "1.1.0" +version = "1.2.0" dependencies = [ "assert_cmd", "clap", @@ -3203,7 +3203,7 @@ dependencies = [ [[package]] name = "pipdock-core" -version = "1.1.0" +version = "1.2.0" dependencies = [ "async-trait", "insta", @@ -6371,7 +6371,7 @@ checksum = "ea6fc2961e4ef194dcbfe56bb845534d0dc8098940c7e5c012a258bfec6701bd" [[package]] name = "xtask" -version = "1.1.0" +version = "1.2.0" dependencies = [ "pipdock-core", ] diff --git a/Cargo.toml b/Cargo.toml index df251ab..1509e16 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,7 +3,7 @@ resolver = "3" members = ["crates/pipdock-core", "crates/pipdock-cli", "src-tauri", "xtask"] [workspace.package] -version = "1.1.0" +version = "1.2.0" edition = "2024" rust-version = "1.94" license = "GPL-3.0-only" diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index a242a22..42b4a82 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -740,7 +740,7 @@ Three things it settled that outlive it: ## Post-1.0 (P1 wave) -Security tab (pip-audit), pin auto-suggest, requirements/constraints export-import, cache manager, command palette, dependency graph view, scheduled check. Then P2 candidates by demand: macOS/Linux, per-env engine, elevation broker, winget, JP locale. +Security tab (pip-audit), pin auto-suggest, requirements/constraints export-import, cache manager, command palette, dependency graph view, scheduled check. **Five of the seven have shipped** — four in 1.1.0 and the Security tab in 1.2.0; the graph view and the scheduled check remain. Then P2 candidates by demand: macOS/Linux, per-env engine, elevation broker, winget, JP locale. **About shipped early, in Phase 4** — see above. Two smaller items were added to this wave rather than done at 1.0: @@ -757,9 +757,10 @@ than done at 1.0: way, and the count is worth stating because the sentence here used to read as though there were seven files. -Also worth doing when the Security tab lands: `capabilities/external-links.json` will need an OSV -host, because DISCLAIMER §4 and SECURITY §6 both say findings link to the OSV entry and the current -allowlist would reject it — silently, which is the failure mode SECURITY §4 exists to name. +~~Also worth doing when the Security tab lands: an OSV host in +`capabilities/external-links.json`.~~ **Done in P1-1**, along with the prose §4 requires — and the +entry records what makes it different from `docs.astral.sh`: `advisory_url` *builds* the URL from a +validated id, so the tool chooses the id and never the destination. ### The P1 wave, closed — 1.1.0, 2026-08-14 @@ -866,6 +867,102 @@ one. About tab and do show eight entries, and `about.png` shows nine. Reworded rather than "corrected", because correcting it would have introduced the error. +### Post-1.0 · P1-1 — the Security tab — **done 2026-08-18** + +Eight commits, and **1.2.0**. The last major P1 item; PRD P1-1 has been on the list since the PRD +was written and had a spike behind it from Phase 0. + +| | What landed | +|---|---| +| **Core** | `health::pins_for`/`sync_steps`/`needs_sync`/`sync_tools_venv` take a tool list; `AUDIT_TOOLS`, `audit_dir`; the whole `audit` module — `Advisory`, `AuditReport`, `parse`, `dedupe`, `sort_advisories`, `advisory_url`, `run`, `markdown`; `cache::Target::Audit` | +| **Bridge** | `audit_run`, `audit_cancel`, `audit_save_report`; `AppState.audit` as `Sessions<()>`; the `audit-progress` channel | +| **CLI** | `pipdock audit`, exit 1 on findings | +| **UI** | `PdSecurity`, `PdAuditReport`, `useSecurityStore` — and `PdSidebar`'s `NOT_YET` is **empty** for the first time | +| **Fixtures** | the pip-audit capture SP-4 asked for in Phase 0 and never got, plus a **computed** `audit_report.json` | +| **Docs & legal** | PRD P1-1, SECURITY §4/§6, UI-SPEC §4/§5/§6, CLI-SPEC §3, CODE-HEALTH-SPEC §2, `capabilities/external-links.json`, and three `legal/` documents | + +**Three decisions the owner closed before any code**, each of which would have been expensive to +reverse: + +1. **pip-audit gets its own venv.** `HEALTH_TOOLS` gave two reasons for excluding it and only one + survives the tab existing — "a feature they cannot reach" stops being true, but `msgpack` still + publishes no universal wheel, and `--only-binary=:all:` is load-bearing. A fourth entry in + Code Health's venv would let a new CPython take Code Health down with the Security tab. +2. **The default PyPI vulnerability service, linking out to OSV.** This is what keeps + `legal/PRIVACY-POLICY.md` §3's "exactly one destination" **true**, and measuring showed it costs + nothing: the same environment under `--vulnerability-service osv` returns the *same eight* + advisories, set difference empty in both directions. The 10-vs-16 row difference is pure + duplication. +3. **The specs get corrected rather than the tool worked around** — see below. + +**Two spec claims were not stale but unimplementable.** SECURITY §6 said pip-audit "runs from the +tools venv"; the code had refused that since P2 with three tests enforcing the refusal. And §6 and +PRD P1-1 both promised a **severity** — "(CVE/GHSA id, severity, fixed-in)", "severity-sorted" — +against a field pip-audit has never had under *either* service. A finding carries `id`, +`fix_versions`, `aliases` and `description`, full stop. The order that shipped is package → +fixable → id, which is the one distinction that changes what a user can do; a severity derived +from the id's year or the prose would be a number PipDock invented, shown beside real ones. + +**SP-4's exit criterion is finally met.** It asked for "command line + JSON fixture pinned" in +Phase 0. The command line was pinned in prose; the fixture never was, so every claim about +pip-audit's output had gone unchecked for a year of development. Both are committed now, with +provenance. + +**Four things found by running, none of them visible in a diff.** + +1. **The watchdog was a linter's.** Written against Code Health's 120 s `TOOL_TIMEOUT`, the first + real run hit it and reported `PD-HLT-003` for a tool that was working. Measured afterwards: + **68 s cold** for one package, 18.6 s warm for one, **20.0 s warm for twelve**. Twelve cost + 1.4 s more than one, so the cost is a one-off advisory-database fetch and a 352-package + environment is not the risk — a cold fetch on a slow link is. `AUDIT_TIMEOUT` is 600 s, + matching `exec::DEFAULT_TIMEOUT`. +2. **That number reopened cancellation.** P4 deferred it for Code Health on a measurement of + **1.3 s**; 18-68 s is a different answer to the same question. Wired *and* mapped, because P4 + also recorded that wiring the token alone renders a cancel as "PipDock hit an internal error" — + `exec` reports a cancel and a crash through the same `IntUnexpected`. `AuditReport.cancelled` is + a state, the step ends `Skipped`, and nothing lands in `problems`. +3. **The screen lied while running.** Mid-run the body read *"No audit has run for this + environment"* — while an audit was running. The report is cleared before the command, so `shown` + is legitimately null during a run and the un-run empty state rendered on that basis. That is + P4's "no issues found before anything had run" **inverted**: a true-looking sentence derived + from a state the screen had not loaded. Found by clicking Run against a deliberately slow + bridge; no test saw it, because every other test renders this screen settled. +4. **`total_bytes` under-reported by a whole venv.** Adding `Target::Audit` gave `Usage` a fourth + entry and the sum still added three — with every existing cache test passing. A wrong total with + nothing to say so is worse than a missing row, so the guard now asserts on distinct powers of + two: a missing term shows up as its own bit rather than as a plausible number. + +**The engine changes what is audited, and the tab does not hide it.** `Engine::freeze` passes +`--all` on pip and uv has no such flag, so auditing the SP-4 environment reports **five advisories +in pip 25.0.1 itself** alongside urllib3's eight. A uv-engine audit of the same environment sees +fewer packages. + +**Verified by running, at every level.** `pipdock audit` cold against a real vulnerable environment +with an isolated `LOCALAPPDATA`: the audit venv bootstrapped, wrote its manifest, reported 13 +advisories across 2 packages, `--json` emitted one camelCase document, exit **1**. The second run +did no bootstrap, which is `needs_sync` returning `Fresh` for `AUDIT_TOOLS`. The runner and the +cancel path were each run against the real tool (`--ignored`, `PIPDOCK_AUDIT_DIR`) and each +mutation-checked. The screen was driven in the browser against a stubbed bridge: `audit_run` +crosses **once**, all three listens precede it, both package groups render, and Cancel reaches +`audit_cancel`. + +**The legal gate re-shows once** for every existing user. `legal/EULA.md`, +`THIRD-PARTY-NOTICES.md` and `DISCLAIMER.md` all described pip-audit as planned-and-not-invoked, +and all three are in `build.rs`'s `DOCUMENTS`. That is the mechanism working, and it was decided +before the work rather than discovered after it. + +**Still owner-verifiable only**, because the stubbed bridge cannot reach them: the save dialog, and +clicking an OSV link to confirm the widened allowlist actually opens — which is the one failure +mode that is *silent*, and the reason SECURITY §4 requires the widening in prose. + +**Deliberately not done:** no `pipdock audit --fix`, and no auto-upgrade from a finding. SECURITY §6 +has always said audit never applies anything; "update to fixed version" is the ordinary Update flow, +reached by the user. + +**What is left of Post-1.0 is two items**: the dependency-graph view (PRD P1-6) and the scheduled +check (PRD P1-7). Both were surveyed on 2026-08-18 and neither is close to P1-1's readiness — see +the analysis above for what blocks each. + ### Four items decomposed, easiest first Surveyed 2026-08-14 against the real tree. Ordered by how much already exists, not by value — each diff --git a/package-lock.json b/package-lock.json index d48c75c..f17a8fc 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "pipdock", - "version": "1.1.0", + "version": "1.2.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "pipdock", - "version": "1.1.0", + "version": "1.2.0", "license": "GPL-3.0-only", "dependencies": { "@tanstack/react-virtual": "^3.14.9", diff --git a/package.json b/package.json index f59ab38..e5fe69e 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "pipdock", - "version": "1.1.0", + "version": "1.2.0", "private": true, "description": "A friendly dock for your Python environments — bulk inspect, install, update and clean up Python packages.", "license": "GPL-3.0-only", diff --git a/src-tauri/tauri.conf.json b/src-tauri/tauri.conf.json index 1dbbcb4..c0eb1de 100644 --- a/src-tauri/tauri.conf.json +++ b/src-tauri/tauri.conf.json @@ -1,7 +1,7 @@ { "$schema": "https://schema.tauri.app/config/2", "productName": "PipDock", - "version": "1.1.0", + "version": "1.2.0", "identifier": "com.skullmute.pipdock", "build": { "beforeDevCommand": "npm run dev",