From d56ad93564a38b1db1c208c1aeaf2220d928fd5b Mon Sep 17 00:00:00 2001 From: poli0981 <127664709+poli0981@users.noreply.github.com> Date: Fri, 14 Aug 2026 17:09:30 +0700 Subject: [PATCH] docs: Phase 4 closed, and the checklist that says so MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All six open items are done, recorded with what was actually exercised rather than "the charter was run": three machines (a real Windows 11 box that had never run PipDock, Windows Sandbox, a Windows 10 VM), no SmartScreen prompt on any — with the caveat that reputation is per-hash and unsigned binaries can still warn a future user, which is why the checksum instructions stay. The three owed charter items plus a non-ASCII Windows *username*, which is a different case from the non-ASCII path because the username is in %LOCALAPPDATA% and therefore in the data root, the logs and the tools venv. The icon is a decision now, not a deferral. It was called a placeholder because nobody had chosen it. RELEASE-CI §5 ticks all eight, and three of the last four turned out to be already done and never ticked — CodeQL default setup was already not-configured, Discussions were already on, the secrets were set today. §2's "main protected" claim is true for the first time; its exact settings, the reason CI / Integration is excluded (a paths-filtered required check never starts, so it blocks forever), the two contexts owned by the ops repo, and how to unwedge it are all written down. Also recorded: the four things Phase 4 found that were not on its list, and the three rules the About tab settled. Post-1.0 gains the Third-Party-Notices generation deferred here, a screenshot re-capture, and the OSV host the Security tab will need. Two long-standing self-contradictions fixed: NOT_YET is two (lib.rs is the authority; ROADMAP and CLAUDE.md each said two in one paragraph and three or four in another), and 15 of UI-SPEC §6's 16 components exist, not 16. Co-Authored-By: Claude Opus 5 --- CLAUDE.md | 44 +++++++++++++--- docs/RELEASE-CI.md | 31 +++++++++-- docs/ROADMAP.md | 125 +++++++++++++++++++++++++++++++++++++-------- 3 files changed, 169 insertions(+), 31 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index b8a75dd..79854c6 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, M2 and Phase 3 complete; Phase 4 in progress — the pipeline builds and installs, the RC tag is the owner's call**. +Repo `poli0981/pipdock` · GPL-3.0-only · **Status: 1.0.0. M1, M2, Phase 3 and Phase 4 all complete — the release pipeline runs, `main` is protected, the manual charter is done, and the legal documents match the code.** Post-1.0 is the P1 wave in `docs/ROADMAP.md`. ## Read the docs before changing anything @@ -73,8 +73,10 @@ Every caller needs an explicit `permissions:` block — callers without one defa and search+install all 2026-08-04). The app discovers, lists, previews, decides, executes, streams, summarises and installs over real commands. **"Update everything" is 4 clicks and "install one" is 4 clicks**, both counted by hand in the running app; search is **22 ms median per keystroke** -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. +against a 50 ms budget. **15 of UI-SPEC §6's 16 components exist** — `PdEnvSwitcher` alone does +not, and nothing needs it while the header shows the selected interpreter. (This line said 16 of 16 +for two milestones; §6 itself was corrected in P4 and is the authority.) `docs/ROADMAP.md` Phase 2 +has a table per stage and says where to pick up; read it before starting a slice. **Phase 3 is complete** — six slices, exit criteria met and recorded. P4 put Code Health on screen: `PdHealthReport` is UI-SPEC §6's fifteenth of sixteen, `EnvRow.healthProject` remembers the folder per environment, and @@ -99,11 +101,14 @@ wrong; the record says why). P1 closed **P0-10**: pip's version is on every Envi *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 +P2 touched no `NOT_YET` entry: 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. +**`NOT_YET` is two**, and only two: `env_add_manual` and `logs_tail`, both M3-general. +`src-tauri/src/lib.rs:25-28` is the authority and three tests keep it honest in both directions — +this file used to say "four" in one paragraph and "two" in another, each true when written and +neither updated. + 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 @@ -177,6 +182,33 @@ Things worth knowing before you change any of it: run showed *Back to packages* twice and every suite stayed green. Found by a human using the installed build. When adding a component test, ask what renders it. +- **A green badge is not a green `main`.** The README badge is per *workflow file* and shows that + file's last run, which may be a schedule on a different commit. `main` was red for a day at + `3eeda05` — every cargo job failing before a crate compiled — because `Cargo.lock` carried a + dependency edge to `thiserror 2.0.19` while its package entry said `2.0.20`, which `--locked` + refuses to repair. Start with `gh run list --branch main`, not the badge. And when bumping a + version: it lives in **five** places (`Cargo.toml`, `Cargo.lock`, `package.json`, + `package-lock.json`, `tauri.conf.json`) and they move together or you have reproduced this bug. + `cargo metadata --locked` is the one-command check. + +- **A `docs/` fix and a `legal/` fix are two different changes.** Removing the self-updater updated + `THIRD-PARTY-NOTICES.md` and not `PRIVACY-POLICY.md`, so the shipped privacy policy described a + feature that no longer existed — and, worse, still told users to delete `%LOCALAPPDATA%\PipDock\` + for "a complete reset", which is the folder the program installs into. `docs/SECURITY.md` had + recorded the data-root move correctly the whole time. Anything under `legal/` is what a *user* + reads; grep it separately whenever behaviour changes. Every `legal/*.md` and `LICENSE` is hashed + into `PIPDOCK_LEGAL_DOCS_HASH`, so any edit re-shows the gate once — that is the mechanism + working, not a regression. + +- **A spec sentence is not a test.** UI-SPEC §8 asserted for two milestones that `Ctrl+1..N` refused + while a plan owned the screen. It did not: `App.tsx` guarded on `guardOpen`, and `PANEL_PHASES` + excludes `guard` on purpose, so the two sets are disjoint and guarding on one guarded neither. + Invisible until the plan ended and dropped the user on a tab they never chose. + +- **Appending to `NAV_KEYS` is free; inserting is not.** `Ctrl+9` for About cost one array entry. + Four comments claimed "a ninth entry would renumber `Ctrl+1..8`" and had the reason wrong — + Snapshots stays a mode of Environments because it would sit *beside* Environments, an insert. + - **Building and installing are their own test tier, and nothing else substitutes.** The first bundle ever produced exposed three defects in one afternoon: `release.yml` could not have run (`--locked` is cargo's flag and goes after `--`), the installers shipped no `pipdock.exe` at all, diff --git a/docs/RELEASE-CI.md b/docs/RELEASE-CI.md index b1a9234..1f9ae67 100644 --- a/docs/RELEASE-CI.md +++ b/docs/RELEASE-CI.md @@ -38,6 +38,24 @@ permissions: { contents: read } `main` protected (PR + green CI required). SemVer; tags `vX.Y.Z`. Conventional commits feed the changelog generator. +**Applied 2026-08-14, and it had been false until then** — `/branches/main/protection` returned 404 for four milestones, which is also why `gh pr merge --auto` merged immediately on this repo rather than waiting: with no required checks there is nothing for auto-merge to wait on. Exact settings: + +| Setting | Value | Why | +|---|---|---| +| Required checks | `fmt · clippy · test`, `cargo audit`, `lint · typecheck · test · build / build`, `npm audit`, `analyze / Analyze (javascript-typescript)` | the five that run on **every** PR | +| Check app | pinned to `app_id: 15368` (`github-actions`) | a check from another app cannot satisfy a requirement | +| `enforce_admins` | `true` | the owner is the only contributor; protection that exempts them protects nothing | +| Required approvals | **0** | a solo owner cannot approve their own PR, so 1 would deadlock. A PR is still required | +| `strict` | `false` | up-to-date-before-merge is friction on a repo that rebase-merges | +| Linear history | `true` | matches rebase-merge | +| Force pushes / deletions | `false` | | + +**`CI / Integration` is deliberately excluded, and this is the trap worth remembering:** its `pull_request` trigger is `paths:`-filtered, so on a docs-only or UI-only PR it never starts — and a required check that never starts stays *pending forever*. Requiring it would deadlock exactly the PRs it has no opinion about. `Re-capture against the latest engines` is schedule-only and excluded for the same reason. The bare `CodeQL` check belongs to the `github-advanced-security` app rather than Actions and is left out too. + +**Two required contexts are named by the ops repo, not by this one.** `analyze / Analyze (javascript-typescript)` and `lint · typecheck · test · build / build` come from `poli0981/.github`'s reusables. If either job is renamed upstream, every PipDock PR deadlocks with no obvious cause and no failing check to point at — the fix is to update the protection payload, not the code. + +**If protection wedges**, `PUT` the same endpoint with `enforce_admins: false`, or `DELETE /branches/main/protection`. Worth knowing before it is needed rather than discovering it during an incident. + Dependency updates use **Dependabot** (`.github/dependabot.yml`) — the portfolio standard, as evidenced by the ops repo's `dependabot-summary.yml`; there is no Renovate configuration anywhere in the ops repo. Four ecosystems: `cargo`, `npm`, `github-actions`, and `pip` scoped to `tools-requirements.txt` (the Code Health pins). Weekly schedule with minor/patch grouped per ecosystem; security advisories arrive as **immediate, ungrouped** PRs (Dependabot's default for security updates), and the `pip` ecosystem stays its own group so Code Health pin bumps are reviewable in isolation. Watching `pip`/`uv` releases to trigger the parser-fixture job is the scheduled job in `ci-integration.yml`, not the dependency bot. ## 3. Release pipeline (tag `v*`) @@ -66,7 +84,12 @@ Two active lines at most: latest release gets features; previous minor gets secu - [x] `.github/ISSUE_TEMPLATE/bug_report.yml` (shipped in this suite) + `config.yml` disabling blank issues. - [x] `.github/dependabot.yml` covering cargo, npm, github-actions and the Code Health pins. - [x] `rust-toolchain.toml`, `.nvmrc` (24), `Cargo.lock`/`package-lock.json` committed. -- [ ] **Repo settings (owner, via the GitHub UI or `gh` — not committable):** branch protection on `main`; disable Advanced Security → CodeQL *Default setup* (the reusable is advanced-setup and is rejected at upload time otherwise); enable Discussions for the issue-template contact links. -- [ ] **Secrets via `gh secret set`:** the Discord webhooks (`DISCORD_RELEASES_WEBHOOK`, `DISCORD_REPO_WEBHOOK`, `DISCORD_CI_WEBHOOK`). No signing key — see §3. -- [ ] Replace the placeholder app icon (`src-tauri/icons/`) in the ROADMAP Phase 3 branding pass. -- [ ] README badges: CI, CodeQL, release, license. +- [x] **Repo settings (owner, via the GitHub UI or `gh` — not committable):** branch protection on `main`; disable Advanced Security → CodeQL *Default setup* (the reusable is advanced-setup and is rejected at upload time otherwise); enable Discussions for the issue-template contact links. +- [x] **Secrets via `gh secret set`:** the Discord webhooks (`DISCORD_RELEASES_WEBHOOK`, `DISCORD_REPO_WEBHOOK`, `DISCORD_CI_WEBHOOK`). No signing key — see §3. +- [x] App icon settled (`src-tauri/icons/`). It was called a placeholder because nobody had chosen it; the owner chose it in Phase 4, which is what "a brand decision" needed. +- [x] README badges: CI, CodeQL, release, license. + +**Closed 2026-08-14, and three of the last four were already true.** CodeQL *Default setup* read +`not-configured` and Discussions were already on — both had been done and never ticked, which is +its own small lesson about a checklist nobody reads back. The Discord secrets were set the same +day. Branch protection was the only genuinely outstanding item; §2's exact settings are below. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index f29ff50..d2c51bc 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -386,19 +386,16 @@ against the slice that owes it. **Phase 3 is complete.** P1 (pip upkeep), P2 (the tools venv), P3 (the runners and `HealthReport`), P4 (the Health screen), P5 (the gated `ruff --fix`) and P6 (the tail) are all merged, each with a stage table above, and the exit criteria are recorded with the numbers they were measured at. -**Next is Phase 4** — the release pipeline, the manual charter, and a clean install of the RC on a -machine that has never run PipDock. +**Phase 4 is complete too** — see its section below. `1.0.0` is tagged. `NOT_YET` is down to **two**, both M3-general: `env_add_manual` (*Browse…* has no surface) and -`logs_tail` (needs the logging subsystem). The M3 debt list is otherwise unchanged: dead +`logs_tail` (needs the logging subsystem). `src-tauri/src/lib.rs:25-28` and the three tests that +police it in both directions are the authority; a paragraph here used to say "three" and was +describing the state before P5 merged. The M3 debt list is otherwise unchanged: dead `pins::hold_requirements`, unread `allow_externally_managed`, DATA-FLOW §8's dry-run resolve, snapshot retention, `PdEnvSwitcher`, CLI-SPEC §6's NDJSON gap, and `RunOptions`/the confidence floor reaching Settings. -`NOT_YET` is down to three and **only `health_fix` is Phase 3's**. P4 did add two commands after -all — `health_save_report` and, had it been taken, `health_cancel` — so the earlier claim that it -needed none was wrong; both land implemented, so neither is owed. - The four things P4 was warned it would otherwise rediscover all held: `@tauri-apps/plugin-dialog` really was absent from `package.json`, the opener really was scoped to GitHub only, UI-SPEC §6 really said 14, and deptry really does name a module rather than a distribution. What the warnings @@ -654,27 +651,113 @@ window; the real `HWND` style carries no `WS_MAXIMIZEBOX` and still carries `WS_ steps against real artifacts); the installer ships both binaries; program and data no longer share a directory; the shell bugs above are fixed; README carries the badges RELEASE-CI §5 asks for. -**Still open, in rough order:** +### Phase 4 closed — 2026-08-14 -1. **A genuinely clean machine.** This one has run PipDock; isolating the app-data root - approximates the criterion rather than meeting it. -2. **SmartScreen.** The installer has only ever been run scripted, and SmartScreen is an Explorer - behaviour — it needs a double-click on a freshly downloaded file. -3. **The rest of the manual charter** (TESTING §4): the VI locale sweep of the mutation dialogs, - corporate-proxy simulation for `PD-NET-002`, and cancel mid-Phase-B. Fixtures for the scale and - non-ASCII cases are already recorded above. -4. **The icon**, still the Tauri-era placeholder — a brand decision, deliberately not invented. -5. **Version and tag.** Everything is `0.1.0`; the RC and the `v*` tag that fires `release.yml` - are the owner's call, and that tag is the first time the pipeline runs for real. -6. **`docs/README` screenshots**, which want the finished icon first. +All six of the items above are done. What actually happened, item by item, because "we ran the +charter" ages into nothing: -**Repo scaffolding (RELEASE-CI §5)** still owes the two owner-only items: branch protection plus -disabling CodeQL default setup, and the three Discord webhook secrets. Neither is committable. +1. **A genuinely clean machine.** The RC was installed and driven on a real Windows 11 machine + that had never run PipDock, plus **Windows Sandbox** and a **Windows 10 VM under VirtualBox**. + Three installs, three uninstalls, no failures. +2. **SmartScreen produced no prompt** on any of the three. Worth knowing *why* that is not a + guarantee: SmartScreen's reputation check is per-file-hash and per-publisher, and the binaries + are still not EV-code-signed, so a warning on some future user's first download remains + possible. The README's checksum instructions are the answer either way, and they stay. +3. **The manual charter is complete** (TESTING §4). The three that were owed — the VI locale sweep + of the mutation dialogs, cancel mid-Phase-B, and corporate-proxy simulation for `PD-NET-002` — + were all executed, as was a **non-ASCII Windows username**, which is a different case from the + non-ASCII *path* already covered by `E:\sp5\dự án tiếng việt`: the username is in + `%LOCALAPPDATA%`, so it is in the data root, the log paths and the tools venv. +4. **The icon is decided, not deferred.** The green triangle stays. It was called a placeholder + because nobody had chosen it; the owner has now chosen it, which is what "a brand decision" + needed. `bundle.icon` still names only `icons/icon.ico` — correct for a Windows-only build; the + Square*.png set is Microsoft Store furniture nothing reads. +5. **Version is `1.0.0`** in all five places (`Cargo.toml`, `Cargo.lock`, `package.json`, + `package-lock.json`, `tauri.conf.json`). The `v1.0.0` tag is the first real run of + `release.yml`. +6. **Seven screenshots** are in `screenshot/` and referenced from the README. They predate the + About tab, so their sidebar has eight entries where 1.0 has nine. + +**Repo scaffolding (RELEASE-CI §5) is complete**, and three of its items turned out to be already +done and undocumented: the Discord webhook secrets were set 2026-08-14, CodeQL *Default setup* was +already `not-configured` (which is what the advanced-setup caller requires), and Discussions were +already on. **Branch protection** was the only genuinely outstanding one and is now applied over +the API — five required checks, `enforce_admins: true`, PR required, linear history. RELEASE-CI §2 +has claimed `main` was protected since it was written; that claim is true for the first time. + +`CI / Integration` is deliberately **not** a required check: its `pull_request` trigger is +`paths:`-filtered, and a required check that never starts leaves a PR pending forever — so +requiring it would deadlock every docs-only and UI-only PR. + +### What Phase 4 found that was not on its list + +Four things, three of them defects that had been shipping. + +**`main` was red and nobody knew.** `Cargo.lock` at `3eeda05` carried a dependency edge to +`thiserror 2.0.19` while its package entry said `2.0.20` — a lockfile cargo wants to repair and +`--locked` forbids repairing, so every cargo job in every workflow died before compiling a crate. +Same shape as the ruff-pin defect in P4: a Dependabot bump whose base predated the code that would +have caught it. The lesson is the one already written — **check `gh run list` before believing a +green badge**, because the badge is per-workflow-file and shows the last run, not the last commit. + +**The privacy policy described a self-updater deleted two weeks earlier**, and told users to delete +`%LOCALAPPDATA%\PipDock\` for "a complete reset" — the folder the program installs into. Following +the shipped privacy policy uninstalled the application. `d829c4f` had updated +THIRD-PARTY-NOTICES and not PRIVACY-POLICY; SECURITY §8 recorded the data-root move and the legal +document never got it. **A `docs/` fix and a `legal/` fix are two different changes**, and the +second is the one a user reads. + +**Four documents credited `specta`/`tauri-specta`,** which `bindings.rs` has recorded since M1 that +the project deliberately does not use. One of them was `legal/THIRD-PARTY-NOTICES.md`, i.e. a +licence attribution for a dependency that does not exist, beside eleven that do and were unlisted. + +**`Ctrl+N` never refused while a plan owned the screen,** despite UI-SPEC §8 asserting it did since +S3. `App.tsx` guarded on `guardOpen`, and `PANEL_PHASES` excludes `guard` on purpose — the two sets +are disjoint, so guarding on one guarded neither. Invisible, because the sidebar was disabled and +the panel kept rendering, until the plan finished and dropped the user on a tab they never chose. +**A spec sentence is not a test.** Found by reading `App.tsx` to add a ninth tab. + +### The About tab (early out of the Post-1.0 wave) + +UI-SPEC §4 has specified *Legal & About* since the spec was written, as a section inside Settings, +and four milestones shipped without it — so after acceptance there was no in-app path back to the +documents at all. It is the ninth tab instead, because a read-only surface folded into a screen of +controls is the thing that never gets built. + +Three things it settled that outlive it: + +- **Appending to `NAV_KEYS` is free; inserting is not.** `Ctrl+9` cost one array entry and one + label. Every comment saying "a ninth entry would renumber `Ctrl+1..8`" was wrong about the + reason: Snapshots stays a mode of Environments because it would have to sit *beside* + Environments, which is an insert. +- **A review is not a revocation.** Re-opening the gate by setting `accepted = false` was one line + and would have offered Accept and a Decline-that-quits to someone re-reading their privacy + policy. `useLegalStore.review` is its own flag and the gate takes a presentational prop. +- **`app_info` fired twice per mount, and only the running app said so.** StrictMode's doubling is + dev-only, but it exposed the real one: `key={nav}` remounts `
`, so every visit re-fetched a + value baked in at compile time. `PdAbout.test.tsx` asserted one call and passed, because Testing + Library does not use StrictMode. **Run it, don't just test it** — the twenty-fifth time. ## 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. +**About shipped early, in Phase 4** — see above. Two smaller items were added to this wave rather +than done at 1.0: + +- **Generate `legal/THIRD-PARTY-NOTICES.md`.** Both it and SECURITY §7 claimed `cargo about` + + `license-checker` regenerated it at release into a `licenses/` directory; no `about.toml`, no + such directory and no such release step have ever existed. The claim now describes what is + actually done — a hand-maintained inventory of the *direct* dependencies, reconciled against the + manifests at each release. Making it true is the item. Doing it at 1.0 would have meant + complicating `release.yml` on the first run it had ever had. +- **Re-capture the screenshots** once anything visible changes; the seven in `screenshot/` show an + eight-entry sidebar. + +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. + ## Standing risks | Risk | Mitigation |