101 Commits
Author SHA1 Message Date
dependabot[bot] fdc51a8f2a build(deps): Bump rusqlite from 0.42.0 to 0.43.0 (#114)
Bumps [rusqlite](https://github.com/rusqlite/rusqlite) from 0.42.0 to 0.43.0.
- [Release notes](https://github.com/rusqlite/rusqlite/releases)
- [Changelog](https://github.com/rusqlite/rusqlite/blob/master/Changelog.md)
- [Commits](https://github.com/rusqlite/rusqlite/compare/v0.42.0...v0.43.0)

---
updated-dependencies:
- dependency-name: rusqlite
  dependency-version: 0.42.0
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
2026-11-21 23:54:33 +07:00
poli0981andClaude Opus 5.5 2303aa2c7e fix(ci): no unused-crate inspection in Qodana for Rust
One run in five on #120 reported "Unused crate: sha2", the crate
env_hash is built on, on a commit that changed only a Markdown file.
Every run's sanity check finds the Cargo project only partly loaded in
the linter's container, and the inspection sometimes concludes from
that. A baseline entry would not hold, because its fingerprint hashes
neighbouring lines that Dependabot rewrites weekly.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 23:22:12 +07:00
poli0981andClaude Opus 5.5 807d9bf839 docs(roadmap): the second smoke, on the review's fixes
The installed build from a fresh release dry run, against a real
--symlinks venv: added as itself with its own identity, listed beside
its base with its own packages, removed for good; a deleted venv's
broken row removed for good; the installed CLI agreeing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 23:22:12 +07:00
poli0981andClaude Opus 5.5 bb056c511d fix(core): a venv made with --symlinks is its own environment
Its python.exe links to the Python it was made from, and env_hash
followed the link, so the venv's pins, snapshots and cached graph,
report and audit were filed under its base. Nothing showed it while no
screen could list the two apart; Add interpreter now can. A venv's own
interpreter, recognised by its pyvenv.cfg, is resolved only up to its
folder. No other path's identity changes, and a linked venv's earlier
pins and snapshots stay with the base they were filed under.

Checked against a real --symlinks venv: `env use` stores the venv with
its own prefix, and the venv and its base keep two identities.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 23:22:12 +07:00
poli0981andClaude Opus 5.5 2539950cd5 fix: what an independent review of 1.6.0 found
A venv made with --symlinks is run and stored as itself, not as the base
Python its python.exe links to: validate_interpreter returned the
canonical path, so `--env .venv update --all --yes` would have changed
the system Python. Canonicalizing now only decides where a link leads
and whether it is PipDock's own; a link to another program is refused,
and a Microsoft Store alias (os error 1920) is judged by its own path.

The GUI merges and removes an added row by its path rather than by
envHash, which follows links: a re-add replaces a broken row, removal
sticks for an entry whose file is gone (a share), and neither runs
during a scan. Added entries are validated again on every listing in
both heads (envs::probe_listed), and the CLI checks its stored default
when it uses it. `env remove` makes a typed path absolute first.

SECURITY section 2 and env_probe's doc claimed an enforcement point over
IPC; they now say what is checked, and backlog X36-b records the rest.
notify.yml reports a Triage failure on a pull request.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 23:22:12 +07:00
poli0981andClaude Opus 5.5 a85242db1a fix(ci): an ASCII name for the Vietnamese wording in triage.cjs
Qodana for JS (JSNonASCIINames, High): a variable named in Vietnamese
mixed ASCII and non-ASCII. The text it holds is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 23:22:12 +07:00
poli0981andClaude Opus 5.5 567142901f docs(changelog): 1.6.0
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 23:22:12 +07:00
poli0981andClaude Opus 5.5 e15d1637b0 fix(cli): env remove <dir> finds the deleted venv it exists for
A new integration test found it: removing an added venv by its
directory answered 'not on the list' once the venv was gone — the very
case remove is for — because interpreter_in resolves only an interpreter
that exists and fell back to the bare directory. The directory is now
also matched as the venv whose interpreter it would hold
(envs::venv_interpreter), existing or not.

tests/manual_envs.rs drives the binary with an app-data root of its own
and no Python: a non-interpreter is refused and nothing stored; an added
interpreter whose file is gone is listed with PD-ENV-001 and removed by
its directory; removing it again is not an error. The first failed
against the code before this fix.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 23:22:12 +07:00
poli0981andClaude Opus 5.5 11a643777b docs: AI-DISCLOSURE for 1.6.0 — who decided, who did, and the eight checks
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 23:22:12 +07:00
poli0981andClaude Opus 5.5 957343c07b fix(core): a free-threaded python3.14t.exe is a Python too
Found by running env list against this machine: the python.org
installer puts python3.14t.exe (PEP 703) beside python.exe, the registry
lists it, and the new name rule refused it — so Add interpreter… could
not add an interpreter discovery itself reports. A version may now end
in t; pythonw3.14t, pythont and python3.14tt are still refused.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 23:22:12 +07:00
poli0981andClaude Opus 5.5 b0b5d5e25c refactor(cli): one builder for an env list element
env add --json promises exactly what env list --json prints for the same
interpreter; it built its own copy of the object. Both use env_json now.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 23:22:12 +07:00
poli0981andClaude Opus 5.5 f21329b1f8 docs: CLAUDE.md for 1.6.0 — Browse… shipped, NOT_YET empty, maintenance mode
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 23:22:12 +07:00
poli0981andClaude Opus 5.5 38e0226878 chore(release): 1.6.0
The five places the version lives, moved together: Cargo.toml, Cargo.lock,
package.json, package-lock.json and tauri.conf.json. `cargo metadata
--locked` agrees.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 23:22:12 +07:00
poli0981andClaude Opus 5.5 39be719b22 docs: maintenance mode — what is taken, what is not planned, and why
README carries the status in both languages, CONTRIBUTING a 'Scope in
maintenance mode' section the triage bot links to, and ROADMAP a section
recording the decision: dependency, security, major-upgrade, defect and
wording work is taken; P1-7, X19, the engine caches and P2 are not
planned, each with its reason. The Audit backlog is the maintenance
backlog.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 23:22:12 +07:00
poli0981andClaude Opus 5.5 61e5e26c4e ci: close feature requests in maintenance mode, and say why
triage.yml labels a feature request enhancement and out-of-scope,
answers in English and Vietnamese with CONTRIBUTING linked, and closes
it as not planned — on unmistakable signals only: a title that says it
is one, a feat: pull request, or the enhancement label going on.
Maintainers, bots and policy-exception are never closed. The rules live
in .github/scripts/triage.cjs with node --test cases (run by npm
licences); pull_request_target checks out only the base branch's
scripts; workflow_dispatch is a dry run. notify.yml hears about it.

Templates: a Wording or translation form (i18n), a contact link saying
features are not taken, a maintenance note on the bug form, and the
kinds of change a pull request can be. eslint.config.js lints the
CommonJS helper as Node, outside the type-aware program.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 23:22:12 +07:00
poli0981andClaude Opus 5.5 cfa5b4e1be docs: Add interpreter… in the specs, ACCESSIBILITY.md and the privacy policy
PRD P0-1, UI-SPEC §4, CLI-SPEC (env add/remove, their JSON, --env's new
refusal), CLI-GUIDE, ERROR-CATALOG (PD-ENV-001's new cases, and the
first button its advice ever had) and TESTING's golden count. SECURITY
§2 claimed for two milestones that interpreter paths were canonicalized
before use while the only check was existence; it now describes the
validator that makes it true. PRD also records P0-9's first-run uv
detection, P1-7 and P2 as not planned in maintenance mode.

legal/PRIVACY-POLICY.md 1.3 names the interpreter paths a person adds,
kept until removed, in both languages. With the repository URL it
already changed, the first-run gate shows once in 1.6.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 23:22:12 +07:00
poli0981andClaude Opus 5.5 9f9efbba79 feat(cli): env add and env remove; env list shows added interpreters
The CLI half of Add interpreter…: env add validates, probes and stores
an interpreter or environment directory, env remove takes it off the
list (matched by identity, or by the stored path when the file is gone),
and env list appends the added ones after discovery. --env and env use
go through the same validator. Two new help goldens; help-env and
help-env-list re-blessed for the new lines.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 23:22:12 +07:00
poli0981andClaude Opus 5.5 c9128e479e feat(ui): Add interpreter… and Remove from list on Environments
The header and the empty state offer Add interpreter…, which asks for a
python.exe and selects what it added; an added row, broken or not,
offers Remove from list. Busy is aria-disabled with a click guard, an
add and a scan refuse to overlap, the result is said in a status region
mounted before its words, and focus goes to the heading when the row
holding it leaves. Ctrl+K has the add too. PD-ENV-001's copy now covers
a file PipDock will not run, in both catalogues.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 23:22:12 +07:00
poli0981andClaude Opus 5.5 ab16742989 feat(core): interpreters a person adds — validated, stored, listed
PRD P0-1's manual browse, the last command NOT_YET owed (env_add_manual).

- envs::validate_interpreter, the enforcement point for every path a
  person supplies: an existing file named python[X[.Y]].exe, not one of
  PipDock's own tools or audit venvs (canonical, so .. cannot walk past),
  returned canonical and without the verbatim prefix. A missing file reads
  exactly as the probe's own message, so the CLI's goldens do not move.
- store v5: manual_envs, apart from the CLI's recents and default.
- scan_reporting appends the manual list last: discovery keeps its own
  source, and an added interpreter whose file is gone stays listed, so
  its PD-ENV-001 row can be removed.
- env_add_manual validates, probes, then stores; env_remove_manual takes
  an entry off the list and touches nothing else. env_probe validates a
  manual path too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 23:22:12 +07:00
poli0981andClaude Opus 5.5 ccae96dbeb chore: move to poli0981org — self-contained CI, Qodana, an npm licence gate, this week's dependencies (#119)
The repository now lives in the poli0981org organization, and this makes it at home there.

- main was red since 2026-11-18: RUSTSEC-2026-0543 (chrono), in Cargo.lock only through serde_with's weak features and compiled into nothing; ignored with its reason and exit condition.
- Supersedes #113–#118 (Rust 1.100.0, rusqlite 0.42.0, Tauri 2.12.6, code-health pins, actions, npm) plus jsdom 31.0.1; minimatch 11 closes GHSA-g3hv-75wg-m249. rfd 0.18 (#112) is held again until tauri-plugin-dialog moves.
- Dependabot's tauri groups never worked (it picks the most specific group); exclude-patterns on the catch-alls fix it.
- CI is self-contained: no workflow calls poli0981/.github; every action is pinned by commit; notify.yml vendors the Discord notifier.
- npm licences: scripts/check-licenses.mjs, deny.toml's allowlist for the npm half. Required, with cargo deny and tauri lockstep — eight required checks.
- Qodana in two parts (Rust, TS/JS), full scans, a triaged Rust baseline, fail on anything new. The Rust container needed its toolchain and CARGO_HOME pointed somewhere writable before it analysed anything.
- SonarQube Cloud analyses into poli0981org_pipdock; every npm ci runs with --ignore-scripts (S6505).
- Every repository URL points at the organization. README's attestation command for 1.4.0/1.5.0 had stopped working; it now says --owner poli0981 --signer-repo poli0981/pipdock.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 21:50:41 +07:00
dependabot[bot] efee3ca8d9 build(deps): Bump taiki-e/install-action (#103)
Bumps the actions group with 1 update in the / directory: [taiki-e/install-action](https://github.com/taiki-e/install-action).


Updates `taiki-e/install-action` from 2.89.1 to 2.90.0
- [Release notes](https://github.com/taiki-e/install-action/releases)
- [Changelog](https://github.com/taiki-e/install-action/blob/main/CHANGELOG.md)
- [Commits](https://github.com/taiki-e/install-action/compare/682ce6c3c696a4cd5168a05f98e51aa02b877941...b80e2bb2635f28eb98b9fce1e2f0887e1535c6b2)

---
updated-dependencies:
- dependency-name: taiki-e/install-action
  dependency-version: 2.89.1
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: actions
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
2026-11-10 20:18:52 +07:00
poli0981andClaude Fable 5.2 90fdfb3a2a test(a11y): hold the click guards that replaced disabled
A `disabled` button cannot be clicked; an `aria-disabled` one can. So every
button that became aria-disabled while busy depends on a guard in its handler,
and a guard that is missing starts a second scan, run or audit over the first.
SonarQube's gate saw those branches uncovered (78.7% on new code).

busy.test.tsx drives each one both ways: Use and Rescan, Code Health's Run,
Security's Run audit, the plan panel's Stop, and the two requirements buttons,
where the second press must not open a second picker. It also holds the other
half of the rule: a control with nothing to act on is still `disabled`.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-10 20:01:03 +07:00
poli0981andClaude Fable 5.2 7ee00893a7 fix(a11y): four defects from an independent review of the diff
- Visually-hidden text is position: absolute, and with no positioned ancestor
  it is laid out against the viewport, outside every scroller above it. A pin
  chip's hidden sentence did that on Pins: a long list made the whole window
  scroll and took the header with it. Every parent of hidden text is relative.
- A run that failed before producing a summary rendered no <h1>, so the focus
  rule had nothing to land on. The branch has a heading.
- The console drawer stays open across runs, so the next run mounts it with no
  opener to return focus to. It falls back to the Console button.
- Under forced-colors the selection outline followed the focus ring at equal
  specificity and replaced it on a focused current tab.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-10 20:01:03 +07:00
poli0981andClaude Fable 5.2 f9c5001dc4 docs: say "display scale" where the statement and the issue form said zoom
There is no zoom in 1.5.0, so asking a reporter for their zoom level asks for
something the application does not have.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-10 20:01:03 +07:00
poli0981andClaude Fable 5.2 2df161cb36 docs: 1.5.0 — the changelog, the slice's record, and what running found
changelog/1.x.md gains 1.5.0, written by reader: keyboard, screen reader,
contrast theme, everyone. It says that Narrator was not run again on this
release and that zoom was built and held back.

ROADMAP records the slice: the decisions and why, and the defects that were in
code with green tests and were found by driving the installed build over
WebView2's debugging port — the high-contrast border that had never been
drawn, the buttons that dropped focus when they went busy, the legal gate, two
accessible names. U45, U47 and U48 close; A1-A7 open, each with what it is
waiting for, and A7 is the testing only a person can do.

ACCESSIBILITY.md, UI-SPEC and TESTING are corrected to what the build actually
does: no zoom, a double border, busy as aria-disabled. CLAUDE.md carries the
rules the slice left behind and the recipe that found the defects.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-10 20:01:03 +07:00
poli0981andClaude Fable 5.2 95e45d7acc chore(release): 1.5.0
The five places the version lives, moved together: Cargo.toml, Cargo.lock,
package.json, package-lock.json and tauri.conf.json. `cargo metadata --locked`
agrees.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-10 20:01:03 +07:00
poli0981andClaude Fable 5.2 5aa4da87f4 fix(a11y): five defects found by driving the installed build
Every one of these was in code whose tests were green. They were found by
installing the bundle, opening WebView2's debugging port, and pressing real
keys while reading document.activeElement and the accessibility tree.

- The high-contrast border on destructive buttons had never been drawn. The
  rule sat in @layer base; every button carries Tailwind's border utility, a
  later layer wins whatever the selectors say, and border: 2px lost to
  border-width: 1px. It is outside every layer, and a double border, because
  2px beside 1px is not a difference anyone sees.
- Accepting the legal gate left focus on nothing: the gate is rendered instead
  of the shell, so the screen was replaced with the tab unchanged.
- A button that disabled itself when pressed dropped focus to <body>, because
  a browser takes focus from a control that becomes disabled and jsdom does
  not. Use, Rescan, Run, Run audit, Add, Download the index, Stop and the two
  requirements buttons are aria-disabled while busy and ignore a second press.
- A dialog's name read "Remove packages : certifi": a browser puts a space
  before visually-hidden text. The second half of the name is an aria-label.
- The Updates tab's name read "Updates(5)".

Zoom hotkeys were tried and are not in this commit: at 200% in the default
window the package-name column collapsed to zero width.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-10 20:01:03 +07:00
poli0981andClaude Fable 5.2 4732f05197 docs: sync the specs with the accessibility pass
UI-SPEC §7 no longer describes a forced-colors list that is "not complete": the
mark is data-destructive. §8 gains the five rules the pass left behind — focus
on every screen replacement, names that contain the visible text, composite
widgets as one tab stop, chip meanings as text, status regions that exist
before their first message.

TESTING says which of the three new tests holds what, and that none of them
knows what a screen reader says; the manual charter gains a ten-minute
accessibility pass. CLI-SPEC writes down that the CLI has no colour and nothing
that animates, which was true of the code and stated nowhere.

RELEASE-CI: the conversation-resolution rule the protection table never listed,
the labels box that had been true for weeks, and .nvmrc, which still said 24 a
month after every workflow moved to 26.

README links the new files and gains Accessibility and Contributing sections.
AI-DISCLOSURE and About name the model that produced 1.5.0.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-10 20:01:03 +07:00
poli0981andClaude Fable 5.2 3e2c5e1a07 docs: accessibility statement, contributing guide, code of conduct and templates
GitHub's community profile listed five things missing, and the ops repository
supplies no defaults despite its description, so they are added here.

ACCESSIBILITY.md is at the root, where GitHub looks and where the README can
link it. It follows the Accessibility Toolkit's structure, rewritten for a
Windows desktop application and a CLI: the target (WCAG 2.2 AA, as a target and
not a conformance claim), what is supported, a table of what was tested and by
whom, what was not tested, the known limitations, and how to report a barrier
without a GitHub account. It commits to an answer within seven days and to no
fix date, because one person cannot honestly promise one.

CONTRIBUTING.md states the rules a contributor actually meets: the checks CI
runs, generated bindings, goldens, both locales, and the invariants that are
not negotiable. CODE_OF_CONDUCT.md is Contributor Covenant 2.1, unmodified
apart from the contact address. The pull request template carries an
accessibility checklist, and accessibility.yml is an issue form that asks for
impact rather than for a diagnosis. bug_report.yml keeps its name: the in-app
Report bug link is built from it.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-10 20:01:03 +07:00
poli0981andClaude Fable 5.2 d016b80014 fix(a11y): name dialogs by their heading, and four smaller things
A PdDialog's name was an aria-label holding what it was about, so a screen
reader announced "numpy, dialog" and then "Cancel": the question being asked
was on screen and never spoken. It is named by its visible heading, followed by
what it is about, and described by its body.

The legal gate replaces the whole shell, declares itself modal, and had no
focus inside it. Its heading takes focus on arrival, as a screen's does.

A package row's focus ring was drawn 2px outside a row that is absolutely
positioned in a scroller and stacked against its neighbours, so three sides of
it were clipped or painted over. It sits inside the row, in every mode rather
than only in forced-colors.

The dock bay's remove button was a bare glyph about 8px wide. It is 24px each
way.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-10 20:01:03 +07:00
poli0981andClaude Fable 5.2 885bca416c feat(about): the accessibility statement and where to report a barrier
Someone who cannot use part of the app is the person least able to go looking
for a repository file about it. About gains an Accessibility section: a button
that opens ACCESSIBILITY.md, and accessibility@poli0981.dev beside the two
addresses already there, copyable the same way. No capability is widened:
https://github.com/* was already in scope.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-10 20:01:03 +07:00
poli0981andClaude Fable 5.2 a5fc204de8 fix(a11y): mark destructive controls by attribute for high contrast (U45)
Forced-colors drops every tint, so a danger-treated primary is drawn exactly
like the Cancel beside it. The stylesheet gave five data-action values a border
and had missed Remove, Allow, Clear, the Force-latest confirm and a forced
plan's Confirm for as long as the list existed.

The mark is one attribute, data-destructive, and destructive.test.ts reads the
source to hold both halves: every button drawn in the danger colour carries it,
and the stylesheet draws it.

The active sidebar tab carries aria-current="page" and the outline rule matched
'true', so high contrast drew it like every other tab.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-10 20:01:03 +07:00
poli0981andClaude Fable 5.2 f1bab20306 fix(a11y): say what Search is doing, and expose the tab shortcuts
Search told a screen reader nothing between a keystroke and its answer: the
index loading, a search running, how many results came back and "nothing
matches" were plain spans or not text at all. One status region carries them,
mounted from the first render so there is an earlier state for a message to
differ from. The result whose details are showing was a background colour; it
carries aria-current.

The sidebar's ^1..^9 hints were aria-hidden and at half opacity: about 2.6:1,
and the shortcut existed nowhere else. They are drawn in a token, and each tab
carries aria-keyshortcuts.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-10 20:01:03 +07:00
poli0981andClaude Fable 5.2 6b70580b91 fix(a11y): finish the tab, radio group and listbox patterns (U47, U48)
Health's tabs were three buttons with role="tab": three tab stops, no arrow
keys, no panel. They are one stop with Left/Right/Home/End, tied to a tabpanel.
Their accessible name was an aria-label reading "Dependencies, 3 findings" over
a tab that says "deptry 3", which fails WCAG 2.5.3; the name is the visible
text now, followed by what the tab is about.

A conflict's three choices were role="radio" with none of a radio group's
keyboard. They are one stop, and the arrows move between them. The arrows move
focus and choose nothing: checking what focus lands on would open Force
latest's destructive confirm from an arrow key.

The palette's highlight is an aria-activedescendant, not focus, so nothing
scrolled the list and the selection left the visible window. It is scrolled
into view.

The vulture whitelist link was told from the sentence around it by a colour
1.4:1 away and underlined only on hover. It is underlined at rest.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-10 20:01:03 +07:00
poli0981andClaude Fable 5.2 567b0ae8fa fix(a11y): move focus when the screen is replaced, not only when the tab changes
The shell moved focus to the new screen's heading on a tab change and on
nothing else. Four things replace what <main> shows without changing the tab:
the plan panel and each of its phases, the dependency view, and an opened
environment. Each unmounts the control that was just pressed, so focus fell to
<body>, the next Tab started from the top of the window, and a screen reader
said nothing about a screen that had entirely changed.

A second effect covers them, and only acts when focus was actually lost: a run
advancing from resolving to preview must not pull a keyboard user off Back.

The console drawer had the same hole. Escape closed it and dropped focus; it
goes back to whatever opened the drawer. Its close button was named "Cancel",
beside a Stop that cancels the run, and is "Close console".

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-10 20:01:03 +07:00
poli0981andClaude Fable 5.2 9754b95e66 test(a11y): run axe-core over every screen, and fix the grid it failed
No accessibility tooling stood behind any of this: roles were asserted one at a
time, wherever a test happened to reach for getByRole. axe-core now runs over
every screen inside the shell and over the components with structure of their
own. It is called directly: eslint-plugin-jsx-a11y peers ESLint 9 at most and
this repository is on 10, and the matcher packages are wrappers pinned to a
runner's major. color-contrast stays off under jsdom and stays tokens.test.ts's
job.

Its first run failed on the package grid, which is fixed here:

- the row checkbox was a direct child of role="row"; it is in a gridcell
- the header had five column headers over six cells; the checkbox and action
  columns are named, visually hidden
- the grid says rows are multi-selectable, which aria-selected needs

And one axe cannot see: a pin chip's meaning lived in a title attribute on a
span that cannot take focus. It is text now, visually hidden.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-10 20:01:03 +07:00
2329d55298 build(deps): cooled-down npm, actions and tools bumps (supersedes #103, #104, #105) (#106)
* build(deps): Bump taiki-e/install-action

Bumps the actions group with 1 update: [taiki-e/install-action](https://github.com/taiki-e/install-action).


Updates `taiki-e/install-action` from 2.88.0 to 2.89.1
- [Release notes](https://github.com/taiki-e/install-action/releases)
- [Changelog](https://github.com/taiki-e/install-action/blob/main/CHANGELOG.md)
- [Commits](https://github.com/taiki-e/install-action/compare/86f7a0ffb25f40114606501a311ebcfaf882ea32...682ce6c3c696a4cd5168a05f98e51aa02b877941)

---
updated-dependencies:
- dependency-name: taiki-e/install-action
  dependency-version: 2.89.1
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: actions
...

Signed-off-by: dependabot[bot] <support@github.com>

* build(deps): Bump the npm-minor-patch group with 6 updates

Bumps the npm-minor-patch group with 6 updates:

| Package | From | To |
| --- | --- | --- |
| [i18next](https://github.com/i18next/i18next) | `26.7.1` | `26.7.2` |
| [react-i18next](https://github.com/i18next/react-i18next) | `17.1.12` | `17.1.13` |
| [zustand](https://github.com/pmndrs/zustand) | `5.0.16` | `5.1.0` |
| [@tailwindcss/vite](https://github.com/tailwindlabs/tailwindcss/tree/HEAD/packages/@tailwindcss-vite) | `4.3.4` | `4.3.5` |
| [tailwindcss](https://github.com/tailwindlabs/tailwindcss/tree/HEAD/packages/tailwindcss) | `4.3.4` | `4.3.5` |
| [vite](https://github.com/vitejs/vite/tree/HEAD/packages/vite) | `8.3.5` | `8.3.6` |


Updates `i18next` from 26.7.1 to 26.7.2
- [Release notes](https://github.com/i18next/i18next/releases)
- [Changelog](https://github.com/i18next/i18next/blob/master/CHANGELOG.md)
- [Commits](https://github.com/i18next/i18next/compare/v26.7.1...v26.7.2)

Updates `react-i18next` from 17.1.12 to 17.1.13
- [Changelog](https://github.com/i18next/react-i18next/blob/master/CHANGELOG.md)
- [Commits](https://github.com/i18next/react-i18next/compare/v17.1.12...v17.1.13)

Updates `zustand` from 5.0.16 to 5.1.0
- [Release notes](https://github.com/pmndrs/zustand/releases)
- [Commits](https://github.com/pmndrs/zustand/compare/v5.0.16...v5.1.0)

Updates `@tailwindcss/vite` from 4.3.4 to 4.3.5
- [Release notes](https://github.com/tailwindlabs/tailwindcss/releases)
- [Changelog](https://github.com/tailwindlabs/tailwindcss/blob/main/CHANGELOG.md)
- [Commits](https://github.com/tailwindlabs/tailwindcss/commits/v4.3.5/packages/@tailwindcss-vite)

Updates `tailwindcss` from 4.3.4 to 4.3.5
- [Release notes](https://github.com/tailwindlabs/tailwindcss/releases)
- [Changelog](https://github.com/tailwindlabs/tailwindcss/blob/main/CHANGELOG.md)
- [Commits](https://github.com/tailwindlabs/tailwindcss/commits/v4.3.5/packages/tailwindcss)

Updates `vite` from 8.3.5 to 8.3.6
- [Release notes](https://github.com/vitejs/vite/releases)
- [Changelog](https://github.com/vitejs/vite/blob/main/packages/vite/CHANGELOG.md)
- [Commits](https://github.com/vitejs/vite/commits/v8.3.6/packages/vite)

---
updated-dependencies:
- dependency-name: i18next
  dependency-version: 26.7.2
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: npm-minor-patch
- dependency-name: react-i18next
  dependency-version: 17.1.13
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: npm-minor-patch
- dependency-name: zustand
  dependency-version: 5.1.0
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: npm-minor-patch
- dependency-name: "@tailwindcss/vite"
  dependency-version: 4.3.5
  dependency-type: direct:development
  update-type: version-update:semver-patch
  dependency-group: npm-minor-patch
- dependency-name: tailwindcss
  dependency-version: 4.3.5
  dependency-type: direct:development
  update-type: version-update:semver-patch
  dependency-group: npm-minor-patch
- dependency-name: vite
  dependency-version: 8.3.6
  dependency-type: direct:development
  update-type: version-update:semver-patch
  dependency-group: npm-minor-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

* build(deps): sonarqube-scan-action 8.4.1; regenerate tools constraints

sonarqube-scan-action 8.4.1 was six days old at Monday's Dependabot run and is
past the seven-day cooldown today.

tools-constraints.txt is regenerated with the command in its header, bounded to
the releases that are past the cooldown (filelock 4.2.7, platformdirs 4.14.3).
The result is byte-identical to the hand edit in #104, which is the check that
edit was missing.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-10 18:54:22 +07:00
dependabot[bot] 17031c871d build(deps): Bump taiki-e/install-action (#99)
Bumps the actions group with 1 update in the / directory: [taiki-e/install-action](https://github.com/taiki-e/install-action).


Updates `taiki-e/install-action` from 2.87.32 to 2.88.0
- [Release notes](https://github.com/taiki-e/install-action/releases)
- [Changelog](https://github.com/taiki-e/install-action/blob/main/CHANGELOG.md)
- [Commits](https://github.com/taiki-e/install-action/compare/5488ac5a951645ce95062214902ac4b6bc1a1037...86f7a0ffb25f40114606501a311ebcfaf882ea32)

---
updated-dependencies:
- dependency-name: taiki-e/install-action
  dependency-version: 2.87.32
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: actions
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
2026-11-04 10:37:06 +07:00
poli0981andClaude Opus 5.5 093ea4fce4 build(deps): dependencies to latest; classify pip 26.3's backend-unavailable (#102)
- cargo update (~60 bumps, 627 -> 616 crates) clears the yanked async-executor 1.14.0 that
  had turned cargo audit red on main and on every Dependabot PR since 2026-11-03 (Linux-only,
  never in the shipped binary). rusqlite 0.41.1 (SQLite 3.54.1), no code change. rfd 0.17 with
  tauri-plugin-dialog 2.8.4, which met the rfd ignore's own condition, so the ignore goes.
- npm: thirteen packages to latest; TypeScript still held at 6.0.3 (typescript-eslint peers <6.1).
- Tools: ruff 0.17.3, certifi, msgpack, platformdirs; constraints regenerated.
- Actions: taiki-e/install-action v2.87.32, sonarqube-scan-action v8.4.0; Node 24 -> 26 LTS.
  "Latest" means the newest release past each ecosystem's Dependabot cooldown.
- pip 26.3 renders an unloadable build backend as `error: backend-unavailable`, which fell
  through to PD-BLD-003; a classifier rule restores PD-BLD-002. Found by the drift job; live
  corpus re-captured with pip 26.3 / uv 0.13.7, the 26.2.1 capture frozen as pip-26.2/, and a
  test holds both renderings to one code.
- Docs: ARCHITECTURE §10 re-verified, ERROR-CATALOG, TESTING, ROADMAP, CLAUDE.md.

Supersedes #97, #98, #99, #100, #101.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 10:21:48 +07:00
dependabot[bot] df1ad1518d build(deps): Bump rfd (#96)
Bumps the cargo-minor-patch group with 1 update: [rfd](https://github.com/PolyMeilex/rfd).


Updates `rfd` from 0.16.0 to 0.16.1
- [Release notes](https://github.com/PolyMeilex/rfd/releases)
- [Changelog](https://github.com/PolyMeilex/rfd/blob/master/CHANGELOG.md)
- [Commits](https://github.com/PolyMeilex/rfd/commits)

---
updated-dependencies:
- dependency-name: rfd
  dependency-version: 0.16.1
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: cargo-minor-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
2026-10-28 09:33:31 +07:00
dependabot[bot] d8ef9c4e99 build(deps): Bump the npm-minor-patch group with 4 updates (#95)
Bumps the npm-minor-patch group with 4 updates: [@tanstack/react-virtual](https://github.com/TanStack/virtual/tree/HEAD/packages/react-virtual), [i18next](https://github.com/i18next/i18next), [react-i18next](https://github.com/i18next/react-i18next) and [zustand](https://github.com/pmndrs/zustand).


Updates `@tanstack/react-virtual` from 3.14.21 to 3.14.22
- [Release notes](https://github.com/TanStack/virtual/releases)
- [Changelog](https://github.com/TanStack/virtual/blob/main/packages/react-virtual/CHANGELOG.md)
- [Commits](https://github.com/TanStack/virtual/commits/@tanstack/react-virtual@3.14.22/packages/react-virtual)

Updates `i18next` from 26.5.4 to 26.5.7
- [Release notes](https://github.com/i18next/i18next/releases)
- [Changelog](https://github.com/i18next/i18next/blob/master/CHANGELOG.md)
- [Commits](https://github.com/i18next/i18next/compare/v26.5.4...v26.5.7)

Updates `react-i18next` from 17.1.0 to 17.1.5
- [Changelog](https://github.com/i18next/react-i18next/blob/master/CHANGELOG.md)
- [Commits](https://github.com/i18next/react-i18next/compare/v17.1.0...v17.1.5)

Updates `zustand` from 5.0.15 to 5.0.16
- [Release notes](https://github.com/pmndrs/zustand/releases)
- [Commits](https://github.com/pmndrs/zustand/compare/v5.0.15...v5.0.16)

---
updated-dependencies:
- dependency-name: "@tanstack/react-virtual"
  dependency-version: 3.14.22
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: npm-minor-patch
- dependency-name: i18next
  dependency-version: 26.5.7
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: npm-minor-patch
- dependency-name: react-i18next
  dependency-version: 17.1.5
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: npm-minor-patch
- dependency-name: zustand
  dependency-version: 5.0.16
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: npm-minor-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
2026-10-28 09:31:33 +07:00
dependabot[bot] 8cc0323c59 build(deps): Bump the code-health group in /tools with 3 updates (#94)
Bumps the code-health group in /tools with 3 updates: [certifi](https://github.com/certifi/python-certifi), [filelock](https://github.com/tox-dev/py-filelock) and [platformdirs](https://github.com/tox-dev/platformdirs).


Updates `certifi` from 2026.7.22 to 2026.10.18
- [Commits](https://github.com/certifi/python-certifi/compare/2026.07.22...2026.10.18)

Updates `filelock` from 4.2.1 to 4.2.4
- [Release notes](https://github.com/tox-dev/py-filelock/releases)
- [Changelog](https://github.com/tox-dev/filelock/blob/main/docs/changelog.rst)
- [Commits](https://github.com/tox-dev/py-filelock/compare/4.2.1...4.2.4)

Updates `platformdirs` from 4.13.4 to 4.13.5
- [Release notes](https://github.com/tox-dev/platformdirs/releases)
- [Changelog](https://github.com/tox-dev/platformdirs/blob/main/docs/changelog.rst)
- [Commits](https://github.com/tox-dev/platformdirs/compare/4.13.4...4.13.5)

---
updated-dependencies:
- dependency-name: certifi
  dependency-version: 2026.10.18
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: code-health
- dependency-name: filelock
  dependency-version: 4.2.4
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: code-health
- dependency-name: platformdirs
  dependency-version: 4.13.5
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: code-health
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
2026-10-28 09:17:41 +07:00
poli0981andClaude Opus 5.5 0112b000ec docs(sonar): a version bump moves the new-code baseline one analysis late (#93)
The analysis that first sent 1.4.0 still measured from 2026-09-27; the
next measured from the last analysis of the version before (2026-10-20).
The docs said the version did not move it at all. They now say when it
does, what that means for the merge carrying a release bump, and what
main's gate read after #91.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-25 07:47:58 +07:00
dependabot[bot] 41ab1e8085 build(deps): Bump the cargo-minor-patch group across 1 directory with 3 updates (#92)
Bumps the cargo-minor-patch group with 3 updates in the / directory: [tokio](https://github.com/tokio-rs/tokio), [tauri](https://github.com/tauri-apps/tauri) and [tauri-build](https://github.com/tauri-apps/tauri).


Updates `tokio` from 1.53.3 to 1.54.1
- [Release notes](https://github.com/tokio-rs/tokio/releases)
- [Commits](https://github.com/tokio-rs/tokio/compare/tokio-1.53.3...tokio-1.54.1)

Updates `tauri` from 2.12.4 to 2.12.5
- [Release notes](https://github.com/tauri-apps/tauri/releases)
- [Commits](https://github.com/tauri-apps/tauri/compare/tauri-v2.12.4...tauri-v2.12.5)

Updates `tauri-build` from 2.7.3 to 2.7.4
- [Release notes](https://github.com/tauri-apps/tauri/releases)
- [Commits](https://github.com/tauri-apps/tauri/compare/tauri-build-v2.7.3...tauri-build-v2.7.4)

---
updated-dependencies:
- dependency-name: tokio
  dependency-version: 1.54.1
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: cargo-minor-patch
- dependency-name: tauri
  dependency-version: 2.12.5
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: cargo-minor-patch
- dependency-name: tauri-build
  dependency-version: 2.7.4
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: cargo-minor-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
2026-10-25 07:47:00 +07:00
dependabot[bot] aaa97f1b02 build(deps): Bump the npm-minor-patch group with 5 updates (#89)
Bumps the npm-minor-patch group with 5 updates:

| Package | From | To |
| --- | --- | --- |
| [i18next](https://github.com/i18next/i18next) | `26.4.7` | `26.5.4` |
| [react-i18next](https://github.com/i18next/react-i18next) | `17.0.20` | `17.1.0` |
| [@tauri-apps/cli](https://github.com/tauri-apps/tauri) | `2.12.3` | `2.12.4` |
| [typescript-eslint](https://github.com/typescript-eslint/typescript-eslint/tree/HEAD/packages/typescript-eslint) | `8.71.2` | `8.72.0` |
| [vite](https://github.com/vitejs/vite/tree/HEAD/packages/vite) | `8.3.4` | `8.3.5` |


Updates `i18next` from 26.4.7 to 26.5.4
- [Release notes](https://github.com/i18next/i18next/releases)
- [Changelog](https://github.com/i18next/i18next/blob/master/CHANGELOG.md)
- [Commits](https://github.com/i18next/i18next/compare/v26.4.7...v26.5.4)

Updates `react-i18next` from 17.0.20 to 17.1.0
- [Changelog](https://github.com/i18next/react-i18next/blob/master/CHANGELOG.md)
- [Commits](https://github.com/i18next/react-i18next/compare/v17.0.20...v17.1.0)

Updates `@tauri-apps/cli` from 2.12.3 to 2.12.4
- [Release notes](https://github.com/tauri-apps/tauri/releases)
- [Commits](https://github.com/tauri-apps/tauri/compare/@tauri-apps/cli-v2.12.3...@tauri-apps/cli-v2.12.4)

Updates `typescript-eslint` from 8.71.2 to 8.72.0
- [Release notes](https://github.com/typescript-eslint/typescript-eslint/releases)
- [Changelog](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/typescript-eslint/CHANGELOG.md)
- [Commits](https://github.com/typescript-eslint/typescript-eslint/commits/v8.72.0/packages/typescript-eslint)

Updates `vite` from 8.3.4 to 8.3.5
- [Release notes](https://github.com/vitejs/vite/releases)
- [Changelog](https://github.com/vitejs/vite/blob/main/packages/vite/CHANGELOG.md)
- [Commits](https://github.com/vitejs/vite/commits/v8.3.5/packages/vite)

---
updated-dependencies:
- dependency-name: i18next
  dependency-version: 26.5.4
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: npm-minor-patch
- dependency-name: react-i18next
  dependency-version: 17.1.0
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: npm-minor-patch
- dependency-name: "@tauri-apps/cli"
  dependency-version: 2.12.4
  dependency-type: direct:development
  update-type: version-update:semver-patch
  dependency-group: npm-minor-patch
- dependency-name: typescript-eslint
  dependency-version: 8.72.0
  dependency-type: direct:development
  update-type: version-update:semver-minor
  dependency-group: npm-minor-patch
- dependency-name: vite
  dependency-version: 8.3.5
  dependency-type: direct:development
  update-type: version-update:semver-patch
  dependency-group: npm-minor-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
2026-10-25 07:35:07 +07:00
dependabot[bot] 56ba7dcadd build(deps): Bump the code-health group in /tools with 2 updates (#88)
Bumps the code-health group in /tools with 2 updates: [filelock](https://github.com/tox-dev/py-filelock) and [platformdirs](https://github.com/tox-dev/platformdirs).


Updates `filelock` from 4.2.0 to 4.2.1
- [Release notes](https://github.com/tox-dev/py-filelock/releases)
- [Changelog](https://github.com/tox-dev/filelock/blob/main/docs/changelog.rst)
- [Commits](https://github.com/tox-dev/py-filelock/compare/4.2.0...4.2.1)

Updates `platformdirs` from 4.13.3 to 4.13.4
- [Release notes](https://github.com/tox-dev/platformdirs/releases)
- [Changelog](https://github.com/tox-dev/platformdirs/blob/main/docs/changelog.rst)
- [Commits](https://github.com/tox-dev/platformdirs/compare/4.13.3...4.13.4)

---
updated-dependencies:
- dependency-name: filelock
  dependency-version: 4.2.1
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: code-health
- dependency-name: platformdirs
  dependency-version: 4.13.4
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: code-health
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
2026-10-25 07:34:59 +07:00
dependabot[bot] 0085eae1ca build(deps): Bump taiki-e/install-action (#87)
Bumps the actions group with 1 update: [taiki-e/install-action](https://github.com/taiki-e/install-action).


Updates `taiki-e/install-action` from 2.87.28 to 2.87.29
- [Release notes](https://github.com/taiki-e/install-action/releases)
- [Changelog](https://github.com/taiki-e/install-action/blob/main/CHANGELOG.md)
- [Commits](https://github.com/taiki-e/install-action/compare/1168f6810a3cb30a3514bf5756a3b7f0422c6df8...8cca0918f8471c33515202b73f56ab27f2bed283)

---
updated-dependencies:
- dependency-name: taiki-e/install-action
  dependency-version: 2.87.29
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: actions
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
2026-10-25 07:34:51 +07:00
poli0981andClaude Opus 5.5 2f6ad04967 fix: the 16 Rust findings and the coverage gap from the first CI analysis of main (#91)
The first CI analysis of main failed its gate: 16 Rust bugs and new-code
coverage 78.3 % against 80 %, over all of 1.4.0 (sending a version did not
move the previous-version baseline).

- rust:S6677 x3: a failure's message is logged as `error`, not as a second
  `message` field (CLI, update flow, app startup); golden.rs reads the
  CLI's log to hold it, and failed first.
- rust:S7493 x13: std::fs inside async fns goes through tokio::fs (tools
  venv sync, deptry's report, export/requirements/report commands).
- Tests for 1.4.0 code nothing drove: rollback end to end, forcing a
  latest this Python cannot run, PEP 691 parsing (L55), user_file_error
  (U25), a plan verified in another environment, PyPiReleases' cache, and
  the plan/env stores' success and late-error paths. InstallSet::only had
  no caller and is removed.
- ROADMAP, TESTING and CLAUDE.md record what the analysis found.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-25 07:21:45 +07:00
poli0981andClaude Opus 5.5 4a617722d6 ci(sonar): CI-based SonarQube Cloud analysis, with Rust and TypeScript coverage (#85)
Automatic analysis could not build, so it never analysed the Rust two
thirds of the code and imported no coverage; it also sent no project
version, leaving the previous-version new-code period anchored to the
first analysis. sonar.yml runs on Windows, produces cargo-llvm-cov and
vitest LCOV plus clippy's JSON, and scans with sonarqube-scan-action
v8.3.0 (pinned), passing the version from package.json. The token
reaches the scan step alone; the job is skipped without one (Dependabot,
forks) and refuses a dispatch off main, which this plan cannot analyse.

Unblocks the required audits, red on main since 2026-10-21:
rustls-webpki 0.103.16, webpki-root-certs 1.0.11, clipboard-win 5.4.3,
zod 4.6.7. Dependabot groups vitest with @vitest/*.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-25 06:38:10 +07:00
dependabot[bot] a3146895a0 build(deps): Bump taiki-e/install-action (#81)
Bumps the actions group with 1 update in the / directory: [taiki-e/install-action](https://github.com/taiki-e/install-action).


Updates `taiki-e/install-action` from 2.87.27 to 2.87.28
- [Release notes](https://github.com/taiki-e/install-action/releases)
- [Changelog](https://github.com/taiki-e/install-action/blob/main/CHANGELOG.md)
- [Commits](https://github.com/taiki-e/install-action/compare/ab6895351a88b908e96a4697860d4ffea5e57dbe...1168f6810a3cb30a3514bf5756a3b7f0422c6df8)

---
updated-dependencies:
- dependency-name: taiki-e/install-action
  dependency-version: 2.87.28
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: actions
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
2026-10-20 06:52:52 +00:00
dependabot[bot] 3d45f2e936 build(deps): Bump the npm-minor-patch group across 1 directory with 2 updates (#82)
Bumps the npm-minor-patch group with 2 updates in the / directory: [react-i18next](https://github.com/i18next/react-i18next) and [eslint](https://github.com/eslint/eslint).


Updates `react-i18next` from 17.0.19 to 17.0.20
- [Changelog](https://github.com/i18next/react-i18next/blob/master/CHANGELOG.md)
- [Commits](https://github.com/i18next/react-i18next/compare/v17.0.19...v17.0.20)

Updates `eslint` from 10.12.0 to 10.13.0
- [Release notes](https://github.com/eslint/eslint/releases)
- [Commits](https://github.com/eslint/eslint/compare/v10.12.0...v10.13.0)

---
updated-dependencies:
- dependency-name: eslint
  dependency-version: 10.13.0
  dependency-type: direct:development
  update-type: version-update:semver-minor
  dependency-group: npm-minor-patch
- dependency-name: react-i18next
  dependency-version: 17.0.20
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: npm-minor-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
2026-10-20 06:50:00 +00:00
poli0981andClaude Opus 5.5 57ed5756c4 ci: unblock cargo audit on zbus 5, redact pip 26's finished progress bar, hold rfd at 0.16 (#84)
Three things have kept CI red since 2026-10-18; none touches the shipped program.

- **cargo audit** (required on every PR, and the daily Security scan) fails on
  RUSTSEC-2026-0370/0371/0372: zvariant, zbus_names and zvariant_derive were folded into
  zbus 6 on 2026-10-16 and marked unmaintained the same day. zbus reaches the tree only
  through tauri-plugin-opener and tauri-plugin-single-instance, for D-Bus on Linux;
  `cargo tree -i zbus --target x86_64-pc-windows-msvc` prints nothing. Every release of both
  plugins, the 3.0 alphas included, still requires zbus ^5.9, so there is no update to take.
  Ignored individually in .cargo/audit.toml with that reason and a removal condition.
  `cargo audit --deny warnings` is clean locally.

- **The Monday fixture-drift job** failed on pip/build-backend-failure/stdout.txt: pip 26
  ends a finished bar with the bare elapsed time, not `eta 0:00:00`, so `_is_progress` let
  the transfer rate through (15.1 MB/s committed, 75.1 MB/s on the next runner). The rule now
  keys on a trailing time token. Old vs new over every committed fixture line: exactly this
  one line changes verdict. The fixture is restored to `<PROGRESS>` in binary mode, 7 CRLF
  before and after; its blob is again b349d1f, the pre-pip-26 bytes.

- **rfd**: Dependabot's 0.17.2 bump (#83) adds a second rfd to the binary, because
  tauri-plugin-dialog 2.8.3 requires ^0.16 and src-tauri depends on rfd only because the
  plugin already compiles it. dependabot.yml now ignores rfd >= 0.17 until the plugin moves.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 06:37:19 +00:00
poli0981andClaude Opus 5.5 283605a4a0 chore(sonar): NOSONAR on the line SonarCloud flags (#80)
SonarCloud honours a NOSONAR only on the flagged line. 1.4.0 put this one on
the line above the `cargo` call, so S4036 stayed open on `main` and kept the
project's security rating at B while the PR gate reported "0 new issues" — the
issue was old, not new. The call now fits on one line, with the marker on it.
The two in `spikes/` were already on their flagged lines and are cleared.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 01:16:31 +07:00
dependabot[bot] 8c5f7e0b95 build(deps): Bump taiki-e/install-action (#79)
Bumps the actions group with 1 update: [taiki-e/install-action](https://github.com/taiki-e/install-action).


Updates `taiki-e/install-action` from 2.87.22 to 2.87.27
- [Release notes](https://github.com/taiki-e/install-action/releases)
- [Changelog](https://github.com/taiki-e/install-action/blob/main/CHANGELOG.md)
- [Commits](https://github.com/taiki-e/install-action/compare/83ac0ad63c0167e6f06796fab0fce28db1bf3db0...ab6895351a88b908e96a4697860d4ffea5e57dbe)

---
updated-dependencies:
- dependency-name: taiki-e/install-action
  dependency-version: 2.87.27
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: actions
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
2026-10-17 01:12:59 +07:00
poli0981andClaude Opus 5.5 87dcb3452f fix(spikes): scrub progress bars line by line, not with a backtracking regex
SonarCloud's PR analysis flagged the progress-bar regex in capture.py's redaction again (S8786,
super-linear backtracking) — the second regex form of this rule it has flagged. A per-line test
cannot backtrack at all. It replaces exactly the lines the regex did on the LF text
`subprocess.run(text=True)` produces, checked against seventeen sample lines including the edge
cases (no space after the dashes, trailing whitespace, several "eta"s, a final line without a
newline); no committed fixture changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 6cd7e99385 chore(release): 1.4.0
The version in all five places it lives — Cargo.toml, Cargo.lock, package.json,
package-lock.json and tauri.conf.json — checked with `cargo metadata --locked` and with the
release workflow's own tag check run locally against v1.4.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 7124227262 docs: the specs say what the code does; 1.4.0 recorded, with its audit backlog
Every spec checked against the code rather than against itself, in four passes that each read the
branch's commits and then the source:
- CLI-SPEC/CLI-GUIDE: one JSON document per command (with the per-command table and the paths
  that print nothing), environment selection, logging, Ctrl-C and exit 130, the prompts as they
  are rather than the [A]bort and countdown that never existed, `.heldBack`, a `pipdock audit`
  section, and the rules every mutating command now follows.
- ARCHITECTURE/DATA-FLOW/ERROR-CATALOG: the Engine trait's real signatures, Requires-Python's
  three checkpoints, store v4 and the log folder, §7's return types and events, the state machine
  with re-probing and Force latest, where each §9 invariant is enforced, and 35 codes in 32 rows.
- SECURITY/TESTING/RELEASE-CI/CODE-HEALTH-SPEC: the PEP 668 override as built, four browser hosts
  and the exact capability set, attested releases, the new CI, the tools constraints, and test
  tiers that describe what runs rather than what was planned.
- UI-SPEC/PRD/README/I18N: the screens as they render, the keyboard, tokens and their contrast
  sweep, the feature matrix's status, attestation instructions, and I18N's one stated exception.

ROADMAP gets the 1.4.0 record — what was wrong, what running found that reading did not, what was
deliberately not done — and the **Audit backlog**: every finding not fixed, with where it is and
why it waited. CLAUDE.md's counts and contradictions are corrected, with the rules this release
left behind. changelog/1.x.md has the 1.4.0 entry, including "Changed for scripts" and "You will
see this once". AI-DISCLOSURE, README and About say which model and who released what. The legal
documents' effective date moves to the release date.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 42f227c1aa fix: what installing the build found, and what the doc pass turned up
The release build was installed and driven before tagging. Two defects showed up that no suite
could see:
- Every dialog opened in the window's top-left corner. Tailwind's preflight sets `margin: 0` on
  everything, which removes the `margin: auto` a modal <dialog> is centred by; PdDialog (and so the
  uninstall guard, since it was written) and the Ctrl+K palette were both affected. `m-auto` /
  `mx-auto`, measured in the dev server: (0,0) before, centred after.
- On a profile that had never downloaded the index, Search said "preparing the package index"
  for ever and never offered the download. Moving the load into the background let a failed load
  restart on the next search, which reset the slot to Warming before the failure could be read,
  and the screen asked again every 150 ms. A failed load now stays failed until a refresh; a test
  in state.rs failed first against the old rule.

From the documentation pass, each checked against the code:
- The GUI's snapshot diff used the plain diff while the CLI's and the rollback used the
  engine-aware one, so the two heads disagreed about pip and setuptools across engines (G5).
- `--json`'s help still promised NDJSON; `--yes`, `--quiet`, `--verbose`, `--log-file`, the
  install spec and `engine` described behaviour they did not have. Corrected, and the 32 help
  goldens re-blessed for exactly those lines. `pipdock engine` now marks the configured engine,
  as its help always said; `health --fix` printed a dirty-tree warning to stdout before its JSON;
  the text preview now lists withdrawn releases, as the GUI's does.
- Copy that promised what the code does not do: a pinned package "can still be updated on its
  own" (an Exclude pin filters a named package too), a held pin left only "out of bulk updates",
  and an empty Environments screen pointing at a Browse… button that does not exist.
- Stale comments in exec, the pip and uv parsers, index refresh, health, the pin screen, the
  status line, the settings store and i18n.ts (whose missing-key warning never fires). The
  ExecutionSummary.cancelled description is part of the public schema, so that golden and the
  TypeScript bindings move with it.
- Metadata lookups reuse the shared HTTP client (M37 had been half done); insta was a dev
  dependency of core that nothing in core used; the integration workflow's checkouts no longer
  persist credentials; the capability file cites SECURITY §4, where the rule lives.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 310436552c fix: a bug-report link GitHub will open; uninstall output that finishes printing
- report.rs: the excerpt was capped at 6000 characters *before* percent-encoding, which is what
  decides the length GitHub sees - an accented letter costs up to nine bytes, a path separator
  three - so a log full of Vietnamese paths built a ~20 KB link and GitHub answered with an error
  page instead of the form (M51). Lines are now dropped from the front until the encoded excerpt
  fits; a single enormous line is trimmed rather than dropped. Two tests, both failing first.
- run.rs: `pipdock uninstall` dropped its output pump's handle instead of awaiting it, so the
  summary could print over the last engine lines - the ones that say how the removal ended (X38).
  The other three pumps already waited.
- bug_report.yml: the version placeholder read "1.0.0", which every release since made wrong; it
  now says where to find the version instead (X48).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 25f0269631 fix(build): the legal hash ignores line endings; the privacy policy says what is stored
build.rs hashed each document's raw length two lines above the normalisation that existed so a
CRLF checkout would hash like an LF one (X25). It did not: a build from a Windows checkout with
autocrlf - the runner's default - carried a different hash from an LF build of the same commit.
The algorithm moves to src/legal_hash.rs, which build.rs includes by #[path] and the library
compiles under cfg(test), so the tests exercise the function that runs at build time: a CRLF pair
hashes like its LF pair (this failed against the old code), a changed document or text moved
between documents changes the hash, and the hand-rolled SHA-256 agrees with sha2 across block
boundaries.

legal/, as users read it (X26):
- PRIVACY §2 names what is now stored: the log files exist (they record the commands PipDock ran,
  so they hold package names and paths), PipDock's own tools/ and audit/ environments, and the
  per-release Python ranges. §3 says what the one destination, PyPI, is asked for - including
  pip-audit's advisory data, which comes from PyPI's own service - and adds osv.dev to the pages
  handed to the browser. The Vietnamese summary follows.
- THIRD-PARTY §A gains rfd (the startup-failure dialog), §C osv.dev: four browser destinations,
  not three.

Both documents are hashed into the consent record, so the legal gate is shown once more after
updating - the mechanism working, as CLAUDE.md says.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 12bf723daa ci: failures reach someone, audits run on what is merged, releases are attested
- notify-ci-failure.yml lists its workflows by name. `workflows: ['*']` is not a wildcard to
  workflow_run: it matched nothing, so `main` was red from 2026-09-23 with no one told.
- cargo audit runs a prebuilt cargo-audit (taiki-e/install-action, pinned by commit) with
  `--deny warnings`, replacing rustsec/audit-check@v2 - Node 20, a check-run write token, and on a
  pull request a failure only for "critical", which is how September's advisories passed every PR.
  .cargo/audit.toml's contract (a new informational advisory fails CI) is now what runs.
- security-scan.yml: both audits daily against `main`, so an advisory against something already
  merged is reported the day it is published, not at the next PR.
- cargo deny (licences, sources, bans) with deny.toml: the licence allowlist makes "every bundled
  licence is GPL-3.0-compatible" a test. The workspace declares `publish = false`, which it never
  had - and without which cargo-deny judged the app crates as published ones.
- CodeQL analyses rust and actions as well as javascript-typescript. The comment saying CodeQL had
  no Rust support stopped being true in 2025.
- ci-node.yml: Pages and id-token write move from the workflow to the one job that needs them
  (Sonar S8233); the audit installs with --ignore-scripts (S6505); a new `tauri lockstep` job
  fails when a Tauri crate and its npm package drift apart on Cargo.lock and package-lock.json.
- release.yml: build (read-only token, no persisted credentials) and publish (attest + draft) are
  separate jobs; the tag must match all five version fields; SHA256SUMS.txt is LF, which
  `sha256sum -c` elsewhere needs; actions/attest-build-provenance attests the .exe and .msi;
  softprops/action-gh-release is pinned by commit; `workflow_dispatch` with `dry_run` builds any
  ref without attesting or drafting.
- ci-integration.yml also runs for the CLI, exec, audit, release metadata, errors, store, index,
  Cargo.lock and rust-toolchain.toml - every one of which its end-to-end steps run through.
- dependabot.yml: cooldowns, a group per ecosystem for Tauri packages and for actions and pip,
  TypeScript held below 6.1 (typescript-eslint's peer range), and the rust-toolchain ecosystem.
  A multi-ecosystem group would put both Tauri halves in one PR, but what it does to dependencies
  outside its patterns is undocumented; the lockstep job covers the gap instead.
- Sonar: NOSONAR with reasons on the dev scripts' argv and PATH lookups; bundle-cli.mjs no longer
  claims to run from beforeBuildCommand. The dev CSP moves out of index.html into a Vite plugin
  that reads devCsp from tauri.conf.json, so a release build carries one policy, the strict one
  (S7039); checked in the dev server, where React Refresh's preamble still runs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 7c6a506652 chore: remove what nothing uses, and finish what was half-wired
Dead code, each checked for callers first:
- graph::ReverseDeps::leaves (only its own test called it), health::run::sink_for (no caller,
  and a doc describing something else), SnapshotProof::id and is_waived (no caller).
- Two whitespace collapsers become one, errors::catalog::collapse_whitespace; the classifier's
  normalize is that plus lowercase. Three hand-folded SHA-256 hex digests become
  model::sha256_hex (build.rs keeps its own: a build script cannot use the crate it builds).
- Six copies of asPdError become one, beside isPdError in ipc/errors.ts.
- Thirteen strings no screen renders, from both catalogs (status.resolving/executing/ready,
  actions.confirm/browse/retry/openLogs, env.requiresPython/unusable,
  packages.updateSelectedSoon, health.notInstalled, settings.localeSystem/saved).
- fixtures.rs is compiled only for tests and for xtask (feature `fixtures`), not into release.

Half-wired, finished rather than deleted: engine_info had a typed wrapper and no caller, while
ARCHITECTURE §7 promised a version beside each engine radio. Settings now shows it for the
selected environment, and says "not found" for an engine that is not installed.

Docs that described another project: core's "Phase 0" status, model.rs's specta, pip.rs's "lands
in M1", snapshot.rs's "execute takes a Snapshot" (it takes a SnapshotProof), declared_source's
doc stranded on validate_project, the pin validators' "character-class check" (they share
pep440::is_version now), three health wrappers in ipc/index.ts each under another's doc, and
three %LOCALAPPDATA% paths missing the data\ folder.

Repo: production builds carry no source maps - Tauri embeds dist/ in the executable, so
`sourcemap: true` shipped 2 MB of them to every user (X51). .gitignore covers insta's pending
snapshots and a downloaded SHA256SUMS.txt.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 4da4c0f3ec fix(ui): the shell - window, grants, CSP, language, keys, table, contrast
The window (U21). It may now be maximized and snapped; the 1600x1100 cap is gone, and the content
column stops at max-w-content (87.5rem) instead, centred in what is left. The window is created
hidden and src-tauri/src/window.rs fits it to the monitor's work area before showing it: 1180x760
is taller than the work area of a 1920x1080 panel at 150% and of a 1366x768 laptop, so the status
line and the plan panel's Confirm opened under the taskbar. Never below 900x560; pinned to the
corner rather than centred off-screen when even that does not fit. UI-SPEC §5 says so.

The webview's grants (U1, U32). core:default granted some sixty core commands nothing called and
not core:window:allow-close, so Decline on the legal gate did nothing in the installed app while
its component test - which mocks close() - passed. default.json now holds exactly the five the
frontend calls, and a test in lib.rs pins the union of every capability file, plus the opener's
four hosts.

CSP (U56): object-src, base-uri and form-action 'none'. A release build's style-src drops
'unsafe-inline' - React sets styles through CSSOM, which CSP does not govern. index.html keeps it
for `npm run dev`, where Vite injects <style> elements; both policies are enforced, so the
stricter decides. To be confirmed on the installed build.

Language (U3): the choice is stored and applied at start. save() sent locale: null every time, so
choosing Vietnamese lasted until the window closed. Settings now load before the legal gate, so the
gate is in the chosen language too, and <html lang> follows the UI.

Keys: a screen's data-autofocus wins over the heading (U12) - Search's field lost focus to the
shell's effect, which runs after its children's - and `/` works from Search itself. Ctrl+1..9 by
e.code (U49): on AZERTY Ctrl+3 reports `"`. A release build swallows F5, Ctrl+R, Ctrl+P, Ctrl+F,
F3 and Alt+arrows (U20), which reloaded, printed and found in a single-page app.

Also: Security scrolls (U2); the legal gate shows a consent that cannot be recorded (U29); Report
bug asks for the link again with the environment, so the issue carries the Python and engine
versions, at one subprocess per click rather than per row (U31); the package table's header and
rows share one set of widths and one gutter, and narrow tables drop Size so names stay visible at
900px (U22, U23); the grid is focusable (Sonar S6852); --color-danger is #F26A63 and danger badges
use a 15% tint, with tokens.test.ts now compositing every badge tint over every surface (U46 -
3.92:1 before); test seeds typecheck instead of `as never`, the IPC mock uses the real isPdError
and has the audit cache entry (U10).

U14 and U26 were already fixed by earlier commits in this release.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 8e4b87e4ab feat(ui): the PEP 668 override asks first and is shown; the preview says what the report says
SECURITY §3 asks for two things the override never had: a confirmation before it turns on, and a
persistent chip on every mutating screen while it applies. Turning it on now opens PdDialog with
Cancel focused; turning it off saves at once. PdOverrideChip shows on Installed/Updates, Search's
dock bay, the plan panel and an environment's detail - only where the override applies: the
setting is on and the environment carries the EXTERNALLY-MANAGED marker. A venv never does, and a
chip there would claim the flag is being sent.

The preview renders the three fields ResolutionReport gained in this release, which nothing showed:
- forced: "Will break (n)" in danger, each dependent named with the constraint the forced version
  violates; the Confirm button carries the count and the danger treatment (DISCLAIMER §2).
- incompatible: left out for Requires-Python, with the range against this interpreter (invariant
  10). A plan whose only content is one is no longer "nothing to change".
- yanked: PD-PKG-003 as a warning row beside the change it belongs to.

The summary says when the post-run check could not run (CheckReport.error) instead of showing
nothing, which read as a pass (M30). The same defect survived on the empty-plan path of
plan::execute, which kept its own unwrap_or(ok: true); it now goes through post_check like every
other path, with a test that failed first.

Also: settings load at app start once the documents are accepted, so the status line's engine and
the chip are right before anyone opens Settings (U13); the plan panel names the interpreter it
changes (part of U15); pins.suggestIntro no longer claims a pinned package can still be updated one
at a time - an Exclude pin filters a named package too (DATA-FLOW §9.5).

flow_step_forced.json is computed by derive_forced and release::mismatch over the scenario rows
rather than written, for the reason fixtures.rs gives for its other computed fixtures.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 73e65303ca fix(ui): an answer for what the user has left is dropped
Every store awaited a command and then wrote what came back, without asking whether the question
was still the one being asked. A slow answer for the environment the user had just left landed on
the one they switched to:
- the package list and the outdated badges (U5), pin suggestions (U43) and the snapshot timeline
  check the environment after each await;
- a pin write re-joins the rows from the store as it is after the write, not as it was before
  two awaits (U6);
- two clicks down the timeline show the second entry's diff whichever answers first (U42);
- the dependency view loads the environment switched to while the previous one was loading,
  rather than bailing on "already loading" and showing nothing (U34).

The plan store counts generations. Leaving a plan the backend is still working on - Back during
a resolve or a guard, or out of a parked preview - now stops it there with plan_cancel, and its
late answer no longer re-opens the panel the user closed (U9). A failed decision round keeps the
preview (U24, the UI half). The progress subscription stays open 50 ms past the command's reply,
which arrives separately from its last events and in no promised order. The uninstall guard's
probe has its own phase, so the table is not swapped for the plan panel for half a second and its
scroll position kept (U14).

- Back from a preview is not a finished run: the selection is kept and nothing is refetched (U11).
- Search asks again while the index warms instead of waiting for another keystroke (U7); the
  backend now always answers the first search at once.
- Install from the dock bay keeps the queue until the resolve answers (U30).

ui/src/stores/races.test.ts holds a command open, moves on, then lets it answer: six of its seven tests
fail on the previous stores.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 a9f476a2ae fix(app): a claimed slot releases itself; IO errors say what happened; quieter locks
- The session slot is claimed through a guard that releases it on drop unless it was parked
  (U4). Release was a call every exit path had to remember, and plan_resolve, uninstall_guard and
  the rollback preview each had a `?` between claim and release: one failed settings read left the
  slot Busy and every later plan answered PD-RES-003 until a restart. The slot is a std mutex now,
  held only to swap a value, so the drop can take it; a test returns early through a claim and
  finds the slot free and the token gone.
- A guard refusal in uninstall_execute keeps the flow parked: the dialog is still on screen and
  Force remove is still a choice, and its buttons used to answer "no plan".
- A file the user chose - an export, a saved report, a requirements file - fails with the code
  that fits: read-only is PD-PRM-003, in use is PD-PRM-002, a full disk is still PD-SYS-002. Every
  one of them was PD-SYS-002, "not enough free disk space" (U25).
- cache_clear holds the slot of the feature that owns the target - Health for the tools venv, the
  Security tab for the audit venv, the plan slot for snapshots - so a clear is refused while that
  feature runs instead of deleting the venv in use, and a parked preview is put back (U36). The
  deletion runs off the async workers.
- The name index loads in the background on its own connection (U35). The load held the store's
  lock for 140 ms - every command that wanted the store waited behind a keystroke - on a worker
  the app shares; the triggering search answers ready:false, as the command's doc always said.
- Environment probes run four at a time instead of in series (U19, part).
- The audit's cancellation token is registered before the freeze, so Stop during it is honoured
  (U37); a run stopped that early skips the venv sync and reports itself cancelled.
- A cache test named its scratch folder after the clock alone, so two tests in one tick shared it
  and the fresh-install test read the other's files. It failed once in this run; a counter fixes it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 040571c7f7 fix(cli)!: one JSON document per command, env use is honoured, Ctrl-C stops the run
Changed for scripts: every `--json` invocation now prints exactly one document on stdout
(CLI-SPEC §6), with prompts, previews-before-a-prompt and prose on stderr (X5). The preview and
then the summary used to be two documents, so `pipdock install x --json | ConvertFrom-Json`
failed on the second. The document is: the ResolutionReport when nothing runs (a dry run, an
empty plan, a declined prompt - exit 2), the ExecutionSummary when something does, the FlowStep
when there is nothing to plan, the GuardReport for a refused removal (with --force, only the
summary), and the entity itself for env use, pin add/remove, snapshot create, engine and
pip-upgrade ({before, after}). Prompts moved to stderr in both modes.

- `env use` is honoured (X3): --env, then the default it set, then a .venv here - as --env's help
  always said. It was written and never read. A default whose interpreter is gone is said and
  skipped. The help line says "the one `env use` set" now (32 help snapshots re-blessed for that
  line alone).
- Ctrl-C (and Ctrl-Break, which a supervisor can send) trips the flow's token (X6): the engine's
  process tree is killed, what ran is summarized with the snapshot to roll back to, and the exit
  is 130; a second press quits at once. Verified against a resolve hung on a server that never
  answers: exit 130 the instant the signal arrived, no python left running.
- `update` with neither names nor --all exits 2 instead of planning nothing (X16); `audit` uses
  --engine (X14); `engine` needs no environment (X15); `doctor` judges the configured engine, not
  pip, so a uv-only venv passes (no pip is the uv default); an impossibility skipped off a TTY says
  what and why (X26); `list` probes once instead of twice (X28); names and versions honour
  `{:<32}` (X27); `snapshot diff` compares the way a rollback would across engines.

Verified with a script driving the real binary through each of these: every stdout parses as one
JSON document and every exit matches CLI-SPEC §5.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 77ca18cc33 feat(app): the GUI logs, says when it cannot start, and shows where the log is
- The GUI writes data\logs\pipdock.<date>.log through the same core::logging the CLI uses, with
  the panic hook installed, so a crash leaves a record where it used to leave nothing.
- A data folder that cannot be opened is said in a dialog before any window exists (U18). The
  store was opened inside Tauri's setup hook, whose failure is a panic in the event loop: a
  release build has no console, so the user double-clicked and nothing happened. It now opens
  before Tauri starts, and the failure shows the code, the message and the log path through
  rfd - already in the tree via tauri-plugin-dialog, so Cargo.lock gains one dependency edge and
  no crate. It is the one place GUI copy is written in Rust (both languages at once), because no
  webview exists yet to load a catalog.
- logs_tail returns LogTail { dir, lines } - a new schema, so schema-LogTail is blessed and
  schema-unknown-type lists one more type. NOT_YET is down to one entry, env_add_manual.
- Settings gains a Logs row: the folder, as a path, and "Copy recent log", which re-reads the tail
  at the moment of copying so the clipboard holds the run that just went wrong. The clipboard
  permission "Copy full log" already had is enough; no capability changes. en + vi copy.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 b7fa16a281 feat(logging): a log exists, and the CLI's logging flags do something
There was no log. tracing was a dependency of three crates and called zero times, --verbose and
--log-file were parsed and ignored, LOG_RETENTION_DAYS had no reader, and the privacy policy
described "log files (14-day rotation)" that did not exist. A bug report could attach the last
run's engine output and nothing about what PipDock itself had done.

core::logging owns what both heads share: one file per UTC day under data\logs
(<prefix>.<date>.log, so the GUI and CLI never interleave), a sweep that keeps
LOG_RETENTION_DAYS and never touches a file it did not name, tail() for reading it back, and a
panic hook. What is logged: every spawn's argv, exit code and duration, every stop and its
reason (exec); each resolve's outcome, each snapshot, each run's counts or refusal (flows); and
the engine's own lines at DEBUG.

The CLI always writes its file, at PIPDOCK_LOG or INFO; --verbose adds stderr at DEBUG;
--log-file adds a copy; an internal error (exit 10) prints the log's path on stderr. Nothing goes
to stdout - verified: `install --dry-run --json --log-file x` leaves one JSON document on stdout
and nothing on stderr. The golden suite runs under a scratch LOCALAPPDATA now, and no golden
changed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 f4cf9e4959 build(tools): pin the tools venvs' whole dependency tree, not just the tools
tools-requirements.txt pins four tools and nothing beneath them, so every sync resolved their
thirty-odd dependencies against whatever PyPI held that day: a Code Health report was
reproducible for a build only as far as the top of the tree, and a broken or compromised release
of requests, rich or msgpack reached every user on their next sync (H27).

tools/tools-constraints.txt is that tree, compiled once with
`uv pip compile --universal --python-version 3.10 --only-binary :all: --no-emit-package pip`
(the command is in its header), embedded in the binary and passed to the bootstrap as `-c`. One
file serves both venvs because a constraint does not install anything. pip is left out on purpose:
it is the installer, and pip-audit's dependency on it would otherwise make pip replace itself
half-way through installing pip-audit. A test refuses a ledger pin the constraints do not match,
with the command to fix it, so a Dependabot bump cannot ship half-applied.

The manifest hash still covers the tool pins alone, so no existing venv is forced to re-sync.
Verified by syncing both venvs from nothing: every installed package is the constrained version.
Hashes (`--require-hashes`) remain in the backlog.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 535b4c8707 fix(health, audit, index, snapshot): what was previewed is what is fixed, and smaller holes
Code Health
- ruff --fix ran `check . --fix` with none of the exclusions the previewed run used (C4). Real
  ruff 0.17.1, verified: it rewrote every .ipynb in the tree - the preview excludes notebooks -
  and, in a project whose pyproject sets its own `exclude` (which replaces ruff's defaults), the
  files under .venv as well. The fix argv is now the read-only argv plus --fix, by construction;
  re-run against both cases, neither file changes.
- git status runs with -c core.fsmonitor=false (M40): a project folder that carries its own
  .git/config could name a program for `git status` to run, and asking "is it safe to write
  here" would have run it.
- One tool whose output cannot be read is that tool's problem, not the run's (H24). A `?` at the
  last step returned from the whole run, taking the other tools' findings with it.
- The fix's own failures speak Code Health's codes, and a timeout says files may already have
  been rewritten (M39). Project paths lose Windows' \?\ prefix, which every filename in the
  report carried (M47).

Security tab
- pip-audit is given pins, not the raw freeze (H21): one editable install failed the whole audit.

Index
- TLS failures read the error's source chain (M32): reqwest's top-level message never mentions
  the certificate, so PD-NET-002's guidance never showed.
- Typed, borrowing parse instead of a Value tree of 700k objects; the ingest runs on a blocking
  thread; connect/read timeouts replace a single 120 s total a slow link could exceed while
  making progress (M36). An empty project list is refused rather than ingested over the index
  (L55).

Snapshots
- Ids are fixed width and the list orders by created_at (M43): the timestamp's trimmed fraction
  made `…09-42Z` sort after `…09-4235606Z`. A sidecar whose id is not a PipDock id is ignored
  rather than used to build a freeze-file path (L54).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 545e86bd31 fix(flow): rollback across engines keeps pip; Hold pins hold; a failed round keeps the preview
- A rollback never removes pip, and across engines leaves pip, setuptools and wheel out of the
  comparison (C7). uv's freeze has no --all, so a uv snapshot never lists them; compared with
  pip's freeze every one looked added since, and the restore uninstalled pip from the
  environment. Meta::engine was recorded for exactly this and read by nothing. Verified: a uv
  snapshot previewed for a pip rollback now reports the environment already matches.
- Hold pins are restated at their version in every resolve (H17). hold_requirements existed and
  nothing called it, so a held package was only left out of the upgrade list and free to move as
  anyone's dependency. A hold never releases the packages it collides with - only a forced pin
  does - so its impossibility is shown as it stands.
- PinMode::Exclude's doc promised one-at-a-time updates that filter_upgrades never allowed. The
  rule stays DATA-FLOW §9.5 and the doc now says so (schema-Pin re-blessed for the wording).
- decide() is transactional and the GUI keeps the flow parked when it fails (U24): a failed
  re-resolve used to leave the new request beside the old report, and plan_decide dropped the
  flow, so the preview on screen had a Confirm that answered "no plan".
- An install no longer runs `list --outdated`, a network sweep of every installed package that
  nothing in an install reads (M28).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 e2e75f63fb feat(flow): PipDock enforces Requires-Python itself, as hard invariant 10 says
Invariant 10 says PipDock enforces Requires-Python because the engines disagree, and nothing
did (C2): PD-PKG-001 existed in the catalog and was never raised. pip refused an incompatible
exact pin with the "No matching distribution" it gives a typo (PD-PKG-002); uv honours the
lower bound, ignores the upper one, planned scipy==1.7.3 on Python 3.14 and failed at install
time building it from source.

The update flow now checks three places:
- exact pins the user typed (name==v, name===v), before any engine sees them. A request that is
  nothing but such pins is PD-PKG-001 with the range and the interpreter; otherwise the pin is
  left out and the preview says so (report.incompatible).
- forced pins: forcing a release this Python cannot run stays held back, with the reason.
- what the engine planned. pip's report already says what each release requires, so nothing is
  asked; for uv's plan PyPI is, and each release that excludes this Python is ruled out by name
  (`name!=v`) and the engine asked again, at most twice - it, not PipDock, picks what is next.

crate::release asks https://pypi.org/pypi/{name}/{version}/json for info.requires_python, at most
eight at once with a 15 s watchdog each, and remembers every answer forever in a new store table
(an uploaded release's metadata never changes). A failure is asked again; unknown never blocks.
The PyPI client is shared per process now, rather than rebuilt for every request (M37, part).

Store v4. Migrations ran on every open - a journal_mode write and eight CREATE TABLEs, on a store
some paths open twice per lookup - and an older build set user_version back down, so the next
newer build re-ran them (M38). Both fixed, with tests.

Verified on Python 3.14: `install scipy==1.7.3` is PD-PKG-001 under pip and uv alike, and
`install scipy==1.7.3 six==1.17.0` plans six and says why scipy was left out.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 6ff2a10631 fix(flow): Force latest forces, and says what it breaks before it runs
Choosing Force latest recorded the decision in the request and nothing read it, so the "forced"
resolve was the held-back one again (C6). forced_requirements had existed since M2 with no
production caller. The flow now turns Strategy::ForceLatest into the resolve's GuardAdjust: the
forced package pinned to its latest, and the packages whose constraints held it back released
from the guard set.

Forcing still failed in the canonical case, because the guard set pins every installed package
the plan does not move - the forced package's own dependencies included: httpcore 1.0.9 needs
h11>=0.16 and the guard had h11==0.12.0. Which pins collide is resolution, and PipDock does not
resolve (invariant 3), but the engine names them in its impossibility; forced_collisions
releases exactly those, installed and still pinned, and asks again, at most three times.

report.forced carries each forced package with its blockers - the "Will break" rows DISCLAIMER
§2 requires before anything runs - and the CLI prints them. Verified on a venv seeded with
httpx 0.23.0: under pip and uv both, httpcore -> 1.0.9 and h11 -> 0.16.0, breaking httpx, named.

The underlying over-pinning (a selective upgrade cannot move its target's dependencies) is
recorded in the audit backlog rather than changed here.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 3cfb8f82ec fix(flow): PEP 668 is decided on a fresh probe, and the override works
The gate read env.externally_managed - whatever the caller last cached - before anything was
probed, and the rollback flow had no gate at all (H12). The Settings override saved and nothing
read it, so turning it on changed nothing (H11). Every mutating flow now starts with one
preamble: probe, then decide on what the probe says. Without the override a managed
environment is PD-ENV-002 before any engine command; with it, the flow carries
SystemPackages::OverrideAllowed to every mutating engine call.

SystemPackages is a named value, not a bool, for the reason SnapshotProof is a named waiver:
hard invariant 5 says the flag is never passed implicitly, and this makes "implicitly"
greppable. It reaches pip and uv installs and removals, and uv's dry run, which refuses a
managed environment without it (verified, uv 0.13.1); pip's --dry-run --report is exempt and is
never given it. pip implemented PEP 668 in 23.0 and added the flag in 23.0.1, so below 23.0
nothing is passed and pip 23.0 itself is PD-ENV-002.

The CLI reads the override from the store both heads share - deliberately with no flag of its
own - and says on stderr, every run, that it is in force. Verified against a uv-managed
CPython 3.13 with an EXTERNALLY-MANAGED marker: refused without the override (exit 3); with it,
pip installed and uv dry-ran and removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 5d63b31098 fix(flow): a stale or drifted preview is refused, before the snapshot
DATA-FLOW §9.3 refuses a preview older than ten minutes or one whose environment changed. Both
checks existed in AcceptedPlan::verify and neither could fire (C1): the flow created the plan
inside execute() with the current time, so its age was always zero; it passed the resolve-time
listing as the "current" one, so the fingerprint always matched; and plan::execute compared the
plan's env hash with itself.

AcceptedPlan::accept now takes the basis the report was resolved over - the listing and the
resolve time - and the flow re-probes in take_snapshot, after the user confirmed and before
anything is written, so a refusal costs no snapshot. plan::execute verifies against the hash of
the environment it is actually changing, and acts on the re-probed listing.

The same rule reaches the other two flows (M44): an uninstall re-probes before its snapshot, since
a package installed after the guard ran may depend on what is about to go, and a rollback compares
the freeze it takes with the one its restore plan was diffed against.

One plan id (M31): the snapshot said "update-<env>" for every plan ever made in an environment and
the summary carried a different id. Both now carry the flow's, which is unique per plan.

Five new flow tests fail on the previous code and pass on this one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 f9984fa4fb refactor(flow): FlowOptions and an Engine::probe seam
Every flow probed through a free function, so nothing `start` decides - the PEP 668 gate, the
graph, the drift basis, what reaches the resolver - could be reached by a test without a real
interpreter, and the bugs the next commits fix were all there. Engine::probe is a provided
method (it is probe.py, not an engine command; no adapter overrides it), and tests/flows.rs
drives whole flows against a scripted engine that owns a small, mutable world.

FlowOptions carries what the caller decides before a flow starts: the cancellation token and a
clock. The token is the caller's because the first resolve runs inside `start`, and a token
made there could only be handed out after the resolve it was needed to stop. The GUI
registered a token of its own for that window which nothing listened to, so Stop during a first
resolve did nothing at all (H13); plan_resolve now hands its token to the flow, and a test
proves a hung resolve ends on Stop rather than on its watchdog.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 7e6ad52b4f fix(graph): platform markers are read, and the lexer is safe on any text
The marker evaluator knew python_version and python_full_version and treated every other
variable as unknown, which keeps the requirement in force. The platform markers had been left
out as "constants for a Windows-only v1" - but a constant still has to be read. Unread,
ipython's `pexpect; sys_platform != "win32"` was in force on Windows, so the dependency view
reported pexpect missing from every Windows environment with ipython in it, and the uninstall
guard and pin suggestions counted edges that do not exist there (H25).

ReverseDeps::for_probe evaluates against probe schema 3's marker environment: platform
variables compare as strings with ==, != and PEP 508's `in` / `not in`, which the lexer now
reads. Whatever the probe did not report - platform_release on Windows - still keeps the
requirement. Every production graph (update and uninstall flows, deps_graph, pin suggestions)
is built this way; build_for remains for callers that know only the Python version.

The lexer skipped whitespace a byte at a time and sliced a word's length before checking the
prefix, so a no-break or ideographic space in some installed package's Requires-Dist cut a
character in half and panicked the command (H19).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 53dedf8625 fix(probe): one METADATA parse, a marker environment, and paths with spaces
probe.py read each distribution's METADATA three times - dist.metadata, then dist.version and
dist.requires, which each re-parse it - on the path every environment open pays (M42). One
parse now; an .egg-info still gets its requires.txt. On CPython 3.14 with 64 distributions the
probe went from 154 ms to 118 ms (median of 15, twice), and the dists array is byte-identical.

Probe schema 3 adds the PEP 508 marker environment, so the graph can tell a requirement in
force from one gated to another platform (H25, consumed in the next commit). It is built from
sys and os: platform.uname() is a WMI query on Windows (55 ms on 3.14) for two values almost no
requirement mentions, which are left out there and stay unevaluated.

Discovery:
- py -0p and uv python list rows are "<key> [*] <path>", and the path may contain spaces
  (H26). Taking the last token turned C:\Program Files\Python312\python.exe - where every
  all-users python.org install goes - into a relative path the existence check dropped.
- A 32-bit all-users Python registers under Wow6432Node, which a 64-bit process does not see
  through the default registry view (M48). HKLM is now read in both views.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 c0301fa3e8 fix(parse): uv is read by its exit status; check findings name the right package
uv's adapter handed every outcome to the plan parser, which looked for the words of a plan
(C3). A build that failed still printed "Resolved 1 package", so it previewed as "no changes";
a refused connection matched nothing and was reported as a uv newer than PipDock (PD-ENG-003);
an unknown name came through the resolver as an impossibility and was auto-skipped as a
conflict. uv_resolution and pip_resolution now decide by exit status first: zero is a plan, an
impossibility is a report, anything else is classified like every other engine failure. A new
corpus test asks that function - the one each resolve returns through - about every failed
capture; classifier_corpus.rs had proved each stderr classifies correctly while the adapter
never asked the classifier. Verified against real uv 0.13.1: PD-PKG-002 and PD-NET-001 (exit 6).

check_text read one of the three shapes real engines print (H18, and one found by breaking an
environment on purpose): pip's version conflicts say "has requirement" and were dropped - the
case a post-run check exists for - and every uv finding ("The package `httpx` requires ...")
was filed under a package called "the".

- A pip yank reason is the one line after the warning that names the package (H23). Flattening
  the whole stderr ran it over pip's [notice] lines, which carry the user's home directory, and
  gave the first of two yanked packages both reasons.
- pip's unreadable output is PD-ENG-999, not PD-ENG-003, whose advice is to switch to pip (M34).
- A pip below 22.2 stops at --dry-run, the first option it does not know, so that line is
  PD-ENG-002 too.
- uv 0.11 (miette glyphs) and 0.13 ("cause:" labels) now explain one conflict in the same words.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 8b18dc4795 feat(engine): a resolve can be stopped, and pip's impossibility is a report
Engine::resolve takes a ResolveCtx: the flow's cancellation token, which now reaches the dry-run
command, and a GuardAdjust the flow will use for Force latest, Hold pins and Requires-Python
exclusions (pins replace a name in the request and the guard set, releases leave the guard set,
exclusions ride as `name!=v`). A stopped resolve is FlowStep::Nothing(Cancelled) - nothing
planned, nothing ran - instead of an error (H13).

pip's ResolutionImpossible was a hard error, so under pip one unsatisfiable package failed the
whole preview while uv offered a per-package Skip. The pip adapter now returns
report.impossible, built from pip's "Cannot install A and B" line (H15). The same request now
exits 2 under both engines.

Running it found a defect the requirement files introduced: pip names a requirement that came
from a file as "-r <temp path> (line N)", so the impossibility lost the package the user asked
for and every error row showed a temp path that had already been deleted.
RequirementFiles::humanize puts the line back; uv names requirements by their text and needs
none of it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 d2993bbd7d feat(wire)!: the preview carries what it was missing, and stops carrying the engine's output
A contract change, deliberately in one commit; four schema goldens re-blessed for it
(`ResolutionReport`, `FlowStep`, `CheckReport`, `ExecutionSummary`).

**`ResolutionReport.raw` leaves the wire.** It was pip's whole `--report` document — every
package's README — cloned into each `FlowStep`, serialized over IPC on every round and printed by
`--json` (33 KB for two packages, megabytes for "update all"). Nothing in the UI ever read it. It
stays in Rust (`#[serde(skip)]`) for the log, and for pip it now holds stderr — pip's warnings —
rather than the report the parser already consumed.

**New fields, all omitted when empty, so existing JSON reads the same:**
- `incompatible: [PythonMismatch]` — pins whose `Requires-Python` excludes this environment
  (PD-PKG-001), as structured data: the preview shows the required range against the
  environment's version, which a sentence assembled in Rust could not let it do (invariant 4).
  Filled by a later commit.
- `forced: [HeldBack]` — what "Force latest" will break. Filled by a later commit.
- `yanked: [YankWarning]` — **both adapters parsed yank warnings and then dropped them**
  (`.map(|p| p.report)`), so PD-PKG-003's preview warning has never been shown.
  `ParsedPlan::into_report` keeps them.

**`CheckReport.error`.** A post-execution check that could not run was reported as
`ok: true` — "verified" exactly when nothing was, for instance when the run had broken pip
itself. It is now `ok: false` with the reason's code; the rows still carry the per-package truth.
`CheckReport` therefore embeds `Code`, which makes it the sixth schema that does.

**`NothingReason::Cancelled`**, for a resolve the user stopped (wired in a later commit); the
CLI maps it to exit 130.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 80b2cee9e7 fix(engine): requirements and constraints reach the engine as files
**The command line no longer grows with the environment.** Every plan restates the whole
installed set as requirements (SP-1), and it did so as one argv entry per package — at about 1,300
packages that passes Windows' 32,767-character command line, the spawn fails with os error 206,
and the user was told to install an engine. Resolves and installs now pass `-r <file>` (and
`-c <file>`), written under fresh random names with `TempFile` and deleted on drop. The files hold
exactly the tokens argv held: rendered `PinnedSpec`s and validated `Spec`s. A test restates 2,000
long names and asserts the command line stays under 1,000 characters.

**Every install step holds the rest of the environment still.** SP-1's rule was applied to the
resolve only. Phase B then ran `pip install alpha==2` bare, free to move any dependency — pip warns
and exits 0 when it breaks an installed package's bound — so a failed batch could leave a state
the preview never showed. `Engine::install` now takes an `InstallSet { specs, constraints }`:
Phase A constrains everything the plan does not touch to its current version; a Phase B step adds
the rest of the plan at its planned versions; a rollback restore holds the rest of the restore at
the snapshot's.

Verified against real engines in a throwaway venv (pip 26.2.1 and uv 0.13.1): `-r`/`-c` dry
runs, the SP-1 held-back case and a real install all behave as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 6559ebcc84 feat(model): PEP 440 at the boundary where text becomes argv
SECURITY §2 has always said names *and versions* are validated before argv. Names were; versions
were plain strings, so a dock-bay entry of `2.0 ; python_version<'0'` reached argv as one token pip
read as a requirement whose marker is false — a silent no-op install — and requirements import
failed outright on any range, because `build_request` split on `==` alone (`django>=5.0,<6`
became a "package name"; `pkg===1.0` became version `=1.0`).

New `pep440` module, the one place that says what a version and a specifier set may look like: a
hand-written reader of `packaging`'s `VERSION_PATTERN` (epochs, every pre/post/dev spelling, local
labels — nothing legitimate is refused), a specifier-set grammar (`===`, `.*` prefixes, whitespace
only between an operator and its version), and `is_argv_safe` for installed versions that are not
PEP 440, which the guard set now restates with `===` (packaging dropped `LegacyVersion`, so `==`
would be refused).

Wired in at every way text arrives:
- `Spec::parse` for CLI/GUI install specs and imported requirements; `Spec` and `PinnedSpec` now
  deserialize through the same checks, closing the IPC door the way `PkgName` already did.
- The guard set skips an installed version that could be read as more than one token.
- uv's `+ pkg==0.1.0 (from file:///…)` keeps only the version (it reached argv whole).
- pip report changes and freeze lines with such versions are dropped / unrestorable.
- `pins::validated_hold` and `health::validated_version` were the same charset check twice; both
  use `pep440::is_version` now, which also rejects `1.0--break-system-packages`, a string whose
  every character is in a version's alphabet.

`version_req` is normalized to an operator form (`==0.28.1`), which `plan_argv_specs` already
rendered identically. The one golden that moved is `schema-PlanRequest`, for its doc text.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 3e4f3d0243 fix(plan): Phase A under Stop, a watchdog and an environment-wide failure
`plan::execute` ran the batch with `engine.install(...).await?`. The real adapters return `Err`
when the batch is stopped or cannot start, so that `?` sent all of these out of `execute` as
PD-INT-001 — no summary, no "cancelled", no rollback offer:

- **Stop during Phase A**, which is most of any run: the cancelled-Phase-A branch right below was
  unreachable outside a test whose fake engine returned `Ok` on cancel.
- **The watchdog** on a long sdist build: the whole run aborted, contradicting the
  skip-and-continue requirement it exists to keep.
- **An engine that will not start**.

Now an `Err` is an outcome: a user's cancel marks every row Skipped with `cancelled: true`; any
other failure becomes the batch's code on every row.

**Phase B only runs when it could help.** Isolating re-ran every package one at a time after
*any* batch failure — offline, read-only site-packages, a full disk, a missing or too-old pip, a
watchdog — each meeting the same wall after pip's own retry backoff. `isolates()` keeps those in
Phase A, with the stderr tail on the first row only instead of N copies of one network trace.

**Rows say what they moved from** (`StepResult.from`), taken from the plan's changes; the
engines cannot know it, so every row carried `None` and the summary and `--json` called every
upgrade a fresh install.

A rollback no longer runs `pip check` between its removals and its restores — it nested
`execute_uninstall`, post-check included; both now share the removal loop.

Five new tests, each failing before this: a fake engine that returns `Err(Stop::Cancelled)`,
`Err(Stop::TimedOut)` and a spawn failure the way the adapters do, an offline batch that must not
be isolated, and `from` through both phases.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 8ddb2317f4 refactor(exec): a stopped run says why in its type; the pump survives any bytes
**Typed stops.** A cancelled or watchdog-killed command now returns a `PdError` carrying
`stop: Some(Stop::Cancelled | Stop::TimedOut(_))` (never on the wire). Three modules decided
"was this a cancel or a timeout?" by matching the `"cancelled:"` / `"timed out"` prefixes
`Command::stopped` happened to write — so pip's own "Read timed out" network error was relabelled
a watchdog by Code Health's remap. They ask `is_cancelled()` / `is_timeout()` now. A timeout
carries PD-ENG-004 at this layer; Code Health and the audit still remap it to their own codes.

**The pump reads bytes.** tokio's `lines()` errors at the first byte that is not UTF-8, and the
loop treated that as end of stream: it stopped reading and dropped the pipe, so the child died on
a broken pipe mid-install and the stderr the classifier needed was cut short. MSVC prints in the
OEM code page, so a non-English Windows was one failed source build away. Lines are now read
with `read_until` and decoded lossily; a test writes raw cp-1252/cp-932 bytes through
`cmd /C type` and asserts the line after them arrives.

**Watchdogs per kind of work** (`exec::watchdog`): install 30 min, resolve and `--outdated`
10 min, local queries 3 min, `probe.py` 60 s, `py -0p` / `uv python list` 30 s. One 600 s budget
let a hung `py -0p` hold the Environments screen for ten minutes and killed a slow scipy build.

**Spawn failures map by cause**: a missing interpreter is PD-ENV-001 (it was PD-ENG-001,
"install the engine"), a command line past 32,767 characters is PD-SYS-001.

**`TempFile`** replaces `write_temp`: `create_new` with retry, deleted on drop. The old function
documented that an overwritten temp file would be harmful and then called `fs::write`, and its
comment described a nonce scheme the code did not use. `io_error` maps filesystem failures to
the code whose advice fits (disk full, path too long, permission) instead of always "disk full".

**`Command::python_tool`** gives vulture, deptry and pip-audit the UTF-8 environment
`Command::python` gives interpreters; they are Python launchers and were spawned without it.

**`probe.py` runs with `-X utf8`.** `-I` implies `-E`, which ignores PYTHONUTF8 and
PYTHONIOENCODING, so the probe wrote through the ANSI code page: a venv under a folder named with
Vietnamese diacritics crashed it with UnicodeEncodeError (PD-ENV-003, reproduced) and a Latin-1
path came back as mojibake. `-X` is a command-line option, which isolated mode honours.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 9409a82e84 test(fixtures): pip 26.2.1 and uv 0.13.1 captures, both uv renderings under test
Re-captured by the drift job itself (workflow_dispatch on this branch, Python 3.12.10, artifact
`captured-fixtures`) rather than on a dev machine, so next Monday's run compares like with like.
Copied byte for byte; CRLF counts unchanged where the engine's output did not change.

What actually moved:

- **uv 0.13.1** renders every failure as `error: …` / `cause: …` instead of miette's `× …`,
  `╰─▶` and "Caused by:". The phrases the classifiers key on survived, so nothing reclassified —
  `both_uv_renderings_classify_identically` now pins that, against the frozen `uv-0.11/` corpus.
  The build failure also moved from `build_wheel` to `get_requires_for_build_wheel` and gained a
  `hint:` line.
- **pip 26.2.1** (it was 25.0.1 all along — the capture never upgraded it) prints no release
  notice, and for an unsatisfiable `scipy==1.7.3` now says *which* versions it ignored and why:
  "Ignored the following versions that require a different python version: … 1.7.3
  Requires-Python >=3.7,<3.11". pip 25 said only "No matching distribution found", which is why
  ERROR-CATALOG calls PD-PKG-001 unclassifiable from stderr. On pip ≥ 26 it no longer is.
- `clean-upgrade` now upgrades to the pinned idna 3.10 in both live corpora.

`plan_parsers.rs` and `classifier_corpus.rs` run over `pip/`, `uv/` and `uv-0.11/`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 2b4681954b feat(errors): PD-ENG-004 for an engine watchdog; WinError rules match exactly
**PD-ENG-004 `EngTimedOut`.** Every engine command shares one watchdog, and when it fired the run
reported PD-INT-001 — "PipDock hit an internal error" — for an sdist build that was simply still
compiling, and in the batch phase that error aborted the whole run with no summary and no
per-package retry. A timeout is a fact about the engine, not a PipDock bug, so it gets its own
code. Raised by PipDock, never classified from stderr, so it joins the `internally_raised` table of
the corpus gate. The exec layer starts producing it in the next commit.

The nine places: the catalog variant (`as_str`, `area`, `ALL`), both count tests (34 → 35), the
corpus gate, both `errors.json` catalogues, `codes.json` and `generated.ts` (regenerated, not
edited), the ERROR-CATALOG row (31 → 32 rows), and the five schema goldens that embed `Code` —
`Code`, `StepResult`, `ExecutionSummary`, `HealthReport`, `AuditReport` — each re-blessed for
exactly one new `const`, which is the contract change this is.

**WinError needles include the closing bracket.** Python prints `[WinError N]`, and the bare
"winerror 5" also matched 50, 53 and 59: `[WinError 53] The network path was not found` came out
as PD-PRM-001, "use a venv". `[WinError 53]` and `[WinError 10013]` (a firewall refusing the
socket, raised *as* a PermissionError) now classify as network failures, ahead of the permission
rules that would otherwise take them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 2b07d4057b test(fixtures): the drift gate measures engines, not PyPI
The weekly re-capture has failed seven Mondays running (since 2026-08-31), and for most of them no
engine had changed at all:

- `clean-upgrade` asked for the *latest* idna, so 3.18 → 3.20 was "drift". Pinned to idna==3.10.
- pip's "(from versions: …)" listed every scipy release, so the requires-python fixture grew with
  each one. Redacted, like the release notice before it; no classifier reads it.
- The capture never upgraded pip: every venv ran the CPython-bundled 25.0.1 while 26.2.1 was
  current, so the job meant to catch a pip output change could not see one. `venv.create(...,
  upgrade_deps=True)`, and the report's `pip_version` is redacted because it now moves with each
  pip release (provenance still records it).
- `python-version: '3.12'` floated with the runner image, and the Python patch is recorded in both
  engines' output. Pinned to 3.12.10, the version every committed fixture was captured with.

The job now uploads what it captured whether or not the gate passes, so a real drift is fixed by
reviewing and committing exactly those bytes. `capture.py` also refuses an unknown `--only` name
(it used to capture nothing and exit 0) and exits 1 when nothing was captured; its two
backtracking-prone patterns (SonarCloud S8786) became a `[ \t]` class and a `partition`.

The other half of the red was real: uv 0.13.0 (2026-10-09) replaced its miette rendering — `×`,
`╰─▶`, "Caused by:" — with "error:" / "cause:". `UV_MIN_VERSION` is 0.10, so both renderings stay
under test: the current captures are frozen as `uv-0.11/` (uv 0.11.32, byte-identical copy) before
`uv/` is re-captured against the newest uv. The disposable-venv suite also stops running twice on
Monday mornings (the drift cron matched it too).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 91a846c0fd build(deps): every dependency to its latest release
Supersedes Dependabot #75, #76 and #77, which could not merge while `main`'s audits were red.

Rust (floors raised to what is locked, so the manifests say what is built):
- tauri 2.11.5 → 2.12.4 and tauri-build 2.7.3, with the plugins dialog 2.8.3, opener 2.7.2,
  clipboard-manager 2.5.0 and single-instance 2.5.4 — in lockstep with `@tauri-apps/*` 2.12, which
  Tauri's own version check requires.
- **rusqlite 0.37 → 0.40.2** (libsqlite3-sys 0.38.2, SQLite 3.53.2). ARCHITECTURE §10 held it
  because libsqlite3-sys used the then-unstable `cfg_select!`; that is stable since 1.95 and the
  toolchain is now 1.99.1. Nothing here used `u64`/`usize` `ToSql` (disabled by default since
  0.38) or `prepare_cached` (optional since 0.38), and 0.40.1 fixes a SAVEPOINT-name injection.
- reqwest 0.13.5, tokio 1.53.3, tokio-util 0.7.20, jiff 0.2.38, clap 4.6.7, schemars 1.2.3,
  sha2 0.11.1, thiserror 2.0.21, serde_json 1.0.154, async-trait 0.1.92, insta 1.49.0, and 211
  transitive updates (h2 0.4.20 among them).

npm: React 19.3.1, Vite 8.3.4, @vitejs/plugin-react 6.1.2, **Vitest 5.0.5** (all 18 `vi.mock`
calls were already top-level), ESLint 10.12.0, typescript-eslint 8.71.2, jsdom 30.1.3,
@tanstack/react-virtual 3.14.21, i18next 26.4.7, react-i18next 17.0.19, @types/* current.
**TypeScript stays 6.0.3**: typescript-eslint 8.71.2 still peers `>=4.8.4 <6.1.0`.

Code Health pin: ruff 0.16.3 → 0.17.1. Verified by running it, not by reading its changelog:
`health/sample/capture.py` reproduces all four committed `ruff/*.json` byte for byte, and exit
codes 0/1/2 still mean clean/findings/error.

Two things the upgrade surfaced in the frontend, both real:

- virtual-core 3.19 measures the scroll element with `clientWidth`/`clientHeight` (it used
  `getBoundingClientRect()`), and that first reading replaces `initialRect`. jsdom reports 0, so 13
  table tests and 5 App-level ones went back to rendering an empty grid; the setup now stubs the
  two properties beside the `offset*` ones.
- jsdom 30.1 implements "a closed `<dialog>`'s contents cannot take focus", which is the spec.
  React applies `autoFocus` by calling `focus()` during commit — *before* PdDialog's effect calls
  `showModal()` — and never writes the `autofocus` attribute, so neither path focused Cancel. It
  worked in WebView2 only because Cancel is the first focusable element. PdDialog and the palette
  now focus explicitly after `showModal()`, and return focus to whatever opened them on close
  (it fell to `<body>` before).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 d9c62ec6c9 fix(deps): rustls 0.23.46, quinn-proto 0.11.19, and the npm highs — main is green again
`main` has failed `cargo audit` since 2026-09-23 and every PR with it, because both audit checks are
required:

- rustls 0.23.42 → 0.23.46 (RUSTSEC-2026-0285, TLS 1.3 handshake messages accepted across key
  changes). `cargo update -p rustls` alone stops at 0.23.43: the fix needs aws-lc-rs 1.18 and
  rustls-webpki 0.103.15, which a conservative update will not move, so it is pinned with
  `--precise`.
- quinn-proto 0.11.16 → 0.11.19 (RUSTSEC-2026-0338..0342). Lockfile-only — nothing compiles quinn
  — but `cargo audit` scans the whole lockfile.
- chacha20 0.10.1 → 0.10.2 (the old one is yanked).
- npm: undici 8.9.0 → 8.12.2 (via jsdom), source-map-js 1.2.1 → 1.2.2, brace-expansion → 5.0.12, all
  dev-only. `npm audit fix` without `--force`; `npm audit --audit-level=high` reports 0.

Dependabot could not have done this: there are no Dependabot alerts for rustls, and its grouped PRs
only move direct dependencies.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 1af0ec127b build(toolchain): Rust 1.99.1
Five stable releases behind (1.94.1, 2026-03-25). Two reasons to move now rather than on the next
Dependabot nudge:

- The rustls fix for RUSTSEC-2026-0285 (>= 0.23.45) does not resolve under `rust-version = "1.94"`:
  resolver 3 is MSRV-aware and stops at 0.23.43, so `main`'s red `cargo audit` cannot be fixed on
  the old pin at all.
- `cfg_select!` is stable since 1.95, which is the condition ARCHITECTURE §10 set for lifting the
  rusqlite 0.37 hold.

`rust-version` moves with the pin, so the workspace never claims a floor it is not built with.
Clippy 1.99 adds `chunks_exact_to_as_chunks`; the build script's SHA-256 now uses `as_chunks`, which
also removes two `try_into().unwrap_or` fallbacks that could never fire.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
dependabot[bot] 2300b637a9 build(deps): Bump @vitest/mocker and vitest
Bumps [@vitest/mocker](https://github.com/vitest-dev/vitest/tree/HEAD/packages/mocker) to 4.1.11 and updates ancestor dependency [vitest](https://github.com/vitest-dev/vitest/tree/HEAD/packages/vitest). These dependencies need to be updated together.


Updates `@vitest/mocker` from 4.1.10 to 4.1.11
- [Release notes](https://github.com/vitest-dev/vitest/releases)
- [Changelog](https://github.com/vitest-dev/vitest/blob/main/docs/releases.md)
- [Commits](https://github.com/vitest-dev/vitest/commits/v4.1.11/packages/mocker)

Updates `vitest` from 4.1.10 to 4.1.11
- [Release notes](https://github.com/vitest-dev/vitest/releases)
- [Changelog](https://github.com/vitest-dev/vitest/blob/main/docs/releases.md)
- [Commits](https://github.com/vitest-dev/vitest/commits/v4.1.11/packages/vitest)

---
updated-dependencies:
- dependency-name: "@vitest/mocker"
  dependency-version: 4.1.11
  dependency-type: indirect
- dependency-name: vitest
  dependency-version: 4.1.11
  dependency-type: direct:development
...

Signed-off-by: dependabot[bot] <support@github.com>
2026-09-23 07:32:37 +07:00
poli0981andClaude Opus 5 f770e9c85f fix(deps): h2 0.4.16 — RUSTSEC-2026-0258
Unrelated to this slice, and blocking its required `cargo audit` gate.
`main` is equally affected: the advisory was published 2026-08-17 and
reached the RustSec database at 10:23+02:00 on the 18th, while main's
last audit ran at 07:08 that morning and passed. The next push to main
would have failed on it regardless of this branch.

Low severity, denial-of-service: h2 accepted and queued empty DATA
frames without limit, so an undrained stream could grow memory without
bound or panic on length overflow. Reached transitively through
reqwest and hyper; PipDock's only network use is the package index and
metadata fetches, both to pypi.org, so nothing here is exposed to an
attacker-chosen peer. Fixed rather than ignored anyway, because
SECURITY.md is explicit that the vulnerability gate is never relaxed —
the `.cargo/audit.toml` ignore list is for *informational* advisories
on crates we cannot influence, and this one has a patch release.

`cargo update -p h2 --precise 0.4.16` and nothing else. The lockfile
diff looks alarming and is not: sixteen of its eighteen lines are
dependency *edges* re-pointing between `windows-sys` copies that
already coexist in the lock — five of them before this change and five
after. No package is added, removed or downgraded, and the only version
that moves is h2's own. `cargo check --workspace --all-targets` and the
full test suite pass on it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-21 08:35:15 +07:00
poli0981andClaude Opus 5 02cc17d95d docs: the dependency view recorded, and 1.3.0
UI-SPEC §4 gains the screen and **loses the sentence it contradicted**.
It said the third row action folds all three into a `⋮` menu "with the
budget intact"; that makes uninstall four clicks where §5's table
records three, hand-counted. The correction is written as a correction
rather than an overwrite, because the reason it slipped through is the
useful part: four is under the ceiling of five, and a ceiling is not a
ratchet — a table of measured counts is. §5 gains the row, §6 the
component, ARCHITECTURE §4 the forward direction and the whole-graph
value.

**The dangling cross-reference is repaired by writing what it promised.**
`ROADMAP.md` has pointed at "the analysis above" for what blocks P1-6
and P1-7 since 1.2.0, and no such analysis was anywhere in the document
— the survey lived only outside the repository, and the sentence had
been copied into CLAUDE.md as well. P1-6's half is its slice record.
P1-7's is now written too, and counted against the tree rather than
recalled: no toast component, no notification/autostart/tray dependency,
one plan-scoped `tokio::spawn` and zero intervals in either head, and no
surface that can report a failure at 03:00 while `logs_tail` is still
`NOT_YET`. Drafting this commit I nearly shipped a CLAUDE.md line
claiming that survey existed before I had written it, which is the same
defect one layer up.

Version in five places, moved together: the workspace inherits it, so
`Cargo.toml`, `package.json` and `tauri.conf.json` are the only hand
edits and the two lockfiles are regenerated. Hand-editing `Cargo.lock`
would have been wrong twice over — `scopeguard` and `simd_cesu8` are
also at 1.2.0 and `fs_extra` was already at 1.3.0. `cargo metadata
--locked` passes, which is the one-command check.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-21 08:35:15 +07:00
poli0981andClaude Opus 5 8609518a37 test(ui): drive the shell against a logging bridge
The jsdom form of the recipe that has found more real defects here than
any suite: render the app, log every command that crosses, read back
what actually happened. Stage 2 found every screen fetching twice this
way and Stage 4 found a plan resolving into a screen that does not
render it — both faults *between* components, which is the one place a
component suite cannot look.

It proves the premise the slice is built on where it can actually be
observed: `deps_graph` crosses **once** when the view opens and **zero**
times on a re-centre. It also covers the seam nothing else did — the
row's new button through the table, the screen, the store and out to the
bridge — and pins the three row actions with none of them a tab stop.

Writing it found the trap the browser recipe already records, in its
jsdom form. `App` calls `checkConsent()` on mount and
`useLegalStore.check` **fails closed**, so setting `accepted: true` in
the store is undone a tick later by the real command rejecting and the
legal gate replaces the entire shell. The store reached `phase: 'ready'`
with the graph in hand and every assertion was reading a licence
agreement. Both halves have to be stubbed; the comment says so.

The browser pane could not reach localhost in this session, so this
stands in for the live drive rather than replacing it — the Rust side
of a command and the real window still want a human.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-21 08:35:15 +07:00
poli0981andClaude Opus 5 6ef677bc01 feat(ui): the dependency view, drawn at the one depth that survives the data
A mode of the package screen, not a tenth tab. `PdEnvironments` switches
to `PdEnvDetail` on `openFor`; this switches on `focus`, for UI-SPEC §4's
reason: `Ctrl+1..9` is positional over `NAV_KEYS`, appending is free and
inserting is not, and a Dependencies tab would have to sit beside
Installed to read as related. `NAV_KEYS` is already nine, so a tenth
entry would have no digit at all.

Three columns at depth 1, and depth is navigated by re-centring rather
than drawn. That is a measurement, not a preference: on the 352-package
fixture a depth-1 neighbourhood is a median of 7 nodes, and depth 2 is a
median of 172 and exceeds 60 for 212 of 352 packages. No layout
algorithm makes 172 nodes legible, so the eleventh runtime dependency, a
THIRD-PARTY-NOTICES edit that re-shows the legal gate, and a CSP
argument all buy a picture nobody can use. Transitive reach is two
numbers instead, and paths are not offered at all — `setuptools` has
more than 2000 distinct paths to a root in that environment.

**UI-SPEC §4 said the third row action folds all three into a `⋮` menu.
It does not.** A menu spends one click opening and one choosing, so
uninstall becomes four clicks where §5's table records three,
hand-counted. Four is under the ceiling of 5, which is exactly why the
budget alone would have let it through. A third inline button costs
nothing: the row is the only tab stop, so the controls are a roving
sequence and a third is one more arrow step, not 200 more stops.

Nothing is carried by colour. `styles.css` rebinds every `--color-*` to
a system keyword in forced-colors, so every edge states its specifier as
text and the columns are told apart by heading and position.

`deps_graph.json` is computed by `fixtures::deps_graph`, never written —
`numpy_blockers`' lesson. It turned out to carry two dependents with two
different specifiers *and* two packages with unsatisfied requirements,
which is more than a hand-written one would have thought to include.

Two defects the tests found by being run against mutations rather than
by being written: a column helper keyed on copy silently matched nothing
once the heading pluralised ("2 packages require this", not "requires"),
and a name-only comparison of the dependents column passed a mutation
that dropped the version and the specifier from every row.

The invalidation is the one this slice was warned about: `freshGraph`
keys on `envHash`, which a mutation does not change, so `App.tsx` resets
the slice in `onFinished`. Health and Security guard and never reset
because nothing they read is altered by an install. Edges are exactly
what an install alters.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-21 08:35:15 +07:00
poli0981andClaude Opus 5 c58fcac523 feat: deps_graph, and the shape it deliberately is not
`pin_suggestions`' shape, not `audit_run`'s. No `Sessions` slot, no
progress channel, no cancellation: those exist because an audit is
18-68 seconds, and a probe is 605 ms. Borrowing them here would be a
constant carrying its original units — the mistake `AUDIT_TIMEOUT`
already records.

One call per environment rather than one per package, which is the
whole reason the value is shaped this way. The view re-centres on a
click; a `deps_for(pkg)` command would read more naturally and pay a
probe for every click to answer a question the previous probe already
held the data for.

No store read, so there is no guard to drop — `pkg_list` is the same
and for the same reason. All five sites: the command, the handler list,
`COMMANDS`, the wrapper with `DepsGraph` added to the `import type`
list (`export type *` does not bring it into scope for a wrapper's own
signature), the `test/ipc.ts` mock, and ARCHITECTURE §7 — with its
trailing pipe, which the test added two commits ago now checks.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-21 08:35:15 +07:00
poli0981andClaude Opus 5 4ddec61ebb feat(wire): DepsGraph is a schema type
Registered in `schema_for!` and `SCHEMA_TYPES`, and in `golden.rs`'s own
copy of that list — the deliberate second list, which
`schema_lists_exactly_the_documented_types` holds in step by reading the
real one back out of the binary.

Only the root type, as the comment beside `HealthReport` says: the
generator hoists every `$defs` entry, so `DepEdge` and `DepsNode` arrive
as their own TS declarations without being listed, and listing them
would emit each twice.

`golden__schema-unknown-type.snap` churns because the error message
enumerates every known type, which is a real behaviour change rather
than noise. 67 snapshots.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-21 08:35:15 +07:00
poli0981andClaude Opus 5 bf2947b6c3 feat(core): the forward direction, and the graph as one value
`ReverseDeps` has been reverse-only since S3. Three features read it and
all three look exactly one edge out, so nothing ever needed to ask what
a package requires. PRD P1-6 does.

`forward` is built in the same pass, from the same parse, and filtered
by the same `applies_in` rule — a second traversal is how the two
directions would come to disagree. `edges_to` goes further and projects
`breaking_dependents` rather than walking `edges` again, so the
dependents column and the uninstall guard are the same set by
construction; the test asserts it whole rather than by name, after a
mutation that dropped the version and the constraint passed a name-only
comparison.

`unsatisfied` is the one thing this can say that the package list
cannot, and it is only trustworthy because the markers are evaluated.
Measured on the 352-package fixture: counting raw `Requires-Dist` names
reports **7** missing packages; evaluating markers reports **1**. The
other six are backports gated on a Python this environment is not. That
gap is the whole argument for this living in Rust.

`view` crosses the bridge whole rather than a package at a time,
because the alternative pays a 605 ms probe on every re-centring click.
Uncapped on purpose: the window is bounded in the view, but the
"+ N more" count has to come from the full set or a capped view
misreports a total.

Measured in --release against C:\Python314, 352 packages: build 1.8 ms,
view 42.9 ms, payload 249 KB, 1858 in-force edges, impact median 20 /
p90 111 / max 178. Having `reach` walk `forward` itself takes the view
to 31.4 ms — 1.8% of the probe the user is already waiting for, bought
with a second copy of the in-force rule. Declined, and the number is in
the doc so it is not re-litigated.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-21 08:35:15 +07:00
poli0981andClaude Opus 5 3152c55eaa fix(docs): three things main was carrying, and the gate that missed one
Found while surveying P1-6. None is caught by any suite, which is the
common thread rather than a coincidence.

`docs/ARCHITECTURE.md`'s `audit_run` row was the only row in the §7
command table missing its trailing pipe, so the table rendered wrong
from 1.2.0. Every gate passed: the command is registered, declared and
documented, and `documented()` strips only the *leading* pipe, so the
row parsed correctly and nothing looked at its shape. A spec sentence
is not a test — and neither is a spec table. The new
`the_architecture_table_is_well_formed` asserts the shape as well as the
contents, and was mutation-checked against the row it was written for.

`catalog.rs`'s comment read "Rust has 33; docs tabulates 30" three
lines above `assert_eq!(Code::ALL.len(), 34)`. Both numbers were one
behind; the doc tabulates 31, folding PD-HLT-001..004 into one row.

CLAUDE.md's error-code checklist named three schemas embedding `Code`
while saying "four", and 1.2.0 made it genuinely four by adding
`AuditReport` via `ToolProblem.code` — five snapshot files in all. So
anyone adding a code today would leave `golden__schema-AuditReport.snap`
stale. The line now says to grep `PD-ENV-001` across the snapshots
rather than trust the list, because that is how the omission was found.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-21 08:35:15 +07:00
346 changed files with 28917 additions and 5536 deletions

No files matched your search

+25 -6
View File
@@ -8,8 +8,9 @@
# individually rather than switched off as a class, so a new one still fails CI and has to be
# looked at rather than silently absorbed.
#
# Review obligation: when Tauri drops GTK3, or a `unic-*` dependent moves on, delete the
# corresponding lines. A stale ignore is how a real advisory eventually gets waved through.
# Review obligation: when Tauri drops GTK3, its plugins move to zbus 6, or a `unic-*` dependent
# moves on, delete the corresponding lines. A stale ignore is how a real advisory eventually gets
# waved through.
[advisories]
ignore = [
@@ -29,12 +30,30 @@ ignore = [
"RUSTSEC-2024-0419", # gtk3-macros — unmaintained
"RUSTSEC-2024-0420", # gtk-sys — unmaintained
"RUSTSEC-2024-0429", # glib — unsound (VariantStrIter::impl_get); same GTK3 stack
# --- Build-time only -----------------------------------------------------
# A proc-macro helper pulled in by a build dependency. It never reaches a shipped binary, and
# the advisory is "unmaintained", not a defect.
# A proc-macro, reached through glib-macros: the same stack, not a build dependency of
# PipDock's as this file used to say (`cargo tree -i proc-macro-error --target all`).
"RUSTSEC-2024-0370", # proc-macro-error — unmaintained
# --- zbus 5's D-Bus stack (Linux only) -----------------------------------
# zbus 6 (2026-10-16) folded these three crates into itself, and the advisories were filed the
# same day. zbus reaches the tree only through tauri-plugin-opener and
# tauri-plugin-single-instance, which use D-Bus on Linux alone: `cargo tree -i zbus --target
# x86_64-pc-windows-msvc` prints nothing. Every release of both plugins — 2.x and the 3.0
# alphas alike — still requires zbus ^5.9, so there is no update to take. Delete these lines
# when the plugins move to zbus 6, or at P2-1 with the GTK3 block above.
"RUSTSEC-2026-0370", # zvariant — unmaintained, merged into zbus 6
"RUSTSEC-2026-0371", # zbus_names — unmaintained, merged into zbus 6
"RUSTSEC-2026-0372", # zvariant_derive — unmaintained, merged into zbus 6
# --- chrono, listed and never compiled ----------------------------------
# Cargo.lock names chrono only because serde_with 3.24's `std` feature carries the weak
# features `chrono_0_4?/clock` and `chrono_0_4?/std`, and Cargo's lock resolution records an
# optional dependency that a weak feature mentions even when nothing enables it. serde_with
# comes in through tauri-utils; `cargo tree -i chrono --target all` prints nothing, so no
# target — the shipped Windows one included — compiles it. PipDock's own dates are jiff, the
# advisory's first recommendation. Delete this line when Cargo.lock stops listing chrono.
"RUSTSEC-2026-0543", # chrono — unmaintained
# --- unic-* Unicode tables ----------------------------------------------
# Superseded upstream but functionally frozen data tables, reached transitively. Nothing here
# parses untrusted input on PipDock's behalf.
+66
View File
@@ -0,0 +1,66 @@
name: Accessibility barrier
description: Something in PipDock is hard or impossible to use with a keyboard, a screen reader, high contrast or larger text
title: "[A11y]: "
labels: ["accessibility", "triage"]
body:
- type: markdown
attributes:
value: |
Thank you for telling us. You do not need to know the cause, name a WCAG criterion or
suggest a fix — what you were trying to do and what happened is a complete report.
If filling in a form is itself the barrier, write to **accessibility@poli0981.dev**
instead. Vui lòng viết bằng English hoặc Tiếng Việt đều được.
- type: textarea
id: what-happened
attributes:
label: What were you trying to do, and what happened instead?
placeholder: "I tabbed to a package row and could not reach the Remove button."
validations:
required: true
- type: dropdown
id: impact
attributes:
label: How much does it get in your way?
description: This decides how soon it is fixed. A barrier that stops you goes into the next release.
options:
- "It stops me — I cannot do this at all"
- "I can do it, but only with real difficulty or a workaround"
- "It slows me down or is confusing"
- "It is a small annoyance"
validations:
required: true
- type: input
id: assistive-tech
attributes:
label: Assistive technology and version, if any
placeholder: "Narrator (Windows 11 24H2) · NVDA 2026.3 · a contrast theme · 200% display scale · keyboard only"
- type: dropdown
id: where
attributes:
label: Where in PipDock?
options:
- "The desktop application"
- "The pipdock command line"
- "The installer"
- "The documentation or this repository"
validations:
required: true
- type: input
id: pd-version
attributes:
label: PipDock version
placeholder: "x.y.z — shown under About → This build"
validations:
required: true
- type: input
id: os
attributes:
label: Windows version
placeholder: "Windows 11 24H2 (26100.x)"
- type: textarea
id: steps
attributes:
label: Steps to reproduce (optional)
description: The keys you pressed, or what your screen reader said, in order. A recording is welcome and not required.
placeholder: "1. Ctrl+2 … 2. Tab to the first row … 3. …"
+6 -1
View File
@@ -9,11 +9,16 @@ body:
Thanks for the report! If you came here from the in-app **Report bug** button, most fields
are prefilled and the full log was copied to your clipboard — paste it below if asked.
Vui lòng viết bằng English hoặc Tiếng Việt đều được.
PipDock is in **maintenance mode**: bugs, UI/UX defects and accessibility barriers are
exactly what it is maintained for. A feature request filed here is closed automatically —
see CONTRIBUTING.md, "Scope in maintenance mode".
- type: input
id: pd-version
attributes:
label: PipDock version
placeholder: "1.0.0"
# Not a version number: any example goes stale with the next release, as "1.0.0" did.
placeholder: "x.y.z — shown under About → This build"
validations:
required: true
- type: input
+6 -3
View File
@@ -3,9 +3,12 @@
blank_issues_enabled: false
contact_links:
- name: Feature request — not accepted during maintenance
url: https://github.com/poli0981org/pipdock/blob/main/CONTRIBUTING.md#scope-in-maintenance-mode
about: Since 1.6.0 PipDock takes fixes, not features. An issue or pull request asking for one is closed automatically; this explains what is accepted, and where to argue that something is truly necessary.
- name: Question or idea
url: https://github.com/poli0981/pipdock/discussions
about: Ask about usage, propose a feature, or share a workflow.
url: https://github.com/poli0981org/pipdock/discussions
about: Ask about usage or share a workflow. Ideas are welcome to discuss, but during maintenance they are not on a roadmap.
- name: Security vulnerability
url: https://github.com/poli0981/pipdock/security/advisories/new
url: https://github.com/poli0981org/pipdock/security/advisories/new
about: Report privately via GitHub Security Advisories. Please do not open a public issue.
+52
View File
@@ -0,0 +1,52 @@
name: Wording or translation problem
description: Text in PipDock that is wrong, misleading, misspelt, or reads badly in English or Vietnamese — Câu chữ hoặc bản dịch sai, gây hiểu nhầm, sai chính tả hay không tự nhiên
title: "[Wording]: "
labels: ["i18n", "triage"]
body:
- type: markdown
attributes:
value: |
PipDock is in maintenance mode, and fixing words is part of it: a sentence that misleads, a
spelling mistake that changes the meaning, or a translation that does not sound like
Vietnamese as people speak it is a bug worth a report. Quote the text exactly as it
appears — that is how it is found in the catalogues.
PipDock đang ở giai đoạn bảo trì, và sửa câu chữ là một phần việc đó: một câu dễ gây hiểu
nhầm, lỗi chính tả làm sai nghĩa, hay bản dịch không giống cách người Việt vẫn nói đều đáng
được báo. Hãy chép nguyên văn đoạn chữ như nó hiện trên màn hình.
- type: dropdown
id: language
attributes:
label: Which language? / Ngôn ngữ nào?
options:
- "English"
- "Tiếng Việt"
- "Both / Cả hai"
validations:
required: true
- type: textarea
id: current
attributes:
label: The text as it is now / Đoạn chữ hiện tại
description: Exactly as it appears, and where — the screen, the dialog, or the CLI command.
placeholder: "Environments → the button beside Rescan: \"…\""
validations:
required: true
- type: textarea
id: problem
attributes:
label: What is wrong with it / Vấn đề là gì
description: Misleading, wrong, misspelt, unnatural — and, if it misleads, what you understood from it.
validations:
required: true
- type: textarea
id: suggestion
attributes:
label: A better wording, if you have one / Cách viết tốt hơn, nếu có
- type: input
id: pd-version
attributes:
label: PipDock version
placeholder: "x.y.z — shown under About → This build"
validations:
required: true
+49
View File
@@ -0,0 +1,49 @@
<!--
One pull request is one slice: a single thing, taken deep, with its tests. CONTRIBUTING.md has the
details. Delete the sections that do not apply.
PipDock is in maintenance mode (CONTRIBUTING.md, "Scope in maintenance mode"): a pull request that
adds a feature is closed automatically, and so is one titled `feat:`.
-->
## What kind of change
- [ ] A bug fix
- [ ] A UI/UX defect
- [ ] An accessibility barrier
- [ ] Wording or a translation (English or Vietnamese)
- [ ] A dependency, runtime or toolchain update
- [ ] A security fix
- [ ] Documentation
## What this changes
<!-- What a user or a script would notice, and why. Link the issue or the docs/ROADMAP.md entry. -->
## How it was checked
<!-- The commands you ran, and what you did in the running app. "Tests pass" is not the whole answer:
most defects in this project were found by running it. -->
- [ ] A test fails without this change and passes with it
- [ ] `npm run lint`, `npm run typecheck`, `npm test`
- [ ] `cargo fmt --check`, `cargo clippy --workspace --all-targets -- -D warnings`, `cargo test --workspace --locked`
## If it touches…
- [ ] **A Rust type that crosses to the UI** — bindings regenerated (`cargo run -p xtask -- bindings`)
- [ ] **CLI output** — goldens re-blessed deliberately, and the diff is the change you meant
- [ ] **User-visible text** — added to both `ui/src/locales/en` and `ui/src/locales/vi`; nothing phrased in Rust
- [ ] **A new error code** — every place `CLAUDE.md` lists, both `errors.json` included
- [ ] **Behaviour a user reads about** — `docs/` updated, and `legal/` checked separately
- [ ] **Something a user would notice** — an entry in `changelog/`
## Accessibility (for any change to the interface)
- [ ] Everything new can be reached and operated with the keyboard alone
- [ ] Focus is visible, and goes somewhere sensible when the screen changes or a dialog closes
- [ ] Controls that show only a symbol have an accessible name; inputs have labels
- [ ] Nothing is said by colour alone, and a destructive button carries `data-destructive`
- [ ] Checked once with a screen reader, or said here that it was not
<!-- ACCESSIBILITY.md is the statement these keep true. -->
+2 -2
View File
@@ -4,13 +4,13 @@
The latest release gets fixes. The previous minor gets security-only patches for 90 days. There is
no update channel — PipDock does not update itself, so a fix reaches you when you download the new
build from [Releases](https://github.com/poli0981/pipdock/releases).
build from [Releases](https://github.com/poli0981org/pipdock/releases).
## Reporting a vulnerability
**Do not open a public issue.** Use either:
- [GitHub Security Advisories](https://github.com/poli0981/pipdock/security/advisories/new) — preferred
- [GitHub Security Advisories](https://github.com/poli0981org/pipdock/security/advisories/new) — preferred
- `code@poli0981.dev`
Target acknowledgment is 7 days. Coordinated disclosure is preferred; tell us if you have a
+78 -10
View File
@@ -1,13 +1,31 @@
# Dependency updates — docs/RELEASE-CI.md §2.
#
# Dependabot, not Renovate: there is no Renovate configuration anywhere in the poli0981/.github
# ops repo, and that repo ships a dependabot-summary.yml, which makes Dependabot the portfolio
# standard.
# Dependabot, not Renovate: Dependabot was the standard of the owner's ops repo when the CI was
# set up, and it still is across the poli0981org organization.
#
# Grouping intent carried over from the original spec: weekly grouped minor/patch PRs per
# ecosystem, and Code Health pins kept in their own group so they stay reviewable in isolation.
# Security advisories bypass grouping and schedule automatically — that is Dependabot's default
# for security updates and cannot be configured away here.
# Weekly grouped PRs per ecosystem, with Code Health's pins kept apart so a tool bump is reviewed
# on its own. Security advisories bypass grouping and schedule — that is Dependabot's default for
# security updates and cannot be configured away here.
#
# **Cooldown**: a release has to be a few days old before it is proposed. Most yanked or
# compromised releases are pulled within that window, and nothing here needs a dependency the day
# it ships.
#
# **Tauri moves in lockstep**: the `tauri` crate and `@tauri-apps/api` must share a minor or the
# app will not start, and Dependabot cannot bump Cargo and npm in one pull request — a
# multi-ecosystem group can, but what it does to the dependencies outside its patterns is not
# documented, and guessing wrong would silently stop every other update. So each ecosystem groups
# its Tauri packages into one PR, and ci-node.yml's `tauri lockstep` job fails either PR until its
# counterpart is merged beside it.
#
# **A group's position decides nothing.** Dependabot gives a dependency to the *most specific*
# group that matches it, and a group with `update-types` counts as more specific than one with
# patterns alone: on 2026-11-21 its log read "Skipping tauri-plugin-dialog for group 'tauri' -
# belongs to more specific group 'cargo-minor-patch'", and every Tauri bump of that week (#116,
# #118) landed in the catch-all groups. This file said the order kept them out. What does is
# `exclude-patterns` on each catch-all, below.
#
# The labels below must exist in the repository, or Dependabot opens its PRs without them.
version: 2
@@ -18,9 +36,23 @@ updates:
interval: weekly
day: monday
open-pull-requests-limit: 5
cooldown:
default-days: 3
semver-major-days: 14
ignore:
# src-tauri takes rfd only because tauri-plugin-dialog already compiles it, and 2.8.4 — the
# newest — still requires rfd ^0.17, so rfd 0.18 alone (#112) would put a second rfd in the
# binary. Remove this when tauri-plugin-dialog moves to rfd 0.18, and bump both together:
# `cargo tree -i rfd --target all` must still show one rfd. (The same ignore, at 0.17, went
# on 2026-11-04 when its own condition was met.)
- dependency-name: rfd
versions: ['>=0.18.0']
groups:
tauri:
patterns: ['tauri', 'tauri-*']
cargo-minor-patch:
update-types: [minor, patch]
exclude-patterns: ['tauri', 'tauri-*']
labels: [dependencies, rust]
- package-ecosystem: npm
@@ -29,9 +61,25 @@ updates:
interval: weekly
day: monday
open-pull-requests-limit: 5
cooldown:
default-days: 3
semver-major-days: 14
ignore:
# typescript-eslint 8.71 peers `typescript >=4.8.4 <6.1.0`, so a 6.1 bump fails `npm ci` with
# ERESOLVE before a single check runs. Remove once typescript-eslint widens its range.
- dependency-name: typescript
versions: ['>=6.1.0']
groups:
tauri:
patterns: ['@tauri-apps/*']
# @vitest/coverage-v8 peers `vitest` at its exact version, so the two must move in one PR —
# majors included, which is why this group names no update-types: a vitest major bumped
# alone fails `npm ci` with ERESOLVE, as the typescript one below would.
vitest:
patterns: ['vitest', '@vitest/*']
npm-minor-patch:
update-types: [minor, patch]
exclude-patterns: ['@tauri-apps/*', 'vitest', '@vitest/*']
labels: [dependencies, frontend]
- package-ecosystem: github-actions
@@ -39,14 +87,34 @@ updates:
schedule:
interval: weekly
day: monday
cooldown:
default-days: 7
groups:
actions:
patterns: ['*']
labels: [dependencies, ci]
# Code Health tool pins (deptry / vulture / ruff), shipped with the app and resolved at release
# time — CODE-HEALTH-SPEC §2. Kept as its own ecosystem so a bump here is never bundled with
# application dependencies.
# Code Health tool pins (deptry / vulture / ruff / pip-audit), shipped with the app and resolved
# at release time — CODE-HEALTH-SPEC §2. Its own ecosystem, so a bump here is never bundled with
# application dependencies. A bump also needs tools-constraints.txt regenerated (the command is
# in its header); `cargo test` fails until it is.
- package-ecosystem: pip
directory: /tools
schedule:
interval: weekly
day: monday
cooldown:
default-days: 7
groups:
code-health:
patterns: ['*']
labels: [dependencies, code-health]
# rust-toolchain.toml's pinned channel. A toolchain bump brings new clippy lints, which is why
# it gets a PR of its own rather than arriving with a cargo update.
- package-ecosystem: rust-toolchain
directory: /
schedule:
interval: weekly
day: monday
labels: [dependencies, rust]
+164
View File
@@ -0,0 +1,164 @@
#!/usr/bin/env python3
"""Post PipDock's release announcements and CI-failure alerts to Discord webhooks.
Vendored on 2026-11-21, when the repository moved to the poli0981org organization: until then the
notifier was a reusable workflow in the owner's personal ops repo (`poli0981/.github`), which checked
out that repo's `main` and ran *its* copy of a script like this one with PipDock's webhooks in the
environment. A project in the organization no longer runs code another account can change, so the
script lives here — adapted from OmniDeck's self-contained notifier.
Standard library only, so the workflow needs no setup step. Every input comes from environment
variables set by `notify.yml`, never from `${{ }}` interpolated into a shell:
release GITHUB_REPOSITORY, GH_TOKEN, TAG, DISCORD_WEBHOOK, DISCORD_WEBHOOK_EXTRA (optional)
failure GITHUB_REPOSITORY, WORKFLOW_NAME, RUN_URL, BRANCH, COMMIT_SHA, COMMIT_MESSAGE, ACTOR,
EVENT, DISCORD_WEBHOOK
A missing webhook (a fork, or a secret not set) is a notice, not a failure. DRY_RUN=1 prints the
payload instead of posting it, which is how the script is checked without telling Discord anything.
"""
from __future__ import annotations
import json
import os
import sys
import urllib.error
import urllib.parse
import urllib.request
COLOR_RELEASE = 0x57F287 # green
COLOR_PRERELEASE = 0xFEE75C # yellow
COLOR_FAILURE = 0xED4245 # red
# Discord's edge rejects Python's default user agent.
USER_AGENT = "PipDock-notify (+https://github.com/poli0981org/pipdock)"
# The release's downloads, in the order a reader wants them: the installer most people need, the
# MSI for managed deployment, and the checksums both are verified against.
ASSET_SUFFIXES = ("_x64-setup.exe", "_x64_en-US.msi", "SHA256SUMS.txt")
def env(name: str) -> str:
return os.environ.get(name, "").strip()
def truncate(text: str, limit: int) -> str:
return text if len(text) <= limit else text[: limit - 1].rstrip() + "…"
def compact(embed: dict) -> dict:
return {key: value for key, value in embed.items() if value}
def get_release(repository: str, tag: str, token: str) -> dict:
url = f"https://api.github.com/repos/{repository}/releases/tags/{urllib.parse.quote(tag, safe='')}"
headers = {
"Accept": "application/vnd.github+json",
"User-Agent": USER_AGENT,
"X-GitHub-Api-Version": "2022-11-28",
}
if token:
headers["Authorization"] = f"Bearer {token}"
with urllib.request.urlopen(urllib.request.Request(url, headers=headers), timeout=20) as response:
return json.load(response)
def downloads(assets: list[dict]) -> str:
lines = []
for suffix in ASSET_SUFFIXES:
asset = next((a for a in assets if a.get("name", "").endswith(suffix)), None)
if asset:
lines.append(f"[{asset['name']}]({asset['browser_download_url']})")
return "\n".join(lines)
def release_payload() -> dict:
repository, tag = env("GITHUB_REPOSITORY"), env("TAG")
if not tag:
raise ValueError("TAG is empty")
release = get_release(repository, tag, env("GH_TOKEN"))
prerelease = bool(release.get("prerelease"))
fields = [{"name": "Type", "value": "Pre-release" if prerelease else "Stable", "inline": True}]
files = downloads(release.get("assets") or [])
if files:
fields.append({"name": "Downloads", "value": files, "inline": False})
embed = {
"title": f"PipDock {tag}" + (" (pre-release)" if prerelease else ""),
"url": release.get("html_url"),
"description": truncate(release.get("body") or "", 1500),
"color": COLOR_PRERELEASE if prerelease else COLOR_RELEASE,
"fields": fields,
"footer": {"text": repository},
"timestamp": release.get("published_at"),
}
return {"username": "Release Bot", "embeds": [compact(embed)]}
def failure_payload() -> dict:
repository, sha = env("GITHUB_REPOSITORY"), env("COMMIT_SHA")
message_lines = env("COMMIT_MESSAGE").splitlines()
commit = f"[{sha[:7]}](https://github.com/{repository}/commit/{sha})" if sha else "?"
embed = {
"title": f"{env('WORKFLOW_NAME') or 'Workflow'} failed: {repository}",
"url": env("RUN_URL"),
"description": truncate(message_lines[0], 300) if message_lines else "",
"color": COLOR_FAILURE,
"fields": [
{"name": "Ref", "value": env("BRANCH") or "?", "inline": True},
{"name": "Event", "value": env("EVENT") or "?", "inline": True},
{"name": "Commit", "value": commit, "inline": True},
{"name": "Actor", "value": env("ACTOR") or "?", "inline": True},
],
"footer": {"text": repository},
}
return {"username": "CI Bot", "embeds": [compact(embed)]}
def post(webhook: str, payload: dict) -> None:
request = urllib.request.Request(
webhook,
data=json.dumps(payload).encode("utf-8"),
headers={"Content-Type": "application/json", "User-Agent": USER_AGENT},
method="POST",
)
with urllib.request.urlopen(request, timeout=20):
pass # urlopen raises HTTPError for any non-2xx answer
def webhooks(kind: str) -> list[str]:
hooks = [env("DISCORD_WEBHOOK")]
if kind == "release":
# The releases channel and the repository's own channel both hear about a release, as they
# did under the ops-repo announcer.
hooks.append(env("DISCORD_WEBHOOK_EXTRA"))
return [hook for hook in hooks if hook]
def main(argv: list[str]) -> int:
if len(argv) != 2 or argv[1] not in ("release", "failure"):
print("usage: discord_notify.py release|failure", file=sys.stderr)
return 2
kind = argv[1]
targets = webhooks(kind)
dry_run = env("DRY_RUN") == "1"
if not targets and not dry_run:
print("::notice::No Discord webhook is available to this run; nothing was posted.")
return 0
try:
payload = release_payload() if kind == "release" else failure_payload()
if dry_run:
print(json.dumps(payload, indent=2, ensure_ascii=False))
return 0
for target in targets:
post(target, payload)
except (urllib.error.URLError, ValueError, KeyError) as error:
# Never print a webhook URL: it is a secret.
print(f"::error::Discord {kind} notification failed: {error}")
return 1
print(f"Posted the {kind} notification to {len(targets)} Discord webhook(s).")
return 0
if __name__ == "__main__":
sys.exit(main(sys.argv))
+154
View File
@@ -0,0 +1,154 @@
/**
* Maintenance-mode triage — run by .github/workflows/triage.yml through actions/github-script.
*
* Since 1.6.0 PipDock takes bug fixes, UI/UX and accessibility problems, wording and translation
* fixes, and dependency and security updates, and no new features (CONTRIBUTING.md, "Scope in
* maintenance mode"). A feature request is labelled `enhancement` and `out-of-scope`, answered in
* English and Vietnamese, and closed as not planned.
*
* **Only on signals that cannot be a bug report**, because closing a real report would be worse
* than leaving a request open: a title that says it is a feature (`[Feature]`, `Feature request:`,
* `[Tính năng]` …), a pull request titled with the Conventional Commits `feat` type the repository
* uses, or the `enhancement` label being put on. Words in a body decide nothing.
*
* **Never** for the owner, members and collaborators, for bots (Dependabot), or for anything
* labelled `policy-exception` — the maintainer's way of keeping open a feature judged truly
* necessary, which the policy allows.
*
* `classify` is pure and tested with `node --test` (triage.test.cjs); `run` is the thin part that
* talks to GitHub.
*/
'use strict'
const MAINTAINERS = new Set(['OWNER', 'MEMBER', 'COLLABORATOR'])
const EXEMPT = 'policy-exception'
const FEATURE_LABEL = 'enhancement'
const OUT_OF_SCOPE = 'out-of-scope'
const POLICY_URL =
'https://github.com/poli0981org/pipdock/blob/main/CONTRIBUTING.md#scope-in-maintenance-mode'
const IDEAS_URL = 'https://github.com/poli0981org/pipdock/discussions/categories/ideas'
/** `[Feature] …`, `[Feature request]: …`, `Feature request: …`, `[Tính năng] …`, `Đề xuất tính năng: …`. */
const FEATURE_TITLE =
/^\s*(?:\[\s*(?:feature(?:\s+request)?|enhancement|request|tính năng|đề xuất(?:\s+tính năng)?)\s*\]|(?:feature\s+request|feature|enhancement|đề xuất tính năng|tính năng mới)\s*:)/iu
/** `feat: …`, `feat(ui): …`, `feat!: …` — the Conventional Commits type this repository uses. */
const FEAT_COMMIT = /^\s*feat(?:\([^)]*\))?!?:/i
/**
* Whether an issue or pull request is a feature request this policy closes.
*
* @param {object} item
* @param {'issue'|'pull_request'} item.kind
* @param {string} item.title
* @param {string[]} item.labels Names of the labels it carries now.
* @param {string} item.association The author's `author_association`.
* @param {boolean} item.authorIsBot
* @param {string} item.state `open` or `closed`.
* @param {string|null} item.addedLabel The label a `labeled` event put on, else null.
* @returns {{close: boolean, reason: string}}
*/
function classify(item) {
if (item.state !== 'open') return { close: false, reason: 'not open' }
if (item.authorIsBot) return { close: false, reason: 'opened by a bot' }
if (MAINTAINERS.has(item.association)) return { close: false, reason: 'opened by a maintainer' }
if (item.labels.includes(EXEMPT)) return { close: false, reason: `labelled ${EXEMPT}` }
if (item.labels.includes(OUT_OF_SCOPE)) return { close: false, reason: 'already handled' }
if (item.addedLabel === FEATURE_LABEL) return { close: true, reason: `labelled ${FEATURE_LABEL}` }
if (item.addedLabel !== null) return { close: false, reason: `labelled ${item.addedLabel}` }
if (item.kind === 'pull_request' && FEAT_COMMIT.test(item.title)) {
return { close: true, reason: 'a feat: pull request' }
}
if (FEATURE_TITLE.test(item.title)) return { close: true, reason: 'titled as a feature request' }
return { close: false, reason: 'not a feature request' }
}
/** The answer left on a closed request, in both of the project's languages. */
function comment(kind) {
const what = kind === 'pull_request' ? 'pull request' : 'issue'
const whatVi = kind === 'pull_request' ? 'Pull request' : 'Issue'
return [
'Thanks for taking the time to write this.',
'',
`PipDock has been in **maintenance mode** since 1.6.0: it takes bug fixes, UI/UX and accessibility problems, wording and translation fixes, and dependency and security updates — and no new features. This ${what} reads as a feature request, so it has been labelled \`${OUT_OF_SCOPE}\` and closed. [CONTRIBUTING.md](${POLICY_URL}) says what is accepted and why.`,
'',
`If it is really a bug or a barrier, say so in a comment and it will be looked at again. If you believe the feature is truly necessary, make the case in [Discussions → Ideas](${IDEAS_URL}).`,
'',
'---',
'',
`Cảm ơn bạn đã dành thời gian viết. Từ bản 1.6.0, PipDock ở **giai đoạn bảo trì**: chỉ nhận sửa lỗi, lỗi UI/UX và khả năng tiếp cận, sửa câu chữ và bản dịch, cập nhật phụ thuộc và bảo mật — không nhận tính năng mới. ${whatVi} này là một đề xuất tính năng, nên đã được gắn nhãn \`${OUT_OF_SCOPE}\` và đóng lại. Nếu đây thật ra là lỗi, hãy bình luận để được xem lại; nếu bạn tin tính năng này thật sự cần thiết, hãy trình bày ở [Discussions → Ideas](${IDEAS_URL}).`,
].join('\n')
}
/** The item an `issues` or `pull_request_target` event is about, in `classify`'s shape. */
function itemOf(payload) {
const kind = payload.pull_request ? 'pull_request' : 'issue'
const raw = payload.pull_request ?? payload.issue
return {
kind,
number: raw.number,
title: raw.title ?? '',
labels: (raw.labels ?? []).map((l) => l.name),
association: raw.author_association ?? 'NONE',
authorIsBot: raw.user?.type === 'Bot',
state: raw.state,
addedLabel: payload.action === 'labeled' ? (payload.label?.name ?? null) : null,
}
}
/** Entry point for actions/github-script. */
async function run({ github, context, core }) {
if (context.eventName === 'workflow_dispatch') {
// A dry run: classify what the inputs describe and say so. Nothing is touched.
const inputs = context.payload.inputs ?? {}
const item = {
kind: inputs.kind === 'pull_request' ? 'pull_request' : 'issue',
title: inputs.title ?? '',
labels: (inputs.labels ?? '').split(',').map((s) => s.trim()).filter(Boolean),
association: inputs.association ?? 'NONE',
authorIsBot: false,
state: 'open',
addedLabel: null,
}
const verdict = classify(item)
core.notice(`${verdict.close ? 'would close' : 'would leave open'}: ${verdict.reason}`)
core.summary.addRaw(`**${verdict.close ? 'Would close' : 'Would leave open'}** — ${verdict.reason}`)
await core.summary.write()
return verdict
}
const item = itemOf(context.payload)
const verdict = classify(item)
core.info(`#${item.number}: ${verdict.close ? 'closing' : 'leaving open'} — ${verdict.reason}`)
if (!verdict.close) return verdict
const { owner, repo } = context.repo
await github.rest.issues.addLabels({
owner,
repo,
issue_number: item.number,
labels: [FEATURE_LABEL, OUT_OF_SCOPE],
})
await github.rest.issues.createComment({
owner,
repo,
issue_number: item.number,
body: comment(item.kind),
})
if (item.kind === 'pull_request') {
await github.rest.pulls.update({ owner, repo, pull_number: item.number, state: 'closed' })
} else {
await github.rest.issues.update({
owner,
repo,
issue_number: item.number,
state: 'closed',
state_reason: 'not_planned',
})
}
return verdict
}
module.exports = { classify, comment, itemOf, run, FEATURE_TITLE, FEAT_COMMIT }
+129
View File
@@ -0,0 +1,129 @@
// `node --test .github/scripts/*.test.cjs` — Node's built-in runner, as for scripts/*.test.mjs.
'use strict'
const assert = require('node:assert/strict')
const { test } = require('node:test')
const { classify, comment, itemOf } = require('./triage.cjs')
const base = {
kind: 'issue',
title: '',
labels: [],
association: 'NONE',
authorIsBot: false,
state: 'open',
addedLabel: null,
}
const item = (over) => ({ ...base, ...over })
test('a title that says it is a feature request is closed, in either language', () => {
for (const title of [
'[Feature] Dark/light theme toggle',
'[Feature request]: conda support',
'[Enhancement] faster search',
'[Request] macOS build',
'Feature request: export to Poetry',
'feature: portable mode',
'[Tính năng] Hỗ trợ conda',
'[Đề xuất tính năng] chế độ portable',
'Đề xuất tính năng: giao diện sáng',
]) {
assert.equal(classify(item({ title })).close, true, title)
}
})
test('a bug report is never closed, whatever words it uses', () => {
for (const title of [
'[Bug]: crash when adding an interpreter',
'The feature to roll back is broken',
'Rollback feature does nothing',
'Request timed out while searching',
'Enhancement of the dock bay stopped working after 1.6.0',
'[Accessibility]: Remove from list has no focus ring',
]) {
assert.equal(classify(item({ title })).close, false, title)
}
})
test('a pull request titled feat: is closed; fix:, docs: and build(deps): are not', () => {
for (const title of ['feat: conda envs', 'feat(ui): light theme', 'feat!: drop pip']) {
assert.equal(classify(item({ kind: 'pull_request', title })).close, true, title)
}
for (const title of ['fix(ui): focus ring', 'docs: typo', 'build(deps): Bump vite', 'i18n(vi): sửa lỗi chính tả']) {
assert.equal(classify(item({ kind: 'pull_request', title })).close, false, title)
}
// An issue titled like a commit is a person's wording, not a commit type.
assert.equal(classify(item({ kind: 'issue', title: 'feat: something' })).close, false)
})
test('putting the enhancement label on closes it; any other label does not', () => {
assert.equal(classify(item({ title: 'Make it faster', addedLabel: 'enhancement' })).close, true)
// A label event is about the label: a feature title already open and now labelled `bug` was
// let through when it was opened, and re-judging it on every label would close it late.
assert.equal(classify(item({ title: '[Feature] x', addedLabel: 'bug' })).close, false)
})
test('maintainers, bots and policy exceptions are never closed', () => {
for (const association of ['OWNER', 'MEMBER', 'COLLABORATOR']) {
assert.equal(classify(item({ title: '[Feature] x', association })).close, false, association)
}
assert.equal(classify(item({ kind: 'pull_request', title: 'feat: x', authorIsBot: true })).close, false)
assert.equal(
classify(item({ title: '[Feature] x', labels: ['policy-exception'], addedLabel: 'enhancement' })).close,
false,
)
})
test('what is closed or already handled is left alone', () => {
assert.equal(classify(item({ title: '[Feature] x', state: 'closed' })).close, false)
assert.equal(classify(item({ title: '[Feature] x', labels: ['out-of-scope'] })).close, false)
})
test('the answer is in both languages and says what kind of item it is', () => {
const pr = comment('pull_request')
assert.match(pr, /This pull request reads as a feature request/)
assert.match(pr, /Pull request này/)
assert.match(pr, /CONTRIBUTING\.md#scope-in-maintenance-mode/)
assert.match(comment('issue'), /This issue reads as a feature request/)
})
test('an event payload becomes an item, the added label included', () => {
const fromIssue = itemOf({
action: 'labeled',
label: { name: 'enhancement' },
issue: {
number: 7,
title: 'Make it faster',
labels: [{ name: 'triage' }, { name: 'enhancement' }],
author_association: 'NONE',
user: { type: 'User' },
state: 'open',
},
})
assert.deepEqual(fromIssue, {
kind: 'issue',
number: 7,
title: 'Make it faster',
labels: ['triage', 'enhancement'],
association: 'NONE',
authorIsBot: false,
state: 'open',
addedLabel: 'enhancement',
})
const fromPr = itemOf({
action: 'opened',
pull_request: {
number: 9,
title: 'feat: x',
labels: [],
author_association: 'FIRST_TIME_CONTRIBUTOR',
user: { type: 'User' },
state: 'open',
},
})
assert.equal(fromPr.kind, 'pull_request')
assert.equal(fromPr.addedLabel, null)
assert.equal(classify(fromPr).close, true)
})
-28
View File
@@ -1,28 +0,0 @@
# Caller into the ops repo's Discord announcer.
#
# docs/RELEASE-CI.md §1 originally described a `notify.yml` cross-posting to six platforms; the
# ops repo has no such workflow. Announcements are Discord-only, via
# poli0981/.github/.github/scripts/discord_notify.py.
name: Announce Release
on:
release:
types: [published]
workflow_dispatch:
inputs:
tag:
description: Tag to announce (for re-runs)
required: true
type: string
permissions:
contents: read
actions: read
jobs:
announce:
uses: poli0981/.github/.github/workflows/announce-release.yml@main
with:
tag_override: ${{ inputs.tag || '' }}
secrets: inherit
+43 -8
View File
@@ -23,7 +23,19 @@ on:
# against a real interpreter is only ever exercised here.
- 'crates/pipdock-core/src/probe.py'
- 'crates/pipdock-core/src/health/**'
# Every end-to-end step drives the CLI, and these are what it runs through. A change to
# any of them reached `main` without this job ever seeing it.
- 'crates/pipdock-cli/**'
- 'crates/pipdock-core/src/exec.rs'
- 'crates/pipdock-core/src/audit.rs'
- 'crates/pipdock-core/src/release.rs'
- 'crates/pipdock-core/src/errors/**'
- 'crates/pipdock-core/src/store/**'
- 'crates/pipdock-core/src/index/**'
- 'crates/pipdock-core/tests/**'
# A dependency or toolchain bump is a change to all of the above at once.
- 'Cargo.lock'
- 'rust-toolchain.toml'
- 'spikes/capture.py'
# A Dependabot bump to the Code Health pins has to re-run the bootstrap: whether the new
# pin set still resolves to wheels on 3.10 and 3.14 is exactly what this job can answer
@@ -57,6 +69,9 @@ env:
jobs:
disposable-venvs:
name: Real engines, throwaway venvs
# The Monday cron exists for the drift job below. Without this the whole suite ran twice every
# Monday morning, an hour apart, against the same commit.
if: github.event_name != 'schedule' || github.event.schedule != '17 4 * * 1'
runs-on: windows-latest
timeout-minutes: 45
strategy:
@@ -66,10 +81,12 @@ jobs:
python: ['3.10', '3.14']
steps:
- name: Checkout
uses: actions/checkout@v7
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Setup Python ${{ matrix.python }}
uses: actions/setup-python@v7
uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: ${{ matrix.python }}
@@ -83,7 +100,7 @@ jobs:
shell: pwsh
- name: Cache cargo
uses: actions/cache@v6
uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
with:
path: |
~/.cargo/registry
@@ -383,12 +400,17 @@ jobs:
timeout-minutes: 30
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Setup Python
uses: actions/setup-python@v7
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
python-version: '3.12'
persist-credentials: false
# An exact patch, on purpose. pip's report records `python_full_version` and uv prints "Using
# Python 3.12.x environment", so a floating `3.12` turns every runner-image Python bump into
# a fixture diff that says nothing about pip or uv. Bump it deliberately, and re-capture.
- name: Setup Python
uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: '3.12.10'
- name: Install the newest uv
run: |
@@ -402,6 +424,19 @@ jobs:
python spikes\capture.py --engine pip
python spikes\capture.py --engine uv --uv-exe .uvtools\Scripts\uv.exe
# Uploaded whether or not the gate below passes: when it fails, the fix is to review and
# commit exactly these bytes, and re-running the capture elsewhere produces different ones
# (another interpreter, another network, another day's index).
- name: Upload the captured fixtures
if: always()
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: captured-fixtures
path: |
crates/pipdock-core/tests/fixtures/pip
crates/pipdock-core/tests/fixtures/uv
if-no-files-found: error
# A diff means an engine changed its output. That is exactly the PD-ENG-003 situation the
# adapters degrade into, and catching it here is what stops a user meeting it first.
#
+92 -22
View File
@@ -1,11 +1,15 @@
# Caller into the ops repo's React reusable, plus one local job.
# The frontend's checks, all project-local.
#
# The reusable runs Node 24, `npm ci`, then lint / typecheck / test when the matching npm script
# exists, then the build. It has no `npm audit` step, so that gate lives here — see
# docs/RELEASE-CI.md §1.
# Until the move to poli0981org (2026-11-21) the `lint · typecheck · test · build` job was a caller
# into the owner's personal ops repo — `poli0981/.github`'s reusable-web-react.yml, at `@main`,
# unpinned. A project in the organization no longer runs a workflow another account can change, so
# the job's steps live here, pinned like every other action in this repository. Two things went
# with the reusable: the `pages: write` and `id-token: write` grants its always-skipped Pages job
# forced on the caller, and the `dist` artifact nothing downloaded.
#
# It also has no working-directory input, which is why package.json sits at the repo root with
# Vite configured `root: './ui'` (ARCHITECTURE §2).
# package.json still sits at the repository root with Vite's `root: './ui'` (ARCHITECTURE §2). The
# reusable's missing `working-directory` input was the original reason and is gone; SonarCloud,
# Qodana, the scripts below and Tauri's own configuration all assume the root now.
name: CI / Node
@@ -14,13 +18,8 @@ on:
push:
branches: [main]
# The reusable declares a Pages-deploy job needing `pages: write` and `id-token: write`. It is
# skipped here (`deploy-pages: false`), but permissions are validated at startup regardless of
# `if:`, so a caller that grants less than the callee declares is rejected before it runs.
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: ci-node-${{ github.ref }}
@@ -28,14 +27,40 @@ concurrency:
jobs:
web:
# A required check under exactly this name (RELEASE-CI.md §2): renaming it means changing the
# branch protection payload in the same breath.
name: lint · typecheck · test · build
uses: poli0981/.github/.github/workflows/reusable-web-react.yml@main
with:
node-version: '24'
package-manager: npm
build-command: npm run build
dist-dir: dist
deploy-pages: false
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Setup Node.js
uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: '26'
cache: npm
# No install script runs: the only package in the lockfile that has one is fsevents, which
# is macOS-only, and a lifecycle script is how a compromised dependency runs on the runner
# (SonarCloud githubactions:S6505). `npm licences` and `npm audit` never needed them either.
- name: Install
run: npm ci --ignore-scripts
- name: Lint
run: npm run lint
- name: Typecheck
run: npm run typecheck
- name: Test
run: npm test
- name: Build
run: npm run build
audit:
name: npm audit
@@ -43,16 +68,61 @@ jobs:
timeout-minutes: 10
steps:
- name: Checkout
uses: actions/checkout@v7
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Setup Node.js
uses: actions/setup-node@v7
uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: '24'
node-version: '26'
cache: npm
# The audit reads the lockfile; nothing is built, so no install script has a reason to run.
- name: Install
run: npm ci
run: npm ci --ignore-scripts
- name: Audit
run: npm audit --audit-level=high
licences:
# The npm half of what deny.toml does for the crates: every package the production build can
# bundle must carry a GPL-3.0-compatible licence (THIRD-PARTY-NOTICES, SECURITY §7). It reads
# package-lock.json and installs nothing.
name: npm licences
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Setup Node.js
uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: '26'
# The repository's own CI scripts — this checker, and the maintenance-mode triage beside the
# workflows — test themselves with Node's built-in runner, so they need no dependency either.
- name: Test the CI scripts
run: node --test scripts/*.test.mjs .github/scripts/*.test.cjs
- name: Production dependencies under GPL-3.0-compatible licences
run: node scripts/check-licenses.mjs
lockstep:
name: tauri lockstep
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
# Tauri refuses to run when the `tauri` crate and `@tauri-apps/api` are on different minors,
# and Dependabot bumps the two ecosystems in separate PRs — so either one, merged alone,
# leaves a `main` that builds and does not start. The script reads both lockfiles.
- name: Crate and npm package on one minor
run: node scripts/check-tauri-lockstep.mjs
+45 -16
View File
@@ -1,5 +1,4 @@
# Project-local: the ops repo (poli0981/.github) has no reusable Rust workflow, and only its
# desktop-csharp reusable runs on Windows. See docs/RELEASE-CI.md §1.
# Project-local, like every workflow here since the move to poli0981org (RELEASE-CI.md §1).
#
# Windows runner because the environment-discovery module reads the PEP 514 registry and the `py`
# launcher — a Linux run would skip exactly the code most likely to break.
@@ -29,7 +28,9 @@ jobs:
timeout-minutes: 45
steps:
- name: Checkout
uses: actions/checkout@v7
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
# rust-toolchain.toml pins the exact version, so no toolchain action is needed — rustup
# honours it on first invocation and installs rustfmt and clippy with it.
@@ -39,7 +40,7 @@ jobs:
cargo --version
- name: Cache cargo
uses: actions/cache@v6
uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
with:
path: |
~/.cargo/registry
@@ -62,19 +63,47 @@ jobs:
runs-on: ubuntu-latest
timeout-minutes: 15
env:
# The action builds cargo-audit from source, and rust-toolchain.toml would otherwise pin
# that build to PipDock's toolchain. cargo-audit's own dependency tree already requires a
# newer rustc than we pin (kstring needs 1.96), so the audit failed to compile rather than
# finding anything. It only reads Cargo.lock, so building it with stable is correct — the
# pin exists to make *PipDock* reproducible, not its tooling.
# cargo-audit only reads Cargo.lock, so it runs under the runner's stable cargo rather than
# making rustup install the toolchain rust-toolchain.toml pins — that pin exists to make
# PipDock reproducible, not its tooling.
RUSTUP_TOOLCHAIN: stable
steps:
- name: Checkout
uses: actions/checkout@v7
# RustSec advisories against the committed Cargo.lock. Split from the Windows job because
# it needs no target build — it is a lockfile scan.
- name: Audit
uses: rustsec/audit-check@v2
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
token: ${{ secrets.GITHUB_TOKEN }}
persist-credentials: false
# A prebuilt cargo-audit, pinned by commit. This replaced rustsec/audit-check@v2, which ran
# on Node 20, needed a check-run write token, and on a pull request failed only on
# "critical" — so the advisories that turned `main` red in September passed every PR.
- name: Install cargo-audit
uses: taiki-e/install-action@4a76afe23f9e08d2d9550fb56e556444e8611d21 # v2.90.4
with:
tool: cargo-audit
# RustSec advisories against the committed Cargo.lock. `--deny warnings`, because
# .cargo/audit.toml's contract is that a *new* informational advisory fails CI and is looked
# at; the known ones are ignored there one by one, with reasons.
- name: Audit
run: cargo audit --deny warnings
deny:
name: cargo deny
runs-on: ubuntu-latest
timeout-minutes: 15
env:
RUSTUP_TOOLCHAIN: stable
steps:
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Install cargo-deny
uses: taiki-e/install-action@4a76afe23f9e08d2d9550fb56e556444e8611d21 # v2.90.4
with:
tool: cargo-deny
# Licences, sources and bans — deny.toml says why each. Advisories stay cargo audit's.
- name: Licences, sources, bans
run: cargo deny --locked check licenses sources bans
+41 -17
View File
@@ -1,12 +1,18 @@
# Caller into the ops repo's CodeQL reusable.
# CodeQL, project-local since the move to poli0981org (2026-11-21).
#
# JavaScript/TypeScript only: CodeQL has no Rust analyzer, and the reusable's supported set is
# csharp, python, javascript-typescript, ruby, c-cpp, java-kotlin, go and swift. Rust's static
# analysis is clippy `-D warnings` plus `cargo audit`, both blocking in ci-rust.yml.
# See docs/RELEASE-CI.md §1 and docs/SECURITY.md §7.
# It was a caller into the owner's personal ops repo (`poli0981/.github`'s reusable-codeql.yml, at
# `@main`), whose steps used `github/codeql-action@v4` by tag. The same analysis runs here with the
# action pinned by commit, and the write permission on the one job that uploads.
#
# The reusable notes that repo Settings → Advanced Security → CodeQL "Default setup" must be
# DISABLED, or this advanced-setup workflow is rejected at upload time.
# Three languages, all `build-mode: none`. **Rust** — CodeQL analyses it without a build; this
# file said for six releases that CodeQL had no Rust support, which stopped being true in 2025.
# **Actions** — the workflows themselves: write permissions at workflow level, unpinned
# third-party actions, untrusted input in a `run:`. **JavaScript/TypeScript** — the frontend, and
# a required check under exactly the name `Analyze (javascript-typescript)` (RELEASE-CI.md §2).
# The `category` values are the reusable's, so existing alerts keep their history.
#
# Settings → Advanced Security → CodeQL "Default setup" must stay disabled, or this advanced
# setup is rejected at upload time.
name: CodeQL
@@ -18,18 +24,36 @@ on:
# Weekly, offset off the hour to avoid the top-of-hour scheduling pileup.
- cron: '37 4 * * 1'
# A caller cannot grant a called workflow less than its jobs declare, or the run is rejected before
# it starts. reusable-codeql.yml's analyze job asks for `packages: read` to fetch internal CodeQL
# packs, so omitting it here produced a startup_failure with no logs to explain it — the same
# permissions trap RELEASE-CI.md §1 records, from the other direction.
permissions:
actions: read
contents: read
packages: read
security-events: write
jobs:
analyze:
uses: poli0981/.github/.github/workflows/reusable-codeql.yml@main
with:
languages: '["javascript-typescript"]'
name: Analyze (${{ matrix.language }})
runs-on: ubuntu-latest
timeout-minutes: 60
permissions:
actions: read
contents: read
packages: read # CodeQL's own query packs
security-events: write # upload the results
strategy:
fail-fast: false
matrix:
language: [javascript-typescript, rust, actions]
steps:
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Initialize CodeQL
uses: github/codeql-action/init@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3
with:
languages: ${{ matrix.language }}
build-mode: none
- name: Perform CodeQL analysis
uses: github/codeql-action/analyze@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3
with:
category: /language:${{ matrix.language }}
-20
View File
@@ -1,20 +0,0 @@
# Caller into the ops repo's Discord CI-failure notifier.
#
# The reusable skips workflows that have their own dedicated notifier (release, CodeQL,
# Dependabot), so this does not double-report.
name: Notify CI Failure
on:
workflow_run:
workflows: ['*']
types: [completed]
permissions:
contents: read
actions: read
jobs:
notify:
uses: poli0981/.github/.github/workflows/notify-ci-failure.yml@main
secrets: inherit
+98
View File
@@ -0,0 +1,98 @@
# Discord notifications, self-contained in this repository since the move to poli0981org
# (2026-11-21). They were two callers into the owner's personal ops repo, whose notifier checked
# out *that* repo's `main` and ran its script with PipDock's webhooks in the environment; the
# script is vendored now (.github/scripts/discord_notify.py, standard library only).
#
# - ci-failure: a run of a listed workflow failed outside a pull request — a push to `main`, the
# daily or weekly schedule, a dispatch, a release tag -> DISCORD_CI_WEBHOOK. Pull-request runs
# report on the pull request, and a fork's or Dependabot's get no secrets anyway. The filter is
# on the event alone, never on a branch name or a login, which a fork controls. **Triage is the
# one exception**: it runs on `pull_request_target`, against a stranger's pull request, where
# nobody watching can fix it — and a broken triage leaves feature PRs open with nobody told. Its
# name is safe to filter on because a `pull_request_target` run's workflow file comes from the
# base branch, never from the fork; the failure is posted as an embed, which pings nobody.
# - announce: a release was published, or re-announced with a dispatch -> DISCORD_RELEASES_WEBHOOK
# and DISCORD_REPO_WEBHOOK. Publishing the draft (RELEASE-CI.md §3) is done with a person's token,
# which does fire `release: published`; a release published with GITHUB_TOKEN would not.
#
# **The list is by exact `name:`.** `workflows: ['*']`, which the ops repo's own example
# suggested, is not a wildcard to `workflow_run`: it matched nothing, and `main` was red for three
# weeks in September with nobody told. A new workflow is added here by name. Unlike the ops-repo
# reusable, which skipped anything named like CodeQL or Release because they had "dedicated
# notifiers" PipDock never had, CodeQL, Qodana and Release are listed: a failed Release run used
# to reach no channel at all.
name: Notify
on:
workflow_run:
workflows:
- CI / Rust
- CI / Node
- CI / Integration
- CodeQL
- Qodana
- Release
- Security scan
- SonarCloud
- Triage
types: [completed]
release:
types: [published]
workflow_dispatch:
inputs:
tag:
description: Release tag to announce again (e.g. v1.6.0)
required: true
type: string
permissions:
contents: read
jobs:
ci-failure:
if: >-
github.event_name == 'workflow_run' &&
github.event.workflow_run.conclusion == 'failure' &&
github.event.workflow_run.event != 'pull_request' &&
(github.event.workflow_run.event != 'pull_request_target' ||
github.event.workflow_run.name == 'Triage')
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
sparse-checkout: .github/scripts
- name: Post the failure to Discord
env:
DISCORD_WEBHOOK: ${{ secrets.DISCORD_CI_WEBHOOK }}
WORKFLOW_NAME: ${{ github.event.workflow_run.name }}
RUN_URL: ${{ github.event.workflow_run.html_url }}
BRANCH: ${{ github.event.workflow_run.head_branch }}
COMMIT_SHA: ${{ github.event.workflow_run.head_sha }}
COMMIT_MESSAGE: ${{ github.event.workflow_run.head_commit.message }}
ACTOR: ${{ github.event.workflow_run.actor.login }}
EVENT: ${{ github.event.workflow_run.event }}
run: python3 .github/scripts/discord_notify.py failure
announce:
if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
sparse-checkout: .github/scripts
- name: Announce on Discord
env:
GH_TOKEN: ${{ github.token }}
TAG: ${{ github.event.release.tag_name || inputs.tag }}
DISCORD_WEBHOOK: ${{ secrets.DISCORD_RELEASES_WEBHOOK }}
DISCORD_WEBHOOK_EXTRA: ${{ secrets.DISCORD_REPO_WEBHOOK }}
run: python3 .github/scripts/discord_notify.py release
+187
View File
@@ -0,0 +1,187 @@
# JetBrains Qodana, in two parts — added 2026-11-21 with the move to poli0981org.
#
# **A monorepo to Qodana.** The repository holds a Rust workspace and a TypeScript frontend, and
# Qodana Cloud has a project for each, with its own token (QODANA_TOKEN_RUST, QODANA_TOKEN_TS_JS)
# and its own configuration (qodana-rust.yaml, qodana-js.yaml): JetBrains' layout for a monorepo.
# The two jobs below never inspect the same file.
#
# **Rust runs in Docker, TypeScript natively.** qodana-rust has no native mode; it is RustRover in
# a Linux container, so `#[cfg(windows)]` code is invisible to it — clippy, CodeQL and SonarQube
# Cloud, all on Windows, cover that. qodana-js runs on the runner after `npm ci`, so it resolves
# the node_modules the build does, with the Node every other workflow uses.
#
# **No token, no analysis**, the way sonar.yml does it: Dependabot's and a fork's pull requests get
# no repository secrets, so their runs are skipped rather than failed.
#
# **No caches** (`use-caches: false`). The repository's Actions cache is near its 10 GB limit, and
# a Qodana cache — an IDE's indexes, and Cargo's registry inside the container — would evict the
# cargo caches the required checks restore. A run is slower for it, and it is not a required
# check (RELEASE-CI.md §2): a failure on `main` reaches Discord through notify.yml.
#
# **Every run is a full scan, and only a new problem fails it.** `pr-mode` is off: a whole scan is
# two to three minutes a part, so analysing only a pull request's files would save little and make
# a result depend on which files happened to change. `.qodana/rust.sarif.json` is the baseline —
# the 62 problems the first real run found, triaged on 2026-11-21 (ROADMAP: two Critical that are
# RustRover misreading what rustc compiles, and 60 Moderate style findings), trimmed to the results
# and their fingerprints. `--fail-threshold 0` then fails on anything outside it. The TypeScript
# half has no baseline because it has no accepted problem: the six it found were fixed.
#
# **Only new problems reach Code scanning**, under `qodana-rust` and `qodana-js` — a baseline
# problem is triaged already, and alerting on it again would bury the next real one.
name: Qodana
on:
pull_request:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: read
concurrency:
group: qodana-${{ github.ref }}
cancel-in-progress: true
jobs:
tokens:
name: tokens present
runs-on: ubuntu-latest
timeout-minutes: 2
outputs:
rust: ${{ steps.check.outputs.rust }}
js: ${{ steps.check.outputs.js }}
steps:
# `secrets` cannot be read in an `if:`, so presence becomes an output. Only the emptiness test
# sees the values; nothing is checked out and nothing else runs.
- name: Check
id: check
env:
RUST: ${{ secrets.QODANA_TOKEN_RUST }}
JS: ${{ secrets.QODANA_TOKEN_TS_JS }}
run: |
for part in RUST JS; do
name=$(echo "$part" | tr '[:upper:]' '[:lower:]')
if [ -n "${!part}" ]; then
echo "$name=true" >> "$GITHUB_OUTPUT"
else
echo "$name=false" >> "$GITHUB_OUTPUT"
echo "::notice::No Qodana token for the $name part in this run (a Dependabot or fork pull request); it is skipped."
fi
done
rust:
name: qodana · rust
needs: tokens
if: needs.tokens.outputs.rust == 'true'
runs-on: ubuntu-latest
timeout-minutes: 60
permissions:
contents: read
checks: write # annotations
pull-requests: write # the summary comment
security-events: write # new problems to Code scanning
steps:
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
# The pull request's own head, and the history pull-request mode diffs against.
ref: ${{ github.event.pull_request.head.sha }}
fetch-depth: 0
persist-credentials: false
- name: Qodana
uses: JetBrains/qodana-action@3e8d76ff0e0241618abd808682f426afe84bab3f # v2026.2.2
env:
QODANA_TOKEN: ${{ secrets.QODANA_TOKEN_RUST }}
# The container runs as the runner's user, and the image's CARGO_HOME (/usr/local/cargo)
# belongs to root, so `cargo metadata` could not write the registry it downloads and
# RustRover loaded no Cargo project — 0 problems from 0 files analysed. /data/cache is
# the container's mount of the action's cache directory, which this user owns.
CARGO_HOME: /data/cache/cargo-home
with:
args: --config qodana-rust.yaml --linter qodana-rust --baseline .qodana/rust.sarif.json --fail-threshold 0
env-vars-to-linter: CARGO_HOME
pr-mode: false
use-caches: false
upload-result: true
artifact-name: qodana-rust
- name: Keep the problems outside the baseline
id: filter
if: ${{ !cancelled() }}
env:
SARIF: ${{ runner.temp }}/qodana/results/qodana.sarif.json
run: |
if [ ! -f "$SARIF" ]; then echo "::notice::The scan left no SARIF."; exit 0; fi
jq '.runs |= map(.results |= map(select((.baselineState // "new") != "unchanged" and (.baselineState // "new") != "absent")))' \
"$SARIF" > "$RUNNER_TEMP/qodana-rust.sarif"
echo "ready=true" >> "$GITHUB_OUTPUT"
- name: Upload to Code scanning
if: ${{ !cancelled() && steps.filter.outputs.ready == 'true' }}
uses: github/codeql-action/upload-sarif@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3
with:
sarif_file: ${{ runner.temp }}/qodana-rust.sarif
category: qodana-rust
js:
name: qodana · ts/js
needs: tokens
if: needs.tokens.outputs.js == 'true'
runs-on: ubuntu-latest
timeout-minutes: 45
permissions:
contents: read
checks: write # annotations
pull-requests: write # the summary comment
security-events: write # new problems to Code scanning
steps:
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ github.event.pull_request.head.sha }}
fetch-depth: 0
persist-credentials: false
- name: Setup Node.js
uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: '26'
cache: npm
# No install script runs: the only package in the lockfile that has one is fsevents, which
# is macOS-only, and a lifecycle script is how a compromised dependency runs on the runner
# (SonarCloud githubactions:S6505). `npm licences` and `npm audit` never needed them either.
- name: Install
run: npm ci --ignore-scripts
- name: Qodana
uses: JetBrains/qodana-action@3e8d76ff0e0241618abd808682f426afe84bab3f # v2026.2.2
env:
QODANA_TOKEN: ${{ secrets.QODANA_TOKEN_TS_JS }}
with:
args: --config qodana-js.yaml --linter qodana-js --within-docker false --fail-threshold 0
pr-mode: false
use-caches: false
upload-result: true
artifact-name: qodana-js
- name: Keep the problems outside the baseline
id: filter
if: ${{ !cancelled() }}
env:
SARIF: ${{ runner.temp }}/qodana/results/qodana.sarif.json
run: |
if [ ! -f "$SARIF" ]; then echo "::notice::The scan left no SARIF."; exit 0; fi
jq '.runs |= map(.results |= map(select((.baselineState // "new") != "unchanged" and (.baselineState // "new") != "absent")))' \
"$SARIF" > "$RUNNER_TEMP/qodana-js.sarif"
echo "ready=true" >> "$GITHUB_OUTPUT"
- name: Upload to Code scanning
if: ${{ !cancelled() && steps.filter.outputs.ready == 'true' }}
uses: github/codeql-action/upload-sarif@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3
with:
sarif_file: ${{ runner.temp }}/qodana-js.sarif
category: qodana-js
+121 -22
View File
@@ -1,11 +1,20 @@
# Project-local: the ops repo has no reusable Tauri/build workflow (docs/RELEASE-CI.md §1).
# Project-local, like every workflow here (RELEASE-CI.md §1).
#
# Produces the NSIS .exe and .msi, publishes SHA256SUMS.txt and leaves a DRAFT release for owner
# review. Publishing is manual on purpose — RELEASE-CI.md §3.4 — and announce-release.yml fires on
# `release: published`.
# Builds the NSIS .exe and .msi, attests where they were built, publishes SHA256SUMS.txt and leaves
# a DRAFT release. Publishing is a separate, human-directed step (RELEASE-CI.md §3.4), and
# notify.yml's announcement fires on `release: published`.
#
# **Two jobs, so the token that can write releases never runs the build.** Building executes
# third-party code — every crate's build script, every npm package's — and gets a read-only token
# with no credentials left in the checkout. The publish job only attests and uploads what the build
# produced.
#
# `workflow_dispatch` with `dry_run` builds and checksums any ref — a branch before it merges —
# without attesting or drafting anything: the release recipe is tested before a tag depends on it.
#
# PipDock does not update itself, so there is no signing key and no `latest.json` here. Users get
# new versions from the GitHub Releases page. The checksums below are what they verify against.
# new versions from the GitHub Releases page; the checksums and the attestation are what they
# verify against (docs/SECURITY.md §5).
name: Release
@@ -15,12 +24,17 @@ on:
workflow_dispatch:
inputs:
tag:
description: Tag to build (for re-runs)
required: true
description: Tag to build (for re-runs). Empty builds the selected ref.
required: false
type: string
dry_run:
description: Build and checksum only — no attestation, no draft release.
required: false
type: boolean
default: false
permissions:
contents: write # release assets
contents: read
concurrency:
group: release-${{ github.ref }}
@@ -31,23 +45,60 @@ env:
jobs:
build:
name: Build · checksum · draft
name: Build · checksum
runs-on: windows-latest
timeout-minutes: 90
permissions:
contents: read
outputs:
tag: ${{ steps.version.outputs.tag }}
steps:
- name: Checkout
uses: actions/checkout@v7
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ inputs.tag || github.ref }}
persist-credentials: false
# The version lives in five places and they move together (CLAUDE.md), and a tag names the
# one they must all carry. A tag pushed before the bump commit, or a bump that missed one
# file, would otherwise build an installer whose About states another version.
- name: The tag and all five versions agree
id: version
shell: pwsh
env:
REF: ${{ inputs.tag || github.ref_name }}
DRY_RUN: ${{ inputs.dry_run || false }}
run: |
$ErrorActionPreference = 'Stop'
$found = [ordered]@{}
$found['Cargo.toml'] = (Select-String -Path Cargo.toml -Pattern '^version = "([^"]+)"' |
Select-Object -First 1).Matches[0].Groups[1].Value
$lock = Get-Content Cargo.lock -Raw
if ($lock -notmatch '(?m)^name = "pipdock-core"\r?\nversion = "([^"]+)"') { throw 'pipdock-core is not in Cargo.lock' }
$found['Cargo.lock'] = $Matches[1]
$found['package.json'] = (Get-Content package.json -Raw | ConvertFrom-Json).version
# -AsHashtable: package-lock.json has a property named "", which plain ConvertFrom-Json refuses.
$found['package-lock.json'] = (Get-Content package-lock.json -Raw | ConvertFrom-Json -AsHashtable)['version']
$found['tauri.conf.json'] = (Get-Content src-tauri/tauri.conf.json -Raw | ConvertFrom-Json).version
$found.GetEnumerator() | ForEach-Object { Write-Host ("{0,-18} {1}" -f $_.Key, $_.Value) }
$versions = @($found.Values | Sort-Object -Unique)
if ($versions.Count -ne 1) { throw "the five versions disagree: $($versions -join ', ')" }
$v = $versions[0]
if ($env:REF -match '^v\d') {
if ($env:REF -ne "v$v") { throw "tag $env:REF does not match version $v" }
} elseif ($env:DRY_RUN -ne 'true') {
throw "$env:REF is not a version tag; only a dry run builds a branch"
}
"tag=v$v" >> $env:GITHUB_OUTPUT
- name: Setup Node.js
uses: actions/setup-node@v7
uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: '24'
node-version: '26'
cache: npm
- name: Cache cargo
uses: actions/cache@v6
uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
with:
path: |
~/.cargo/registry
@@ -56,8 +107,12 @@ jobs:
key: ${{ runner.os }}-cargo-release-${{ hashFiles('**/Cargo.lock', 'rust-toolchain.toml') }}
restore-keys: ${{ runner.os }}-cargo-release-
# No install script runs: the only package in the lockfile that has one is fsevents, which
# is macOS-only, and a lifecycle script is how a compromised dependency runs on the runner
# (SonarCloud githubactions:S6505). The bundle does not need them: Tauri's CLI arrives as
# an optional platform package, not a download in a postinstall.
- name: Install frontend dependencies
run: npm ci
run: npm ci --ignore-scripts
# One script owns the recipe (`package.json` → `bundle`), so the workflow cannot drift
# from what a developer runs locally. It stages the CLI sidecar, then bundles with the
@@ -79,21 +134,65 @@ jobs:
ForEach-Object { Copy-Item $_.FullName $out }
Get-ChildItem $out
- name: Publish checksums
- name: Checksums
shell: pwsh
run: |
# SmartScreen warns on first run because the binaries are not EV-code-signed, so the
# README tells users to verify these instead (docs/SECURITY.md §5).
Get-ChildItem release-artifacts -File |
#
# LF line endings, written byte for byte: `Set-Content` wrote CRLF, and `sha256sum -c`
# on any other platform reads the CR as part of the file name and reports it missing.
$lines = Get-ChildItem release-artifacts -File |
Where-Object { $_.Name -ne 'SHA256SUMS.txt' } |
ForEach-Object { "$((Get-FileHash $_.FullName -Algorithm SHA256).Hash.ToLower()) $($_.Name)" } |
Set-Content release-artifacts\SHA256SUMS.txt -Encoding ascii
Sort-Object Name |
ForEach-Object { "$((Get-FileHash $_.FullName -Algorithm SHA256).Hash.ToLower()) $($_.Name)" }
[IO.File]::WriteAllText(
(Join-Path $PWD 'release-artifacts\SHA256SUMS.txt'),
(($lines -join "`n") + "`n"),
[Text.Encoding]::ASCII)
Get-Content release-artifacts\SHA256SUMS.txt
- name: Draft GitHub release
uses: softprops/action-gh-release@v3
- name: Upload the build
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
tag_name: ${{ inputs.tag || github.ref_name }}
draft: true # owner reviews, then publishes; publishing triggers the announcement
name: release-artifacts
path: release-artifacts/*
if-no-files-found: error
publish:
name: Attest · draft
needs: build
if: ${{ !inputs.dry_run }}
runs-on: ubuntu-latest
timeout-minutes: 15
permissions:
contents: write # the draft release and its assets
id-token: write # Sigstore, for the attestation
attestations: write
steps:
- name: Download the build
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: release-artifacts
path: release-artifacts
# Build provenance for the two installers: `gh attestation verify <file> --repo
# poli0981org/pipdock` proves an installer came from this workflow, at this commit — which a
# checksum published beside the file cannot, since whoever could replace one could replace
# both. An attestation stays with the account that made it: those of 1.4.0 and 1.5.0, made
# before the repository moved to the organization, verify with `--owner poli0981
# --signer-repo poli0981/pipdock` and no longer with any `--repo` (README, Install).
- name: Attest provenance
uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
with:
subject-path: |
release-artifacts/*.exe
release-artifacts/*.msi
- name: Draft GitHub release
uses: softprops/action-gh-release@8a0cd651e5b2365bd640854a3fa5dfc70e4875f3 # v3.0.4
with:
tag_name: ${{ needs.build.outputs.tag }}
draft: true # reviewed, then published; publishing triggers the announcement
generate_release_notes: true
files: release-artifacts/*
+64
View File
@@ -0,0 +1,64 @@
# Daily advisory scans of `main` — docs/SECURITY.md §7.
#
# The PR gates (ci-rust.yml's `cargo audit`, ci-node.yml's `npm audit`) only run when something
# changes. An advisory published against a dependency already on `main` therefore sat unnoticed
# until the next pull request happened to fail on it: that is how `main` went red in September
# with no PR open to say so. This runs the same two scans every day against what is merged, and a
# failure reaches Discord through notify-ci-failure.yml.
#
# Not a required check — it runs on no pull request.
name: Security scan
on:
schedule:
# Daily, off the hour.
- cron: '41 5 * * *'
workflow_dispatch:
permissions:
contents: read
jobs:
cargo:
name: cargo audit
runs-on: ubuntu-latest
timeout-minutes: 15
env:
RUSTUP_TOOLCHAIN: stable
steps:
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Install cargo-audit
uses: taiki-e/install-action@4a76afe23f9e08d2d9550fb56e556444e8611d21 # v2.90.4
with:
tool: cargo-audit
- name: Audit
run: cargo audit --deny warnings
npm:
name: npm audit
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Setup Node.js
uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: '26'
cache: npm
# Nothing is built here, so no package's install script has a reason to run.
- name: Install
run: npm ci --ignore-scripts
- name: Audit
run: npm audit --audit-level=high
+151
View File
@@ -0,0 +1,151 @@
# SonarQube Cloud, CI-based. sonar-project.properties says what is analysed, and why this replaced
# automatic analysis: that could not build, so it saw no Rust and imported no coverage.
#
# **One Windows job**, for the reason ci-rust.yml is on Windows: the Rust suite exercises the PEP 514
# registry and the `py` launcher, so coverage measured on Linux would be coverage of a different
# program. Scanning on the runner that produced the reports also means both LCOV files name paths
# the scanner can resolve, with nothing rewritten in between.
#
# **The token reaches one step.** Producing the reports runs third-party code — every crate's build
# script, every npm package's — so SONAR_TOKEN is in no environment but the scanner's, the same
# reasoning that keeps release.yml's write token away from its build.
#
# **No token, no analysis.** Dependabot's pull requests are given Dependabot secrets only, and a
# fork's none, so on those `secrets.SONAR_TOKEN` is empty and the job is skipped instead of failing
# on a missing token. Adding SONAR_TOKEN as a Dependabot secret as well brings their PRs back in.
#
# Not a required check. The quality gate is still reported as SonarCloud's own check on the PR, and
# `sonar.qualitygate.wait` makes this job fail with it — which is what lets a red gate on `main`
# reach Discord through notify-ci-failure.yml, where this workflow is listed by name.
name: SonarCloud
on:
pull_request:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: read
concurrency:
group: sonar-${{ github.ref }}
cancel-in-progress: true
env:
CARGO_TERM_COLOR: always
# ci-rust.yml's, so the clippy run below matches the fingerprints in the cache it restores.
RUSTFLAGS: -D warnings
jobs:
token:
name: token present
runs-on: ubuntu-latest
timeout-minutes: 2
outputs:
present: ${{ steps.check.outputs.present }}
steps:
# `secrets` cannot be read in an `if:`, so its presence is turned into an output here. Only
# the emptiness test sees the value; nothing is checked out and nothing else runs.
- name: Check
id: check
env:
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
run: |
if [ -n "$SONAR_TOKEN" ]; then
echo "present=true" >> "$GITHUB_OUTPUT"
else
echo "present=false" >> "$GITHUB_OUTPUT"
echo "::notice::No SONAR_TOKEN for this run (a Dependabot or fork pull request); the analysis is skipped."
fi
analyze:
name: coverage · analysis
needs: token
# A dispatch from any branch but `main` would be a *branch* analysis, which this organization's
# plan does not offer: the report uploads, and then the gate check fails with "not allowed to
# access data from non main branches" (tried 2026-10-25). Pull requests and `main` are the two
# analyses there are.
if: >-
needs.token.outputs.present == 'true' &&
(github.event_name != 'workflow_dispatch' || github.ref == 'refs/heads/main')
runs-on: windows-latest
timeout-minutes: 60
steps:
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
# Full history: new code is decided by blame, and a shallow clone has none to give.
fetch-depth: 0
persist-credentials: false
- name: Setup Node.js
uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: '26'
cache: npm
# No install script runs: the only package in the lockfile that has one is fsevents, which
# is macOS-only, and a lifecycle script is how a compromised dependency runs on the runner
# (SonarCloud githubactions:S6505). `npm licences` and `npm audit` never needed them either.
- name: Install frontend dependencies
run: npm ci --ignore-scripts
- name: TypeScript coverage
run: npm run test:coverage
# Restore only, from ci-rust.yml's key. The registry and clippy's build are reused from it;
# the instrumented build lands in target/llvm-cov-target and is rebuilt every run, because
# saving a fourth multi-GB cargo cache would evict the three the required checks depend on.
- name: Restore cargo cache
uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
with:
path: |
~/.cargo/registry
~/.cargo/git
target
key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock', 'rust-toolchain.toml') }}
restore-keys: ${{ runner.os }}-cargo-
# For the toolchain rust-toolchain.toml pins, which installs itself on the first cargo call;
# adding the component there instead would make every contributor download it.
- name: Add llvm-tools
run: rustup component add llvm-tools-preview
- name: Install cargo-llvm-cov
uses: taiki-e/install-action@4a76afe23f9e08d2d9550fb56e556444e8611d21 # v2.90.4
with:
tool: cargo-llvm-cov
- name: Rust coverage
run: cargo llvm-cov --workspace --locked --lcov --output-path target/lcov-rust.info
# The same invocation as ci-rust.yml's gate, as JSON. That job is what fails on a finding;
# this one only records it, so a red clippy still leaves a report for the scanner to import.
- name: Clippy report
shell: pwsh
run: |
cargo clippy --workspace --all-targets --locked --message-format=json -- -D warnings |
Out-File -Encoding utf8NoBOM target/clippy.json
exit 0
# package.json is one of the five places the version lives, and a tag cannot be pushed while
# they disagree (release.yml), so any of them would do. Checked against a version's shape
# because it is spliced into the scanner's argv below, in the step that holds the token.
- name: Project version
id: version
shell: pwsh
run: |
$v = (Get-Content package.json -Raw | ConvertFrom-Json).version
if ($v -notmatch '^\d+\.\d+\.\d+(-[0-9A-Za-z.]+)?$') { throw "package.json version '$v' is not a version" }
"version=$v" >> $env:GITHUB_OUTPUT
- name: Scan
uses: SonarSource/sonarqube-scan-action@59202af334b4ba7b5db01b701b8e79f8b3bef0f4 # v8.5.0
env:
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
with:
args: >
-Dsonar.projectVersion=${{ steps.version.outputs.version }}
-Dsonar.qualitygate.wait=true
+71
View File
@@ -0,0 +1,71 @@
# Maintenance-mode triage, from 1.6.0 (CONTRIBUTING.md, "Scope in maintenance mode").
#
# A feature request — titled as one, a `feat:` pull request, or labelled `enhancement` — is labelled
# `enhancement` and `out-of-scope`, answered in English and Vietnamese, and closed as not planned.
# Never one opened by a maintainer or a bot, or labelled `policy-exception`, the maintainer's way of
# keeping open a feature judged truly necessary. .github/scripts/triage.cjs holds the rules and says
# why they are only ever the unmistakable ones; its tests run in ci-node.yml's `npm licences` job.
#
# **`pull_request_target` checks out the base branch and nothing else.** That event runs with a
# write token even for a fork's pull request, which is the reason it is used here — a plain
# `pull_request` from a fork gets a read-only token and could not label or close anything — and
# exactly why nothing from the pull request is checked out or executed: the script reads the
# event's title and labels as data.
#
# `workflow_dispatch` is a dry run: it classifies the title and labels it is given and touches
# nothing, which is how the rules are tried without opening a public issue.
name: Triage
on:
issues:
types: [opened, labeled]
pull_request_target:
types: [opened, labeled]
workflow_dispatch:
inputs:
kind:
description: What to classify
type: choice
options: [issue, pull_request]
default: issue
title:
description: Its title
required: true
type: string
labels:
description: Its labels, comma-separated
required: false
type: string
default: ''
association:
description: The author's association
type: choice
options: [NONE, CONTRIBUTOR, FIRST_TIME_CONTRIBUTOR, COLLABORATOR, MEMBER, OWNER]
default: NONE
permissions:
contents: read
jobs:
policy:
name: maintenance policy
runs-on: ubuntu-latest
timeout-minutes: 5
permissions:
contents: read
issues: write # label, comment, close
pull-requests: write # the same on a pull request
steps:
- name: Checkout the base branch's scripts
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
sparse-checkout: .github/scripts
- name: Apply the policy
uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
with:
script: |
const triage = require('./.github/scripts/triage.cjs')
await triage.run({ github, context, core })
+10 -3
View File
@@ -8,6 +8,8 @@ node_modules/
dist/
dist-ssr/
.vite/
# `npm run test:coverage` (vitest's LCOV, read by sonar.yml).
/coverage/
*.tsbuildinfo
# Tauri build output
@@ -16,9 +18,9 @@ dist-ssr/
# Environments (test venvs created by the integration suite / spikes)
.venv/
venv/
# Scratch venvs for verifying by hand. Note that the GUI will only ever *see* one named exactly
# `.venv`, `venv`, `env` or `.env` in the working directory — `envs::venv_scan` matches that fixed
# list and `env_add_manual` (Browse…) is still owed — so a suffixed one here is CLI-only.
# Scratch venvs for verifying by hand. Discovery only *finds* one named exactly `.venv`, `venv`,
# `env` or `.env` in the working directory (`envs::venv_scan`'s fixed list); a suffixed one here has
# to be added — Add interpreter… in the GUI, `pipdock env add` in the CLI.
/.venv-*/
__pycache__/
*.py[cod]
@@ -51,6 +53,11 @@ tauri-signing-private.key*
# Logs & scratch
*.log
# insta's pending snapshots: review them with `cargo insta review`, never commit them.
*.snap.new
*.pending-snap
# A release's checksums, when downloaded beside the checkout to verify an installer.
/SHA256SUMS.txt
/spikes/out/
# Spike tooling venvs (SP-1 needs several uv versions side by side)
+1 -1
View File
@@ -1 +1 @@
24
26
File diff suppressed because it is too large. Load diff
+210
View File
@@ -0,0 +1,210 @@
# Accessibility
PipDock is meant to be usable by someone who uses a keyboard and no mouse, by someone who uses a
screen reader, and by someone who needs high contrast or larger text. This document says what that
means in practice, what has actually been tested and what has not, what is known not to work, and
how to tell us when something gets in your way.
**If you have hit a barrier, skip to [Reporting a barrier](#reporting-a-barrier).** You do not need
a GitHub account, and you do not need to diagnose the problem first.
## What we are working toward
The target is [WCAG 2.2](https://www.w3.org/TR/WCAG22/) Level AA, applied to a desktop application
and a command-line tool.
**This is a target, not a conformance claim.** PipDock has not been audited by anyone independent,
and the sections below list things that are known to fall short. What it has is a set of rules the
code is held to, tests that hold some of them, and one person's hands-on testing.
The priorities, in the order they are defended:
1. **Everything works from the keyboard.** No function needs a pointer.
2. **A screen reader is told what is on screen and what just changed.**
3. **Nothing is said by colour alone**, and text has enough contrast to read.
4. **The system's own settings are respected** — contrast themes, reduced motion, language.
## What is supported
### Keyboard
Every control is reachable and operable from the keyboard. The focus ring is a 2 px outline and is
never removed.
| Keys | What they do |
|---|---|
| `Tab` / `Shift+Tab` | Move between controls. In the package table each row is one stop |
| `Ctrl+1` … `Ctrl+9` | Go to a sidebar tab, by key position (works on layouts where digits need Shift) |
| `Ctrl+K` | Open the command palette; type to filter, `↑` `↓` to move, `Enter` to run, `Esc` to close |
| `/` | Go to Search and put the cursor in its field |
| `Space` | On a package row: select or deselect it |
| `Ctrl+A` | In the package table: select every row the screen is showing |
| `Enter` | On a package row: pin or unpin it. Never removes anything |
| `←` `→` | On a package row: move through its buttons (dependencies, pin, remove) |
| `←` `→` `Home` `End` | In Code Health: move between the tool tabs |
| `←` `→` `↑` `↓` | In a version conflict: move between *Keep compatible*, *Skip* and *Force latest*. Nothing is chosen until you press `Space` or `Enter` |
| `Esc` | Close a dialog, the palette or the console drawer; inside a package row, return to the row |
When the screen changes — a new tab, a plan's preview, its summary, the dependency view — focus
moves to the new screen's heading. So it does when *Remove from list* takes away the row whose
button you pressed (1.6.0). When a dialog, the palette or the console drawer closes, focus
returns to what opened it. A button that is busy after you press it stays where focus is. Every
confirmation that removes, forces or rewrites something opens with focus on **Cancel**.
The full map and the reasoning behind it are in [`docs/UI-SPEC.md`](docs/UI-SPEC.md) §8.
### Screen readers
- Each screen has landmarks (header, navigation, main, footer) and one top-level heading.
- The package table is exposed as a grid with column headers, a row count and selection state.
- Buttons that show only a symbol have names. Status chips say what they mean in text.
- Dialogs are named by their heading and described by their body.
- A run announces its progress ("3 of 15 complete") once, not once per output line. Search
announces that it is searching, how many results came back, and when nothing matched.
- On Environments, adding or removing an interpreter is said in a status line ("Added … to the
list."). *Remove from list* is named with the path it removes, beginning with the words on the
button. The file picker *Add interpreter…* opens is Windows' own dialog, with Windows' own
accessibility.
- Error messages are announced when they appear, and carry a code (`PD-XXX-000`) you can quote.
- The interface is in English and Vietnamese, and the document language follows the one in use.
### High contrast
Under a Windows contrast theme (forced colours), every colour in the interface is replaced by the
system's own. Because that removes every tint, the things a tint used to say are drawn another way:
destructive buttons get a double border, and the selected row, the selected search result and the
current sidebar tab get an outline.
PipDock follows the Windows display scale (Settings → Display → Scale), which enlarges the whole
window. It has no zoom of its own yet — see the limitations below.
### Colour, contrast and motion
- Text and status chips are checked against their backgrounds for at least 4.5:1 by a test that
runs on every change. Status is always a word or a symbol as well as a colour.
- There is no animation in the interface. `prefers-reduced-motion` is honoured for anything that
is ever added.
### The command line
`pipdock` prints plain text with no colour, no spinners and no lines that rewrite themselves. Every
command takes `--json` for one machine-readable document on standard output and `--quiet` to drop
progress; prompts, progress and warnings go to standard error; failures use documented exit codes.
Most of what the GUI does is available there — [`docs/CLI-GUIDE.md`](docs/CLI-GUIDE.md) lists the
few things that are not — so it is often a workable alternative while a GUI barrier is being fixed.
## What has been tested, and how
Honesty about this matters more than a long list.
| What | How | By whom, when |
|---|---|---|
| Every main flow with the mouse unplugged | By hand, on the installed 1.4.0 build, Windows 11 | The maintainer, November 2026. No blocking problem found |
| The same flows with Narrator | By hand, on the installed 1.4.0 build, Windows 11 | The maintainer, November 2026. No blocking problem found |
| Structure: roles, names, required parts | [axe-core](https://github.com/dequelabs/axe-core) over every screen, on every change | Automated, from 1.5.0 |
| Keyboard behaviour and where focus goes | Unit tests, on every change | Automated |
| Text contrast | Computed from the design tokens, on every change | Automated |
| Where focus goes, what the accessibility tree exposes, forced colours | In the installed build, driven by real key presses over the webview's debugging port, with forced colours emulated | During the 1.5.0 release. It found defects no test had; all are fixed |
**Not tested, and said so rather than implied:**
- **Narrator has not been run again on 1.5.0 or 1.6.0.** 1.5.0 changed what a screen reader hears
in several places (see the [changelog](changelog/1.x.md)), and 1.6.0 added *Add interpreter…* and
*Remove from list*. Those were checked against the accessibility tree, which says what is
exposed — not against speech, which is what you hear.
- **NVDA and JAWS** have not been used with PipDock at all. Reports from people who use them are
especially welcome.
- **Each Windows contrast theme by hand.** Forced colours were emulated; the four built-in themes
were not each switched on.
- **Windows 10.** PipDock supports it, and the testing above was on Windows 11.
- **The installers.** The setup program and the MSI are produced by NSIS and WiX, and their
accessibility is whatever those tools provide. It has not been assessed.
- Voice control, switch access and screen magnifiers.
## Known limitations
These are real, they are tracked in [`docs/ROADMAP.md`](docs/ROADMAP.md) under *Audit backlog*, and
where there is a workaround it is given.
- **One theme.** The interface is dark, with no light theme. A Windows contrast theme, light ones
included, replaces every colour.
- **The package table is one tab stop per row.** There is no `↑` / `↓` between rows yet, so
passing a long table by `Tab` is slow. *Workaround:* `Ctrl+1` … `Ctrl+9` jump past it, and the
Updates tab lists only what is outdated.
- **Only the rows on screen exist.** The table draws about 25 rows at a time, so a screen reader's
own "list all rows" finds only those. The row count and each row's position are exposed.
- **Live output is not read line by line.** The console drawer shows an engine's output as it
arrives and deliberately does not announce it; progress is announced instead. The text is there
to read at your own pace.
- **Some announcements are unverified.** A few status messages appear together with the part of
the screen that carries them, and several errors can appear at once after a failed batch.
Whether a screen reader says them, and in what order, has not been confirmed on 1.5.0.
- **A few failures say nothing.** If saving a report, copying to the clipboard or opening a file
picker fails, the screen does not change. Nothing is lost, but nothing tells you either.
- **Why a control is disabled is sometimes only in a tooltip**, which a keyboard cannot reach
because a disabled control cannot be focused.
- **No zoom inside the application.** It was built for 1.5.0 and held back: at 200 % in the
default window the package-name column collapsed to nothing and the last sidebar tabs were cut
off, which is worse than no zoom. *Workaround:* the Windows display scale enlarges everything
correctly.
- **Long paths and package names are cut off** rather than wrapped in a few places, most of all
in a narrow window.
- **Dates and sizes are not formatted for the interface language.**
- **`Ctrl+K` is matched by the letter the layout types**, unlike the digit shortcuts, so it moves
on a layout where K is elsewhere.
- **The legal documents open in your browser**, on GitHub, rather than inside the application.
## Reporting a barrier
Either of these reaches the same person:
- **[Open an accessibility issue](https://github.com/poli0981org/pipdock/issues/new?template=accessibility.yml)**
on GitHub, or
- write to **[accessibility@poli0981.dev](mailto:accessibility@poli0981.dev)** — no account needed.
Write in English or Vietnamese — tiếng Việt cũng được. It helps to include:
- what you were trying to do, and what happened instead;
- the PipDock version (**About → This build**) and your Windows version;
- the assistive technology you use and its version, if any — Narrator, NVDA, a contrast theme,
display scale, keyboard only;
- whether it stops you completely or slows you down.
You do not have to work out the cause, name a WCAG criterion or propose a fix. "I could not get
past the first screen" is a complete report.
### What happens next
- **You get an answer within 7 days**, the same commitment as for security reports.
- A barrier that stops someone using PipDock is treated as a bug of the highest priority and goes
into the next release. Others are scheduled like any other defect and recorded in the roadmap.
- If there is a workaround — often the command line — you will be told what it is straight away.
- You will be told when a fix ships, and asked whether it worked for you.
**There is no fixed deadline for a fix.** PipDock is made by one person, and a promised date that
slips is worse than none. What is promised is the answer, the priority, and that a report is never
closed as "works for me" without being tried the way you described it.
## For contributors
A change to the interface is not finished until it works without a mouse.
[`CONTRIBUTING.md`](CONTRIBUTING.md) has the checklist, and the pull request template repeats it.
In short: reach it and operate it by keyboard, keep the focus ring, put focus somewhere sensible
when the screen changes, name anything that shows only a symbol, never say something by colour
alone, mark a destructive button `data-destructive`, add copy in both languages, and keep
`npm test` green — it runs axe over every screen.
## Ownership
Accessibility reports go to the maintainer, [@poli0981](https://github.com/poli0981), who triages
them, keeps the list of known limitations above true, and updates this document with each release
that changes it.
Last reviewed: 2026-11-10, for PipDock 1.5.0.
---
The structure of this document follows the
[Accessibility Toolkit's `ACCESSIBILITY.md`](https://github.com/open-source-accessibility/accessibility-toolkit/blob/main/ACCESSIBILITY.md)
(MIT), following GitHub's
[guide to accessibility in open source](https://opensource.guide/accessibility-best-practices-for-your-project/).
+172 -35
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-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`.
Repo `poli0981org/pipdock` (moved from `poli0981/pipdock` on 2026-11-21) · GPL-3.0-only · **Status: 1.6.0, and in maintenance mode since that release.** M1, M2, Phase 3, Phase 4, the P1 wave, the Security tab and the dependency view are all complete, and 1.6.0 closed the last P0 gap, *Browse…* (`env_add_manual`). **Read ROADMAP's *Maintenance mode* section before starting anything**: dependency, security, major-upgrade, defect and wording work is taken; features are not, and `triage.yml` closes requests for them. 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); 1.3.0 added the dependency view (P1-6), which is a *mode of the package screen* rather than a tab and adds no runtime dependency — read its ROADMAP record before touching `graph/`, because the shape of the screen is a consequence of measurements rather than of taste. 1.4.0 added no feature: it is the audit release — about 170 findings, every Critical and High fixed with a test that failed first, and the rest in ROADMAP's **Audit backlog**, with file:line and a reason each. Read that table before starting a slice; most of what is wrong with the codebase is already written down there. 1.5.0 added no feature either: it is the accessibility pass (backlog U45, U47, U48) — focus, names, keyboard patterns and high contrast, axe-core in the suite, and `ACCESSIBILITY.md`, which is a *record of what was tested* and has to be kept true like one. 1.6.0 added *Add interpreter…* (GUI) and `pipdock env add`/`env remove` (CLI) over a `manual_envs` table and `envs::validate_interpreter`, moved the repository to the poli0981org organization with CI that calls nothing outside it, and put the project in maintenance mode. **Nothing is left of Post-1.0**: the scheduled check (P1-7) was closed as not planned, for the reasons ROADMAP's survey of it gives — no toast component, no notification/autostart/tray plugin, nothing on a timer, and no surface that can report a background failure.
## Read the docs before changing anything
@@ -12,15 +12,19 @@ The design is fully specified. Read in this order; do not invent behaviour that
3. `docs/DATA-FLOW.md` — update/install/uninstall/rollback state machines, engine command mapping, **invariants §9**
4. `docs/UI-SPEC.md` — design tokens, screens, click budgets, keyboard map
5. `docs/CLI-SPEC.md` — commands, flags, exit codes, JSON contracts
6. `docs/ERROR-CATALOG.md` — the launch codes and their stderr classifiers. **34 in Rust**
6. `docs/ERROR-CATALOG.md` — the launch codes and their stderr classifiers. **35 in Rust**
(`Code::ALL`, pinned by two tests); the doc tabulates fewer rows because it folds
`PD-HLT-001..004` into one. Adding a code means the catalog, `Code::ALL`, both counts, the
"no code without a fixture" gate in `classifier_corpus.rs`, **both `locales/*/errors.json`**,
a regenerated `codes.json` (`cargo run -p xtask -- ipc-fixtures`), regenerated bindings, and
re-blessed goldens — `golden__schema-Code.snap` **and every schema that embeds it**, which
since P3 is **four**: `StepResult`, `ExecutionSummary` and `HealthReport`, the last via
`ToolProblem.code`. Nine places; the gates will tell you which you forgot, including
`i18n.test.ts`, which fails on a code with no copy in either language
`PD-HLT-001..004` into one, so it shows **32 rows**. Adding a code means the catalog,
`Code::ALL`, both counts, the "no code without a fixture" gate in `classifier_corpus.rs`,
**both `locales/*/errors.json`**, a regenerated `codes.json`
(`cargo run -p xtask -- ipc-fixtures`), regenerated bindings, and re-blessed goldens —
`golden__schema-Code.snap` **and every schema that embeds it**, which since 1.4.0 is
**five**: `StepResult`, `ExecutionSummary`, `CheckReport` (its `error`), `HealthReport` and
`AuditReport`, the last two via `ToolProblem.code`. **Six snapshot files in all.** This line
has been wrong about the count twice — grep `PD-ENV-001` across
`crates/pipdock-cli/tests/snapshots/` rather than trusting the list. Nine places; the
gates will tell you which you forgot, including `i18n.test.ts`, which fails on a code with
no copy in either language
7. `docs/CODE-HEALTH-SPEC.md`, `docs/SECURITY.md`, `docs/TESTING.md`, `docs/RELEASE-CI.md`, `docs/I18N.md`, `docs/ROADMAP.md`
8. `legal/` — EULA, Disclaimer, Privacy, Third-Party Notices (public; the in-app legal gate links to these GitHub URLs)
@@ -43,7 +47,8 @@ failed package never aborts a batch (skip-and-continue, then a `"13 successful,
`--dry-run --report -` crashes on Windows/cp1252 (pip 25 *and* 26), data-dependently.
8. **uv writes its plan to stderr**, so classify errors only after a plan-parse attempt.
9. **`env_hash` lowercases the interpreter path on Windows**, or one env splits its pins and
snapshots in two.
snapshots in two — and since 1.6.0 stops at a venv's own `python.exe`, or a `--symlinks` venv
files its pins and snapshots under the Python it was made from.
10. **PipDock enforces `Requires-Python` itself** (`src/compat.rs`) — the engines disagree, and the
preview must not depend on which one is selected.
@@ -58,11 +63,11 @@ failed package never aborts a batch (skip-and-continue, then a `"13 successful,
minor range at roughly 600 lines and never renumber an existing range file —
`changelog/README.md` is the authority.
- Crates `pipdock-*`; React components prefixed `Pd` (`PdPackageRow`, `PdConflictDialog`)
- Crates `pipdock-*`; React components prefixed `Pd` (`PdPackageRow`, `PdConflictRow`)
- Tauri identifier `com.skullmute.pipdock`; CLI binary `pipdock`
- Frontend lives in `ui/`, but `package.json` sits at the **repo root** so the ops-repo
`reusable-web-react.yml` (which has no `working-directory` input) works unmodified; Vite is
configured with `root: './ui'`
- Frontend lives in `ui/`, but `package.json` sits at the **repo root** — first for the ops
repo's reusable CI workflow, which had no `working-directory` input, and now because SonarCloud,
Qodana, the scripts and Tauri's config all assume it; Vite is configured with `root: './ui'`
- Rust ↔ TS types are generated by `cargo run -p xtask -- bindings` over `schemars` — never
hand-mirror a type. (ARCHITECTURE §9 originally said `specta`/`tauri-specta`; `bindings.rs` records
why it is not, and drift is a `cargo test` failure rather than a compile error)
@@ -70,11 +75,53 @@ failed package never aborts a batch (skip-and-continue, then a `"13 successful,
## CI reality
`docs/RELEASE-CI.md` is authoritative *as corrected*: the ops repo `poli0981/.github` has **no
reusable Rust or Tauri workflow**, its notifiers are **Discord-only**, dependency bumps are
**Dependabot** (not Renovate), and its CodeQL reusable has **no Rust support**. So `ci-rust.yml` and
`release.yml` are project-local; `ci-node.yml`, `codeql.yml` and the notifiers are callers.
Every caller needs an explicit `permissions:` block — callers without one default to `none`.
`docs/RELEASE-CI.md` is authoritative. **Every workflow is project-local since 2026-11-21**, when
the repository moved to the poli0981org organization: `ci-node.yml`'s web job, `codeql.yml` and the
Discord notifier were callers into the owner's personal ops repo (`poli0981/.github`, at `@main`)
until then, and a project in the organization no longer runs code another account can change.
**Every action is pinned by commit** with its version in a comment, GitHub's own included, and a
write permission belongs on the job that needs it, not the workflow. Dependency bumps are
**Dependabot** (not Renovate); notifications are **Discord-only**, through the vendored
`.github/scripts/discord_notify.py` (`DRY_RUN=1` prints instead of posting).
**Eight checks are required on `main`** — `fmt · clippy · test`, `cargo audit`, `cargo deny`,
`lint · typecheck · test · build`, `npm audit`, `npm licences`, `tauri lockstep`,
`Analyze (javascript-typescript)` — and a required name is this repository's own now, so renaming a
job means changing the protection payload in the same change (RELEASE-CI §2). `npm licences` is the
npm half of `deny.toml`: `scripts/check-licenses.mjs` with the same allowlist, entry for entry.
**`notify.yml` lists its workflows by name, and a new workflow has to be added to it.**
`workflows: ['*']` — the ops repo's old example — is not a wildcard to `workflow_run`: it matched
nothing, and `main` was red from 2026-09-23 for three weeks with no one told. Start any CI
question with `gh run list --branch main`, and remember that `security-scan.yml` exists for the
case no PR will catch: an advisory against something already merged.
**Dependabot gives a dependency to the *most specific* group, not the first.** A group with
`update-types` beats one with patterns alone, so the `tauri` groups caught nothing until the
catch-alls got `exclude-patterns` (2026-11-21); the order of groups in `dependabot.yml` decides
nothing. Its log says which group took what ("belongs to more specific group").
**Qodana runs as two Qodana Cloud projects** — `qodana-rust.yaml` (RustRover in Docker; it cannot
see `#[cfg(windows)]` code) and `qodana-js.yaml` (WebStorm, native), one token each — and is not a
required check. A new workflow cannot be dispatched before it exists on `main`, so a workflow's
first full run happens in its own PR.
**An attestation stays with the account that made it.** After the transfer, 1.4.0 and 1.5.0 verify
only with `gh attestation verify <file> --owner poli0981 --signer-repo poli0981/pipdock`; every
`--repo` form returns 404 for them. 1.6.0 on verifies with `--repo poli0981org/pipdock`.
**SonarQube Cloud is CI-based since 2026-10-25** — `sonar.yml` and `sonar-project.properties`;
since 2026-11-21 the project is `poli0981org_pipdock` in the `poli0981org` organization (the old
`poli0981_pipdock` keeps the history to 1.5.0). Automatic analysis is off in the project's settings
and must stay off, or the CI analysis is refused. Automatic analysis never analysed a line of Rust and imported no coverage, which is why it
went. The gate's "new code" is *previous version*, with the version from `package.json`, and a
bump takes effect **one analysis late**: the analysis that first sent `1.4.0` still measured from
2026-09-27, and the next measured from the last analysis of the version before it (2026-10-20,
`a314689`). So the merge carrying a release bump is gated on the whole previous period, and
`periods` in `api/qualitygates/project_status` says which baseline a gate used. New code needs
80 % coverage and no new issue, so a slice whose new lines no test reaches turns `main`'s gate red,
and so does a `std::fs` call inside an `async fn` (`rust:S7493`) or a tracing field named
`message` (`rust:S6677`). Dependabot PRs have no `SONAR_TOKEN` and skip the analysis.
## Current state
@@ -89,7 +136,7 @@ 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
`health_save_report` writes Markdown + JSON. **`NOT_YET` is down to two**, both M3-general — P5 landed the
`health_save_report` writes Markdown + JSON. `NOT_YET` was down to two after it, 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).
@@ -107,16 +154,106 @@ P2 built the tools venv — `health::sync_tools_venv` fills
`%LOCALAPPDATA%\PipDock\data\tools\.venv` from the shipped pins over `pipdock tools sync`, and there is
no `TOOLS_PYTHON_MAX` because deptry ships an abi3 wheel (ROADMAP's premise for that const was
wrong; the record says why). P1 closed **P0-10**: pip's version is on every Environments row and
*Upgrade pip* is 2 clicks. **Next is P3** (the three runners + `HealthReport`), then P4 (the Health
screen) and P5 (the gated `ruff --fix`); `~/.claude/plans/b-n-c-th-b-t-snappy-rabin.md` has all
four decomposed, including six corrections to the specs found by running the pinned tools.
P2 touched no `NOT_YET` entry: it is CLI-only on purpose, so P3's `health_run` owns the
*Upgrade pip* is 2 clicks. P3–P5 followed — the three runners and `HealthReport`, the Health
screen, the gated `ruff --fix` — and are recorded in ROADMAP. 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.
**`NOT_YET` is empty since 1.6.0**: `env_add_manual` shipped with *Add interpreter…*, beside a
second command, `env_remove_manual`. `NOT_YET` in `src-tauri/src/lib.rs` is the authority and three
tests keep it honest in both directions — this file has said "four", "two" and "two" in different
paragraphs at once, each true when written and none updated. A future command that is declared
before it is built goes back on that list, not into a sentence here.
**1.4.0, the audit release, left these behind** — most found by running rather than by reading, and each
rule below backed by a test where a test can hold it:
- **A flow is only as safe as what can drive it.** The stale-plan and drift checks (DATA-FLOW
§9.3) never fired, because nothing could run a flow without a real engine, so nothing did.
`FlowOptions`, the `Engine::probe` seam and `tests/flows.rs`'s scripted engine exist so that
every flow decision has a test needing no pip. A new flow decision without one is a regression.
- **A check that cannot run must not report a pass.** `unwrap_or(ok: true)` said "verified"
exactly when nothing was — a pip broken by the run it was checking. `CheckReport.error` says so.
The empty-plan path kept its own copy of the bug until the last UI commit of the release.
- **`python -I` ignores `PYTHONUTF8` and `PYTHONIOENCODING`** (it implies `-E`), so invariant 7's
variables did nothing for the probe, and every venv under a folder named in Vietnamese crashed
it. `-X utf8` survives isolation; `probe.py` runs under it.
- **A grant is a contract no frontend test can see.** Decline on the legal gate did nothing in the
installed app while its test passed: the test mocks `close()`, and `core:default` never granted
`core:window:allow-close`. `lib.rs` pins the webview's exact permissions now — widening them is
a test change, on purpose.
- **Data drift and format drift look identical in a red drift job.** Seven weeks of red were two
causes: PyPI data (idna's newest release, scipy's version list) and uv 0.13 rewriting its error
rendering. Data is redacted in `capture.py`; a format change gets a frozen corpus of its own
(`tests/fixtures/uv-0.11/`, the last miette-style uv) beside the live one (`uv/`) — or, when
only some scenarios moved, a partial one: `pip-26.2/` holds the one capture pip 26.3 re-rendered.
- **Normalise everything you hash, not most of it.** The legal-docs hash normalised CRLF in the
content and hashed the raw length, so a Windows checkout re-showed the gate for nothing.
- **`--json` is one document.** Scripts parse stdout with one `ConvertFrom-Json`; prose, prompts
and warnings go to stderr. Every command's shape is in CLI-SPEC §6, and the goldens hold it.
- **Never put a backslash in a Bash heredoc** that becomes source code: the tool collapses `\\`
to `\`, which turned `b"\r\n"` test strings into real line breaks and a CRLF test into one that
could not fail. Write such files with the Write/Edit tools, then check the failing-first run
actually failed.
**1.5.0, the accessibility pass, left these behind** — the first found by reading, the rest by
driving the installed build:
- **jsdom is wrong about focus and blind to the cascade, and both cost a shipped defect.** A
browser takes focus from a control that becomes `disabled`; jsdom does not. So nine buttons that
disabled themselves when pressed dropped focus to `<body>` with every test green. **Busy is
`aria-disabled` plus a click guard; `disabled` is for unavailable.** And jsdom applies no
stylesheet: the forced-colors border on destructive buttons sat in `@layer base`, lost to
Tailwind's `border` utility in a later layer, and had never been drawn. **A rule that must beat
a utility goes outside every `@layer`**, and `destructive.test.ts` counts the braces.
- **The recipe that found them.** Install the bundle, launch with
`WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=<n>` and a scratch
`LOCALAPPDATA` (a release build honours it), and speak CDP to `http://127.0.0.1:<n>/json`:
`Input.dispatchKeyEvent` for real key presses (`Enter` needs a `char` event with `\r`),
`Runtime.evaluate` for `document.activeElement`, `Accessibility.getFullAXTree` for names, and
`Emulation.setEmulatedMedia` with `forced-colors: active`. No system setting changes. It cannot
hear a screen reader — say so wherever the result is written down. **A scratch profile still
discovers the owner's real interpreters**: select the scratch venv before starting any plan.
- **Anything that replaces what `<main>` shows without changing `nav` belongs in `App.tsx`'s
second focus effect.** There were four; the legal gate was a fifth, found after the first four
were fixed and tested. The effect acts only when focus was lost, so adding a dependency is safe.
- **A destructive button carries `data-destructive`**, whatever colour it is drawn in, and a test
reads the source for it. Do not add a `data-action` to a stylesheet list; there is no list.
- **An accessible name is assembled without spaces.** Inline spans join as `Updates(5)`; put a
literal `{' '}`. A browser *adds* one before visually-hidden text, so `: numpy` in an `sr-only`
span read "Remove packages : numpy" — use `aria-label` for a name with punctuation in it.
- **`sr-only` text needs a positioned parent.** It is `position: absolute`, so with no positioned
ancestor it is laid out against the viewport, outside every scroller: a list of pin chips on
Pins made the whole window scroll. Put `relative` on whatever holds the hidden text.
- **`ACCESSIBILITY.md` is hand-kept and says who tested what.** A change to keyboard, focus,
names or contrast is a change to it, the way a behaviour change is a change to `legal/`. It
currently says Narrator was not re-run on 1.5.0, and only a person can change that sentence.
- **`eslint-plugin-jsx-a11y` peers ESLint 9 at most**, like `react/jsx-no-literals`. axe-core is
called directly from `ui/src/test/axe.ts`; `color-contrast` is off there, and is
`tokens.test.ts`'s job.
- **Zoom is off on a measurement** (`zoomHotkeysEnabled`): at 200 % in the default window the
table's name column collapses to zero. Backlog A5 says what has to change first.
**1.6.0, *Add interpreter…*, left these behind** — found by an independent review after every suite
and the installed-build smoke were green:
- **The path you check is not the path you run.** `validate_interpreter` canonicalized to compare
against PipDock's own venvs and returned that, so a `--symlinks` venv — whose `python.exe` links
to its base — was run and stored as the base, and `--env .venv update --all` would have changed
the system Python. Resolve to *decide*; run and store what was given, made absolute. **The
identity followed the same link**: `env_hash` filed a linked venv's pins, snapshots and reports
under its base, which nothing showed while no screen could list the two apart. A venv's own
interpreter (recognised by `pyvenv.cfg`) is now resolved only up to its folder. Rows are still
matched by path, never by hash: two names for one Python share one.
- **Anything that resolves a path needs a fallback to the path.** A Microsoft Store Python is an
app-execution alias that `canonicalize()` refuses (os error 1920). `canonical_interpreter` always
fell back; the new validator did not, and `env use` would have broken for every Store user.
- **A check made once is a claim about the past.** An added entry is validated again on every
listing (`envs::probe_listed`, both heads), and the CLI's stored default when it is used: a link
can be re-pointed after it was accepted.
- **Remove a row by what it shows, not by an identity recomputed from it.** For a file that is
gone, `env_hash` hashes the stored text, which is not the identity it was added under whenever
canonicalizing changed it (a share: `UNC\server\…`); removal by hash reported success, and the
row came back on the next scan.
Three rules P1 left behind, all found by running rather than reading:
@@ -125,9 +262,10 @@ Three rules P1 left behind, all found by running rather than reading:
with, so every venv built from a uv-managed, Debian, Homebrew or Fedora Python refused every
mutation. Anything reading a path out of `sysconfig` inside a venv is asking about the base.
- **`envs::venv_scan` matches exactly `.venv`, `venv`, `env`, `.env`.** A scratch venv named
anything else is invisible to `env list` and to the GUI, and `env_add_manual` (*Browse…*) is
still owed — so hand-verification of any environment feature needs one of those four names in
the working directory.
anything else is not *discovered*; since 1.6.0 it can be *added* — *Add interpreter…* in the GUI,
`pipdock env add` in the CLI — and that is how hand-verification reaches a venv outside the
working directory. A path a person supplies goes through `envs::validate_interpreter` (named like
Python, not PipDock's own venvs) before anything runs it; the picker is not the check.
- **Every pip below 22.2 is broken on Python 3.12+** (`distutils`, `pkgutil.ImpImporter`), so the
one case *Upgrade pip* exists for is also a pip that cannot run. `upgrade_pip` falls back to
`ensurepip`, and decides by asking `pip --version` rather than matching a traceback.
@@ -197,7 +335,7 @@ Things worth knowing before you change any of it:
- **`cargo test` fails when `ui/src/ipc/generated.ts` is stale.** Fix with
`cargo run -p xtask -- bindings`; the failure names that command and the first differing line.
- **The L4 goldens (`crates/pipdock-cli/tests/golden.rs`, 64 snapshots at 1.1.0) are the CLI's output
- **The L4 goldens (`crates/pipdock-cli/tests/golden.rs`, 70 snapshots at 1.6.0) are the CLI's output
contract.** A diff there is a real behaviour change — re-bless deliberately, never reflexively.
They are what made the `core::flow` refactor provably behaviour-preserving.
- **Two tests hold the wire format**: `Code::ALL` must serialize as `as_str()`, and no
@@ -336,6 +474,5 @@ Things worth knowing before you change any of it:
id before execution and the GUI can draw DATA-FLOW §3's distinct states. The cost is that
skipping the snapshot becomes expressible, which is why `flow::proof_from` refuses `NotTaken`
with `PD-SNP-001`. Do not "simplify" them back into one.
- **Fixtures under `tests/fixtures/{pip,uv}/` are not literal engine bytes** — see the redaction
note above. Related: `ScanProgress.label` and every path, version and engine id in the UI are
data and are never translated (I18N §2).
- `ScanProgress.label` and every path, version and engine id in the UI are data and are never
translated (I18N §2).
+84
View File
@@ -0,0 +1,84 @@
# Contributor Covenant Code of Conduct
## Our Pledge
We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
## Our Standards
Examples of behavior that contributes to a positive environment for our community include:
* Demonstrating empathy and kindness toward other people
* Being respectful of differing opinions, viewpoints, and experiences
* Giving and gracefully accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
* Focusing on what is best not just for us as individuals, but for the overall community
Examples of unacceptable behavior include:
* The use of sexualized language or imagery, and sexual attention or advances of any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or email address, without their explicit permission
* Other conduct which could reasonably be considered inappropriate in a professional setting
## Enforcement Responsibilities
Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
## Scope
This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at [contact@poli0981.dev](mailto:contact@poli0981.dev). All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the reporter of any incident.
## Enforcement Guidelines
Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
### 1. Correction
**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
### 2. Warning
**Community Impact**: A violation through a single incident or series of actions.
**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
### 3. Temporary Ban
**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
### 4. Permanent Ban
**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
**Consequence**: A permanent ban from any sort of public interaction within the community.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
[homepage]: https://www.contributor-covenant.org
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
[Mozilla CoC]: https://github.com/mozilla/diversity
[FAQ]: https://www.contributor-covenant.org/faq
[translations]: https://www.contributor-covenant.org/translations
+198
View File
@@ -0,0 +1,198 @@
# Contributing to PipDock
Thank you for wanting to help. PipDock is made by one person, so the most useful contributions are
the ones that arrive easy to say yes to: a bug report that reproduces, or a pull request that does
one thing and proves it.
By taking part you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).
## Scope in maintenance mode
**Since 1.6.0 (2026-11), PipDock is maintained rather than developed.** It does what it was
designed to do — the last missing core feature, adding an interpreter by path, shipped in 1.6.0 —
and from here the work is keeping it correct, safe and current. What that takes in:
- **Regular dependency updates** — Rust crates, npm packages, GitHub Actions and the Code Health
tool pins, the way Dependabot proposes them.
- **Security fixes** — a dependency with a High or Critical advisory, or a serious security problem
in a runtime or toolchain PipDock is built with (Node, Rust, WebView2), fixed promptly and
released when it reaches the shipped program.
- **Major language, runtime and framework upgrades** — Node 26 to 28, TypeScript 6 to 7, a Rust
edition, Tauri 2 to 3 — when they arrive and are stable.
- **Bugs, UI/UX defects and accessibility barriers** — anything that does not work as the docs
describe, gets in someone's way, or cannot be used with a keyboard, a screen reader or high
contrast.
- **Wording and translation** — English or Vietnamese text that is wrong, misspelt in a way that
changes the meaning, misleading, or does not read the way people actually speak. There is an
issue form for it.
**New features are not taken**, as issues or as pull requests. One that asks for a feature — titled
as a feature request, a `feat:` pull request, or labelled `enhancement` — is labelled
`out-of-scope` and closed automatically, with this section linked. That is not a judgement of the
idea. If you believe something is **truly necessary** — it fixes data loss, a security hole, or
makes the program unusable for someone without it — make the case in
[Discussions → Ideas](https://github.com/poli0981org/pipdock/discussions/categories/ideas); the
maintainer can keep an item open with the `policy-exception` label.
What is planned, and what was deliberately not built, is in [`docs/ROADMAP.md`](docs/ROADMAP.md)
under *Maintenance mode*.
## Before you write code
- **A bug** — [open an issue](https://github.com/poli0981org/pipdock/issues/new/choose). The in-app
*Report bug* button fills most of the form in for you.
- **Something that gets in your way as a keyboard, screen-reader or high-contrast user** — see
[ACCESSIBILITY.md](ACCESSIBILITY.md). That report does not need a diagnosis.
- **A security problem** — do not open an issue; follow the [security policy](.github/SECURITY.md).
- **Wrong or misleading text, in either language** — the *Wording or translation problem* form.
- **A question** — [Discussions](https://github.com/poli0981org/pipdock/discussions).
- **A feature** — not during maintenance; see [above](#scope-in-maintenance-mode). The design is
written down in `docs/`, and a fix that contradicts it will be asked to change the docs first,
which is a conversation better had before the code.
## Setting up
PipDock is a Windows application: a Rust core, a Tauri 2 shell and a React 19 frontend.
| You need | Version |
|---|---|
| Windows | 10 or 11, with the WebView2 runtime (Windows 11 has it) |
| Rust | the toolchain in `rust-toolchain.toml`; `rustup` installs it on first use |
| Node.js | the major in `.nvmrc` |
| Python | 3.10 or newer, for the tests that drive a real pip |
| Build tools | the MSVC C++ build tools, as [Tauri requires](https://tauri.app/start/prerequisites/) |
```bash
npm ci
```
```bash
npm run tauri dev
```
`package.json` sits at the repository root although the frontend lives in `ui/`; that is deliberate
and Vite is configured for it.
## The checks, which are the ones CI runs
```bash
npm run lint
```
```bash
npm run typecheck
```
```bash
npm test
```
```bash
cargo fmt --all -- --check
```
```bash
cargo clippy --workspace --all-targets --locked -- -D warnings
```
```bash
cargo test --workspace --locked
```
```bash
node scripts/check-licenses.mjs
```
A pull request needs eight checks green before it can merge — `fmt · clippy · test`, `cargo audit`,
`cargo deny`, `lint · typecheck · test · build`, `npm audit`, `npm licences`, `tauri lockstep` and
CodeQL for JavaScript/TypeScript. Several more run and are read before merging (CodeQL for Rust and
Actions, the real-engine integration tests, SonarQube Cloud, Qodana). New code is expected to be
covered by tests; the SonarQube gate asks for 80 % on new lines. A new dependency the app ships must
be under a licence `deny.toml` allows — the two licence checks fail otherwise, and widening the list
is a licensing decision, not a CI fix.
## What a pull request should look like
**One pull request, one thing, taken all the way.** Not several shallow changes. The
[template](.github/PULL_REQUEST_TEMPLATE.md) is a checklist of the rest; the parts that surprise
people are below.
- **A test that fails first.** Write the test, watch it fail for the reason you expect, then make
the change. A test that has never failed has not been shown to test anything.
- **Run it.** Nearly every unplanned defect in this project was found by running the application or
the CLI against a real environment, not by a passing suite. Say in the pull request what you ran.
- **Commit subjects follow [Conventional Commits](https://www.conventionalcommits.org/)** —
`fix:`, `feat:`, `docs:`, `test:`, `build(deps):`, `ci:`. Nothing is generated from them; they
are for the person reading the log.
- **`main` has linear history**, so pull requests are squashed or rebased, never merge-committed.
- **If a user would notice, add a changelog entry** in [`changelog/`](changelog/README.md), written
for that user. Internals belong in the pull request and in `docs/ROADMAP.md`.
### Things that will fail CI if you forget them
- **Rust types that cross to the UI are generated, never hand-copied.** After changing one:
```bash
cargo run -p xtask -- bindings
```
`cargo test` fails while `ui/src/ipc/generated.ts` is stale, and names that command.
- **The CLI's output is a contract.** `crates/pipdock-cli/tests/golden.rs` holds a snapshot of every
command. A diff there is a real behaviour change: re-bless it because you meant it, never to make
the suite green.
- **Every piece of user-visible text lives in both languages** — `ui/src/locales/en` and
`ui/src/locales/vi`. A string literal in JSX is a lint error, and a key missing from either
language fails `i18n.test.ts`. Rust emits codes and data; it never phrases a sentence.
- **Never rewrite a file under `tests/fixtures/` with a text-mode tool.** They are byte-exact
captures of engine output, line endings included.
## The rules that are not negotiable
These are what make PipDock safe to point at an environment someone depends on. A change that
weakens one will not be merged, however useful it is otherwise.
1. **Nothing mutates an environment without a plan the user accepted and a snapshot that was
written.** If the snapshot fails, nothing runs.
2. **Subprocesses are started with argument arrays, never through a shell**, and package names and
versions are validated before they reach one.
3. **PipDock does not resolve dependencies.** pip or uv resolves; PipDock explains.
4. **`--break-system-packages` is never passed unless the user turned the override on.**
5. **One failed package never aborts a batch**, and every failure carries exactly one catalog code.
[`docs/DATA-FLOW.md`](docs/DATA-FLOW.md) §9 and [`docs/SECURITY.md`](docs/SECURITY.md) are the full
statements.
## Accessibility
A change to the interface is not done until it works without a mouse. Before you open the pull
request:
- reach and operate everything new with the keyboard alone;
- check that focus is visible, and that it lands somewhere sensible when the screen changes or a
dialog closes — never on nothing;
- give any control that shows only a symbol an accessible name, and every input a label;
- do not say anything by colour alone, and put `data-destructive` on a button that removes, forces
or rewrites, so high contrast can still tell it from Cancel;
- keep `npm test` green: it runs [axe-core](https://github.com/dequelabs/axe-core) over every
screen. axe checks structure; it cannot tell you what a screen reader says, so try one if you
can — Narrator is `Ctrl+Win+Enter` — and say in the pull request if you could not.
[ACCESSIBILITY.md](ACCESSIBILITY.md) is the statement these keep true, and
[`docs/UI-SPEC.md`](docs/UI-SPEC.md) §8 is the keyboard map.
## Where things are
| Path | What is there |
|---|---|
| `crates/pipdock-core` | Everything that touches an environment: engines, plans, snapshots, the error catalog |
| `crates/pipdock-cli` | The `pipdock` command line, and its golden tests |
| `src-tauri` | The desktop shell and the IPC commands |
| `ui/src` | The React frontend; nothing in it calls Tauri's `invoke` directly, only the wrappers in `ui/src/ipc` |
| `docs/` | The design: read [`ARCHITECTURE.md`](docs/ARCHITECTURE.md) before a structural change |
| `legal/` | What a user agrees to. Edits here re-show the first-run screen once, by design |
## Licence
PipDock is [GPL-3.0-only](LICENSE). By contributing you agree that your contribution is licensed
under the same terms. Parts of PipDock were written with an AI assistant under human review;
[`docs/AI-DISCLOSURE.md`](docs/AI-DISCLOSURE.md) says how.
Generated
+705 -885
View File
File diff suppressed because it is too large. Load diff
+6 -3
View File
@@ -3,12 +3,15 @@ resolver = "3"
members = ["crates/pipdock-core", "crates/pipdock-cli", "src-tauri", "xtask"]
[workspace.package]
version = "1.2.0"
version = "1.6.0"
edition = "2024"
rust-version = "1.94"
rust-version = "1.99"
license = "GPL-3.0-only"
repository = "https://github.com/poli0981/pipdock"
repository = "https://github.com/poli0981org/pipdock"
authors = ["Kokone (poli0981)"]
# Applications, not libraries: nothing here belongs on crates.io, and cargo-deny treats a
# publishable crate's licence and path dependencies as a published one's (deny.toml).
publish = false
[workspace.lints.rust]
unsafe_code = "forbid"
+60 -23
View File
@@ -1,14 +1,16 @@
# PipDock
[![CI · Rust](https://github.com/poli0981/pipdock/actions/workflows/ci-rust.yml/badge.svg)](https://github.com/poli0981/pipdock/actions/workflows/ci-rust.yml)
[![CI · Node](https://github.com/poli0981/pipdock/actions/workflows/ci-node.yml/badge.svg)](https://github.com/poli0981/pipdock/actions/workflows/ci-node.yml)
[![CodeQL](https://github.com/poli0981/pipdock/actions/workflows/codeql.yml/badge.svg)](https://github.com/poli0981/pipdock/actions/workflows/codeql.yml)
[![Release](https://img.shields.io/github/v/release/poli0981/pipdock?display_name=tag&sort=semver)](https://github.com/poli0981/pipdock/releases)
[![CI · Rust](https://github.com/poli0981org/pipdock/actions/workflows/ci-rust.yml/badge.svg)](https://github.com/poli0981org/pipdock/actions/workflows/ci-rust.yml)
[![CI · Node](https://github.com/poli0981org/pipdock/actions/workflows/ci-node.yml/badge.svg)](https://github.com/poli0981org/pipdock/actions/workflows/ci-node.yml)
[![CodeQL](https://github.com/poli0981org/pipdock/actions/workflows/codeql.yml/badge.svg)](https://github.com/poli0981org/pipdock/actions/workflows/codeql.yml)
[![Release](https://img.shields.io/github/v/release/poli0981org/pipdock?display_name=tag&sort=semver)](https://github.com/poli0981org/pipdock/releases)
[![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-blue)](LICENSE)
**A friendly dock for your Python environments.** Inspect, install, update, and clean up Python packages in bulk — through a keyboard-first GUI or a scriptable CLI — without ever hand-typing another `pip install` incantation or guessing why an upgrade broke your project.
> Repo: `poli0981/pipdock` · License: **GPL-3.0-only** · Platform: **Windows 10/11** · Contact: [contact@poli0981.dev](mailto:contact@poli0981.dev) · [other channels](https://poli0981.dev/links/)
> Repo: `poli0981org/pipdock` · License: **GPL-3.0-only** · Platform: **Windows 10/11** · Contact: [contact@poli0981.dev](mailto:contact@poli0981.dev) · [other channels](https://poli0981.dev/links/)
> **Status: maintenance mode, since 1.6.0.** PipDock is complete for what it set out to do, and is kept correct, safe and current rather than extended: dependency and security updates, major runtime upgrades, bug, UI/UX and accessibility fixes, and wording fixes in either language — no new features. [CONTRIBUTING.md](CONTRIBUTING.md#scope-in-maintenance-mode) says what is accepted. The repository moved from `poli0981/pipdock` to the **poli0981org** organization on 2026-11-21; the old address redirects.
---
@@ -50,40 +52,58 @@
| Area | What you get |
|---|---|
| Environments | Auto-discovery of venvs / uv venvs / system Pythons (PEP 514 + `py` launcher), manual add, PEP 668 guard |
| Environments | Auto-discovery of installed Pythons — the Windows registry (PEP 514), the `py` launcher and the Pythons `uv python list` reports — plus a `.venv`, `venv`, `env` or `.env` folder in the folder PipDock was started from. **Add interpreter…** puts any other Python or virtual environment on the list (`pipdock env add` in the CLI), and *Remove from list* takes it off |
| PEP 668 guard | Pythons marked externally managed are refused by default. An override in Settings, off by default, asks before it turns on, and while it applies every screen that can change that Python says so |
| Installed | Full package list per env; up-to-date packages dimmed, outdated badged |
| Updates | Bulk update with group dry-run resolve, held-back explanations, 3-way conflict choices |
| Updates | Bulk update with group dry-run resolve, held-back explanations, 3-way conflict choices. The preview names every package *Force latest* would break, anything left out because it needs a different Python, and withdrawn (yanked) releases |
| Search & Install | Instant fuzzy search over a locally cached PyPI name index (PEP 691), metadata on demand, install queue |
| Uninstall | Bulk uninstall with reverse-dependency warnings |
| Pins | Exclude packages from bulk updates, with a reason. The Pins screen suggests packages a lot of your others depend on, and the threshold is configurable |
| Dependencies | For any package on the Installed list: what requires it and what it requires, with the version constraint on each, how many packages removing it would leave broken, and any requirement nothing installed satisfies |
| Pins | Keep packages out of every update until you unpin them, with a reason. The Pins screen suggests packages a lot of your others depend on, and the threshold is configurable |
| Snapshots | Automatic pre-batch snapshots, diff view, one-click rollback |
| Engine | pip **or** uv, selectable in Settings (uv auto-detected on first run) |
| Engine | pip **or** uv, chosen in Settings, which shows each one's version for the selected environment (or *not found*). pip is the default; uv has to be on your `PATH` |
| Code Health | deptry + vulture + ruff against a project folder — unused deps, dead code, style — run from PipDock's own isolated tools env |
| Security | pip-audit against an environment's packages: each known advisory with the versions that fix it (or *no fix*), its CVE aliases and a link to its OSV entry, run from PipDock's own isolated audit environment |
| pip upkeep | Check & update pip itself per environment |
| CLI | `pipdock` — full parity for core operations, JSON output, CI-friendly exit codes |
| Requirements | Export an environment as `requirements.txt`; import one and preview what it would install, with every line it will not use reported by number |
| Disk usage | See and clear what PipDock has written — snapshots and the Code Health tools environment |
| Keyboard | `Ctrl+K` command palette, `Ctrl+1`–`Ctrl+9` tabs, full keyboard traversal |
| i18n | English + Tiếng Việt |
| Privacy | No telemetry. **PyPI is the only host PipDock connects to.** It does not check for updates, so it never calls home — GitHub and the ruff docs are only ever handed to your browser as a link you clicked |
| Disk usage | Everything PipDock writes is under `%LOCALAPPDATA%\PipDock\data\`. Settings shows it and clears the parts that are safe to clear — snapshots (`snapshots\`), the Code Health tools environment (`tools\`) and the Security tab's audit environment (`audit\`). `index.db` (package index, settings, pins, the interpreters you added, your acceptance of the legal documents) is shown but never cleared; the logs (`logs\`) are deleted automatically after 14 days |
| Logs | PipDock keeps its own log, one file per day in `data\logs\`, and never sends it anywhere. It records the commands PipDock ran, so it holds package names and file paths. Settings shows the folder and copies the recent lines for a bug report |
| Keyboard | `Ctrl+K` command palette, `Ctrl+1`–`Ctrl+9` tabs (by key position, so AZERTY and other layouts work too), `/` for Search, full keyboard traversal |
| i18n | English + Tiếng Việt, remembered across restarts |
| Privacy | No telemetry. **PyPI is the only host PipDock connects to.** It does not check for updates, so it never calls home — GitHub, the ruff docs, OSV's advisory pages and the author's links page are only ever handed to your browser as a link you clicked |
## Install
Download the installer (NSIS `.exe` or `.msi`) from [GitHub Releases](https://github.com/poli0981/pipdock/releases).
Download the installer (NSIS `.exe` or `.msi`) from [GitHub Releases](https://github.com/poli0981org/pipdock/releases).
PipDock does not update itself — grab a new build from the same page when you want one. That is deliberate: a self-updater is a standing remote-code-execution path into a tool that already runs subprocesses against your interpreters, and it is not worth the convenience (see [docs/SECURITY.md](docs/SECURITY.md) §5).
> Windows SmartScreen may warn on first run because the binaries are not EV-code-signed. Every release publishes `SHA256SUMS.txt`; verify your download against it before running:
> Windows SmartScreen may warn on first run because the binaries are not EV-code-signed. Every release publishes `SHA256SUMS.txt`; verify your download against it before running (replace `<version>` with the version in the file name you downloaded):
>
> ```powershell
> (Get-FileHash .\PipDock_1.0.0_x64-setup.exe -Algorithm SHA256).Hash.ToLower()
> (Get-FileHash .\PipDock_<version>_x64-setup.exe -Algorithm SHA256).Hash.ToLower()
> ```
>
> Compare that against the matching line in `SHA256SUMS.txt`. If they differ, do not run the file.
>
> From 1.4.0 the `.exe` and `.msi` also carry a build-provenance attestation. A checksum published beside a file cannot prove where the file came from — whoever could replace one could replace both — but the attestation proves the installer was built by this repository's release workflow. With the [GitHub CLI](https://cli.github.com/):
>
> ```powershell
> gh attestation verify .\PipDock_<version>_x64-setup.exe --repo poli0981org/pipdock
> ```
>
> That is for 1.6.0 and later. **1.4.0 and 1.5.0 were built before the repository moved to the poli0981org organization** (2026-11-21), and their attestations stayed with the account that made them, so `--repo` finds none for them. Verify those against that account and the repository's old name instead:
>
> ```powershell
> gh attestation verify .\PipDock_1.5.0_x64-setup.exe --owner poli0981 --signer-repo poli0981/pipdock
> ```
>
> Either succeeds only when GitHub holds an attestation from this repository's release workflow for that exact file. If it fails, do not run the file.
## Quick start
**GUI:** launch PipDock → accept the first-run legal gate → pick an environment (auto-discovered or *Browse…*) → the *Updates* tab shows what's outdated → *Select all* → *Update* → review the preview → *Confirm*. Four clicks.
**GUI:** launch PipDock → accept the first-run legal gate → pick an environment from the discovered list (the first usable one is already selected; *Use* picks another) → the *Updates* tab shows what's outdated → *Select all* → *Update* → review the preview → *Confirm*. Four clicks.
**CLI:** the installer puts `pipdock.exe` next to the GUI, in `%LOCALAPPDATA%\PipDock\`.
**PipDock does not edit your `PATH`**; add that folder yourself if you want to type `pipdock`
@@ -103,10 +123,10 @@ pipdock snapshot rollback latest
## Documentation
**Using PipDock?** The [wiki](https://github.com/poli0981/pipdock/wiki) is the user-facing set —
[Getting Started](https://github.com/poli0981/pipdock/wiki/Getting-Started),
[Troubleshooting](https://github.com/poli0981/pipdock/wiki/Troubleshooting) and an
[FAQ](https://github.com/poli0981/pipdock/wiki/FAQ) that explains the design decisions rather than
**Using PipDock?** The [wiki](https://github.com/poli0981org/pipdock/wiki) is the user-facing set —
[Getting Started](https://github.com/poli0981org/pipdock/wiki/Getting-Started),
[Troubleshooting](https://github.com/poli0981org/pipdock/wiki/Troubleshooting) and an
[FAQ](https://github.com/poli0981org/pipdock/wiki/FAQ) that explains the design decisions rather than
just stating them. Everything below is for reading the code.
| Doc | Purpose |
@@ -122,14 +142,27 @@ just stating them. Everything below is for reading the code.
| [docs/ERROR-CATALOG.md](docs/ERROR-CATALOG.md) | Error codes, stderr detection patterns, user guidance |
| [docs/SECURITY.md](docs/SECURITY.md) | Threat model, PEP 668 policy, supply-chain hygiene |
| [docs/TESTING.md](docs/TESTING.md) | Test strategy incl. disposable-venv integration tests |
| [docs/RELEASE-CI.md](docs/RELEASE-CI.md) | CI callers into `poli0981/.github`, release pipeline |
| [docs/RELEASE-CI.md](docs/RELEASE-CI.md) | Workflows, branch protection, Dependabot, release pipeline |
| [docs/I18N.md](docs/I18N.md) | EN/VI localization rules |
| [docs/ROADMAP.md](docs/ROADMAP.md) | Spike week, milestones, exit criteria |
| [ACCESSIBILITY.md](ACCESSIBILITY.md) | What is supported, what has been tested, what is known not to work, and how to report a barrier |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Setting up, the checks CI runs, and what a pull request needs |
| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Contributor Covenant 2.1 |
| [legal/](legal/) | EULA, Disclaimer, Privacy Policy, Third-Party Notices (linked by the in-app legal gate) |
## Accessibility
PipDock is built to work with a keyboard alone, with a screen reader and under a Windows contrast theme, and `pipdock` on the command line is plain text with no colour and nothing that animates. The target is WCAG 2.2 AA; it is a target and not a conformance claim, and [ACCESSIBILITY.md](ACCESSIBILITY.md) says exactly what has been tested, by whom, and what is known to fall short.
If something gets in your way, [open an accessibility issue](https://github.com/poli0981org/pipdock/issues/new?template=accessibility.yml) or write to [accessibility@poli0981.dev](mailto:accessibility@poli0981.dev) — in English or Vietnamese, with no GitHub account needed and no diagnosis expected.
## Contributing
Bug reports, accessibility reports and pull requests are welcome. [CONTRIBUTING.md](CONTRIBUTING.md) covers setup, the checks, and the handful of rules that are not negotiable; everyone taking part is expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md). Security problems go through the [security policy](.github/SECURITY.md), not a public issue.
## How this was built
PipDock was written with substantial help from an AI coding assistant — **Claude Opus 5**, made by [Anthropic](https://www.anthropic.com), through [Claude Code](https://claude.com/claude-code) — under human review. It wrote source code, tests, debugging work and the Vietnamese translation. Every change reached `main` through a pull request the maintainer read and merged, `main` is protected and cannot be bypassed, and the built application was driven by hand on three machines before 1.0.0 shipped.
PipDock was written with substantial help from an AI coding assistant — **Claude Opus 5** through 1.3.0, **Claude Opus 5.5** for 1.4.0 and **Claude Fable 5.2** for 1.5.0, made by [Anthropic](https://www.anthropic.com), through [Claude Code](https://claude.com/claude-code) — under human review. It wrote source code, tests, debugging work and the Vietnamese translation. Every change reached `main` through a pull request, and `main` is protected and cannot be bypassed. Through 1.3.0 the maintainer read and merged each one, and drove the built application by hand on three machines before 1.0.0 shipped; 1.4.0 and 1.5.0 were released by the assistant on the maintainer's written instruction — a plan the maintainer approved — once the checks had passed.
That review mattered: **thirty-five defects** reached or nearly reached `main`, and not one was caught by the test suite that was green at the time. They were found by running the thing.
@@ -146,3 +179,7 @@ PipDock is an independent project. It is not affiliated with or endorsed by the
## Tiếng Việt (tóm tắt)
PipDock là ứng dụng Windows (GUI + CLI) giúp kiểm tra, cài đặt, cập nhật và gỡ **hàng loạt** gói thư viện Python một cách an toàn: luôn chạy dry-run xem trước thay đổi, xử lý xung đột phiên bản với 3 lựa chọn rõ ràng, tự chụp snapshot trước mỗi lần chạy để rollback một chạm, cảnh báo khi gỡ gói mà gói khác đang phụ thuộc, và tổng kết "13 thành công, 2 thất bại" kèm lý do từng gói. Hỗ trợ engine pip hoặc uv (chọn trong Settings), tìm gói tức thì nhờ cache chỉ mục PyPI, kèm module Code Health (deptry/vulture/ruff) để dọn dependency thừa và dead code. Không thu thập dữ liệu. Giấy phép GPL-3.0.
**Trạng thái: giai đoạn bảo trì, từ bản 1.6.0.** PipDock đã làm đủ những gì nó đặt ra, và từ nay được giữ cho đúng, an toàn và cập nhật chứ không mở rộng thêm: cập nhật phụ thuộc định kỳ, sửa lỗi bảo mật (CVE mức High trở lên hoặc lỗi nghiêm trọng của runtime), nâng cấp lớn ngôn ngữ/runtime/framework, sửa lỗi, lỗi UI/UX và rào cản tiếp cận, sửa câu chữ hoặc bản dịch dễ gây hiểu nhầm — **không nhận tính năng mới**; issue hay PR đề xuất tính năng sẽ tự động được gắn nhãn và đóng. Repo đã chuyển từ `poli0981/pipdock` sang tổ chức **poli0981org** ngày 2026-11-21; địa chỉ cũ vẫn tự chuyển hướng. Chi tiết trong [CONTRIBUTING.md](CONTRIBUTING.md#scope-in-maintenance-mode).
**Khả năng tiếp cận:** PipDock dùng được chỉ với bàn phím, với trình đọc màn hình (đã thử với Narrator) và ở chế độ tương phản cao của Windows. Chi tiết, kể cả những gì chưa được kiểm thử, nằm trong [ACCESSIBILITY.md](ACCESSIBILITY.md). Nếu gặp rào cản, hãy [mở issue](https://github.com/poli0981org/pipdock/issues/new?template=accessibility.yml) hoặc viết tới [accessibility@poli0981.dev](mailto:accessibility@poli0981.dev) — tiếng Việt cũng được.
+273
View File
@@ -3,6 +3,279 @@
Newest first. See [`README.md`](README.md) for the conventions, and `docs/ROADMAP.md` for what each
slice cost and what it taught — that is a different document for a different reader.
## 1.6.0 — 2026-11-21
**Add any Python, and the move to maintenance mode.** PipDock can now manage a virtual environment
wherever it lives — the one core feature that was still missing — and with this release it moves
from being developed to being maintained. ([#119](https://github.com/poli0981org/pipdock/pull/119),
[#120](https://github.com/poli0981org/pipdock/pull/120))
### Added
- **Add interpreter…** on Environments — beside *Rescan*, in the empty screen, and in `Ctrl+K`.
Pick any `python.exe`, typically the one in a virtual environment's `Scripts` folder, and it is
added to the list, selected, and remembered across restarts. Until now the app only found a venv
named `.venv`, `venv`, `env` or `.env` in the folder it was started from, which for an installed
app is its own install folder — so most project environments were out of reach.
- **Remove from list** on every interpreter you added. It only forgets the entry; nothing on disk is
touched, and the environment's pins and snapshots are kept for when you add it again. An added
environment that has since been deleted stays listed with its error, so you can remove it.
- The same from the command line: `pipdock env add <path>` and `pipdock env remove <path>`, and
`pipdock env list` shows what you added after what it discovered.
### Changed
- **PipDock checks a path you give it before running anything.** An interpreter you pick, or pass
with `--env`, `env use` or `env add`, has to be a file named `python.exe` (or `python3.exe`,
`python3.12.exe`, the free-threaded `python3.14t.exe`), and cannot be one of PipDock's own tool
environments. Anything else is refused
with `PD-ENV-001`, whose message now reads "That interpreter is missing, or PipDock cannot run it."
An interpreter you added is checked again whenever the list is read, and a default set with
`env use` before 1.6.0 is checked when it is used — if it is refused, it is skipped with a
warning, as a deleted one already was.
- **A virtual environment made with `--symlinks` is its own environment.** Its pins, snapshots and
reports were filed under the Python it was made from, because its `python.exe` is a link to that
Python. They are kept apart now; any made before 1.6.0 stay with that Python.
- **The repository moved to `github.com/poli0981org/pipdock`.** The bug-report button, the legal
documents, About and the docs point there; the old address redirects.
- **The first-run screen asks once more.** The privacy policy now names the interpreter paths you
add (kept until you remove them) and the repository's new address, so the documents changed.
### Verifying a download
`gh attestation verify .\PipDock_1.6.0_x64-setup.exe --repo poli0981org/pipdock` verifies this
release and later ones. **The command in earlier READMEs no longer works for 1.4.0 and 1.5.0**: an
attestation stays with the account that made it, so verify those with
`--owner poli0981 --signer-repo poli0981/pipdock` instead.
### What maintenance mode means for you
- Bugs, UI/UX problems and accessibility barriers are what PipDock is now maintained for, along
with dependency and security updates, major runtime upgrades and wording fixes. There is a new
issue form for wrong or misleading text, in English or Vietnamese.
- **New features are not taken.** An issue or pull request asking for one is labelled and closed
automatically, with a link explaining why. `CONTRIBUTING.md` says what is accepted.
## 1.5.0 — 2026-11-10
**The accessibility release.** PipDock could already be driven from the keyboard and read by
Narrator from end to end — that was tested by hand on 1.4.0, and nothing blocked. This release fixes
the places where it worked but made you work for it, and writes down honestly what is and is not
supported. ([#107](https://github.com/poli0981/pipdock/pull/107))
### If you use the keyboard
- **Focus no longer disappears when the screen changes.** Starting an update, a run reaching its
summary, opening a package's dependencies or opening an environment each replaced the screen and
left focus on nothing, so the next `Tab` started again from the top of the window. Focus now
lands on the new screen's heading. Closing the console drawer returns it to the button that
opened the drawer.
- **Code Health's tabs are one tab stop**, moved through with `←` `→` `Home` `End`. They were three.
- **A version conflict's three choices are one tab stop**, moved through with the arrow keys.
Nothing is chosen until you press `Space` or `Enter` — an arrow key will never open *Force
latest*'s confirmation.
- **The command palette scrolls with its selection.** Past the ninth action the highlight used to
leave the visible list.
- **A button you have just pressed keeps focus while it works.** *Use*, *Rescan*, *Run*, *Run
audit*, *Add*, *Download the index* and *Stop* used to drop it the moment they went busy.
- **The focus ring on a package row is complete.** Three of its four sides were being cut off.
- The first-run screen puts focus on its heading rather than nowhere, and accepting it puts focus
on the first screen.
### If you use a screen reader
- **Dialogs say what they are asking.** A confirmation used to be announced by the package name
alone — "numpy, dialog", then "Cancel". It is now named by its heading and described by its text.
- **Search tells you what it is doing**: that it is searching, how many results came back, and when
nothing matched. Which result's details are showing is announced, not only coloured.
- **Code Health's tabs are named for what you see** — `deptry 3`, followed by what the tool checks —
so "click deptry" works with voice control too.
- **A pin's lock chip says what it means.** A held pin used to read as a bare version number; the
explanation was a mouse-only tooltip.
- **The package table is a well-formed grid**: every column has a header, the checkbox is in a cell,
and the table says more than one row can be selected.
- The console drawer's close button is called *Close console*. It was called *Cancel*, next to a
*Stop* button that cancels the run.
- Each sidebar tab exposes its `Ctrl+1`…`Ctrl+9` shortcut.
### If you use a Windows contrast theme
- **Every destructive button is marked, with a double border.** High contrast removes the red,
and a button that removes, forces or rewrites was then drawn exactly like the *Cancel* beside
it. A border was meant to mark them and, it turns out, had never actually been drawn.
- **The current sidebar tab is outlined.** It was indistinguishable from the rest.
### For everyone
- The sidebar's shortcut hints (`^1`…`^9`) are no longer drawn at half strength.
- The link to vulture's whitelist is underlined all the time, not only under the mouse.
- The remove button in Search's install list is large enough to hit.
### Added
- **[ACCESSIBILITY.md](../ACCESSIBILITY.md)** — what is supported, exactly what has been tested and
by whom, what has *not* been tested, the known limitations, and how to report a barrier. The
target is WCAG 2.2 AA; it is a target, not a claim of conformance.
- **An Accessibility section in About**, with a button that opens the statement and a new address,
`accessibility@poli0981.dev`, for anyone who would rather not use GitHub.
- **An accessibility issue form** that asks what got in your way, not what caused it.
- [CONTRIBUTING.md](../CONTRIBUTING.md) and a [Code of Conduct](../CODE_OF_CONDUCT.md), for anyone
who wants to help.
### Worth knowing
- **There is no zoom yet.** It was built for this release and held back, because at 200 % in the
default window the package names disappeared. The Windows display scale works as before.
- **Narrator has not been run again on this release.** The changes above were checked in the
running application against what it exposes to assistive technology, and by automated tests —
not by listening. If something sounds wrong, that is exactly the report the new address is for.
- The legal documents did not change, so the first-run screen does not reappear.
- Also in this build since 1.4.0: pip 26.3's new wording for an unloadable build backend is
recognised (it was reported under a neighbouring error code, with the same advice), and
dependencies are current.
### Verifying a download
As for 1.4.0: check the installer against `SHA256SUMS.txt`, or run
`gh attestation verify <file> --repo poli0981/pipdock`.
## 1.4.0 — 2026-10-17
**No new feature: everything PipDock already did, made to do what it said.** A review of the whole
codebase found about 170 problems, and this release fixes every serious one. Several were in the
part that matters most — checking a change before it happens — so if you skip release notes as a
rule, read the first section.
### Fixed — the safety checks
- **A preview that is out of date is refused.** A plan confirmed more than ten minutes after it was
made, or for an environment something else changed in the meantime, is refused before anything
is written (`PD-RES-002`). This check existed and never ran.
- **A version your Python cannot run is never planned.** PipDock now checks every release's
`Requires-Python` itself, for pip and for uv alike. A package that cannot be updated for that
reason is listed under *Left out — needs a different Python*, with the range it needs and the
Python you have, instead of pip's misleading "not found" — or uv quietly planning it anyway.
- **Force latest forces.** It used to change nothing. It now installs the newest release, and the
preview has a **Will break** section naming each package that will stop working and the
requirement of its that is being overridden; the Confirm button counts them.
- **Restoring a snapshot with the other engine no longer removes pip.**
- **`ruff --fix` only changes the files the report showed you.** It used to fix everything it could
reach, including files inside `.venv` and notebooks the report had excluded.
- **A failed build is a failure.** With uv, a package whose build failed showed as "nothing to
change".
- **Stop, a timeout or a network outage mid-install** now ends with a summary of what happened and
the snapshot to restore from, instead of an internal error and nothing else.
- **After a run, a check that could not run says so**, instead of showing nothing — which read as
everything being fine.
### Fixed — everything else
- PipDock **crashed on any environment inside a folder with accented characters in its name** —
every Vietnamese-named folder, for one. It no longer does.
- Interpreters installed under a path with a **space** in it are found.
- Requirements that only apply on another platform (`pexpect; sys_platform != "win32"`) are no
longer reported as missing.
- **The PEP 668 setting now does what it says.** It was a checkbox nothing read. Turning it on asks
you first; while it is on, a red *PEP 668 override* chip shows on every screen where it applies,
and only there.
- **Decline on the first-run screen closes PipDock.** It did nothing.
- **The language you choose is kept** after a restart.
- **The window can be maximized and snapped**, and opens at a size that fits your screen — on a
laptop it used to open with the status line under the taskbar. The content stops widening at a
readable width.
- **Switching environment quickly no longer shows the previous one's data** — package lists,
update badges, snapshot diffs, the dependency view and pin suggestions could all land on the wrong
environment.
- A run that failed to start could leave PipDock refusing every other change ("another change is in
progress") until restart.
- **Back** while a preview is still being worked out now stops the engine, rather than leaving it
running.
- The **Security** tab scrolls.
- Typing `/` puts the cursor in Search from any screen — including Search itself, where it did nothing.
- `Ctrl+1`…`Ctrl+9` work on keyboard layouts where the digits need Shift, such as French.
- F5, Ctrl+R, Ctrl+P and Ctrl+F no longer reload, print or search the app as if it were a web page.
- The package table's headings line up with their columns, and names stay visible at the smallest
window size.
- Text on red badges is easier to read.
- A file PipDock cannot write — read-only, or open in another program — is reported as that, not as
a full disk.
- *Report bug* includes your Python and engine versions, and still opens when the log is full of
accented paths.
- Withdrawn ("yanked") releases in a plan are listed in the preview. They were detected and then
never shown.
- Dialogs open in the middle of the window. They opened in its top-left corner.
- On a fresh install, Search offers to download the package index instead of saying it is
"preparing" indefinitely.
### Added
- **PipDock keeps a log** — one file a day in `%LOCALAPPDATA%\PipDock\data\logs\`, kept for 14
days. **Settings → Logs** shows where, and copies the recent part for a bug report. The privacy
policy has described this log since 1.0; now it exists. Nothing in it is sent anywhere.
- If PipDock cannot open its data folder, it **says so in a dialog**, with the log's location,
instead of not starting.
- **Settings shows each engine's version** for the selected environment, and *not found* when one
is missing.
- The plan panel names the environment it is about to change.
### Changed for scripts (`pipdock` CLI)
- **`--json` prints exactly one JSON document** per command, on stdout. Prompts, warnings and
progress go to stderr. Scripts that read several documents, or skipped a leading line, need
updating — `docs/CLI-SPEC.md` §6 lists every command's document.
- **`pipdock env use` is honoured.** The environment is `--env` if given, then the one `env use`
chose, then a `.venv` in the current folder. Before, `env use` was saved and ignored.
- **Ctrl-C stops a run**: the engine is stopped, what completed is printed with the snapshot to
restore from, and the exit code is 130.
- `--verbose` and `--log-file` work. On an internal error, the log's path is printed.
- `pipdock update` with no package and no `--all` is a usage error (exit 2) rather than a silent
no-op. `pipdock audit` follows `--engine`; `pipdock doctor` no longer requires pip when uv is the
configured engine.
### You will see this once
**The first-run legal screen appears again.** The privacy policy now describes the log and the tool
environments PipDock keeps, and the third-party notices name osv.dev; PipDock also stopped
computing the documents' version differently depending on how the files were checked out. Your
acceptance is recorded against that version, so it asks once more. Nothing else resets.
### Verifying a download
Each installer now carries a **build attestation** as well as its checksum:
`gh attestation verify <installer> --repo poli0981/pipdock` proves it was built by this
repository's release workflow from the tagged commit. `SHA256SUMS.txt` is also readable by
`sha256sum -c` on any system now.
## 1.3.0 — 2026-08-20
The **dependency view** — what depends on a package, what it depends on, and what a removal would
cost.
### Added
- **Dependencies**, from any package row: the `⇄` button beside pin and remove. The package sits
between two columns — everything that requires it and everything it requires — and every row
carries the version specifier written on that edge, so you can see *why* something is held where
it is rather than only *that* it is. Click any neighbour to move the view onto it.
- **The two numbers underneath**: how many packages a removal would leave with a missing
dependency, counted all the way through rather than one hop, and how many packages this one
pulls in itself. This is the part the package list could never tell you.
- **Requirements nothing satisfies.** If something in the environment declares a dependency that
is not installed, the view says so. Nothing else in PipDock reports this, and it only counts
requirements that actually apply to your Python — a backport gated on 3.9 is not a hole.
- The environment's dependencies are read **once** when you open the view, so moving from package
to package is instant.
### Changed
- **Package rows now have three buttons instead of two.** Removing a package is still three
clicks; the new one does not sit in front of it.
- **There is no node-link diagram, and there was never going to be a useful one.** Drawn as a
picture, a real environment is unreadable: on a 352-package install the average package has 172
others within two steps, and more than 200 of them exceed 60. So the view shows one step at a
time and lets you walk it, and answers the "everything downstream" question with a number
instead. No new third-party code was added to the application for this.
## 1.2.0 — 2026-08-18
The **Security tab**, which the sidebar has shown greyed out since M2.
+7 -5
View File
@@ -5,6 +5,7 @@ version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
publish.workspace = true
repository.workspace = true
authors.workspace = true
@@ -16,11 +17,12 @@ path = "src/main.rs"
workspace = true
[dependencies]
clap = { version = "4.6.4", features = ["derive"] }
jiff = "0.2.35"
clap = { version = "4.6.7", features = ["derive"] }
jiff = "0.2.38"
pipdock-core = { path = "../pipdock-core" }
serde_json = "1.0.151"
tokio = { version = "1.53.1", features = ["rt-multi-thread", "macros"] }
serde = "1.0.229"
serde_json = "1.0.154"
tokio = { version = "1.53.3", features = ["rt-multi-thread", "macros", "signal"] }
tracing = "0.1.44"
tracing-subscriber = { version = "0.3.23", features = ["env-filter"] }
@@ -28,4 +30,4 @@ tracing-subscriber = { version = "0.3.23", features = ["env-filter"] }
assert_cmd = "2.2.2"
# `filters` gives `Settings::add_filter`, used to keep the crate version out of the help
# snapshots so a release bump does not churn every golden in tests/golden.rs.
insta = { version = "1.48.0", features = ["filters"] }
insta = { version = "1.49.0", features = ["filters"] }
+80
View File
@@ -0,0 +1,80 @@
//! The CLI's subscriber: which log lines go where.
//!
//! - **Always** the daily file, `data\logs\pipdock-cli.<date>.log`, at `PIPDOCK_LOG` or INFO.
//! - `--verbose` adds **stderr**, at DEBUG — every engine line as it was printed.
//! - `--log-file <path>` adds a copy of the file's lines there, for a CI job's artefacts.
//!
//! **Never stdout**, which is the CLI's contract (CLI-SPEC §6): a script reading `--json` gets a
//! document and nothing else, verbose or not. `--quiet` adds nothing, and turns nothing off that
//! is not already off — the file is for after the fact, not for the terminal.
//!
//! Both flags were parsed and ignored before 1.4.0.
use std::path::PathBuf;
use pipdock_core::logging::{self, DailyFile};
use tracing_subscriber::layer::SubscriberExt as _;
use tracing_subscriber::util::SubscriberInitExt as _;
use tracing_subscriber::{EnvFilter, Layer as _, fmt};
use crate::GlobalOpts;
/// Set up logging for one invocation. Returns today's log file, for the line an internal error
/// prints (CLI-SPEC §5: exit 10 says where the log is).
pub fn init(opts: &GlobalOpts) -> PathBuf {
let dir = logging::log_dir(&pipdock_core::store::default_app_data());
// The first reader `LOG_RETENTION_DAYS` has had since it was written.
logging::sweep(
&dir,
pipdock_core::LOG_RETENTION_DAYS,
jiff::Timestamp::now(),
);
let file = DailyFile::new(&dir, "pipdock-cli");
let path = file.current_path();
let level =
|| EnvFilter::try_from_env("PIPDOCK_LOG").unwrap_or_else(|_| EnvFilter::new("info"));
let to_file = fmt::layer()
.with_ansi(false)
.with_writer(move || file.clone())
.with_filter(level());
let to_stderr = opts.verbose.then(|| {
fmt::layer()
.with_ansi(false)
.with_writer(std::io::stderr)
.with_filter(EnvFilter::new("debug"))
});
let to_copy = opts
.log_file
.as_ref()
.and_then(|p| {
std::fs::OpenOptions::new()
.create(true)
.append(true)
.open(p)
.map_err(|e| eprintln!("warning: --log-file {}: {e}", p.display()))
.ok()
})
.map(|f| {
fmt::layer()
.with_ansi(false)
.with_writer(std::sync::Mutex::new(f))
.with_filter(level())
});
// A second init (a test harness, say) keeps the first; logging is never worth failing over.
let _ = tracing_subscriber::registry()
.with(to_file)
.with(to_stderr)
.with(to_copy)
.try_init();
logging::install_panic_hook();
tracing::info!(
target: "pipdock::cli",
version = env!("CARGO_PKG_VERSION"),
args = ?std::env::args().skip(1).collect::<Vec<_>>(),
"start"
);
path
}
+36 -11
View File
@@ -90,7 +90,7 @@ impl ToolArg {
/// Options accepted by every command (CLI-SPEC §2).
#[derive(Debug, Args)]
pub struct GlobalOpts {
/// Interpreter or environment directory. Defaults to the last used env, else an
/// Interpreter or environment directory. Defaults to the one `env use` set, else an
/// auto-detected `.venv` in the working directory.
#[arg(long, global = true, value_name = "PATH")]
pub env: Option<PathBuf>,
@@ -99,23 +99,27 @@ pub struct GlobalOpts {
#[arg(long, global = true, value_enum)]
pub engine: Option<EngineArg>,
/// Machine-readable output; NDJSON for streaming commands.
/// Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
///
/// Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming
/// commands" until 1.4.0, when several commands printed several documents.
#[arg(long, global = true)]
pub json: bool,
/// Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*.
/// Assume the default at every prompt: a held-back package keeps its compatible version and
/// an impossible one is skipped. Only `--strategy latest` forces.
#[arg(long, short = 'y', global = true)]
pub yes: bool,
/// Reduce log output.
/// Do not stream engine output to stderr. (The log file is written regardless.)
#[arg(long, global = true, conflicts_with = "verbose")]
pub quiet: bool,
/// Increase log output.
/// Also write the log to stderr, at debug level.
#[arg(long, global = true)]
pub verbose: bool,
/// Tee logs to a file.
/// Also write the log to this file. The daily log in `data\logs\` is always kept.
#[arg(long, global = true, value_name = "PATH")]
pub log_file: Option<PathBuf>,
@@ -174,7 +178,7 @@ enum Command {
/// Install packages.
Install {
/// `name` or `name==version`.
/// A name with an optional PEP 440 specifier: `six`, `six==1.16.0`, `"six>=1.16,<2"`.
#[arg(required = true)]
specs: Vec<String>,
/// Print the resolution report and exit without changing anything.
@@ -246,7 +250,7 @@ enum Command {
/// Show or set the configured engine.
Engine {
/// Engine to switch to; omit to print the current one.
/// Engine to switch to; omit to list both, with versions, marking the configured one.
engine: Option<EngineArg>,
},
@@ -271,13 +275,23 @@ enum Command {
#[derive(Debug, Subcommand)]
enum EnvCommand {
/// List discovered environments, their sources and PEP 668 flags.
/// List discovered environments and the ones added with `env add`, their sources and PEP 668 flags.
List,
/// Set the default environment.
Use {
/// Interpreter or environment directory.
path: PathBuf,
},
/// Add an interpreter discovery does not find to the list (the GUI's Add interpreter…).
Add {
/// Interpreter or environment directory.
path: PathBuf,
},
/// Take an interpreter added with `env add` off the list. Nothing on disk is touched.
Remove {
/// Interpreter or environment directory, as it was added.
path: PathBuf,
},
}
#[derive(Debug, Subcommand)]
@@ -344,11 +358,13 @@ enum SelfCommand {
ReportBug,
}
mod log;
mod run;
#[tokio::main]
async fn main() -> ExitCode {
let cli = Cli::parse();
let log_path = log::init(&cli.global);
let result = match &cli.command {
Command::Env(EnvCommand::List) => run::env_list(&cli.global).await,
@@ -389,6 +405,8 @@ async fn main() -> ExitCode {
}
Command::Schema { type_name } => run::schema(type_name),
Command::Env(EnvCommand::Use { path }) => run::env_use(&cli.global, path).await,
Command::Env(EnvCommand::Add { path }) => run::env_add(&cli.global, path).await,
Command::Env(EnvCommand::Remove { path }) => run::env_remove(&cli.global, path),
Command::Audit => run::audit(&cli.global).await,
Command::PipUpgrade => run::pip_upgrade(&cli.global).await,
Command::Snapshot(SnapshotCommand::Rollback { id }) => {
@@ -422,6 +440,8 @@ async fn main() -> ExitCode {
match result {
Ok(exit) => exit.into(),
Err(e) => {
tracing::error!(target: "pipdock::cli", code = %e.code, error = %e.message, "failed");
let exit = run::exit_for(e.code);
// ERROR-CATALOG §3: `error[PD-XXX-NNN]: <one-liner>` on stderr, or the JSON envelope.
if cli.global.json {
println!(
@@ -438,7 +458,12 @@ async fn main() -> ExitCode {
eprintln!("{tail}");
}
}
run::exit_for(e.code).into()
// CLI-SPEC §5: an internal error says where the log is. On stderr in both modes, so
// `--json`'s stdout stays the one envelope.
if exit == Exit::Internal {
eprintln!("log: {}", log_path.display());
}
exit.into()
}
}
}
@@ -494,7 +519,7 @@ mod tests {
"--yes",
"--json",
"--log-file",
r"C:\logs\pd.json",
r"C:\logs\pd.log",
])
.expect("nightly maintenance example");
File diff suppressed because it is too large. Load diff
+40
View File
@@ -46,6 +46,7 @@ const SCHEMA_TYPES: &[&str] = &[
"CacheUsage",
"CacheTarget",
"GuardReport",
"DepsGraph",
"Diff",
"SnapshotMeta",
"EngineInfo",
@@ -63,12 +64,20 @@ const SCHEMA_TYPES: &[&str] = &[
"HealthReport",
"AuditReport",
"FixReport",
"LogTail",
];
fn pipdock() -> Command {
let mut cmd = Command::cargo_bin("pipdock").expect("the `pipdock` binary builds");
// Colour and width leak the terminal into the snapshot; pin both.
cmd.env("NO_COLOR", "1").env("COLUMNS", "100");
// Every invocation writes its log under the app-data root, and a test run's belongs in a
// scratch directory rather than in the developer's own profile. Settings and the store move
// with it, which is the isolation a contract test wants anyway.
cmd.env(
"LOCALAPPDATA",
std::env::temp_dir().join(format!("pd-golden-{}", std::process::id())),
);
cmd
}
@@ -145,6 +154,8 @@ fn subcommand_help_is_stable() {
for (parent, child) in [
("env", "list"),
("env", "use"),
("env", "add"),
("env", "remove"),
("pin", "add"),
("pin", "remove"),
("pin", "list"),
@@ -235,6 +246,35 @@ fn the_human_error_line_carries_its_code() {
);
}
#[test]
fn a_logged_failure_names_its_message() {
// `message = %e.message` beside a format string records two fields called `message`, and the
// text formatter prints that field without its name — so the line read `failed
// code=PD-ENV-001 no interpreter at …`, the error's own words indistinguishable from the
// event's (SonarQube rust:S6677). `error=`, as every other failure in the codebase logs it.
let copy = std::env::temp_dir().join(format!("pd-golden-log-{}.log", std::process::id()));
let _ = std::fs::remove_file(&copy);
let copy_arg = copy.to_string_lossy().into_owned();
code_of(&[
"--log-file",
&copy_arg,
"list",
"--env",
"C:/definitely/not/here",
]);
let log = std::fs::read_to_string(&copy).expect("--log-file wrote its copy");
let _ = std::fs::remove_file(&copy);
let line = log
.lines()
.find(|l| l.contains("PD-ENV-001"))
.unwrap_or_else(|| panic!("the failure was not logged:\n{log}"));
assert!(
line.contains("failed") && line.contains("error=no interpreter at"),
"the error's message must be a field of its own: {line}"
);
}
#[test]
fn an_unknown_schema_type_lists_the_known_ones() {
insta::assert_snapshot!("schema-unknown-type", stderr_of(&["schema", "NoSuchType"]));
+231
View File
@@ -0,0 +1,231 @@
//! `env add`, `env remove` and `env list` over the list the GUI's *Add interpreter…* shares (1.6.0).
//!
//! The paths that need no Python, which are the ones a refactor is likeliest to break unseen: a
//! file that is not an interpreter is refused before anything runs it and nothing is stored; an
//! added interpreter whose file has since gone is still listed — with `PD-ENV-001`, because that is
//! the row a person needs in order to remove it — and is removed by the path it was added under.
//! A stored entry, or a stored default, that is no longer a Python is checked again and never run.
//! The success path of `env add` probes a real interpreter, which `ci-integration.yml` has.
//!
//! Each test has an app-data root of its own: the store is a file, and tests run in parallel.
#![allow(clippy::unwrap_used, clippy::expect_used)]
use std::path::{Path, PathBuf};
use assert_cmd::Command;
use pipdock_core::store::Store;
fn scratch(tag: &str) -> PathBuf {
let dir = std::env::temp_dir().join(format!("pd-manual-{tag}-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
std::fs::create_dir_all(&dir).expect("create scratch dir");
dir
}
/// `%LOCALAPPDATA%\PipDock\data`, as the binary will compute it from `LOCALAPPDATA`.
fn app_data(local: &Path) -> PathBuf {
local
.join(pipdock_core::APP_DATA_DIR_NAME)
.join(pipdock_core::APP_DATA_SUBDIR)
}
fn pipdock(local: &Path) -> Command {
let mut cmd = Command::cargo_bin("pipdock").expect("the `pipdock` binary builds");
cmd.env("NO_COLOR", "1")
.env("COLUMNS", "100")
.env("LOCALAPPDATA", local);
cmd
}
fn manual_rows(local: &Path) -> Vec<serde_json::Value> {
let out = pipdock(local)
.args(["env", "list", "--json"])
.output()
.expect("runs");
assert!(out.status.success(), "env list exits 0");
let all: Vec<serde_json::Value> =
serde_json::from_slice(&out.stdout).expect("env list --json is one JSON document");
all.into_iter()
.filter(|row| row["source"] == "manual")
.collect()
}
#[test]
fn another_program_is_refused_before_it_runs_and_nothing_is_stored() {
let local = scratch("refused");
let other = local.join(if cfg!(windows) {
"notepad.exe"
} else {
"notepad"
});
std::fs::write(&other, "").expect("an empty file that is not Python");
let out = pipdock(&local)
.args(["env", "add"])
.arg(&other)
.output()
.expect("runs");
assert_eq!(
out.status.code(),
Some(3),
"PD-ENV-001 is an environment error"
);
let stderr = String::from_utf8_lossy(&out.stderr);
assert!(stderr.contains("error[PD-ENV-001]"), "{stderr}");
assert!(stderr.contains("is not a Python interpreter"), "{stderr}");
let store = Store::open(&app_data(&local)).expect("the store opens");
assert!(
store.manual_envs().expect("reads").is_empty(),
"a refused path is never listed"
);
}
#[test]
fn an_entry_whose_file_is_gone_is_listed_with_its_error_and_removed_by_its_path() {
let local = scratch("gone");
let gone = local
.join("deleted-venv")
.join("Scripts")
.join("python.exe");
{
let store = Store::open(&app_data(&local)).expect("the store opens");
store
.add_manual_env(
&pipdock_core::envs::env_hash(&gone),
&gone.display().to_string(),
"2026-11-21T00:00:00Z",
)
.expect("added, as a venv later deleted would have been");
}
let rows = manual_rows(&local);
assert_eq!(rows.len(), 1, "{rows:?}");
assert_eq!(rows[0]["interpreter"], gone.display().to_string());
assert_eq!(rows[0]["error"]["code"], "PD-ENV-001");
// By the environment directory, as a person would type it: the file cannot be canonicalized
// any more, so the stored path is what matches.
let venv = local.join("deleted-venv");
let out = pipdock(&local)
.args(["env", "remove"])
.arg(&venv)
.output()
.expect("runs");
assert!(out.status.success());
let stdout = String::from_utf8_lossy(&out.stdout);
assert!(stdout.contains("removed from the list"), "{stdout}");
assert!(manual_rows(&local).is_empty(), "gone from the listing");
// Removing it again is not an error: the list is right.
let out = pipdock(&local)
.args(["env", "remove", "--json"])
.arg(&gone)
.output()
.expect("runs");
assert!(out.status.success());
let doc: serde_json::Value = serde_json::from_slice(&out.stdout).expect("one JSON document");
assert_eq!(doc["removed"], false);
}
#[test]
fn an_entry_is_removed_by_a_relative_path_typed_where_it_lives() {
// `env add .venv` stores an absolute path; `env remove .venv`, typed in the same folder, has to
// reach it. Relative text never matched before the path was made absolute.
let local = scratch("relative");
let stored = local.join("rel-venv").join("Scripts").join("python.exe");
{
let store = Store::open(&app_data(&local)).expect("the store opens");
store
.add_manual_env(
&pipdock_core::envs::env_hash(&stored),
&stored.display().to_string(),
"2026-11-21T00:00:00Z",
)
.expect("added");
}
let out = pipdock(&local)
.current_dir(&local)
.args(["env", "remove", "rel-venv", "--json"])
.output()
.expect("runs");
assert!(out.status.success());
let doc: serde_json::Value = serde_json::from_slice(&out.stdout).expect("one JSON document");
assert_eq!(doc["removed"], true, "{doc}");
let store = Store::open(&app_data(&local)).expect("the store opens");
assert!(store.manual_envs().expect("reads").is_empty());
}
/// An empty file named like another program, which nothing should ever run.
fn not_python(local: &Path) -> PathBuf {
let other = local.join(if cfg!(windows) {
"notepad.exe"
} else {
"notepad"
});
std::fs::write(&other, "").expect("an empty file that is not Python");
other
}
#[test]
fn an_added_entry_that_is_no_longer_python_is_listed_with_its_error_and_never_run() {
// What the file was when it was added says nothing about what it is now: a `python.exe` that is
// a link can be pointed at another program. Written to the store directly, since no `env add`
// would accept it — which is the point: the listing is checked on its own account.
let local = scratch("relisted");
let other = not_python(&local);
{
let store = Store::open(&app_data(&local)).expect("the store opens");
store
.add_manual_env(
&pipdock_core::envs::env_hash(&other),
&other.display().to_string(),
"2026-11-21T00:00:00Z",
)
.expect("stored");
}
let rows = manual_rows(&local);
assert_eq!(
rows.len(),
1,
"still listed, so it can be removed: {rows:?}"
);
assert_eq!(rows[0]["error"]["code"], "PD-ENV-001");
let message = rows[0]["error"]["message"].as_str().unwrap_or_default();
assert!(message.contains("is not a Python interpreter"), "{message}");
}
#[test]
fn a_default_that_is_not_python_is_skipped_with_a_warning() {
// `env use` checked nothing before 1.6.0, so a stored default can name any file.
let local = scratch("default");
let other = not_python(&local);
{
let store = Store::open(&app_data(&local)).expect("the store opens");
store
.remember_env(
&pipdock_core::envs::env_hash(&other),
&other.display().to_string(),
"2026-11-21T00:00:00Z",
true,
)
.expect("stored");
}
let empty = local.join("no-venv-here");
std::fs::create_dir_all(&empty).expect("a folder with nothing to fall back to");
let out = pipdock(&local)
.current_dir(&empty)
.arg("list")
.output()
.expect("runs");
let stderr = String::from_utf8_lossy(&out.stderr);
assert_eq!(out.status.code(), Some(3), "{stderr}");
assert!(
stderr.contains("warning: the default environment is not used"),
"{stderr}"
);
assert!(stderr.contains("is not a Python interpreter"), "{stderr}");
assert!(stderr.contains("error[PD-ENV-001]"), "{stderr}");
}
@@ -8,7 +8,7 @@ Usage: pipdock audit [OPTIONS]
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
@@ -18,19 +18,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -8,7 +8,7 @@ Usage: pipdock doctor [OPTIONS]
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
@@ -18,19 +18,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -8,7 +8,7 @@ Usage: pipdock engine [OPTIONS] [ENGINE]
Arguments:
[ENGINE]
Engine to switch to; omit to print the current one
Engine to switch to; omit to list both, with versions, marking the configured one
Possible values:
- pip: `<python> -m pip`
@@ -16,22 +16,24 @@ Arguments:
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -0,0 +1,47 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[parent, child, \"--help\"])"
---
Add an interpreter discovery does not find to the list (the GUI's Add interpreter…)
Usage: pipdock env add [OPTIONS] <PATH>
Arguments:
<PATH>
Interpreter or environment directory
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--json
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Also write the log to stderr, at debug level
--log-file <PATH>
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to.
-h, --help
Print help (see a summary with '-h')
@@ -2,13 +2,13 @@
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[parent, child, \"--help\"])"
---
List discovered environments, their sources and PEP 668 flags
List discovered environments and the ones added with `env add`, their sources and PEP 668 flags
Usage: pipdock env list [OPTIONS]
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
@@ -18,19 +18,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -0,0 +1,47 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[parent, child, \"--help\"])"
---
Take an interpreter added with `env add` off the list. Nothing on disk is touched
Usage: pipdock env remove [OPTIONS] <PATH>
Arguments:
<PATH>
Interpreter or environment directory, as it was added
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--json
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Also write the log to stderr, at debug level
--log-file <PATH>
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to.
-h, --help
Print help (see a summary with '-h')
@@ -12,7 +12,7 @@ Arguments:
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
@@ -22,19 +22,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -7,13 +7,15 @@ Manage environments
Usage: pipdock env [OPTIONS] <COMMAND>
Commands:
list List discovered environments, their sources and PEP 668 flags
use Set the default environment
help Print this message or the help of the given subcommand(s)
list List discovered environments and the ones added with `env add`, their sources and PEP 668 flags
use Set the default environment
add Add an interpreter discovery does not find to the list (the GUI's Add interpreter…)
remove Take an interpreter added with `env add` off the list. Nothing on disk is touched
help Print this message or the help of the given subcommand(s)
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
@@ -23,19 +25,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -8,7 +8,7 @@ Usage: pipdock health [OPTIONS]
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--path <DIR>
Project folder; defaults to the folder remembered for this environment
@@ -32,19 +32,21 @@ Options:
Apply ruff's safe fixes. Prompts before writing
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -8,7 +8,7 @@ Usage: pipdock index refresh [OPTIONS]
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
@@ -18,19 +18,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -12,7 +12,7 @@ Commands:
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
@@ -22,19 +22,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -12,7 +12,7 @@ Arguments:
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
@@ -22,19 +22,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -8,14 +8,14 @@ Usage: pipdock install [OPTIONS] <SPECS>...
Arguments:
<SPECS>...
`name` or `name==version`
A name with an optional PEP 440 specifier: `six`, `six==[VERSION]`, `"six>=1.16,<2"`
Options:
--dry-run
Print the resolution report and exit without changing anything
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
@@ -25,19 +25,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -8,7 +8,7 @@ Usage: pipdock list [OPTIONS]
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--outdated
Show only packages with a newer release available
@@ -21,19 +21,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -12,7 +12,7 @@ Arguments:
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--reason <REASON>
Why it is pinned
@@ -25,19 +25,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -8,7 +8,7 @@ Usage: pipdock pin list [OPTIONS]
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
@@ -18,19 +18,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -12,7 +12,7 @@ Arguments:
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
@@ -22,19 +22,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -14,7 +14,7 @@ Commands:
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
@@ -24,19 +24,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -8,7 +8,7 @@ Usage: pipdock pip-upgrade [OPTIONS]
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
@@ -18,19 +18,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -12,7 +12,7 @@ Arguments:
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
@@ -22,19 +22,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -12,7 +12,7 @@ Arguments:
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--limit <LIMIT>
Maximum results
@@ -27,19 +27,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -8,7 +8,7 @@ Usage: pipdock self report-bug [OPTIONS]
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
@@ -18,19 +18,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -12,7 +12,7 @@ Commands:
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
@@ -22,19 +22,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -8,7 +8,7 @@ Usage: pipdock snapshot create [OPTIONS]
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
@@ -18,19 +18,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -12,7 +12,7 @@ Arguments:
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
@@ -22,19 +22,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -8,7 +8,7 @@ Usage: pipdock snapshot list [OPTIONS]
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
@@ -18,19 +18,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -12,7 +12,7 @@ Arguments:
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
@@ -22,19 +22,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -15,7 +15,7 @@ Commands:
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
@@ -25,19 +25,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -8,7 +8,7 @@ Usage: pipdock tools status [OPTIONS]
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
@@ -18,19 +18,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -8,7 +8,7 @@ Usage: pipdock tools sync [OPTIONS]
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--force
Re-install even when the pin set already matches
@@ -24,19 +24,21 @@ Options:
Build on this interpreter instead of the newest discovered one
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -13,7 +13,7 @@ Commands:
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
@@ -23,19 +23,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -12,7 +12,7 @@ Arguments:
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--force
Proceed even when the guard reports dependents that would break
@@ -25,19 +25,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -15,7 +15,7 @@ Options:
Update every outdated package (pins still apply)
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
@@ -37,22 +37,24 @@ Options:
Ad-hoc exclusions on top of the pin list
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
--dry-run
Print the resolution report and exit without changing anything
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -30,7 +30,7 @@ Commands:
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
@@ -40,19 +40,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -88,6 +88,11 @@ expression: out
"description": "uv emitted a shape the adapter does not recognize (uv newer than PipDock).",
"type": "string"
},
{
"const": "PD-ENG-004",
"description": "An engine command ran past its watchdog and was stopped.\n\n**Raised by PipDock, never classified from stderr.** Its own code because the alternative\nwas `PD-INT-001`, which is what the shared watchdog reported until 1.4.0: an sdist build\nstill compiling after ten minutes is not \"a PipDock bug\", and in the batch phase that error\naborted the whole run — no summary, no per-package retry.",
"type": "string"
},
{
"const": "PD-ENG-999",
"description": "Fallback for engine failures no classifier matched. Always last.",
@@ -22,6 +22,186 @@ expression: out
],
"type": "object"
},
"Code": {
"description": "Every code PipDock can surface at v1 launch.\n\n`docs/TESTING.md` §2 requires at least one captured stderr fixture per variant before ship;\nthe test that enforces \"no code without fixture\" lives beside the classifiers.",
"oneOf": [
{
"const": "PD-ENV-001",
"description": "Interpreter path missing or not executable — the env was deleted or moved.",
"type": "string"
},
{
"const": "PD-ENV-002",
"description": "PEP 668 `EXTERNALLY-MANAGED` marker present; mutation blocked by default.",
"type": "string"
},
{
"const": "PD-ENV-003",
"description": "`probe.py` exited non-zero or produced unparseable output.",
"type": "string"
},
{
"const": "PD-ENG-001",
"description": "pip or uv binary not found.",
"type": "string"
},
{
"const": "PD-ENG-002",
"description": "pip older than 22.2, which predates `--dry-run --report`.",
"type": "string"
},
{
"const": "PD-ENG-003",
"description": "uv emitted a shape the adapter does not recognize (uv newer than PipDock).",
"type": "string"
},
{
"const": "PD-ENG-004",
"description": "An engine command ran past its watchdog and was stopped.\n\n**Raised by PipDock, never classified from stderr.** Its own code because the alternative\nwas `PD-INT-001`, which is what the shared watchdog reported until 1.4.0: an sdist build\nstill compiling after ten minutes is not \"a PipDock bug\", and in the batch phase that error\naborted the whole run — no summary, no per-package retry.",
"type": "string"
},
{
"const": "PD-ENG-999",
"description": "Fallback for engine failures no classifier matched. Always last.",
"type": "string"
},
{
"const": "PD-RES-001",
"description": "`ResolutionImpossible` or the uv equivalent: constraints cannot be satisfied.",
"type": "string"
},
{
"const": "PD-RES-002",
"description": "Plan older than 10 minutes, or the env's probe hash changed since the preview.",
"type": "string"
},
{
"const": "PD-RES-003",
"description": "A plan is already resolving or executing in this session.\n\nThe GUI drives one resumable flow across several IPC calls, so \"start a plan\" and \"run the\nplan\" are different messages arriving at different times — nothing structurally stops a\nsecond one arriving in between. Refusing is the only safe answer: two concurrent plans\nwould interleave engine commands against one environment, and DATA-FLOW §9.3's staleness\ncheck would be comparing against a set the other plan is busy changing.",
"type": "string"
},
{
"const": "PD-RES-004",
"description": "A removal was asked for that the reverse-dependency guard refused (DATA-FLOW §5).\n\nIts own code rather than a reused one. The CLI printed `PD-PKG-002` here, which means \"no\nmatching distribution\" — the opposite of the truth: every package involved exists, and\nthat is precisely why the removal is being refused. A user grepping their logs for a typo\nwould have found this instead.\n\nNot raised when the guard merely *finds* dependents. That is a report the caller shows and\nthe user answers; the code appears only when execution is attempted anyway without the\nuser having accepted the breakage.",
"type": "string"
},
{
"const": "PD-BLD-001",
"description": "MSVC build tools required but absent.",
"type": "string"
},
{
"const": "PD-BLD-002",
"description": "Build backend failed (`pyproject.toml` error, `metadata-generation-failed`).",
"type": "string"
},
{
"const": "PD-BLD-003",
"description": "Generic sdist wheel-build failure.",
"type": "string"
},
{
"const": "PD-PKG-001",
"description": "No matching distribution, and metadata shows a requires-python mismatch.",
"type": "string"
},
{
"const": "PD-PKG-002",
"description": "No matching distribution: name or version typo, or the release is gone.",
"type": "string"
},
{
"const": "PD-PKG-003",
"description": "The requested release was yanked.",
"type": "string"
},
{
"const": "PD-PKG-004",
"description": "Downloaded artifact failed hash verification.",
"type": "string"
},
{
"const": "PD-NET-001",
"description": "Timeout, connection aborted, or DNS failure.",
"type": "string"
},
{
"const": "PD-NET-002",
"description": "TLS/SSL verification failed — typically proxy or AV interception.",
"type": "string"
},
{
"const": "PD-NET-010",
"description": "PEP 691 index refresh failed; the stale index stays searchable.",
"type": "string"
},
{
"const": "PD-NET-011",
"description": "Code Health tools-venv bootstrap could not reach PyPI.",
"type": "string"
},
{
"const": "PD-PRM-001",
"description": "`PermissionError` writing site-packages (admin-owned Python).",
"type": "string"
},
{
"const": "PD-PRM-002",
"description": "File locked by a running process (`WinError 32`).",
"type": "string"
},
{
"const": "PD-PRM-003",
"description": "A source file in the user's project cannot be written.\n\n**Not `PD-PRM-001`.** That one is scoped to site-packages and its catalogued action is\n\"use a venv\", which is nonsense advice for a read-only `util.py` — the same class of wrong\nanswer P3 removed when a corrupted `ruff.exe` reported `PD-ENG-001`, \"install the engine\".\n\nRaised by PipDock **before anything is written**, never classified from stderr: ruff can\nfail to write a file and still exit 1, which `is_findings_exit` accepts as a clean run, so\na stderr-matched code would arrive after a fix had already reported success.",
"type": "string"
},
{
"const": "PD-SNP-001",
"description": "Snapshot write failed before execution. **The plan is aborted; nothing runs.**",
"type": "string"
},
{
"const": "PD-SNP-002",
"description": "A release needed to restore a snapshot is no longer available on PyPI.",
"type": "string"
},
{
"const": "PD-SYS-001",
"description": "`MAX_PATH` exceeded without the long-path opt-in.",
"type": "string"
},
{
"const": "PD-SYS-002",
"description": "Disk full.",
"type": "string"
},
{
"const": "PD-HLT-001",
"description": "A Code Health tool is missing from the tools venv.",
"type": "string"
},
{
"const": "PD-HLT-002",
"description": "A Code Health tool exited non-zero.",
"type": "string"
},
{
"const": "PD-HLT-003",
"description": "A Code Health tool exceeded its watchdog timeout; partial report shown.",
"type": "string"
},
{
"const": "PD-HLT-004",
"description": "`python -m venv` failed while building the tools environment.\n\n**Raised by PipDock, not classified from engine stderr.** Its own code rather than a reused\none: `PD-NET-011` is `Area::Net`, so `run::exit_for` would map a broken interpreter to exit\n6 and a script retrying on network failure would loop forever; `PD-HLT-001` tells the user\nto re-sync, which is the operation that just failed; and a Python built without `venv` is\nnot `PD-INT-001`'s \"a PipDock bug\".",
"type": "string"
},
{
"const": "PD-INT-001",
"description": "A PipDock bug: panic or unexpected state.",
"type": "string"
}
]
},
"PkgName": {
"description": "A PEP 503-normalized distribution name.\n\nConstructing one is the *only* way a package name reaches an argv array, which is what makes\nSECURITY §2's \"validated before it reaches argv\" claim structural rather than aspirational.",
"type": "string"
@@ -30,6 +210,17 @@ expression: out
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "Post-execution environment verification.",
"properties": {
"error": {
"anyOf": [
{
"$ref": "#/$defs/Code"
},
{
"type": "null"
}
],
"description": "Set when the check could not run at all, with the reason's code; `ok` is false then.\n\nA check that could not run used to be reported as `ok: true` — \"verified\" in exactly the\ncase where nothing was verified, such as a pip broken by the run it was meant to check."
},
"findings": {
"default": [],
"description": "Details when `ok` is false.",
@@ -39,7 +230,7 @@ expression: out
"type": "array"
},
"ok": {
"description": "True when the engine reported no broken requirements.",
"description": "True when the check **ran** and the engine reported no broken requirements.",
"type": "boolean"
}
},
@@ -36,6 +36,11 @@ expression: out
"description": "uv emitted a shape the adapter does not recognize (uv newer than PipDock).",
"type": "string"
},
{
"const": "PD-ENG-004",
"description": "An engine command ran past its watchdog and was stopped.\n\n**Raised by PipDock, never classified from stderr.** Its own code because the alternative\nwas `PD-INT-001`, which is what the shared watchdog reported until 1.4.0: an sdist build\nstill compiling after ten minutes is not \"a PipDock bug\", and in the batch phase that error\naborted the whole run — no summary, no per-package retry.",
"type": "string"
},
{
"const": "PD-ENG-999",
"description": "Fallback for engine failures no classifier matched. Always last.",
@@ -0,0 +1,105 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: out
---
{
"$defs": {
"DepEdge": {
"description": "One edge of the dependency graph, seen from a focused package.\n\n`pkg` is always the **other end** of the edge and `constraint` always the specifier written on\nit, so one type serves both directions: in a dependents column `pkg` is who requires the focus,\nin a dependencies column it is what the focus requires. `version` is that package's installed\nversion.\n\nThree fields identical to [`BrokenDependent`], and deliberately a separate type. That one is\nabout *breakage* — its doc is written for the uninstall dialog and its `Ord` exists for the\ndedup in [`ReverseDeps::breaking_dependents`] — so reusing it here would have a dependencies\ncolumn claim every dependency is a broken dependent. The `From` impl below is the bridge, and\n[`ReverseDeps::edges_to`] goes through it precisely so the two cannot drift.\n\n`constraint` is the **bare specifier tail** — `\"<2,>=1.26.0\"`, never `\"numpy<2,>=1.26.0\"` — for\n[`BrokenDependent`]'s reason. The other half of the sentence is the focused package, which the\ncaller already has; Rust emits data and each head writes its own sentence (I18N §1). An empty\nstring means unconstrained, which is a different statement from \"no edge\" and the view says so.",
"properties": {
"constraint": {
"description": "The version specifier written on the edge. Empty when unconstrained.",
"type": "string"
},
"pkg": {
"$ref": "#/$defs/PkgName",
"description": "The package at the other end of the edge."
},
"version": {
"description": "Its installed version, when the graph knows it.",
"type": [
"string",
"null"
]
}
},
"required": [
"pkg",
"constraint"
],
"type": "object"
},
"DepsNode": {
"description": "Everything a focus view needs about one installed package.\n\n`impact` and `reach` are the pair the view exists for. Every other question PipDock answers\nabout the graph is single-hop — the uninstall guard, blocker attribution and pin auto-suggest\nall look one edge out — so the only thing a dependency view adds over shipped behaviour is\n**transitive** reach, and it is a number rather than a picture because the picture does not\nsurvive the scale: measured on the 352-package fixture, a depth-2 neighbourhood is a median of\n172 nodes and exceeds 60 for 212 of 352 packages.",
"properties": {
"dependencies": {
"description": "Installed packages this one requires, in force.",
"items": {
"$ref": "#/$defs/DepEdge"
},
"type": "array"
},
"dependents": {
"description": "Installed packages that require this one, with the constraint each declared.",
"items": {
"$ref": "#/$defs/DepEdge"
},
"type": "array"
},
"impact": {
"description": "How many packages would be left broken if this one went, transitively. The size of\n[`ReverseDeps::removal_closure`] without the package itself.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"reach": {
"description": "How many installed packages this one pulls in, transitively.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"unsatisfied": {
"description": "In-force requirements with nothing installed to satisfy them.",
"items": {
"$ref": "#/$defs/PkgName"
},
"type": "array"
},
"version": {
"description": "The package's own installed version.",
"type": [
"string",
"null"
]
}
},
"required": [
"dependents",
"dependencies",
"impact",
"reach"
],
"type": "object"
},
"PkgName": {
"description": "A PEP 503-normalized distribution name.\n\nConstructing one is the *only* way a package name reaches an argv array, which is what makes\nSECURITY §2's \"validated before it reaches argv\" claim structural rather than aspirational.",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "The in-force dependency graph of one environment (PRD P1-6).\n\nKeyed by package name, one entry per installed distribution. Produced by\n[`ReverseDeps::view`]; see its doc for why this crosses the bridge whole rather than a package\nat a time, and why nothing here is capped.",
"properties": {
"nodes": {
"additionalProperties": {
"$ref": "#/$defs/DepsNode"
},
"description": "Every installed package, including those with no edges in either direction.",
"type": "object"
}
},
"required": [
"nodes"
],
"title": "DepsGraph",
"type": "object"
}
@@ -25,6 +25,17 @@ expression: out
"CheckReport": {
"description": "Post-execution environment verification.",
"properties": {
"error": {
"anyOf": [
{
"$ref": "#/$defs/Code"
},
{
"type": "null"
}
],
"description": "Set when the check could not run at all, with the reason's code; `ok` is false then.\n\nA check that could not run used to be reported as `ok: true` — \"verified\" in exactly the\ncase where nothing was verified, such as a pip broken by the run it was meant to check."
},
"findings": {
"default": [],
"description": "Details when `ok` is false.",
@@ -34,7 +45,7 @@ expression: out
"type": "array"
},
"ok": {
"description": "True when the engine reported no broken requirements.",
"description": "True when the check **ran** and the engine reported no broken requirements.",
"type": "boolean"
}
},
@@ -76,6 +87,11 @@ expression: out
"description": "uv emitted a shape the adapter does not recognize (uv newer than PipDock).",
"type": "string"
},
{
"const": "PD-ENG-004",
"description": "An engine command ran past its watchdog and was stopped.\n\n**Raised by PipDock, never classified from stderr.** Its own code because the alternative\nwas `PD-INT-001`, which is what the shared watchdog reported until 1.4.0: an sdist build\nstill compiling after ten minutes is not \"a PipDock bug\", and in the batch phase that error\naborted the whole run — no summary, no per-package retry.",
"type": "string"
},
{
"const": "PD-ENG-999",
"description": "Fallback for engine failures no classifier matched. Always last.",
@@ -354,7 +370,7 @@ expression: out
"properties": {
"cancelled": {
"default": false,
"description": "True when the user stopped this run part-way.\n\nARCHITECTURE §7 words this as `Skipped(UserCancelled)`, but [`StepStatus`] is a\npayload-free enum and giving it one changes the wire shape for every consumer. A flag on\nthe summary also matches what the summary sheet actually needs: \"cancelled\" is said once\nat the top, not repeated on forty rows.\n\nSteps that never ran are `Skipped`, which is already the honest status for them.",
"description": "True when the user stopped this run part-way.\n\nDATA-FLOW §3 used to word this as `Skipped(UserCancelled)`, but [`StepStatus`] is a\npayload-free enum and giving it one changes the wire shape for every consumer. A flag on\nthe summary also matches what the summary sheet actually needs: \"cancelled\" is said once\nat the top, not repeated on forty rows.\n\nSteps that never ran are `Skipped`, which is already the honest status for them.",
"type": "boolean"
},
"check": {
@@ -158,6 +158,11 @@ expression: out
"const": "everything-skipped",
"description": "Every candidate was skipped while resolving conflicts, so no plan remains.",
"type": "string"
},
{
"const": "cancelled",
"description": "The user stopped the resolve before it finished. Nothing was planned, nothing ran.",
"type": "string"
}
]
},
@@ -165,6 +170,34 @@ expression: out
"description": "A PEP 503-normalized distribution name.\n\nConstructing one is the *only* way a package name reaches an argv array, which is what makes\nSECURITY §2's \"validated before it reaches argv\" claim structural rather than aspirational.",
"type": "string"
},
"PythonMismatch": {
"description": "A pin the user asked for that cannot install on this environment's Python (`PD-PKG-001`).\n\nHard invariant 10 says PipDock enforces `Requires-Python` itself, because the engines disagree:\npip refuses such a pin with the same \"No matching distribution\" it uses for a typo, and uv\nignores an upper bound and plans it. Structured, not a sentence (invariant 4): the preview shows\nthe required range against the environment's version, and a catalog cannot un-join a string.",
"properties": {
"pkg": {
"$ref": "#/$defs/PkgName",
"description": "The package."
},
"python": {
"description": "The environment's Python, e.g. `\"3.12.4\"`.",
"type": "string"
},
"requiresPython": {
"description": "That release's `Requires-Python`, verbatim.",
"type": "string"
},
"version": {
"$ref": "#/$defs/Version",
"description": "The version that was asked for or planned."
}
},
"required": [
"pkg",
"version",
"requiresPython",
"python"
],
"type": "object"
},
"ResolutionReport": {
"description": "The normalized dry-run result.\n\n**Both adapters must emit this same shape** — that is the whole point of the `Engine` trait\n(ARCHITECTURE §3). The pip adapter fills it from `--dry-run --report` JSON; the uv adapter from\nuv's text plan output.\n\nThe exact field set is **provisional until spike SP-1** confirms uv's output is rich enough to\npopulate `held_back.blockers`. If it is not, SP-1's go/no-go says v1.0 ships pip-primary with uv\nbehind a beta flag.",
"properties": {
@@ -176,6 +209,13 @@ expression: out
},
"type": "array"
},
"forced": {
"description": "Packages the user chose to **force** past what installed dependents allow, each with what\nit will break — the \"Will break\" section of the preview (DISCLAIMER §2).",
"items": {
"$ref": "#/$defs/HeldBack"
},
"type": "array"
},
"heldBack": {
"default": [],
"description": "Packages that could not reach `latest`, with attribution.",
@@ -195,19 +235,51 @@ expression: out
],
"description": "Present when the whole resolution failed."
},
"raw": {
"description": "The engine's untouched output, kept for the log and for bug reports.",
"type": "string"
"incompatible": {
"description": "Pins left out because their `Requires-Python` excludes this environment (`PD-PKG-001`).",
"items": {
"$ref": "#/$defs/PythonMismatch"
},
"type": "array"
},
"yanked": {
"description": "Yanked releases the plan would install. A warning, not a failure (`PD-PKG-003`, SP-2):\nboth engines exit 0 and install them. Both adapters parsed these and then dropped them, so\nthe preview never showed one.",
"items": {
"$ref": "#/$defs/YankWarning"
},
"type": "array"
}
},
"required": [
"raw"
],
"type": "object"
},
"Version": {
"description": "A version string as the engine reported it. Never reshaped or localized (I18N §2).",
"type": "string"
},
"YankWarning": {
"description": "A yanked release appearing in a plan.\n\nSP-2: a yank is **not** a failure. Both engines exit 0 and install it, so this is a preview\nwarning row, not an error path (`docs/ERROR-CATALOG.md` PD-PKG-003).",
"properties": {
"pkg": {
"$ref": "#/$defs/PkgName",
"description": "The yanked distribution."
},
"reason": {
"description": "Upstream's stated reason, when given.",
"type": [
"string",
"null"
]
},
"version": {
"$ref": "#/$defs/Version",
"description": "The version that was yanked."
}
},
"required": [
"pkg",
"version"
],
"type": "object"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
@@ -37,6 +37,11 @@ expression: out
"description": "uv emitted a shape the adapter does not recognize (uv newer than PipDock).",
"type": "string"
},
{
"const": "PD-ENG-004",
"description": "An engine command ran past its watchdog and was stopped.\n\n**Raised by PipDock, never classified from stderr.** Its own code because the alternative\nwas `PD-INT-001`, which is what the shared watchdog reported until 1.4.0: an sdist build\nstill compiling after ten minutes is not \"a PipDock bug\", and in the batch phase that error\naborted the whole run — no summary, no per-package retry.",
"type": "string"
},
{
"const": "PD-ENG-999",
"description": "Fallback for engine failures no classifier matched. Always last.",
@@ -0,0 +1,27 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: out
---
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "The end of PipDock's own log, for Settings' Logs row (ARCHITECTURE §7).",
"properties": {
"dir": {
"description": "The folder the log files are in. A path — data, never localized (I18N §2).",
"type": "string"
},
"lines": {
"description": "The most recent lines, oldest first. Empty when nothing has been logged yet.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"dir",
"lines"
],
"title": "LogTail",
"type": "object"
}
@@ -9,12 +9,12 @@ expression: out
"oneOf": [
{
"const": "exclude",
"description": "Excluded from bulk updates. The user can still update it deliberately, one package at a\ntime — a pin is \"do not sweep this up\", not \"never touch this\".",
"description": "Left out of every update until it is unpinned (DATA-FLOW §9.5), whether the update names\nit or sweeps it up with *Select all*.",
"type": "string"
},
{
"additionalProperties": false,
"description": "Held at an exact version: excluded from bulk updates *and* restated at this version in\nevery plan, so the resolver treats it as fixed.",
"description": "Held at an exact version: left out of every update *and* restated at this version in\nevery plan, so the resolver treats it as fixed — including as another package's dependency.",
"properties": {
"hold": {
"properties": {
@@ -16,7 +16,7 @@ expression: out
"description": "Normalized distribution name."
},
"versionReq": {
"description": "PEP 440 specifier such as `\">=2,<3\"`, or `None` for \"latest\".",
"description": "PEP 440 specifier such as `\">=2,<3\"` (or a bare version, read as `==`), or `None` for\n\"latest\". Validated on every way in — [`Spec::parse`] and deserialization — so it is\nnever prose, a marker or an option by the time it reaches argv.",
"type": [
"string",
"null"
@@ -150,9 +150,62 @@ expression: out
"description": "A PEP 503-normalized distribution name.\n\nConstructing one is the *only* way a package name reaches an argv array, which is what makes\nSECURITY §2's \"validated before it reaches argv\" claim structural rather than aspirational.",
"type": "string"
},
"PythonMismatch": {
"description": "A pin the user asked for that cannot install on this environment's Python (`PD-PKG-001`).\n\nHard invariant 10 says PipDock enforces `Requires-Python` itself, because the engines disagree:\npip refuses such a pin with the same \"No matching distribution\" it uses for a typo, and uv\nignores an upper bound and plans it. Structured, not a sentence (invariant 4): the preview shows\nthe required range against the environment's version, and a catalog cannot un-join a string.",
"properties": {
"pkg": {
"$ref": "#/$defs/PkgName",
"description": "The package."
},
"python": {
"description": "The environment's Python, e.g. `\"3.12.4\"`.",
"type": "string"
},
"requiresPython": {
"description": "That release's `Requires-Python`, verbatim.",
"type": "string"
},
"version": {
"$ref": "#/$defs/Version",
"description": "The version that was asked for or planned."
}
},
"required": [
"pkg",
"version",
"requiresPython",
"python"
],
"type": "object"
},
"Version": {
"description": "A version string as the engine reported it. Never reshaped or localized (I18N §2).",
"type": "string"
},
"YankWarning": {
"description": "A yanked release appearing in a plan.\n\nSP-2: a yank is **not** a failure. Both engines exit 0 and install it, so this is a preview\nwarning row, not an error path (`docs/ERROR-CATALOG.md` PD-PKG-003).",
"properties": {
"pkg": {
"$ref": "#/$defs/PkgName",
"description": "The yanked distribution."
},
"reason": {
"description": "Upstream's stated reason, when given.",
"type": [
"string",
"null"
]
},
"version": {
"$ref": "#/$defs/Version",
"description": "The version that was yanked."
}
},
"required": [
"pkg",
"version"
],
"type": "object"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
@@ -166,6 +219,13 @@ expression: out
},
"type": "array"
},
"forced": {
"description": "Packages the user chose to **force** past what installed dependents allow, each with what\nit will break — the \"Will break\" section of the preview (DISCLAIMER §2).",
"items": {
"$ref": "#/$defs/HeldBack"
},
"type": "array"
},
"heldBack": {
"default": [],
"description": "Packages that could not reach `latest`, with attribution.",
@@ -185,14 +245,21 @@ expression: out
],
"description": "Present when the whole resolution failed."
},
"raw": {
"description": "The engine's untouched output, kept for the log and for bug reports.",
"type": "string"
"incompatible": {
"description": "Pins left out because their `Requires-Python` excludes this environment (`PD-PKG-001`).",
"items": {
"$ref": "#/$defs/PythonMismatch"
},
"type": "array"
},
"yanked": {
"description": "Yanked releases the plan would install. A warning, not a failure (`PD-PKG-003`, SP-2):\nboth engines exit 0 and install them. Both adapters parsed these and then dropped them, so\nthe preview never showed one.",
"items": {
"$ref": "#/$defs/YankWarning"
},
"type": "array"
}
},
"required": [
"raw"
],
"title": "ResolutionReport",
"type": "object"
}
@@ -37,6 +37,11 @@ expression: out
"description": "uv emitted a shape the adapter does not recognize (uv newer than PipDock).",
"type": "string"
},
{
"const": "PD-ENG-004",
"description": "An engine command ran past its watchdog and was stopped.\n\n**Raised by PipDock, never classified from stderr.** Its own code because the alternative\nwas `PD-INT-001`, which is what the shared watchdog reported until 1.4.0: an sdist build\nstill compiling after ten minutes is not \"a PipDock bug\", and in the batch phase that error\naborted the whole run — no summary, no per-package retry.",
"type": "string"
},
{
"const": "PD-ENG-999",
"description": "Fallback for engine failures no classifier matched. Always last.",
@@ -2,4 +2,4 @@
source: crates/pipdock-cli/tests/golden.rs
expression: "stderr_of(&[\"schema\", \"NoSuchType\"])"
---
error[PD-PKG-002]: unknown type "NoSuchType"; known types: Dist, OutdatedDist, PyEnv, CheckReport, StepResult, PlanRequest, ResolutionReport, ExecutionSummary, Pin, PinSuggestion, ParsedRequirements, CacheUsage, CacheTarget, GuardReport, Diff, SnapshotMeta, EngineInfo, RollbackPlan, RollbackPreview, Hit, PackageMeta, Freshness, RefreshReport, ProgressEvent, FlowStep, Decision, Intent, Code, HealthReport, AuditReport, FixReport
error[PD-PKG-002]: unknown type "NoSuchType"; known types: Dist, OutdatedDist, PyEnv, CheckReport, StepResult, PlanRequest, ResolutionReport, ExecutionSummary, Pin, PinSuggestion, ParsedRequirements, CacheUsage, CacheTarget, GuardReport, DepsGraph, Diff, SnapshotMeta, EngineInfo, RollbackPlan, RollbackPreview, Hit, PackageMeta, Freshness, RefreshReport, ProgressEvent, FlowStep, Decision, Intent, Code, HealthReport, AuditReport, FixReport, LogTail
+19 -13
View File
@@ -5,33 +5,39 @@ version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
publish.workspace = true
repository.workspace = true
authors.workspace = true
[lints]
workspace = true
[features]
# `fixtures.rs`: the L3 payloads xtask writes for the frontend's tests.
fixtures = []
[dependencies]
async-trait = "0.1.91"
jiff = { version = "0.2.35", features = ["serde"] }
async-trait = "0.1.92"
jiff = { version = "0.2.38", features = ["serde"] }
nucleo = "0.5.0"
reqwest = { version = "0.13.4", default-features = false, features = ["rustls", "http2", "json", "gzip", "charset"] }
rusqlite = { version = "0.37", features = ["bundled"] }
schemars = "1.2.1"
reqwest = { version = "0.13.5", default-features = false, features = ["rustls", "http2", "json", "gzip", "charset"] }
rusqlite = { version = "0.43.0", features = ["bundled"] }
schemars = "1.2.3"
serde = { version = "1.0.229", features = ["derive"] }
serde_json = "1.0.151"
sha2 = "0.11.0"
thiserror = "2.0.19"
tokio = { version = "1.53.1", features = ["rt-multi-thread", "macros", "process", "io-util", "time", "sync"] }
serde_json = "1.0.154"
sha2 = "0.11.1"
thiserror = "2.0.21"
# `fs`: an async fn that touches a file goes through tokio's pool rather than blocking a runtime
# worker (SonarQube rust:S7493).
tokio = { version = "1.53.3", features = ["rt-multi-thread", "macros", "process", "io-util", "time", "sync", "fs"] }
# First-party tokio, for CancellationToken. The alternative was an AtomicBool plus a Notify,
# which is what CancellationToken already is, written worse.
tokio-util = "0.7"
tokio-util = "0.7.20"
tracing = "0.1.44"
[dev-dependencies]
insta = { version = "1.48.0", features = ["json"] }
jiff = "0.2.35"
tokio = { version = "1.53.1", features = ["rt-multi-thread", "macros"] }
jiff = "0.2.38"
tokio = { version = "1.53.3", features = ["rt-multi-thread", "macros"] }
[target."cfg(windows)".dependencies]
winreg = "0.56.0"
+8 -191
View File
@@ -10,6 +10,9 @@
use std::path::{Path, PathBuf};
#[path = "src/legal_hash.rs"]
mod legal_hash;
/// The five documents the gate lists. UI-SPEC §4 says five; `legal/` holds four, and the fifth is
/// the GPL-3.0 `LICENSE` at the repository root.
const DOCUMENTS: &[&str] = &[
@@ -22,27 +25,22 @@ const DOCUMENTS: &[&str] = &[
fn main() {
let root = repo_root();
let mut hasher = Sha256::new();
let mut documents = Vec::with_capacity(DOCUMENTS.len());
for name in DOCUMENTS {
let path = root.join(name);
println!("cargo:rerun-if-changed={}", path.display());
// A missing document must not silently drop out of the hash, or removing a file would
// leave existing consent looking current. Hash the name and the bytes.
// leave existing consent looking current. Its name is still hashed, with no bytes.
let bytes = std::fs::read(&path).unwrap_or_else(|e| {
println!("cargo:warning=legal document {name} unreadable ({e}); hashing its absence");
Vec::new()
});
hasher.update(name.as_bytes());
hasher.update(&(bytes.len() as u64).to_le_bytes());
// Normalise line endings: a CRLF checkout must not produce a different hash from an LF
// one, or every Windows contributor would re-trigger the gate for everybody.
hasher.update(&normalise(&bytes));
documents.push((*name, bytes));
}
let pairs: Vec<(&str, &[u8])> = documents.iter().map(|(n, b)| (*n, b.as_slice())).collect();
println!(
"cargo:rustc-env=PIPDOCK_LEGAL_DOCS_HASH={}",
hex(&hasher.finish())
legal_hash::docs_hash(&pairs)
);
}
@@ -53,184 +51,3 @@ fn repo_root() -> PathBuf {
.and_then(Path::parent)
.map_or_else(|| PathBuf::from("."), Path::to_path_buf)
}
fn normalise(bytes: &[u8]) -> Vec<u8> {
bytes.iter().copied().filter(|b| *b != b'\r').collect()
}
fn hex(digest: &[u8; 32]) -> String {
digest.iter().fold(String::with_capacity(64), |mut acc, b| {
use std::fmt::Write as _;
let _ = write!(acc, "{b:02x}");
acc
})
}
/// A small SHA-256, so the build script needs no dependencies.
///
/// A build-dependency here would be one more crate in the supply chain of the thing that decides
/// whether users see the legal gate (SECURITY §7). FIPS 180-4.
struct Sha256 {
state: [u32; 8],
buffer: Vec<u8>,
length: u64,
}
const K: [u32; 64] = [
0x428a_2f98,
0x7137_4491,
0xb5c0_fbcf,
0xe9b5_dba5,
0x3956_c25b,
0x59f1_11f1,
0x923f_82a4,
0xab1c_5ed5,
0xd807_aa98,
0x1283_5b01,
0x2431_85be,
0x550c_7dc3,
0x72be_5d74,
0x80de_b1fe,
0x9bdc_06a7,
0xc19b_f174,
0xe49b_69c1,
0xefbe_4786,
0x0fc1_9dc6,
0x240c_a1cc,
0x2de9_2c6f,
0x4a74_84aa,
0x5cb0_a9dc,
0x76f9_88da,
0x983e_5152,
0xa831_c66d,
0xb003_27c8,
0xbf59_7fc7,
0xc6e0_0bf3,
0xd5a7_9147,
0x06ca_6351,
0x1429_2967,
0x27b7_0a85,
0x2e1b_2138,
0x4d2c_6dfc,
0x5338_0d13,
0x650a_7354,
0x766a_0abb,
0x81c2_c92e,
0x9272_2c85,
0xa2bf_e8a1,
0xa81a_664b,
0xc24b_8b70,
0xc76c_51a3,
0xd192_e819,
0xd699_0624,
0xf40e_3585,
0x106a_a070,
0x19a4_c116,
0x1e37_6c08,
0x2748_774c,
0x34b0_bcb5,
0x391c_0cb3,
0x4ed8_aa4a,
0x5b9c_ca4f,
0x682e_6ff3,
0x748f_82ee,
0x78a5_636f,
0x84c8_7814,
0x8cc7_0208,
0x90be_fffa,
0xa450_6ceb,
0xbef9_a3f7,
0xc671_78f2,
];
impl Sha256 {
fn new() -> Self {
Self {
state: [
0x6a09_e667,
0xbb67_ae85,
0x3c6e_f372,
0xa54f_f53a,
0x510e_527f,
0x9b05_688c,
0x1f83_d9ab,
0x5be0_cd19,
],
buffer: Vec::new(),
length: 0,
}
}
fn update(&mut self, data: &[u8]) {
self.length = self.length.wrapping_add(data.len() as u64);
self.buffer.extend_from_slice(data);
while self.buffer.len() >= 64 {
let block: [u8; 64] = self.buffer[..64].try_into().unwrap_or([0; 64]);
self.compress(&block);
self.buffer.drain(..64);
}
}
fn finish(mut self) -> [u8; 32] {
let bits = self.length.wrapping_mul(8);
self.buffer.push(0x80);
while self.buffer.len() % 64 != 56 {
self.buffer.push(0);
}
let tail = bits.to_be_bytes();
self.buffer.extend_from_slice(&tail);
while self.buffer.len() >= 64 {
let block: [u8; 64] = self.buffer[..64].try_into().unwrap_or([0; 64]);
self.compress(&block);
self.buffer.drain(..64);
}
let mut out = [0u8; 32];
for (chunk, word) in out.chunks_exact_mut(4).zip(self.state) {
chunk.copy_from_slice(&word.to_be_bytes());
}
out
}
fn compress(&mut self, block: &[u8; 64]) {
let mut w = [0u32; 64];
for (slot, chunk) in w.iter_mut().zip(block.chunks_exact(4)) {
*slot = u32::from_be_bytes(chunk.try_into().unwrap_or([0; 4]));
}
for i in 16..64 {
let s0 = w[i - 15].rotate_right(7) ^ w[i - 15].rotate_right(18) ^ (w[i - 15] >> 3);
let s1 = w[i - 2].rotate_right(17) ^ w[i - 2].rotate_right(19) ^ (w[i - 2] >> 10);
w[i] = w[i - 16]
.wrapping_add(s0)
.wrapping_add(w[i - 7])
.wrapping_add(s1);
}
let [mut a, mut b, mut c, mut d, mut e, mut f, mut g, mut h] = self.state;
for i in 0..64 {
let s1 = e.rotate_right(6) ^ e.rotate_right(11) ^ e.rotate_right(25);
let ch = (e & f) ^ ((!e) & g);
let t1 = h
.wrapping_add(s1)
.wrapping_add(ch)
.wrapping_add(K[i])
.wrapping_add(w[i]);
let s0 = a.rotate_right(2) ^ a.rotate_right(13) ^ a.rotate_right(22);
let maj = (a & b) ^ (a & c) ^ (b & c);
let t2 = s0.wrapping_add(maj);
h = g;
g = f;
f = e;
e = d.wrapping_add(t1);
d = c;
c = b;
b = a;
a = t1.wrapping_add(t2);
}
for (slot, value) in self.state.iter_mut().zip([a, b, c, d, e, f, g, h]) {
*slot = slot.wrapping_add(value);
}
}
}
+1 -1
View File
@@ -13,7 +13,7 @@
//!
//! ```text
//! pipdock index refresh
//! cargo run --release --example sp3_search -- "%LOCALAPPDATA%\PipDock\index.db"
//! cargo run --release --example sp3_search -- "%LOCALAPPDATA%\PipDock\data\index.db"
//! ```
// A measurement harness reports to a human on stdout; the library-level ban does not apply.
+20 -12
View File
@@ -353,11 +353,20 @@ async fn audit_once(audit_dir: &Path, freeze: &str, sink: &ProgressSink) -> Resu
// The environment reaches pip-audit as a *document*, never as a directory: SP-4 found that
// `--path <site-packages>` is rejected outright alongside `--no-deps`. Written to the system
// temp directory rather than into the user's project or the environment being audited, and
// removed on both paths.
let freeze_path = crate::exec::write_temp("pipdock-audit", "txt", freeze)?;
// removed when it drops, on every path.
//
// **Pins only.** An editable install (`-e …`) or a direct reference (`name @ file:///…`) is a
// line pip-audit cannot look up on an index, and it failed the whole run over one: an
// environment with a single `pip install -e .` could not be audited at all (H21). They are not
// on PyPI, so they have no PyPI advisories; the package count says how many were audited.
let pins: String = crate::snapshot::parse_freeze(freeze)
.iter()
.map(|(name, version)| format!("{name}=={version}\n"))
.collect();
let freeze_file = crate::exec::TempFile::create("pipdock-audit", "txt", &pins)?;
let out = Command::new(&exe)
.args(argv(&freeze_path))
let out = Command::python_tool(&exe)
.args(argv(freeze_file.path()))
.timeout(AUDIT_TIMEOUT)
.cancel(sink.cancel.clone())
.run()
@@ -372,8 +381,7 @@ async fn audit_once(audit_dir: &Path, freeze: &str, sink: &ProgressSink) -> Resu
Ok(out) => parse(&out.stdout).map_err(|e| e.with_stderr(&out.stderr)),
Err(e) => Err(e),
};
let _ = std::fs::remove_file(&freeze_path);
drop(freeze_file);
parsed
}
@@ -394,12 +402,12 @@ fn argv(freeze: &Path) -> Vec<String> {
/// Did the user stop it, or did it break?
///
/// `exec` reports both through `Code::IntUnexpected`, distinguished only by the message it built
/// (`exec::Command::stopped`). Reading the message is unlovely, and it is what P4 warned about
/// when it recorded that wiring the token alone would render *"PipDock hit an internal error"* for
/// a cancel — the mapping has to be done, not merely enabled.
/// Asked of the typed [`PdError::stop`], not of the message. P4 recorded that wiring the token
/// alone would render *"PipDock hit an internal error"* for a cancel — the mapping has to be done,
/// not merely enabled — and until 1.4.0 it was done by matching the `"cancelled:"` prefix
/// `exec::Command::stopped` happened to write.
fn is_cancellation(e: &PdError) -> bool {
e.code == Code::IntUnexpected && e.message.starts_with("cancelled:")
e.is_cancelled()
}
/// Translate `exec`'s vocabulary into this path's.
@@ -408,7 +416,7 @@ fn is_cancellation(e: &PdError) -> bool {
/// an internal error, and a tool that will not start is not a missing engine the user should be
/// told to go and install. Health's `run_one` needed the same translation for the same reason.
fn watchdog(e: PdError) -> PdError {
if e.code == Code::IntUnexpected && e.message.contains("timed out") {
if e.is_timeout() {
return PdError::new(
Code::HltTimeout,
format!("{TOOL} exceeded its {AUDIT_TIMEOUT:?} watchdog; its results are missing"),
+10 -6
View File
@@ -19,12 +19,11 @@
//! reported so the number is honest about where the space went; refreshing the index is
//! `index refresh`, which replaces rows rather than deleting a file.
//!
//! # There are no log files
//! # Log files are not a target
//!
//! [`crate::LOG_RETENTION_DAYS`] has never had a reader. The only log is the in-memory ring buffer
//! behind *Report bug*, and `logs_tail` is still owed. When the logging subsystem lands it becomes
//! a fourth entry here; until then, reporting a "logs" line of zero bytes would be inventing a
//! thing that does not exist.
//! Since 1.4.0 there are log files (`crate::logging`), and they look after themselves: the sweep
//! keeps [`crate::LOG_RETENTION_DAYS`] and nothing more, so a "clear logs" button would only take
//! away the one record a bug report needs. Settings shows where they are instead.
use std::path::{Path, PathBuf};
@@ -262,8 +261,13 @@ mod tests {
use super::*;
fn temp() -> PathBuf {
// A counter, not the clock alone: two tests running in parallel inside one tick of the
// system clock got the same directory, and the fresh-install test read the other's files.
static NEXT: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
let dir = std::env::temp_dir().join(format!(
"pipdock-cache-{}",
"pipdock-cache-{}-{}-{}",
std::process::id(),
NEXT.fetch_add(1, std::sync::atomic::Ordering::Relaxed),
jiff::Timestamp::now().as_nanosecond()
));
std::fs::create_dir_all(&dir).expect("temp dir");
+491 -6
View File
@@ -13,7 +13,7 @@ pub mod uv;
use async_trait::async_trait;
use crate::errors::Result;
use crate::errors::{Code, PdError, Result};
use crate::model::{
CheckReport, Dist, EngineId, EngineInfo, ExecMode, OutdatedDist, PinnedSpec, PkgName, PyEnv,
StepResult, StepStatus,
@@ -209,17 +209,25 @@ pub trait Engine: Send + Sync {
/// Dry-run resolve `req` against `env`, normalized into a [`ResolutionReport`].
///
/// This is the only way a plan may be produced; DATA-FLOW §9.1 forbids any mutating call
/// without a report accepted in the same session.
async fn resolve(&self, env: &PyEnv, req: &PlanRequest) -> Result<ResolutionReport>;
/// without a report accepted in the same session. `ctx` carries the cancellation token —
/// a resolve used to be the one engine call nothing could stop, so *Stop* while pip
/// backtracked left it running for up to ten minutes — and what the flow changes about the
/// guard set (forced pins, holds, exclusions).
async fn resolve(
&self,
env: &PyEnv,
req: &PlanRequest,
ctx: &ResolveCtx,
) -> Result<ResolutionReport>;
/// Install an exact pinned set.
/// Install an exact pinned set, holding everything in `set.constraints` where it is.
///
/// `Batch` mode passes the whole set in one invocation (Phase A); `Isolated` mode is the
/// per-package retry loop (Phase B), where a failure must **not** stop the caller's loop.
async fn install(
&self,
env: &PyEnv,
specs: &[PinnedSpec],
set: &InstallSet,
mode: ExecMode,
sink: ProgressSink,
) -> Result<StepResult>;
@@ -230,6 +238,7 @@ pub trait Engine: Send + Sync {
&self,
env: &PyEnv,
names: &[PkgName],
system: SystemPackages,
sink: ProgressSink,
) -> Result<StepResult>;
@@ -247,6 +256,254 @@ pub trait Engine: Send + Sync {
/// Upgrade pip inside `env`. The uv adapter returns an `Unsupported` error — DATA-FLOW §7
/// says pip upkeep is surfaced only when pip is the active engine or present in the env.
async fn upgrade_pip(&self, env: &PyEnv) -> Result<StepResult>;
/// Probe `env`: the interpreter, its marker environment, and every distribution with its
/// requirements.
///
/// Provided, and no adapter overrides it: this is `probe.py`, not an engine command. It is on
/// the trait so a flow can be driven end to end against a scripted engine — every flow probed
/// through a free function, so none of `start`'s decisions (the PEP 668 gate, the graph, the
/// drift basis) could be tested without a real interpreter, and the bugs in them were not.
async fn probe(&self, env: &PyEnv) -> Result<crate::envs::ProbeResult> {
crate::envs::probe(&env.interpreter, env.source).await
}
}
/// Whether an engine call may override PEP 668 with `--break-system-packages` (SECURITY §3).
///
/// A named value rather than a `bool`, for the reason [`crate::snapshot::SnapshotProof`] is a
/// named waiver. The only way to [`Self::OverrideAllowed`] is a flow that probed the environment,
/// found it externally managed, and was told by its caller that the Settings override is on —
/// hard invariant 5 says the flag is never passed implicitly, and this is what makes "implicitly"
/// greppable.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum SystemPackages {
/// The flag is not passed. Everything defaults to this.
#[default]
Protected,
/// The environment is externally managed and the user turned the override on.
OverrideAllowed,
}
impl SystemPackages {
/// `--break-system-packages`, or nothing.
#[must_use]
pub const fn args(self) -> &'static [&'static str] {
match self {
Self::Protected => &[],
Self::OverrideAllowed => &["--break-system-packages"],
}
}
}
/// What the override can do with this engine, for an environment that is externally managed.
///
/// uv has taken `--break-system-packages` throughout its supported range. pip implemented PEP 668
/// in 23.0 and added the flag in 23.0.1: below 23.0 there is nothing to override and the flag is
/// an unknown option, and 23.0 itself enforces the marker with no way past it. An unreadable pip
/// version is assumed modern — a pip that cannot report its version fails on its own first.
///
/// # Errors
/// `PD-ENV-002` for pip 23.0, which no flag gets past.
pub fn system_packages_for(info: &EngineInfo) -> Result<SystemPackages> {
if info.id == EngineId::Uv {
return Ok(SystemPackages::OverrideAllowed);
}
let release = info.version.as_deref().map(|v| {
let mut parts = v.split('.').map(|p| {
p.chars()
.take_while(char::is_ascii_digit)
.collect::<String>()
.parse::<u32>()
.unwrap_or(0)
});
(
parts.next().unwrap_or(0),
parts.next().unwrap_or(0),
parts.next().unwrap_or(0),
)
});
match release {
Some(r) if r < (23, 0, 0) => Ok(SystemPackages::Protected),
Some(r) if r < (23, 0, 1) => Err(PdError::new(
Code::EnvExternallyManaged,
"pip 23.0 enforces PEP 668 and has no override; --break-system-packages arrived in \
pip 23.0.1",
)),
_ => Ok(SystemPackages::OverrideAllowed),
}
}
/// What one resolve is given besides the request itself.
#[derive(Debug, Clone, Default)]
pub struct ResolveCtx {
/// Stops the dry run; a stopped resolve returns an error with `Stop::Cancelled`.
pub cancel: tokio_util::sync::CancellationToken,
/// What the flow changes about the requirement lines the engine is given.
pub adjust: GuardAdjust,
/// uv refuses even a dry run in an externally managed environment without the flag; pip's
/// `--dry-run --report` is exempt and is never given it.
pub system: SystemPackages,
}
/// Changes to the requirement lines of a resolve, made by the flow — never by an adapter.
///
/// SP-1 makes the guard set (every installed package the user is not moving, pinned) the default,
/// and three decisions need to depart from it on purpose: **Force latest** pins a package to its
/// latest and *releases* the packages whose constraints were holding it (DISCLAIMER §2); a **Hold**
/// pin restates its own version; a release whose `Requires-Python` excludes this environment is
/// **excluded** so the engine picks another.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct GuardAdjust {
/// Exact requirements added to the resolve; these names leave the upgrade list and the guard.
pub pins: Vec<PinnedSpec>,
/// Installed packages released from the guard set — what a forced package will break.
pub release: Vec<PkgName>,
/// `name!=version` lines, for releases that cannot install here.
pub exclude: Vec<PinnedSpec>,
}
/// One install invocation: what to install, and what must not move while it happens.
///
/// SP-1's rule — restate the installed set or the resolver breaks it — was applied to the
/// *resolve* only. Phase B then installed each package as a bare `pip install name==v`, with no
/// guard: free to pull a dependency past an installed package's upper bound, which pip reports as
/// a warning and exits 0 on. `constraints` carries the target state of everything else, passed as
/// `-c`, which constrains without installing.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct InstallSet {
/// The exact pins to install.
pub specs: Vec<PinnedSpec>,
/// Everything that must stay at these versions if the engine touches it at all.
pub constraints: Vec<PinnedSpec>,
/// Whether the PEP 668 override applies to this install.
pub system: SystemPackages,
}
/// The requirements (and constraints) files one engine invocation reads, deleted when dropped.
///
/// **Files, not argv.** Every plan restates the whole installed set (SP-1), one argv entry per
/// package — and at around 1,300 packages that passes Windows' 32,767-character command line, so
/// the spawn failed and the user was told to install an engine (PD-ENG-001). `-r`/`-c` keep the
/// command line a constant length. The files hold only rendered [`PinnedSpec`]s and validated
/// [`crate::model::Spec`]s — the same tokens argv held — written under fresh random names.
#[derive(Debug)]
pub struct RequirementFiles {
requirements: crate::exec::TempFile,
constraints: Option<crate::exec::TempFile>,
/// What each file says, line by line, so [`Self::humanize`] can put it back.
requirement_lines: Vec<String>,
constraint_lines: Vec<String>,
}
impl RequirementFiles {
/// Write `requirements` (one per line) and, when there are any, `constraints`.
///
/// # Errors
/// As [`crate::exec::TempFile::create`].
pub fn write(requirements: &[String], constraints: &[PinnedSpec]) -> Result<Self> {
let text = |lines: &[String]| {
let mut text = lines.join("\n");
text.push('\n');
text
};
let requirement_lines = requirements.to_vec();
let constraint_lines: Vec<String> =
constraints.iter().map(PinnedSpec::to_requirement).collect();
let requirements =
crate::exec::TempFile::create("pipdock-req", "txt", &text(&requirement_lines))?;
let constraints = if constraint_lines.is_empty() {
None
} else {
Some(crate::exec::TempFile::create(
"pipdock-con",
"txt",
&text(&constraint_lines),
)?)
};
Ok(Self {
requirements,
constraints,
requirement_lines,
constraint_lines,
})
}
/// Engine text with every reference to these files replaced by the line it points at.
///
/// pip names a requirement that came from a file as `-r <path> (line N)`. Once the plan went
/// through a file, its impossibility read `Cannot install -r C:\…\pipdock-req-….txt (line 1)
/// and h11==0.12.0`: the preview lost the name of the package the user asked for, and every
/// error row showed a path that had already been deleted. Found by running pip, not by
/// reading it — uv names requirements by their text and needs none of this.
#[must_use]
pub fn humanize(&self, text: &str) -> String {
let mut out = replace_file_refs(
text,
&format!("-r {}", self.requirements.path().display()),
&self.requirement_lines,
);
if let Some(c) = &self.constraints {
out = replace_file_refs(
&out,
&format!("-c {}", c.path().display()),
&self.constraint_lines,
);
}
out
}
/// `-r <requirements> [-c <constraints>]`, one argv entry each.
#[must_use]
pub fn args(&self) -> Vec<String> {
let mut out = vec![
"-r".to_owned(),
self.requirements.path().display().to_string(),
];
if let Some(c) = &self.constraints {
out.push("-c".to_owned());
out.push(c.path().display().to_string());
}
out
}
}
/// `<reference> (line N)` becomes line N; `(from <reference> (line N))` goes entirely, since the
/// requirement it annotates is already named just before it.
fn replace_file_refs(text: &str, reference: &str, lines: &[String]) -> String {
let mut out = String::with_capacity(text.len());
let mut rest = text;
while let Some(at) = rest.find(reference) {
let (head, after) = rest.split_at(at);
let after = &after[reference.len()..];
let parsed = after.strip_prefix(" (line ").and_then(|tail| {
let digits = tail.bytes().take_while(u8::is_ascii_digit).count();
let n: usize = tail[..digits].parse().ok()?;
let close = tail[digits..].strip_prefix(')')?;
Some((n, close))
});
let Some((n, close)) = parsed else {
// Not a line reference; keep it as it was.
out.push_str(head);
out.push_str(reference);
rest = after;
continue;
};
if let (Some(before), Some(close)) = (head.strip_suffix("(from "), close.strip_prefix(')'))
{
out.push_str(before.strip_suffix(' ').unwrap_or(before));
rest = close;
continue;
}
out.push_str(head);
match n.checked_sub(1).and_then(|i| lines.get(i)) {
Some(line) => out.push_str(line),
None => out.push_str(&rest[at..rest.len() - close.len()]),
}
rest = close;
}
out.push_str(rest);
out
}
/// The adapter for `id`.
@@ -297,6 +554,11 @@ pub fn plan_requirements(req: &PlanRequest, installed: &[crate::model::Dist]) ->
installed
.iter()
.filter(|d| !moving.contains(&d.name))
// A version that could be read as more than a version — whitespace, a marker, a URL —
// never reaches argv. pip itself cannot install such a distribution, so restating it
// would only fail the resolve; leaving it out leaves it untouched, which is what a guard
// is for.
.filter(|d| crate::pep440::is_argv_safe(&d.version.0))
.map(|d| PinnedSpec {
name: d.name.clone(),
version: d.version.clone(),
@@ -317,7 +579,27 @@ pub fn plan_requirements(req: &PlanRequest, installed: &[crate::model::Dist]) ->
/// Omitting group 3 is the SP-1 failure — the resolver breaks installed dependents at exit 0.
#[must_use]
pub fn plan_argv_specs(req: &PlanRequest, installed: &[crate::model::Dist]) -> Vec<String> {
let mut out: Vec<String> = req.upgrades.iter().map(ToString::to_string).collect();
plan_lines(req, installed, &GuardAdjust::default())
}
/// [`plan_argv_specs`] with the flow's [`GuardAdjust`] applied.
#[must_use]
pub fn plan_lines(
req: &PlanRequest,
installed: &[crate::model::Dist],
adjust: &GuardAdjust,
) -> Vec<String> {
use std::collections::BTreeSet;
let pinned: BTreeSet<&PkgName> = adjust.pins.iter().map(|p| &p.name).collect();
let released: BTreeSet<&PkgName> = adjust.release.iter().collect();
let mut out: Vec<String> = req
.upgrades
.iter()
.filter(|n| !pinned.contains(n))
.map(ToString::to_string)
.collect();
out.extend(req.installs.iter().map(|s| match &s.version_req {
Some(v) if v.starts_with(['=', '<', '>', '!', '~']) => format!("{}{v}", s.name),
@@ -325,11 +607,19 @@ pub fn plan_argv_specs(req: &PlanRequest, installed: &[crate::model::Dist]) -> V
None => s.name.to_string(),
}));
out.extend(adjust.pins.iter().map(PinnedSpec::to_requirement));
out.extend(
plan_requirements(req, installed)
.iter()
.filter(|g| !pinned.contains(&g.name) && !released.contains(&g.name))
.map(PinnedSpec::to_requirement),
);
out.extend(
adjust
.exclude
.iter()
.map(|e| format!("{}!={}", e.name, e.version)),
);
out
}
@@ -517,6 +807,62 @@ mod tests {
);
}
#[test]
fn a_forced_package_is_pinned_and_what_held_it_is_released() {
// Force latest (DISCLAIMER §2): httpcore goes to its latest *exactly*, and httpx — whose
// constraint was holding it — leaves the guard set, or the engine would hold it right back.
let installed = [
dist("httpx", "0.23.0"),
dist("httpcore", "0.15.0"),
dist("h11", "0.12.0"),
];
let req = PlanRequest {
upgrades: vec![PkgName::parse("httpcore").unwrap()],
installs: Vec::new(),
strategy: Strategy::Compatible,
};
let adjust = GuardAdjust {
pins: vec![PinnedSpec {
name: PkgName::parse("httpcore").unwrap(),
version: Version("1.0.9".into()),
}],
release: vec![PkgName::parse("httpx").unwrap()],
exclude: Vec::new(),
};
assert_eq!(
plan_lines(&req, &installed, &adjust),
["httpcore==1.0.9", "h11==0.12.0"]
);
}
#[test]
fn an_excluded_release_rides_alongside_the_request() {
// A release whose Requires-Python excludes this environment is ruled out by name, and the
// engine is left to pick the next one — PipDock still does not resolve (invariant 3).
let installed = [dist("httpx", "0.23.0"), dist("httpcore", "0.15.0")];
let req = PlanRequest {
upgrades: vec![PkgName::parse("httpcore").unwrap()],
installs: Vec::new(),
strategy: Strategy::Compatible,
};
let adjust = GuardAdjust {
exclude: vec![PinnedSpec {
name: PkgName::parse("httpcore").unwrap(),
version: Version("1.0.9".into()),
}],
..GuardAdjust::default()
};
assert_eq!(
plan_lines(&req, &installed, &adjust),
["httpcore", "httpx==0.23.0", "httpcore!=1.0.9"]
);
assert_eq!(
plan_lines(&req, &installed, &GuardAdjust::default()),
plan_argv_specs(&req, &installed),
"no adjustment is exactly the SP-1 default"
);
}
#[test]
fn updating_everything_still_asks_for_something() {
// With --all every package is moving, so the guard set is empty. If only guards were
@@ -576,4 +922,143 @@ mod tests {
};
assert!(plan_requirements(&req, &[]).is_empty());
}
#[test]
fn the_guard_set_leaves_out_a_version_that_is_not_argv_safe() {
let installed = [
crate::model::Dist {
name: PkgName::parse("good").expect("name"),
version: crate::model::Version("1.0".into()),
requires_dist: Vec::new(),
requires_python: None,
size_bytes: None,
},
crate::model::Dist {
name: PkgName::parse("odd").expect("name"),
version: crate::model::Version("1.0 ; python_version < '0'".into()),
requires_dist: Vec::new(),
requires_python: None,
size_bytes: None,
},
];
let req = PlanRequest {
upgrades: Vec::new(),
installs: Vec::new(),
strategy: crate::plan::Strategy::Compatible,
};
let guards = plan_requirements(&req, &installed);
assert_eq!(guards.len(), 1);
assert_eq!(guards[0].to_requirement(), "good==1.0");
}
#[test]
fn a_huge_environment_still_fits_on_a_command_line() {
// Every plan restates the installed set (SP-1). As argv, ~1,300 packages passed Windows'
// 32,767-character limit, the spawn failed with os error 206, and the user was told to
// install an engine. As a file, the command line no longer grows with the environment.
let installed: Vec<crate::model::Dist> = (0..2000)
.map(|i| crate::model::Dist {
name: PkgName::parse(&format!("package-with-a-long-name-{i:04}")).expect("name"),
version: crate::model::Version("12.34.5678".into()),
requires_dist: Vec::new(),
requires_python: None,
size_bytes: None,
})
.collect();
let req = PlanRequest {
upgrades: Vec::new(),
installs: Vec::new(),
strategy: crate::plan::Strategy::Compatible,
};
let lines = plan_argv_specs(&req, &installed);
assert!(
lines.iter().map(|l| l.len() + 1).sum::<usize>() > 32_767,
"the fixture must be big enough to have broken argv"
);
let files = RequirementFiles::write(&lines, &[]).expect("written");
let argv = pip::PipEngine::argv_dry_run(&files.args());
let command_line: usize = argv.iter().map(|a| a.len() + 1).sum();
assert!(
command_line < 1_000,
"command line is {command_line} characters"
);
}
#[test]
fn pip_names_a_file_requirement_by_its_line_and_the_line_comes_back() {
// The sentence pip 26.2.1 printed when the plan went through a file, verbatim but for
// the path, which is this run's own.
let files = RequirementFiles::write(
&["httpcore>=1.0".to_owned(), "httpx==0.23.0".to_owned()],
&[PinnedSpec {
name: PkgName::parse("h11").unwrap(),
version: Version("0.12.0".into()),
}],
)
.expect("written");
let args = files.args();
let (req, con) = (&args[1], &args[3]);
let stderr = format!(
"ERROR: Cannot install -r {req} (line 1) and -r {req} (line 2) because these package \
versions have conflicting dependencies.\n\
ERROR: Could not find a version that satisfies the requirement httpcore>=1.0 \
(from -r {req} (line 1)) (from versions: none)\n\
The user requested (constraint) -c {con} (line 1)\n\
-r {req} (line 9) is not a line this run wrote\n"
);
let out = files.humanize(&stderr);
assert!(
out.contains("Cannot install httpcore>=1.0 and httpx==0.23.0 because"),
"{out}"
);
assert!(
out.contains("requirement httpcore>=1.0 (from versions: none)"),
"{out}"
);
assert!(out.contains("(constraint) h11==0.12.0"), "{out}");
assert!(
out.contains(&format!("-r {req} (line 9)")),
"an unknown line is left alone rather than invented: {out}"
);
// And the impossibility now names the package the user asked for.
let detail = parse::pip_impossible(&out).expect("impossible");
let names: Vec<&str> = detail.packages.iter().map(PkgName::as_str).collect();
assert_eq!(names, ["httpcore", "httpx"]);
}
#[test]
fn the_override_reaches_pip_only_where_pip_has_the_flag() {
let pip = |v: &str| EngineInfo {
id: EngineId::Pip,
version: Some(v.into()),
available: true,
};
// Below 23.0 nothing enforces the marker, and the flag is an unknown option.
assert_eq!(
system_packages_for(&pip("22.3.1")).expect("ok"),
SystemPackages::Protected
);
// 23.0 enforces it and offers no way past.
assert_eq!(
system_packages_for(&pip("23.0")).expect_err("no flag").code,
Code::EnvExternallyManaged
);
for v in ["23.0.1", "24.1b1", "26.2.1"] {
assert_eq!(
system_packages_for(&pip(v)).expect("ok"),
SystemPackages::OverrideAllowed,
"{v}"
);
}
let uv = EngineInfo {
id: EngineId::Uv,
version: Some("0.13.1".into()),
available: true,
};
assert_eq!(
system_packages_for(&uv).expect("ok"),
SystemPackages::OverrideAllowed
);
assert!(SystemPackages::Protected.args().is_empty());
}
}
+382 -79
View File
@@ -15,14 +15,16 @@
//! by the caller from the reverse-dependency graph, not here.
use crate::errors::{Code, PdError, Result};
use crate::model::{Dist, PkgName, Version};
use crate::model::{Dist, EngineId, PkgName, Version};
use crate::plan::{Change, ChangeKind, ImpossibleDetail, ResolutionReport};
/// A yanked release appearing in a plan.
///
/// SP-2: a yank is **not** a failure. Both engines exit 0 and install it, so this is a preview
/// warning row, not an error path (`docs/ERROR-CATALOG.md` PD-PKG-003).
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[derive(
Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize, schemars::JsonSchema,
)]
pub struct YankWarning {
/// The yanked distribution.
pub pkg: PkgName,
@@ -41,14 +43,28 @@ pub struct ParsedPlan {
pub yanked: Vec<YankWarning>,
}
impl ParsedPlan {
/// The report with its yank warnings inside it, where the preview can see them.
///
/// Both adapters used to take `.report` and drop `.yanked`, so the PD-PKG-003 warning both
/// parsers worked to extract never reached a user.
#[must_use]
pub fn into_report(self) -> crate::plan::ResolutionReport {
crate::plan::ResolutionReport {
yanked: self.yanked,
..self.report
}
}
}
// -- pip ---------------------------------------------------------------------
/// Parse pip's `install --dry-run --report -` JSON from stdout.
///
/// # Errors
/// `PD-ENG-002` when stdout is empty, which is what pip leaves behind when it is too old for
/// `--report` **or** when the SP-2 encoding crash struck; `PD-ENG-003` when the JSON is present
/// but not the shape we know.
/// `--report` **or** when the SP-2 encoding crash struck; `PD-ENG-999` when the JSON is present
/// but not the shape we know — not `PD-ENG-003`, whose advice is to switch to pip.
pub fn pip_report(stdout: &str, stderr: &str, installed: &[Dist]) -> Result<ParsedPlan> {
// Checked before anything is parsed, because the SP-2 crash does not leave stdout empty — it
// leaves a *truncated* report, written up to the byte that could not be encoded. That is more
@@ -68,12 +84,8 @@ pub fn pip_report(stdout: &str, stderr: &str, installed: &[Dist]) -> Result<Pars
return Err(PdError::new(Code::EngPipTooOld, "pip produced no report").with_stderr(stderr));
}
let doc: serde_json::Value = serde_json::from_str(trimmed).map_err(|e| {
PdError::new(
Code::EngUvShapeUnknown,
format!("pip report is not JSON: {e}"),
)
})?;
let doc: serde_json::Value = serde_json::from_str(trimmed)
.map_err(|e| shape_error(EngineId::Pip, &format!("pip report is not JSON: {e}")))?;
let version = doc
.get("version")
@@ -81,9 +93,9 @@ pub fn pip_report(stdout: &str, stderr: &str, installed: &[Dist]) -> Result<Pars
.unwrap_or_default();
if version != "1" {
// Fail loudly rather than mis-parsing a future format into a plausible-looking plan.
return Err(PdError::new(
Code::EngUvShapeUnknown,
format!("unsupported pip report version {version:?}; expected \"1\""),
return Err(shape_error(
EngineId::Pip,
&format!("unsupported pip report version {version:?}; expected \"1\""),
));
}
@@ -92,6 +104,7 @@ pub fn pip_report(stdout: &str, stderr: &str, installed: &[Dist]) -> Result<Pars
let mut changes = Vec::new();
let mut yanked = Vec::new();
let mut declared_python = std::collections::BTreeMap::new();
for entry in doc
.get("install")
@@ -106,12 +119,23 @@ pub fn pip_report(stdout: &str, stderr: &str, installed: &[Dist]) -> Result<Pars
let Ok(name) = PkgName::parse(raw_name) else {
continue;
};
let to = Version(
meta.get("version")
.and_then(serde_json::Value::as_str)
.unwrap_or_default()
.to_owned(),
);
let raw_version = meta
.get("version")
.and_then(serde_json::Value::as_str)
.unwrap_or_default();
// pip normalizes report versions to PEP 440; anything else is not something PipDock will
// turn into an argv token, and the change is left out rather than mis-rendered.
if !crate::pep440::is_argv_safe(raw_version) {
continue;
}
let to = Version(raw_version.to_owned());
if let Some(requires) = meta
.get("requires_python")
.and_then(serde_json::Value::as_str)
.filter(|s| !s.trim().is_empty())
{
declared_python.insert(name.clone(), requires.to_owned());
}
if entry.get("is_yanked").and_then(serde_json::Value::as_bool) == Some(true) {
yanked.push(YankWarning {
@@ -144,30 +168,169 @@ pub fn pip_report(stdout: &str, stderr: &str, installed: &[Dist]) -> Result<Pars
changes,
held_back: Vec::new(),
impossible: None,
raw: stdout.to_owned(),
incompatible: Vec::new(),
forced: Vec::new(),
yanked: Vec::new(),
// pip's stderr — its warnings — not the `--report` document on stdout, which carries
// every package's README and is already parsed above.
raw: stderr.to_owned(),
declared_python,
},
yanked,
})
}
/// pip prints the yank reason on stderr, not in the report JSON.
fn yank_reason_from_stderr(stderr: &str, pkg: &PkgName) -> Option<String> {
let flat = flatten(stderr);
let idx = flat.find("Reason for being yanked:")?;
// Only attribute the reason when this package is the one being discussed.
if !flat[..idx].to_ascii_lowercase().contains(pkg.as_str()) {
/// pip's dry run, read **by its exit status first**.
///
/// A zero exit is a plan. A non-zero one is a failure classified from stderr like any other —
/// except an impossibility, which becomes `report.impossible`: **the same shape uv gives**
/// (ARCHITECTURE §3). It used to be a hard error, so under pip one unsatisfiable package in a
/// fifteen-package request failed the whole preview and the per-package *Skip* the preview offers
/// under uv never appeared.
///
/// # Errors
/// The classified engine failure; `PD-INT-001` for the SP-2 encoding crash whatever the exit.
pub fn pip_resolution(
exit_code: Option<i32>,
stdout: &str,
stderr: &str,
installed: &[Dist],
) -> Result<ParsedPlan> {
// The SP-2 crash exits 2, and is PipDock's bug rather than pip's; `pip_report` says so.
if exit_code == Some(0) || stderr.contains("UnicodeEncodeError") {
return pip_report(stdout, stderr, installed);
}
if let Some(detail) = pip_impossible(stderr) {
return Ok(impossible_plan(detail, stderr));
}
Err(PdError::from_engine_stderr(stderr))
}
/// A plan that is nothing but its impossibility.
fn impossible_plan(detail: ImpossibleDetail, text: &str) -> ParsedPlan {
ParsedPlan {
report: ResolutionReport {
impossible: Some(detail),
raw: text.to_owned(),
..ResolutionReport::default()
},
yanked: Vec::new(),
}
}
/// pip's ResolutionImpossible, read into the shape uv's impossibility already has.
///
/// pip runs with `--quiet`, so its whole explanation is one line — `ERROR: Cannot install A and B
/// because these package versions have conflicting dependencies.` — followed by the
/// ResolutionImpossible pointer. The packages are the requirements that line names. `None` when
/// the stderr is not an impossibility at all, so the caller classifies it instead.
#[must_use]
pub fn pip_impossible(stderr: &str) -> Option<crate::plan::ImpossibleDetail> {
if crate::errors::classify_stderr(stderr) != crate::errors::Code::ResImpossible {
return None;
}
let tail = flat[idx + "Reason for being yanked:".len()..].trim();
Some(
tail.trim_end_matches(|c: char| c == '.' || c.is_whitespace())
.to_owned(),
)
let line = stderr
.lines()
.map(str::trim)
.find(|l| l.contains("Cannot install "))
.or_else(|| {
stderr
.lines()
.map(str::trim)
.find(|l| l.starts_with("ERROR:"))
})?;
let explanation = line.trim_start_matches("ERROR:").trim().to_owned();
let mut packages = Vec::new();
if let Some(rest) = explanation.strip_prefix("Cannot install ")
&& let Some((named, _)) = rest.split_once(" because")
{
for token in named.split([',']).flat_map(|t| t.split(" and ")) {
let token = token.trim();
let end = token
.find(['=', '<', '>', '!', '~', '[', ' '])
.unwrap_or(token.len());
if let Ok(name) = PkgName::parse(&token[..end])
&& !packages.contains(&name)
{
packages.push(name);
}
}
}
Some(crate::plan::ImpossibleDetail {
packages,
explanation,
})
}
/// pip prints the yank reason on stderr, not in the report JSON:
///
/// ```text
/// WARNING: The candidate selected for download or install is a yanked version: 'urllib3' candidate (…)
/// Reason for being yanked: Truncated response bodies when streaming a large compressed body.
/// ```
///
/// The reason is **that one line**, and it belongs to the package the warning above it names.
/// Flattening the whole stderr first made it run to the end of the output — over pip's
/// `[notice]` lines, which carry the user's home directory — and gave the first of two yanked
/// packages both reasons and the second none.
fn yank_reason_from_stderr(stderr: &str, pkg: &PkgName) -> Option<String> {
let mut current: Option<PkgName> = None;
for line in stderr.lines().map(str::trim) {
if let Some((_, rest)) = line.split_once("is a yanked version: '") {
current = rest
.split_once('\'')
.and_then(|(name, _)| PkgName::parse(name).ok());
continue;
}
if let Some(reason) = line.strip_prefix("Reason for being yanked:")
&& current.as_ref() == Some(pkg)
{
let reason = reason
.trim()
.trim_end_matches(|c: char| c == '.' || c.is_whitespace());
return (!reason.is_empty()).then(|| reason.to_owned());
}
}
None
}
// -- uv ----------------------------------------------------------------------
/// Parse uv's dry-run plan.
/// uv's dry run, read **by its exit status first** (C3).
///
/// The adapter used to hand every outcome to [`uv_plan`], which looked for the words of a plan:
/// a build that failed still printed `Resolved 1 package`, so it parsed as an empty plan and the
/// preview said *no changes* for a package that could not be built; a refused connection matched
/// nothing and was reported as a uv newer than PipDock; an unknown name came through the resolver
/// as an impossibility. uv exits non-zero on every one of them, so a non-zero exit is classified
/// like any other engine failure, and only an impossibility becomes a report.
///
/// # Errors
/// The classified engine failure, or [`uv_plan`]'s for a zero exit it cannot read.
pub fn uv_resolution(
exit_code: Option<i32>,
stdout: &str,
stderr: &str,
installed: &[Dist],
) -> Result<ParsedPlan> {
if exit_code == Some(0) {
return uv_plan(stdout, stderr, installed);
}
let text = if stderr.trim().is_empty() {
stdout
} else {
stderr
};
if crate::errors::classify_stderr(text) == Code::ResImpossible
&& let Some(detail) = uv_no_solution(text)
{
return Ok(impossible_plan(detail, text));
}
Err(PdError::from_engine_stderr(text))
}
/// Parse uv's dry-run plan — a run that **exited zero**; [`uv_resolution`] decides that.
///
/// **The plan arrives on stderr** (SP-1); stdout is empty for every uv fixture captured. The
/// format is a decorated, hard-wrapped text block:
@@ -192,18 +355,6 @@ pub fn uv_plan(stdout: &str, stderr: &str, installed: &[Dist]) -> Result<ParsedP
stderr
};
if let Some(detail) = uv_no_solution(text) {
return Ok(ParsedPlan {
report: ResolutionReport {
changes: Vec::new(),
held_back: Vec::new(),
impossible: Some(detail),
raw: text.to_owned(),
},
yanked: Vec::new(),
});
}
let recognized = [
"Would make no changes",
"Would install",
@@ -244,7 +395,16 @@ pub fn uv_plan(stdout: &str, stderr: &str, installed: &[Dist]) -> Result<ParsedP
let Ok(name) = PkgName::parse(name.trim()) else {
continue;
};
let version = Version(version.trim().to_owned());
// `+ pkg==0.1.0 (from file:///…)` for a local or direct-URL source: the version is
// the first token, and the rest is uv explaining where it comes from. Kept whole,
// it reached argv as `pkg==0.1.0 (from file:///…)`.
let Some(version) = version.split_whitespace().next() else {
continue;
};
if !crate::pep440::is_argv_safe(version) {
continue;
}
let version = Version(version.to_owned());
if sign == "-" {
removals.insert(name, version);
} else {
@@ -281,17 +441,28 @@ pub fn uv_plan(stdout: &str, stderr: &str, installed: &[Dist]) -> Result<ParsedP
changes,
held_back: Vec::new(),
impossible: None,
incompatible: Vec::new(),
forced: Vec::new(),
yanked: Vec::new(),
raw: text.to_owned(),
declared_python: Default::default(),
},
yanked: uv_yank_warnings(text),
})
}
/// uv's `No solution found` block, with its wrapping undone.
/// uv's `No solution found` block, with its wrapping and its decoration undone.
///
/// uv 0.11 draws it with miette (`×`, `╰─▶`) and uv 0.13 with `error:` / `cause:` labels; the
/// preview shows the sentence, not either rendering, so both read
/// `No solution found when resolving dependencies: Because …`.
fn uv_no_solution(text: &str) -> Option<ImpossibleDetail> {
let flat = flatten(text);
let flat = crate::errors::catalog::collapse_whitespace(&strip_uv_decoration(text));
let idx = flat.find("No solution found when resolving")?;
let explanation = flat[idx..].trim().to_owned();
let explanation = flat[idx..]
.trim()
.replace("dependencies: :", "dependencies:")
.replace(" : ", ": ");
// uv names the packages inside prose ("Because httpx==0.23.0 depends on httpcore>=0.15.0"),
// so pull out the `name==version` and `name>=…` tokens it mentions.
@@ -322,7 +493,10 @@ fn uv_no_solution(text: &str) -> Option<ImpossibleDetail> {
/// `warning: \`urllib3==2.0.0\` is yanked (reason: "…")`
fn uv_yank_warnings(text: &str) -> Vec<YankWarning> {
let mut out = Vec::new();
for line in flatten(text).split("warning:").skip(1) {
for line in crate::errors::catalog::collapse_whitespace(text)
.split("warning:")
.skip(1)
{
if !line.contains("is yanked") {
continue;
}
@@ -363,10 +537,10 @@ fn uv_yank_warnings(text: &str) -> Vec<YankWarning> {
/// the reverse-dependency graph is built from the probe and not from here.
///
/// # Errors
/// `PD-ENG-003` when the output is not the expected JSON array.
pub fn list_json(stdout: &str) -> Result<Vec<Dist>> {
/// [`shape_error`] when the output is not the expected JSON array.
pub fn list_json(stdout: &str, engine: EngineId) -> Result<Vec<Dist>> {
let items: Vec<serde_json::Value> = serde_json::from_str(stdout.trim())
.map_err(|e| PdError::new(Code::EngUvShapeUnknown, format!("list output: {e}")))?;
.map_err(|e| shape_error(engine, &format!("list output: {e}")))?;
Ok(items
.into_iter()
.filter_map(|v| {
@@ -387,10 +561,10 @@ pub fn list_json(stdout: &str) -> Result<Vec<Dist>> {
/// Parse `list --outdated --format=json`.
///
/// # Errors
/// `PD-ENG-003` when the output is not the expected JSON array.
pub fn outdated_json(stdout: &str) -> Result<Vec<crate::model::OutdatedDist>> {
/// [`shape_error`] when the output is not the expected JSON array.
pub fn outdated_json(stdout: &str, engine: EngineId) -> Result<Vec<crate::model::OutdatedDist>> {
let items: Vec<serde_json::Value> = serde_json::from_str(stdout.trim())
.map_err(|e| PdError::new(Code::EngUvShapeUnknown, format!("outdated output: {e}")))?;
.map_err(|e| shape_error(engine, &format!("outdated output: {e}")))?;
Ok(items
.into_iter()
.filter_map(|v| {
@@ -403,6 +577,19 @@ pub fn outdated_json(stdout: &str) -> Result<Vec<crate::model::OutdatedDist>> {
.collect())
}
/// Output in a shape this adapter does not know.
///
/// `PD-ENG-003` means "this uv is newer than PipDock understands — switch to pip for now", which
/// is advice only uv can earn. pip's own unreadable output was reported with it too, telling a pip
/// user to switch to the engine they were already using; it is `PD-ENG-999` instead.
fn shape_error(engine: EngineId, detail: &str) -> PdError {
let code = match engine {
EngineId::Uv => Code::EngUvShapeUnknown,
EngineId::Pip => Code::EngUnclassified,
};
PdError::new(code, detail.to_owned())
}
/// Normalize `pip check` / `uv pip check` output.
///
/// `ok` is the process's own verdict: both engines exit non-zero when they find problems, which
@@ -414,14 +601,20 @@ pub fn check_text(stdout: &str, ok: bool) -> crate::model::CheckReport {
let mut findings = Vec::new();
for line in stdout.lines() {
let line = line.trim();
// "apiclient 1.4 requires requests<2.31, but you have requests 2.32.3 which is incompatible."
let Some((head, _)) = line.split_once(" requires ") else {
continue;
// Three shapes, each taken from a real broken environment:
// pip "anyio 3.7.1 requires sniffio, which is not installed."
// pip "httpx 0.23.0 has requirement httpcore<0.16.0,>=0.15.0, but you have httpcore 1.0.9."
// uv "The package `httpx` requires `httpcore>=0.15.0,<0.16.0`, but `1.0.9` is installed"
// Only the first was read: pip's version conflicts — the case a post-run check exists
// for — were dropped, and every uv finding was filed under a package called "the".
let name = if let Some(rest) = line.strip_prefix("The package `") {
rest.split_once('`').map(|(name, _)| name)
} else if line.contains(" requires ") || line.contains(" has requirement ") {
line.split_whitespace().next()
} else {
None
};
let Some(name) = head.split_whitespace().next() else {
continue;
};
let Ok(pkg) = PkgName::parse(name) else {
let Some(Ok(pkg)) = name.map(PkgName::parse) else {
continue;
};
findings.push(crate::model::CheckFinding {
@@ -432,29 +625,31 @@ pub fn check_text(stdout: &str, ok: bool) -> crate::model::CheckReport {
crate::model::CheckReport {
ok: ok && findings.is_empty(),
findings,
error: None,
}
}
// -- shared ------------------------------------------------------------------
/// Collapse wrapping and CRLF so multi-word phrases can be found.
///
/// uv hard-wraps its diagnostics mid-sentence, so a literal search for a phrase that spans the
/// wrap point finds nothing. The same normalization is applied by the error classifiers, and for
/// the same reason.
fn flatten(text: &str) -> String {
/// uv's diagnostic decoration, removed line by line: miette's box-drawing glyphs (uv ≤ 0.12) and
/// the `cause:` labels that replaced them (0.13). A `cause:` becomes a colon after the line it
/// explains.
fn strip_uv_decoration(text: &str) -> String {
let mut out = String::with_capacity(text.len());
let mut in_space = false;
for ch in text.chars() {
if ch.is_whitespace() {
in_space = true;
for line in text.lines() {
let trimmed = line
.trim()
.trim_start_matches(['×', '╰', '├', '─', '▶', '│', ' ']);
if let Some(rest) = trimmed.strip_prefix("cause:") {
let ends_with_colon = out.trim_end().ends_with(':');
let kept = out.trim_end().len();
out.truncate(kept);
out.push_str(if ends_with_colon { " " } else { ": " });
out.push_str(rest.trim_start());
} else {
if in_space && !out.is_empty() {
out.push(' ');
}
in_space = false;
out.push(ch);
out.push_str(trimmed);
}
out.push('\n');
}
out
}
@@ -532,7 +727,8 @@ mod tests {
fn an_unknown_pip_report_version_fails_loudly() {
let err = pip_report(r#"{"version":"2","install":[]}"#, "", &[])
.expect_err("future format must not be guessed at");
assert_eq!(err.code, Code::EngUvShapeUnknown);
// Not PD-ENG-003, whose advice is to switch to pip.
assert_eq!(err.code, Code::EngUnclassified);
}
#[test]
@@ -575,7 +771,7 @@ mod tests {
╰─▶ Because httpx==0.23.0 depends on httpcore>=0.15.0,<0.16.0 and you\r\n \
require httpcore>=1.0, we can conclude that your requirements and\r\n \
httpx==0.23.0 are incompatible.\r\n";
let plan = uv_plan("", text, &[]).expect("parse");
let plan = uv_resolution(Some(1), "", text, &[]).expect("parse");
let detail = plan.report.impossible.expect("impossible detail");
// The wrapping must be undone, or the explanation reads as broken fragments in the UI.
@@ -665,4 +861,111 @@ mod tests {
"a yank must not make the plan dirty"
);
}
#[test]
fn both_uv_renderings_explain_an_impossibility_in_the_same_words() {
let v011 = " × No solution found when resolving dependencies:\n \
╰─▶ Because a==1.0 depends on b<2 and you require b>=2, we can conclude\n \
that your requirements are unsatisfiable.\n";
let v013 = "error: No solution found when resolving dependencies\n \
cause: Because a==1.0 depends on b<2 and you require b>=2, we can conclude\n \
that your requirements are unsatisfiable.\n";
let explain = |text: &str| {
uv_resolution(Some(1), "", text, &[])
.expect("an impossibility is a report")
.report
.impossible
.expect("impossible")
.explanation
};
let expected = "No solution found when resolving dependencies: Because a==1.0 depends \
on b<2 and you require b>=2, we can conclude that your requirements are \
unsatisfiable.";
assert_eq!(explain(v011), expected);
assert_eq!(explain(v013), expected);
}
#[test]
fn a_failed_uv_run_that_still_says_resolved_is_not_an_empty_plan() {
// C3: uv prints "Resolved 1 package" before a build fails, which is one of the words
// `uv_plan` looks for — so a package that could not be built previewed as "no changes".
let text = "Resolved 1 package in 1.2s\n Building numpy==1.19.5\n\
error: Failed to build `numpy==1.19.5`\n \
cause: The build backend returned an error\n";
let err = uv_resolution(Some(1), "", text, &[]).expect_err("a failure");
assert_eq!(err.code, Code::BldBackendFailed);
}
#[test]
fn two_yanked_packages_each_get_their_own_reason_and_nothing_else() {
let doc = r#"{"version":"1","install":[
{"requested":true,"is_yanked":true,"metadata":{"name":"urllib3","version":"2.0.0"}},
{"requested":true,"is_yanked":true,"metadata":{"name":"idna","version":"3.5"}}
]}"#;
let stderr = "WARNING: The candidate selected for download or install is a yanked \
version: 'urllib3' candidate (version 2.0.0 at https://x/urllib3.whl)\n\
Reason for being yanked: Truncated response bodies.\n\
WARNING: The candidate selected for download or install is a yanked \
version: 'idna' candidate (version 3.5 at https://x/idna.whl)\n\
Reason for being yanked: Bad wheel\n\
[notice] To update, run: C:\\Users\\someone\\venv\\python.exe -m pip \
install --upgrade pip\n";
let plan = pip_report(doc, stderr, &[]).expect("parse");
let reason = |n: &str| {
plan.yanked
.iter()
.find(|y| y.pkg.as_str() == n)
.and_then(|y| y.reason.clone())
};
assert_eq!(
reason("urllib3").as_deref(),
Some("Truncated response bodies")
);
assert_eq!(reason("idna").as_deref(), Some("Bad wheel"));
}
#[test]
fn pip_and_uv_check_findings_name_the_package_that_is_broken() {
// Captured from one broken environment, pip 26.2.1 and uv 0.13.1.
let pip = "anyio 3.7.1 requires sniffio, which is not installed.\n\
httpx 0.23.0 requires sniffio, which is not installed.\n\
httpcore 1.0.9 has requirement h11>=0.16, but you have h11 0.12.0.\n\
httpx 0.23.0 has requirement httpcore<0.16.0,>=0.15.0, but you have httpcore 1.0.9.\n";
let uv = "Checked 8 packages in 174ms\nFound 4 incompatibilities\n\
The package `httpx` requires `sniffio`, but it's not installed\n\
The package `httpx` requires `httpcore>=0.15.0,<0.16.0`, but `1.0.9` is installed\n\
The package `httpcore` requires `h11>=0.16`, but `0.12.0` is installed\n\
The package `anyio` requires `sniffio>=1.1`, but it's not installed\n";
let names = |text: &str| -> Vec<String> {
let report = check_text(text, false);
assert!(!report.ok);
report.findings.iter().map(|f| f.pkg.to_string()).collect()
};
assert_eq!(names(pip), ["anyio", "httpx", "httpcore", "httpx"]);
assert_eq!(names(uv), ["httpx", "httpx", "httpcore", "anyio"]);
}
#[test]
fn unreadable_pip_output_does_not_blame_uv() {
// PD-ENG-003 tells the user to switch to pip; under pip that is advice to do nothing.
let err = pip_report("not json", "", &[]).expect_err("unreadable");
assert_eq!(err.code, Code::EngUnclassified);
assert_eq!(
list_json("not json", EngineId::Pip).expect_err("pip").code,
Code::EngUnclassified
);
assert_eq!(
list_json("not json", EngineId::Uv).expect_err("uv").code,
Code::EngUvShapeUnknown
);
}
#[test]
fn a_uv_line_with_a_source_suffix_keeps_only_the_version() {
// `+ pkg==0.1.0 (from file:///…)` reached argv whole as the version.
let text = "Resolved 1 package in 5ms\nWould install 1 package\n + localpkg==0.1.0 (from file:///C:/src/localpkg)\n";
let plan = uv_plan("", text, &[]).expect("parses");
assert_eq!(plan.report.changes.len(), 1);
assert_eq!(plan.report.changes[0].to.0, "0.1.0");
}
}
+108 -45
View File
@@ -1,20 +1,20 @@
//! The pip adapter: `<env-python> -m pip …`.
//!
//! Command mapping is fixed by `docs/DATA-FLOW.md` §7. Implementation lands in M1; the argv
//! builders below are already exercised by tests because they are the surface SECURITY §2 cares
//! about — nothing else in this file may construct engine arguments.
//! Command mapping is fixed by `docs/DATA-FLOW.md` §7. The argv builders below are the surface
//! SECURITY §2 cares about, and are tested as such — nothing else in this file may construct
//! engine arguments.
use async_trait::async_trait;
use crate::errors::{Code, PdError, Result};
use crate::exec::Command;
use crate::exec::{Command, watchdog};
use crate::model::{
CheckReport, Dist, EngineId, EngineInfo, ExecMode, OutdatedDist, PinnedSpec, PkgName, PyEnv,
StepResult,
};
use crate::plan::{PlanRequest, ResolutionReport};
use super::{Engine, ProgressSink, single_pkg};
use super::{Engine, InstallSet, ProgressSink, ResolveCtx, SystemPackages, single_pkg};
/// Drives pip as a subprocess.
#[derive(Debug, Clone, Copy, Default)]
@@ -44,12 +44,35 @@ impl PipEngine {
]
}
/// argv for an install from requirement files. The PEP 668 flag only when `system` says so.
#[must_use]
pub fn argv_install(files: &[String], system: SystemPackages) -> Vec<String> {
let mut argv = vec!["-m".to_owned(), "pip".to_owned(), "install".to_owned()];
argv.extend(system.args().iter().map(|a| (*a).to_owned()));
argv.extend(files.iter().cloned());
argv
}
/// argv for `pip uninstall -y`. pip ≥ 23.0.1 refuses this in a managed environment too.
#[must_use]
pub fn argv_uninstall(names: &[PkgName], system: SystemPackages) -> Vec<String> {
let mut argv = vec![
"-m".to_owned(),
"pip".to_owned(),
"uninstall".to_owned(),
"-y".to_owned(),
];
argv.extend(system.args().iter().map(|a| (*a).to_owned()));
argv.extend(names.iter().map(ToString::to_string));
argv
}
/// argv for the dry-run resolve, whose JSON report goes to stdout.
///
/// `requirements` comes from [`super::plan_argv_specs`] and carries all three groups: bare
/// names to move, explicit installs, and the pinned guard set.
/// `files` is [`super::RequirementFiles::args`] over [`super::plan_argv_specs`], which carries
/// all three groups: bare names to move, explicit installs, and the pinned guard set.
#[must_use]
pub fn argv_dry_run(requirements: &[String]) -> Vec<String> {
pub fn argv_dry_run(files: &[String]) -> Vec<String> {
let mut argv = vec![
"-m".into(),
"pip".into(),
@@ -64,7 +87,7 @@ impl PipEngine {
"--report".into(),
"-".into(),
];
argv.extend(requirements.iter().cloned());
argv.extend(files.iter().cloned());
argv
}
@@ -91,6 +114,7 @@ impl Engine for PipEngine {
async fn info(&self, env: &PyEnv) -> EngineInfo {
let out = Command::python(&env.interpreter)
.args(["-m", "pip", "--version"])
.timeout(watchdog::QUERY)
.run()
.await;
match out {
@@ -111,72 +135,78 @@ impl Engine for PipEngine {
async fn list_installed(&self, env: &PyEnv) -> Result<Vec<Dist>> {
let out = Command::python(&env.interpreter)
.args(Self::argv_list())
.timeout(watchdog::QUERY)
.run()
.await?;
if !out.ok() {
return Err(out.into_error());
}
super::parse::list_json(&out.stdout)
super::parse::list_json(&out.stdout, EngineId::Pip)
}
async fn list_outdated(&self, env: &PyEnv) -> Result<Vec<OutdatedDist>> {
let out = Command::python(&env.interpreter)
.args(Self::argv_outdated())
.timeout(watchdog::OUTDATED)
.run()
.await?;
if !out.ok() {
return Err(out.into_error());
}
super::parse::outdated_json(&out.stdout)
super::parse::outdated_json(&out.stdout, EngineId::Pip)
}
async fn resolve(&self, env: &PyEnv, req: &PlanRequest) -> Result<ResolutionReport> {
async fn resolve(
&self,
env: &PyEnv,
req: &PlanRequest,
ctx: &ResolveCtx,
) -> Result<ResolutionReport> {
// SP-1: the installed set must be restated or the resolver ignores it and plans an
// upgrade that breaks installed dependents. The caller assembles that set into `req`.
let installed = self.list_installed(env).await?;
let requirements = super::plan_argv_specs(req, &installed);
let out = Command::python(&env.interpreter)
.args(Self::argv_dry_run(&requirements))
let lines = super::plan_lines(req, &installed, &ctx.adjust);
let files = super::RequirementFiles::write(&lines, &[])?;
let mut out = Command::python(&env.interpreter)
.args(Self::argv_dry_run(&files.args()))
.timeout(watchdog::RESOLVE)
.cancel(ctx.cancel.clone())
.run()
.await?;
if !out.ok() {
return Err(out.into_error());
}
super::parse::pip_report(&out.stdout, &out.stderr, &installed).map(|p| p.report)
out.stderr = files.humanize(&out.stderr);
super::parse::pip_resolution(out.code, &out.stdout, &out.stderr, &installed)
.map(super::parse::ParsedPlan::into_report)
}
async fn install(
&self,
env: &PyEnv,
specs: &[PinnedSpec],
set: &InstallSet,
mode: ExecMode,
sink: ProgressSink,
) -> Result<StepResult> {
let mut argv = vec!["-m".to_owned(), "pip".to_owned(), "install".to_owned()];
argv.extend(specs.iter().map(PinnedSpec::to_requirement));
let out = Command::python(&env.interpreter)
.args(argv)
let requirements: Vec<String> = set.specs.iter().map(PinnedSpec::to_requirement).collect();
let files = super::RequirementFiles::write(&requirements, &set.constraints)?;
let mut out = Command::python(&env.interpreter)
.args(Self::argv_install(&files.args(), set.system))
.timeout(watchdog::INSTALL)
.cancel(sink.cancel.clone())
.run_streaming(&sink, single_pkg(specs), mode)
.run_streaming(&sink, single_pkg(&set.specs), mode)
.await?;
Ok(super::step_result(specs, &out))
out.stderr = files.humanize(&out.stderr);
Ok(super::step_result(&set.specs, &out))
}
async fn uninstall(
&self,
env: &PyEnv,
names: &[PkgName],
system: SystemPackages,
sink: ProgressSink,
) -> Result<StepResult> {
let mut argv = vec![
"-m".to_owned(),
"pip".to_owned(),
"uninstall".to_owned(),
"-y".to_owned(),
];
argv.extend(names.iter().map(ToString::to_string));
let out = Command::python(&env.interpreter)
.args(argv)
.args(Self::argv_uninstall(names, system))
.timeout(watchdog::INSTALL)
.cancel(sink.cancel.clone())
.run_streaming(&sink, names.first().cloned(), ExecMode::Isolated)
.await?;
@@ -186,6 +216,7 @@ impl Engine for PipEngine {
async fn check(&self, env: &PyEnv) -> Result<CheckReport> {
let out = Command::python(&env.interpreter)
.args(Self::argv_check())
.timeout(watchdog::QUERY)
.run()
.await?;
// `pip check` exits non-zero when it finds problems, which is a successful check with
@@ -196,6 +227,7 @@ impl Engine for PipEngine {
async fn freeze(&self, env: &PyEnv) -> Result<String> {
let out = Command::python(&env.interpreter)
.args(Self::argv_freeze())
.timeout(watchdog::QUERY)
.run()
.await?;
if !out.ok() {
@@ -257,6 +289,7 @@ impl PipEngine {
async fn install_latest_pip(interpreter: &std::path::Path) -> Result<crate::exec::Output> {
Command::python(interpreter)
.args(["-m", "pip", "install", "-U", "pip"])
.timeout(watchdog::INSTALL)
.run()
.await
}
@@ -290,6 +323,7 @@ impl PipEngine {
async fn ensurepip(interpreter: &std::path::Path) -> Result<()> {
let out = Command::python(interpreter)
.args(["-m", "ensurepip", "--upgrade"])
.timeout(watchdog::INSTALL)
.run()
.await?;
if out.ok() {
@@ -331,8 +365,9 @@ mod tests {
}
#[test]
fn requirements_are_appended_as_separate_argv_entries() {
// One token per argument is what makes shell quoting irrelevant (SECURITY §2).
fn requirements_reach_pip_as_a_file_not_as_argv() {
// A requirements file keeps the command line a constant length whatever the size of the
// environment, and each path is still exactly one argv entry (SECURITY §2).
let specs = [
PinnedSpec {
name: PkgName::parse("httpx").unwrap(),
@@ -344,15 +379,16 @@ mod tests {
},
];
let requirements: Vec<String> = specs.iter().map(PinnedSpec::to_requirement).collect();
let argv = PipEngine::argv_dry_run(&requirements);
assert_eq!(
&argv[argv.len() - 2..],
["httpx==0.28.1", "requests==2.32.3"]
);
assert!(
argv.iter().all(|a| !a.contains(' ')),
"no argv entry may bundle multiple arguments"
);
let files = super::super::RequirementFiles::write(&requirements, &specs[..1])
.expect("files are written");
let argv = PipEngine::argv_dry_run(&files.args());
assert_eq!(&argv[argv.len() - 4..argv.len() - 3], ["-r"]);
assert_eq!(&argv[argv.len() - 2..argv.len() - 1], ["-c"]);
let written =
std::fs::read_to_string(&argv[argv.len() - 3]).expect("requirements file exists");
assert_eq!(written, "httpx==0.28.1\nrequests==2.32.3\n");
let constrained = std::fs::read_to_string(&argv[argv.len() - 1]).expect("constraints");
assert_eq!(constrained, "httpx==0.28.1\n");
}
#[test]
@@ -386,4 +422,31 @@ mod tests {
// Not PD-ENG-001: reaching the spawn would mean the guard ran too late.
assert!(!err.message.contains("could not run"), "{}", err.message);
}
#[test]
fn the_pep668_flag_appears_only_when_the_override_applies() {
let files = ["-r".to_owned(), "req.txt".to_owned()];
let names = [PkgName::parse("idna").unwrap()];
for (system, expected) in [
(SystemPackages::Protected, 0),
(SystemPackages::OverrideAllowed, 1),
] {
for argv in [
PipEngine::argv_install(&files, system),
PipEngine::argv_uninstall(&names, system),
] {
let count = argv
.iter()
.filter(|a| *a == "--break-system-packages")
.count();
assert_eq!(count, expected, "{system:?}: {argv:?}");
}
}
// pip's dry run is exempt from PEP 668 (`--dry-run --report`) and is never given it.
assert!(
!PipEngine::argv_dry_run(&files)
.iter()
.any(|a| a == "--break-system-packages")
);
}
}
+97 -34
View File
@@ -7,8 +7,10 @@
//!
//! Two consequences shape this adapter:
//!
//! - `resolve` parses the plan whether or not uv exited zero, because its failure message is the
//! most useful thing it produces.
//! - `resolve` is decided by uv's exit status first: zero is a plan; a non-zero exit whose text
//! says no solution exists is a report (`impossible`), and anything else — a build failure, an
//! unreachable index — is classified as the failure it is. Parsing the plan regardless of the
//! exit status is how a failed build used to read as "nothing to change" (C3).
//! - Every plan restates the installed set as explicit requirements. Without that, uv upgrades
//! straight past an installed package's constraint and exits 0 — see [`super::plan_requirements`].
//!
@@ -18,14 +20,14 @@
use async_trait::async_trait;
use crate::errors::Result;
use crate::exec::Command;
use crate::exec::{Command, watchdog};
use crate::model::{
CheckReport, Dist, EngineId, EngineInfo, ExecMode, OutdatedDist, PinnedSpec, PkgName, PyEnv,
StepResult,
};
use crate::plan::{PlanRequest, ResolutionReport};
use super::{Engine, ProgressSink, single_pkg};
use super::{Engine, InstallSet, ProgressSink, ResolveCtx, SystemPackages, single_pkg};
/// Drives uv as a subprocess.
#[derive(Debug, Clone, Copy, Default)]
@@ -49,7 +51,7 @@ impl UvEngine {
/// `requirements` comes from [`super::plan_argv_specs`] and carries all three groups: bare
/// names to move, explicit installs, and the pinned guard set.
#[must_use]
pub fn argv_dry_run(python: &str, requirements: &[String]) -> Vec<String> {
pub fn argv_dry_run(python: &str, files: &[String]) -> Vec<String> {
let mut argv = vec![
"pip".into(),
"install".into(),
@@ -58,7 +60,35 @@ impl UvEngine {
"--python".into(),
python.into(),
];
argv.extend(requirements.iter().cloned());
argv.extend(files.iter().cloned());
argv
}
/// argv for an install from requirement files. The PEP 668 flag only when `system` says so.
#[must_use]
pub fn argv_install(python: &str, files: &[String], system: SystemPackages) -> Vec<String> {
let mut argv = vec![
"pip".to_owned(),
"install".to_owned(),
"--python".to_owned(),
python.to_owned(),
];
argv.extend(system.args().iter().map(|a| (*a).to_owned()));
argv.extend(files.iter().cloned());
argv
}
/// argv for `uv pip uninstall`, which also refuses a managed environment without the flag.
#[must_use]
pub fn argv_uninstall(python: &str, names: &[PkgName], system: SystemPackages) -> Vec<String> {
let mut argv = vec![
"pip".to_owned(),
"uninstall".to_owned(),
"--python".to_owned(),
python.to_owned(),
];
argv.extend(system.args().iter().map(|a| (*a).to_owned()));
argv.extend(names.iter().map(ToString::to_string));
argv
}
@@ -85,7 +115,12 @@ impl Engine for UvEngine {
async fn info(&self, _env: &PyEnv) -> EngineInfo {
// uv is a standalone binary on PATH, not a module inside the environment, so this is the
// one engine query that does not involve the interpreter.
match Command::new("uv").arg("--version").run().await {
match Command::new("uv")
.arg("--version")
.timeout(watchdog::QUERY)
.run()
.await
{
Ok(o) if o.ok() => EngineInfo {
id: EngineId::Uv,
// "uv 0.11.32 (3010295ae 2026-07-23 x86_64-pc-windows-msvc)" -> "0.11.32"
@@ -104,12 +139,13 @@ impl Engine for UvEngine {
let python = env.interpreter.display().to_string();
let out = Command::new("uv")
.args(Self::argv_list(&python))
.timeout(watchdog::QUERY)
.run()
.await?;
if !out.ok() {
return Err(out.into_error());
}
super::parse::list_json(&out.stdout)
super::parse::list_json(&out.stdout, EngineId::Uv)
}
async fn list_outdated(&self, env: &PyEnv) -> Result<Vec<OutdatedDist>> {
@@ -123,68 +159,72 @@ impl Engine for UvEngine {
"--python".to_owned(),
python,
])
.timeout(watchdog::OUTDATED)
.run()
.await?;
if !out.ok() {
return Err(out.into_error());
}
super::parse::outdated_json(&out.stdout)
super::parse::outdated_json(&out.stdout, EngineId::Uv)
}
async fn resolve(&self, env: &PyEnv, req: &PlanRequest) -> Result<ResolutionReport> {
async fn resolve(
&self,
env: &PyEnv,
req: &PlanRequest,
ctx: &ResolveCtx,
) -> Result<ResolutionReport> {
// SP-1: without the installed set restated, uv plans an upgrade that breaks installed
// dependents and exits 0. Identical requirement to pip's adapter.
let installed = self.list_installed(env).await?;
let requirements = super::plan_argv_specs(req, &installed);
let lines = super::plan_lines(req, &installed, &ctx.adjust);
let files = super::RequirementFiles::write(&lines, &[])?;
let python = env.interpreter.display().to_string();
let mut argv = Self::argv_dry_run(&python, &files.args());
// uv refuses even a dry run in a managed environment without it (verified, uv 0.13.1).
argv.extend(ctx.system.args().iter().map(|a| (*a).to_owned()));
let out = Command::new("uv")
.args(Self::argv_dry_run(&python, &requirements))
.args(argv)
.timeout(watchdog::RESOLVE)
.cancel(ctx.cancel.clone())
.run()
.await?;
// uv exits non-zero on an unsatisfiable set, but its message is the most useful thing it
// produces (SP-1), so the plan is parsed either way and the parser decides.
super::parse::uv_plan(&out.stdout, &out.stderr, &installed).map(|p| p.report)
// uv exits non-zero on an unsatisfiable set, and its explanation is the most useful thing
// it produces (SP-1) — so the exit decides between a plan, an impossibility and a failure.
super::parse::uv_resolution(out.code, &out.stdout, &out.stderr, &installed)
.map(super::parse::ParsedPlan::into_report)
}
async fn install(
&self,
env: &PyEnv,
specs: &[PinnedSpec],
set: &InstallSet,
mode: ExecMode,
sink: ProgressSink,
) -> Result<StepResult> {
let python = env.interpreter.display().to_string();
let mut argv = vec![
"pip".to_owned(),
"install".to_owned(),
"--python".to_owned(),
python,
];
argv.extend(specs.iter().map(PinnedSpec::to_requirement));
let requirements: Vec<String> = set.specs.iter().map(PinnedSpec::to_requirement).collect();
let files = super::RequirementFiles::write(&requirements, &set.constraints)?;
let out = Command::new("uv")
.args(argv)
.args(Self::argv_install(&python, &files.args(), set.system))
.timeout(watchdog::INSTALL)
.cancel(sink.cancel.clone())
.run_streaming(&sink, single_pkg(specs), mode)
.run_streaming(&sink, single_pkg(&set.specs), mode)
.await?;
Ok(super::step_result(specs, &out))
Ok(super::step_result(&set.specs, &out))
}
async fn uninstall(
&self,
env: &PyEnv,
names: &[PkgName],
system: SystemPackages,
sink: ProgressSink,
) -> Result<StepResult> {
let python = env.interpreter.display().to_string();
let mut argv = vec![
"pip".to_owned(),
"uninstall".to_owned(),
"--python".to_owned(),
python,
];
argv.extend(names.iter().map(ToString::to_string));
let out = Command::new("uv")
.args(argv)
.args(Self::argv_uninstall(&python, names, system))
.timeout(watchdog::INSTALL)
.cancel(sink.cancel.clone())
.run_streaming(&sink, names.first().cloned(), ExecMode::Isolated)
.await?;
@@ -200,6 +240,7 @@ impl Engine for UvEngine {
"--python".to_owned(),
python,
])
.timeout(watchdog::QUERY)
.run()
.await?;
// uv reports findings on stderr where pip uses stdout, so both are given to the parser.
@@ -211,6 +252,7 @@ impl Engine for UvEngine {
let python = env.interpreter.display().to_string();
let out = Command::new("uv")
.args(Self::argv_freeze(&python))
.timeout(watchdog::QUERY)
.run()
.await?;
if !out.ok() {
@@ -269,4 +311,25 @@ mod tests {
.expect_err("uv cannot upgrade pip");
assert_eq!(err.code, crate::errors::Code::EngNotFound);
}
#[test]
fn the_pep668_flag_appears_only_when_the_override_applies() {
let files = ["-r".to_owned(), "req.txt".to_owned()];
let names = [PkgName::parse("idna").unwrap()];
for (system, expected) in [
(SystemPackages::Protected, 0),
(SystemPackages::OverrideAllowed, 1),
] {
for argv in [
UvEngine::argv_install(PY, &files, system),
UvEngine::argv_uninstall(PY, &names, system),
] {
let count = argv
.iter()
.filter(|a| *a == "--break-system-packages")
.count();
assert_eq!(count, expected, "{system:?}: {argv:?}");
}
}
}
}
+629 -41
View File
@@ -19,10 +19,10 @@ use std::path::{Path, PathBuf};
use crate::compat::PyVersion;
use crate::errors::{Code, PdError, Result};
use crate::exec::{Command, canonical_interpreter, write_temp};
use crate::exec::{Command, TempFile, canonical_interpreter, watchdog};
use crate::model::{Dist, EnvSource, PkgName, PyEnv, Version};
/// The embedded introspection helper, executed as `<env-python> -I probe.py --json`.
/// The embedded introspection helper, executed as `<env-python> -X utf8 -I probe.py --json`.
///
/// SECURITY §2: `-I` (isolated mode) makes the probe ignore `PYTHONPATH` and user site, so a
/// poisoned environment cannot inject code into it. It is written to a temp file with a random
@@ -39,27 +39,22 @@ pub struct ProbeResult {
pub env: PyEnv,
/// Installed distributions, sorted by normalized name.
pub dists: Vec<Dist>,
/// The PEP 508 marker environment (`sys_platform`, `platform_machine`, …), from probe schema
/// 3. Empty for an older probe, which leaves those markers unevaluated — the conservative
/// direction (`graph::markers`).
pub markers: BTreeMap<String, String>,
}
/// Identity of an environment: SHA-256 of the canonicalized interpreter path (ARCHITECTURE §6).
///
/// Case-folded on Windows — see the SP-6 note above. This value keys the pin store, the snapshot
/// Case-folded on Windows — see the SP-6 note above. Links are resolved, except that a venv's own
/// interpreter is resolved only up to its folder (since 1.6.0, [`canonical_interpreter`] says why):
/// a `--symlinks` venv is not the Python it was made from. This value keys the pin store, the snapshot
/// directory and the recents list, so a change here orphans a user's data.
#[must_use]
pub fn env_hash(interpreter: &Path) -> String {
use std::fmt::Write as _;
use sha2::{Digest as _, Sha256};
let canonical = canonical_interpreter(interpreter);
let digest = Sha256::digest(canonical.as_bytes());
digest
.iter()
.fold(String::with_capacity(64), |mut acc, byte| {
// Infallible: writing to a String cannot fail, and `?` here would need a Result return
// for a function that has no other failure mode.
let _ = write!(acc, "{byte:02x}");
acc
})
crate::model::sha256_hex(canonical.as_bytes())
}
/// Run `probe.py` against an interpreter.
@@ -75,17 +70,21 @@ pub async fn probe(interpreter: &Path, source: EnvSource) -> Result<ProbeResult>
));
}
let script = write_temp("pipdock-probe", "py", PROBE_PY)?;
// The probe is removed whatever happens; a leaked temp file is harmless but untidy, and
// Removed when it drops, whatever happens; a leaked temp file is harmless but untidy, and
// leaving one behind after every scan is not.
let result = Command::python(interpreter)
.arg("-I")
.arg(script.display().to_string())
let script = TempFile::create("pipdock-probe", "py", PROBE_PY)?;
// **`-X utf8` is not redundant with `Command::python`'s environment.** `-I` implies `-E`, so
// PYTHONUTF8 and PYTHONIOENCODING are ignored and stdout falls back to the ANSI code page. The
// probe prints paths with `ensure_ascii=False`, so a venv under `C:\Dự án\` crashed it with a
// UnicodeEncodeError (PD-ENV-003) and a `Jürgen` came back as mojibake. `-X` is a command-line
// option, which isolated mode honours. Reproduced before fixing.
let out = Command::python(interpreter)
.args(["-X", "utf8", "-I"])
.arg(script.path().display().to_string())
.arg("--json")
.timeout(watchdog::PROBE)
.run()
.await;
let _ = std::fs::remove_file(&script);
let out = result?;
.await?;
if !out.ok() {
return Err(
@@ -183,7 +182,21 @@ pub fn parse_probe(stdout: &str, interpreter: &Path, source: EnvSource) -> Resul
source,
};
Ok(ProbeResult { env, dists })
let markers = doc
.get("markers")
.and_then(serde_json::Value::as_object)
.map(|m| {
m.iter()
.filter_map(|(k, v)| Some((k.clone(), v.as_str()?.to_owned())))
.collect()
})
.unwrap_or_default();
Ok(ProbeResult {
env,
dists,
markers,
})
}
/// A discovered interpreter, before it has been probed.
@@ -200,8 +213,159 @@ pub struct Candidate {
/// Sources are queried independently and merged by canonical identity, so a Chocolatey shim and
/// the installation it points at collapse into one entry (SP-6). The **first** source to report a
/// path wins, and sources are ordered so the more authoritative one is asked first.
///
/// Discovery alone: interpreters a person added are not here. Code Health's choice of a Python to
/// build its tools venv with reads this, and should choose among installations, not among whatever
/// the user pointed the Environments screen at.
pub async fn scan() -> Vec<Candidate> {
scan_reporting(&|_| {}).await
scan_reporting(&[], &|_| {}).await
}
/// Discovery plus the interpreters a person added (*Browse…*, `pipdock env add`), for the two
/// listings — the Environments screen and `pipdock env list`.
pub async fn scan_with(manual: &[PathBuf]) -> Vec<Candidate> {
scan_reporting(manual, &|_| {}).await
}
/// Refuse an interpreter path a person supplied before anything runs it (SECURITY §2).
///
/// Discovery finds interpreters where Python installs them. A path from *Browse…*, `pipdock env
/// add`, `env use` or `--env` can name anything, and the probe **runs** the file — so this is the
/// enforcement point, not the picker, which only suggests:
///
/// - it must exist and be a file, or there is nothing to probe;
/// - its name must be `python.exe`, `python3.exe`, `python3.12.exe` or the free-threaded
/// `python3.14t.exe` (`python`, `python3`, … off
/// Windows), so that adding an interpreter is not a way to start any program with PipDock's
/// arguments. `pythonw.exe` is refused too: it has no console, the probe's output would be empty,
/// and the failure would read as a broken environment instead of the wrong file;
/// - it must not be one of PipDock's own environments — Code Health's tools venv or the Security
/// tab's audit venv — which PipDock builds and replaces itself, and which a user's update would
/// quietly break. The check is on resolved paths too, or `..` or a link would walk past it.
///
/// **Returns the path as given, made absolute — never with its links resolved.** A venv made with
/// `--symlinks` has a `Scripts\python.exe` that is a link to the base interpreter, and running the
/// *link* is what makes Python find the venv's `pyvenv.cfg`. The first version returned the
/// canonical path, so `--env .venv` ran — and *Add interpreter…* stored — the base Python instead
/// of the venv: an update meant for a project would have changed the system's Python. Found by an
/// independent review of 1.6.0 and reproduced before fixing. Where the link really points is still
/// checked: a `python.exe` that links to another program is another program, and is refused.
///
/// A Microsoft Store app-execution alias (`%LOCALAPPDATA%\Microsoft\WindowsApps\python.exe`) is a
/// file Windows will not resolve at all (os error 1920); it is judged by its own path, and accepted,
/// as discovery has always listed it.
///
/// # Errors
/// `PD-ENV-001` for each refusal, the message saying which. A missing file reads exactly as the
/// probe's own "no interpreter at …", so a caller that validates first changes no output.
pub fn validate_interpreter(path: &Path, app_data: &Path) -> Result<PathBuf> {
use crate::health::project::plain;
let refuse = |why: String| PdError::new(Code::EnvInterpreterMissing, why);
if !path.is_file() {
return Err(refuse(format!("no interpreter at {}", path.display())));
}
if !is_python_name(path) {
return Err(refuse(format!(
"{} is not a Python interpreter PipDock will run: the file has to be python.exe \
(or python3.exe, python3.12.exe, python3.14t.exe)",
path.display()
)));
}
let absolute = std::path::absolute(path)
.map(plain)
.map_err(|e| refuse(format!("cannot read {}: {e}", path.display())))?;
let target = path.canonicalize().map(plain).ok();
if let Some(target) = &target
&& !is_python_name(target)
{
return Err(refuse(format!(
"{} leads to {}, which is not a Python interpreter PipDock will run",
path.display(),
target.display()
)));
}
let own_dirs: Vec<PathBuf> = [
crate::health::tools_dir(app_data),
crate::health::audit_dir(app_data),
]
.iter()
.flat_map(|dir| {
[
dir.canonicalize().map(plain).ok(),
std::path::absolute(dir).map(plain).ok(),
]
})
.flatten()
.collect();
let inside_own = |p: &Path| own_dirs.iter().any(|own| p.starts_with(own));
if inside_own(&absolute) || target.as_deref().is_some_and(inside_own) {
return Err(refuse(format!(
"{} is one of PipDock's own environments, which it manages itself",
path.display()
)));
}
Ok(absolute)
}
/// `python`, `python3` or `python3.12`, with `.exe` on Windows; any case. A version may end in `t`,
/// the free-threaded build's name (`python3.14t.exe`, PEP 703) — the python.org installer puts one
/// beside `python.exe`, and the registry reports it; refusing it was found by running `env list`
/// against this machine's own Pythons.
fn is_python_name(path: &Path) -> bool {
let Some(name) = path.file_name().and_then(|n| n.to_str()) else {
return false;
};
let name = name.to_ascii_lowercase();
let stem = if cfg!(windows) {
match name.strip_suffix(".exe") {
Some(stem) => stem,
None => return false,
}
} else {
name.as_str()
};
let Some(version) = stem.strip_prefix("python") else {
return false;
};
let version = match version.strip_suffix('t') {
Some(threaded) if !threaded.is_empty() => threaded,
_ => version,
};
version.is_empty()
|| (version.split('.').count() <= 2
&& version
.split('.')
.all(|part| !part.is_empty() && part.bytes().all(|b| b.is_ascii_digit())))
}
/// An interpreter path, or the interpreter inside an environment directory (CLI-SPEC §2).
///
/// `<dir>\Scripts\python.exe` on Windows, `<dir>/bin/python` elsewhere; anything else comes back
/// unchanged, for [`validate_interpreter`] to refuse with the path the person gave.
#[must_use]
pub fn interpreter_in(path: &Path) -> PathBuf {
if path.is_file() {
return path.to_path_buf();
}
let candidate = venv_interpreter(path);
if candidate.is_file() {
candidate
} else {
path.to_path_buf()
}
}
/// Where a virtual environment's interpreter is, whether or not it is there: `<dir>\Scripts\python.exe`
/// on Windows, `<dir>/bin/python` elsewhere. `pipdock env remove <dir>` needs the answer for a venv
/// that has been deleted — exactly the entry someone wants gone, and one [`interpreter_in`] can no
/// longer resolve.
#[must_use]
pub fn venv_interpreter(dir: &Path) -> PathBuf {
if cfg!(windows) {
dir.join("Scripts").join("python.exe")
} else {
dir.join("bin").join("python")
}
}
/// Where a discovery sweep currently is.
@@ -249,11 +413,21 @@ pub enum ScanPhase {
/// How many sources a sweep reads, for the `total` a caller renders against.
const SCAN_SOURCES: usize = 5;
/// Discover environments, reporting progress as each source is read.
/// Discover environments, reporting progress as each source is read, and append the interpreters a
/// person added.
///
/// `manual` comes last, so an interpreter discovery also finds keeps the discovered source — the
/// chip says where Python put it, which is the more useful fact. Unlike every discovered path, a
/// manual one is kept **when its file is gone**: dropping it would make an entry the user added
/// vanish without a word, and with no row there would be nothing to remove it from. Its probe then
/// fails with `PD-ENV-001`, whose remedy is exactly that removal.
///
/// The callback is synchronous and must not block: it is called between sources, on the task
/// driving the scan.
pub async fn scan_reporting(report: &(dyn Fn(ScanProgress) + Sync)) -> Vec<Candidate> {
pub async fn scan_reporting(
manual: &[PathBuf],
report: &(dyn Fn(ScanProgress) + Sync),
) -> Vec<Candidate> {
let step = |phase: ScanPhase, done: usize| ScanProgress {
phase,
done,
@@ -288,34 +462,104 @@ pub async fn scan_reporting(report: &(dyn Fn(ScanProgress) + Sync)) -> Vec<Candi
.or_insert(Candidate { path, source });
}
}
found.into_values().collect()
merge_manual(found, manual)
}
/// PEP 514 registry entries, from both `HKCU` and `HKLM`.
/// Discovered candidates in canonical order, then the manual ones no source already reported, in
/// the order they were added.
///
/// Compared by the path as listed — made absolute, case-folded on Windows — and **not** by
/// [`canonical_interpreter`]: the first version compared identities, and while identity still
/// followed a venv's link, a venv made with `--symlinks` collapsed into the base interpreter its
/// `python.exe` points at and the venv a person added was never listed. Identity resolves other
/// links still, and what a person added is listed as they added it.
fn merge_manual(found: BTreeMap<String, Candidate>, manual: &[PathBuf]) -> Vec<Candidate> {
let mut out: Vec<Candidate> = found.into_values().collect();
let mut seen: std::collections::HashSet<String> =
out.iter().map(|c| listing_key(&c.path)).collect();
for path in manual {
if seen.insert(listing_key(path)) {
out.push(Candidate {
path: path.clone(),
source: EnvSource::Manual,
});
}
}
out
}
/// A path as a listing compares it: absolute, case-folded on Windows, links left alone.
fn listing_key(path: &Path) -> String {
let absolute = std::path::absolute(path).unwrap_or_else(|_| path.to_path_buf());
let text = absolute.display().to_string();
if cfg!(windows) {
text.to_lowercase()
} else {
text
}
}
/// Probe a candidate a listing returned — the one place both heads decide what a listing runs.
///
/// An added interpreter goes through [`validate_interpreter`] again on **every** listing, not only
/// on the day it was added: that check said what the file was then, and a `python.exe` that is a
/// link can be pointed at another program afterwards. `env_scan` and `env list` probed stored
/// entries unchecked until an independent review of 1.6.0 said so. A discovered path is probed as
/// found — discovery read it from where Python installs interpreters, and no person typed it.
///
/// # Errors
/// What [`validate_interpreter`] or [`probe`] reports: `PD-ENV-001` for a file that is gone (in the
/// probe's own words) or is not a Python PipDock will run, `PD-ENV-003` for a probe that fails.
pub async fn probe_listed(candidate: &Candidate, app_data: &Path) -> Result<ProbeResult> {
if candidate.source == EnvSource::Manual {
let path = candidate.path.clone();
let app_data = app_data.to_path_buf();
// On a blocking thread: the check reads the file system (`rust:S7493`).
tokio::task::spawn_blocking(move || validate_interpreter(&path, &app_data))
.await
.map_err(|e| {
PdError::new(
Code::IntUnexpected,
format!("interpreter check stopped: {e}"),
)
})??;
}
probe(&candidate.path, candidate.source).await
}
/// PEP 514 registry entries: `HKCU`, and both views of `HKLM`.
///
/// SP-6 found `PythonCore` present under **both** hives on the reference machine, which is one of
/// the two ways the same interpreter reaches discovery twice.
///
/// PEP 514 puts a 32-bit all-users install under `HKLM\Software\Wow6432Node\Python`, which a
/// 64-bit process does not see through the default view — so every such Python was missing from
/// the registry source. `HKCU` is shared between the views and needs no second read.
#[must_use]
pub fn registry_interpreters() -> Vec<PathBuf> {
#[cfg(windows)]
{
use winreg::RegKey;
use winreg::enums::{HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, KEY_READ};
use winreg::enums::{HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, KEY_READ, KEY_WOW64_32KEY};
let mut out = Vec::new();
for hive in [HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE] {
for (hive, view) in [
(HKEY_CURRENT_USER, 0),
(HKEY_LOCAL_MACHINE, 0),
(HKEY_LOCAL_MACHINE, KEY_WOW64_32KEY),
] {
let flags = KEY_READ | view;
let root = RegKey::predef(hive);
let Ok(software) = root.open_subkey_with_flags(r"SOFTWARE\Python", KEY_READ) else {
let Ok(software) = root.open_subkey_with_flags(r"SOFTWARE\Python", flags) else {
continue;
};
for company in software.enum_keys().flatten() {
let Ok(company_key) = software.open_subkey_with_flags(&company, KEY_READ) else {
let Ok(company_key) = software.open_subkey_with_flags(&company, flags) else {
continue;
};
for tag in company_key.enum_keys().flatten() {
let Ok(install) =
company_key.open_subkey_with_flags(format!(r"{tag}\InstallPath"), KEY_READ)
company_key.open_subkey_with_flags(format!(r"{tag}\InstallPath"), flags)
else {
continue;
};
@@ -339,7 +583,12 @@ pub fn registry_interpreters() -> Vec<PathBuf> {
/// Interpreters reported by the `py` launcher (`py -0p`).
pub async fn py_launcher_interpreters() -> Vec<PathBuf> {
let Ok(out) = Command::new("py").arg("-0p").run().await else {
let Ok(out) = Command::new("py")
.arg("-0p")
.timeout(watchdog::DISCOVERY)
.run()
.await
else {
return Vec::new();
};
if !out.ok() {
@@ -354,7 +603,12 @@ pub async fn py_launcher_interpreters() -> Vec<PathBuf> {
/// `<download available>` where a path would be, and must be dropped — offering to manage a
/// Python that is not on the machine would be nonsense.
pub async fn uv_interpreters() -> Vec<PathBuf> {
let Ok(out) = Command::new("uv").args(["python", "list"]).run().await else {
let Ok(out) = Command::new("uv")
.args(["python", "list"])
.timeout(watchdog::DISCOVERY)
.run()
.await
else {
return Vec::new();
};
if !out.ok() {
@@ -363,13 +617,25 @@ pub async fn uv_interpreters() -> Vec<PathBuf> {
out.stdout.lines().filter_map(parse_listed_path).collect()
}
/// Take the trailing path from a listing line, rejecting `<download available>` placeholders.
/// The interpreter path of one `py -0p` or `uv python list` row.
///
/// Both print a key that never contains whitespace — `-V:3.14`, `cpython-3.14.7-windows-x86_64-none`
/// — then, for `py`, an optional `*` marking the default, then the path. **The path may contain
/// spaces.** Taking the last whitespace-separated token turned `C:\Program Files\Python312\python.exe`
/// — where every all-users python.org installer puts it — into the relative
/// `Files\Python312\python.exe`, which the existence check then quietly dropped. A row uv offers to
/// download carries `<download available>` where the path would be, and is rejected.
fn parse_listed_path(line: &str) -> Option<PathBuf> {
let last = line.split_whitespace().next_back()?;
if last.starts_with('<') || !last.contains(std::path::MAIN_SEPARATOR) {
let (_key, rest) = line.trim().split_once(char::is_whitespace)?;
let rest = rest.trim_start();
let rest = rest.strip_prefix('*').map_or(rest, str::trim_start);
// uv prints a symlink as `path -> target`; the listed path is the interpreter itself.
let path = rest.split(" -> ").next()?.trim_end();
if path.is_empty() || path.starts_with('<') {
return None;
}
Some(PathBuf::from(last))
let path = PathBuf::from(path);
path.is_absolute().then_some(path)
}
/// Virtual environments in `dir`, one level deep.
@@ -423,6 +689,223 @@ mod tests {
}
}
fn scratch(name: &str) -> PathBuf {
let dir = std::env::temp_dir().join(format!("pd-envs-{name}-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
std::fs::create_dir_all(&dir).expect("create scratch dir");
dir
}
/// An empty file at `dir/rel`, which is all [`validate_interpreter`] looks at — it never runs it.
fn touch(dir: &Path, rel: &str) -> PathBuf {
let path = dir.join(rel);
std::fs::create_dir_all(path.parent().expect("a parent")).expect("parents");
std::fs::write(&path, "").expect("write");
path
}
fn exe(stem: &str) -> String {
if cfg!(windows) {
format!("{stem}.exe")
} else {
stem.to_owned()
}
}
#[test]
fn only_a_file_named_like_python_is_accepted() {
// The free-threaded build (PEP 703) is `python3.14t.exe`, beside `python.exe` in the same
// install — the registry lists it on this repository's own reference machine.
for name in [
"python",
"PYTHON",
"python3",
"python3.12",
"Python3.14",
"python3.14t",
"python3t",
] {
assert!(is_python_name(Path::new(&exe(name))), "{name}");
}
// pythonw has no console; the rest are other programs, or versions that are not versions.
for name in [
"pythonw",
"pythonw3.14t",
"pythont",
"python3.14tt",
"notepad",
"py",
"python3.12.1",
"python3.",
"python.3",
"python3x",
"mypython",
] {
assert!(!is_python_name(Path::new(&exe(name))), "{name}");
}
if cfg!(windows) {
assert!(
!is_python_name(Path::new("python.bat")),
"a script is not an exe"
);
assert!(
!is_python_name(Path::new("python")),
"Windows needs the .exe"
);
}
}
#[test]
fn a_missing_interpreter_reads_exactly_as_the_probe_says_it() {
// The CLI's error-envelope goldens pin this sentence for `--env C:/definitely/not/here`.
let err = validate_interpreter(Path::new("C:/definitely/not/here"), &scratch("missing"))
.expect_err("nothing there");
assert_eq!(err.code, Code::EnvInterpreterMissing);
assert_eq!(err.message, "no interpreter at C:/definitely/not/here");
}
#[test]
fn another_program_is_refused_before_anything_runs_it() {
let dir = scratch("other");
let notepad = touch(&dir, &exe("notepad"));
let err = validate_interpreter(&notepad, &dir.join("data")).expect_err("not python");
assert_eq!(err.code, Code::EnvInterpreterMissing);
assert!(
err.message.contains("is not a Python interpreter"),
"{}",
err.message
);
}
#[test]
fn a_python_is_accepted_and_comes_back_absolute_and_plain() {
let dir = scratch("ok");
let python = touch(&dir, &format!("proj/.venv/Scripts/{}", exe("python")));
let got = validate_interpreter(&python, &dir.join("data")).expect("a python");
assert!(
!got.display().to_string().starts_with(r"\\?\"),
"no verbatim prefix: {}",
got.display()
);
assert_eq!(got, std::path::absolute(&python).expect("absolute"));
}
/// A link, or `None` where this machine may not make one (Windows without Developer Mode).
fn link(target: &Path, at: &Path) -> Option<()> {
std::fs::create_dir_all(at.parent().expect("a parent")).expect("parents");
#[cfg(windows)]
let made = std::os::windows::fs::symlink_file(target, at);
#[cfg(not(windows))]
let made = std::os::unix::fs::symlink(target, at);
made.ok()
}
#[test]
fn a_symlinked_venv_keeps_its_own_path_and_a_link_to_another_program_is_refused() {
// `python -m venv --symlinks`: the venv's python.exe links to the base interpreter, and
// only running the link finds the venv. Resolving it handed back — and stored — the base.
let dir = scratch("links");
let base = touch(&dir, &format!("base/{}", exe("python")));
let venv_python = dir.join("venv").join("Scripts").join(exe("python"));
let Some(()) = link(&base, &venv_python) else {
eprintln!("skipped: this machine cannot create symbolic links");
return;
};
let got = validate_interpreter(&venv_python, &dir.join("data")).expect("a python");
assert_eq!(got, std::path::absolute(&venv_python).expect("absolute"));
assert_ne!(
got,
std::path::absolute(&base).expect("absolute"),
"not the base"
);
// A python.exe that is really another program is still another program.
let other = touch(&dir, &format!("tools/{}", exe("notepad")));
let disguised = dir.join("disguise").join(exe("python"));
link(&other, &disguised).expect("links work here");
let err = validate_interpreter(&disguised, &dir.join("data")).expect_err("not python");
assert!(err.message.contains("leads to"), "{}", err.message);
}
#[test]
fn pipdocks_own_environments_are_refused_even_through_dot_dot() {
let dir = scratch("own");
let app_data = dir.join("data");
for own in ["tools", "audit"] {
let python = touch(&app_data, &format!("{own}/.venv/Scripts/{}", exe("python")));
let err = validate_interpreter(&python, &app_data).expect_err("PipDock's own");
assert!(err.message.contains("PipDock's own"), "{}", err.message);
// Reached the long way round: canonicalized before the comparison, or `..` walks past.
let sideways = app_data
.join("elsewhere")
.join("..")
.join(own)
.join(".venv")
.join("Scripts")
.join(exe("python"));
std::fs::create_dir_all(app_data.join("elsewhere")).expect("dir");
let err = validate_interpreter(&sideways, &app_data).expect_err("still PipDock's own");
assert!(err.message.contains("PipDock's own"), "{}", err.message);
}
// A sibling whose name merely starts with "tools" is someone else's.
let neighbour = touch(&app_data, &format!("tools-mine/{}", exe("python")));
validate_interpreter(&neighbour, &app_data).expect("not inside tools");
}
#[test]
fn an_environment_directory_resolves_to_its_interpreter() {
let dir = scratch("dir");
let inside = if cfg!(windows) {
format!("venv/Scripts/{}", exe("python"))
} else {
"venv/bin/python".to_owned()
};
let python = touch(&dir, &inside);
assert_eq!(interpreter_in(&dir.join("venv")), python);
assert_eq!(interpreter_in(&python), python, "a file is itself");
let nothing = dir.join("nothing-here");
assert_eq!(
interpreter_in(&nothing),
nothing,
"left for the validator to refuse"
);
}
#[test]
fn manual_entries_come_last_and_never_shadow_discovery() {
let discovered = PathBuf::from(r"C:\Python314\python.exe");
let mut found = BTreeMap::new();
found.insert(
canonical_interpreter(&discovered),
Candidate {
path: discovered.clone(),
source: EnvSource::Registry,
},
);
let manual = [
PathBuf::from(r"D:\work\proj\myenv\Scripts\python.exe"),
// The same interpreter the registry reported, in other casing: discovery keeps it.
PathBuf::from(r"c:\python314\python.exe"),
// Added twice, listed once.
PathBuf::from(r"D:\work\proj\myenv\Scripts\python.exe"),
// Gone from disk: still listed, so it can be removed.
PathBuf::from(r"E:\gone\python.exe"),
];
let merged = merge_manual(found, &manual);
let sources: Vec<_> = merged.iter().map(|c| (c.path.clone(), c.source)).collect();
let mut expected = vec![(discovered, EnvSource::Registry)];
if !cfg!(windows) {
// Off Windows the casing differs, so the second is its own interpreter.
expected.push((manual[0].clone(), EnvSource::Manual));
expected.push((manual[1].clone(), EnvSource::Manual));
} else {
expected.push((manual[0].clone(), EnvSource::Manual));
}
expected.push((manual[3].clone(), EnvSource::Manual));
assert_eq!(sources, expected);
}
#[test]
fn env_hash_is_stable_and_case_insensitive_on_windows() {
// SP-6: the Chocolatey shim and the direct install differ only in casing. Two hashes for
@@ -562,6 +1045,78 @@ mod tests {
assert!(parse_listed_path("").is_none());
}
#[test]
fn a_listed_path_with_spaces_survives() {
// Where every all-users python.org installer puts Python. The last token alone was the
// relative `Files\Python312\python.exe`, and the interpreter vanished from discovery.
let program_files = r"C:\Program Files\Python312\python.exe";
for line in [
format!(" -V:3.12 {program_files}"),
format!(" -V:3.12 * {program_files}\r"),
format!(" -3.12-64 {program_files}"),
format!("cpython-3.12.10-windows-x86_64-none {program_files}"),
] {
assert_eq!(
parse_listed_path(&line),
Some(PathBuf::from(program_files)),
"{line:?}"
);
}
// uv's warnings, should one reach stdout, are not paths.
assert!(
parse_listed_path("warning: Failed to inspect Python interpreter from search path")
.is_none()
);
assert!(
parse_listed_path("cpython-3.16.0a1-windows-x86_64-none <download available>")
.is_none()
);
}
#[test]
fn the_marker_environment_is_carried_and_an_older_probe_has_none() {
let doc = r#"{"schema":3,"python":"3.14.7","prefix":"C:\\Python314",
"externally_managed":false,"hidden_user_site":null,
"markers":{"sys_platform":"win32","platform_machine":"AMD64","bogus":7},
"dists":[]}"#;
let got = parse_probe(doc, Path::new("python.exe"), EnvSource::Registry).expect("parse");
assert_eq!(
got.markers.get("sys_platform").map(String::as_str),
Some("win32")
);
assert_eq!(
got.markers.get("platform_machine").map(String::as_str),
Some("AMD64")
);
assert!(
!got.markers.contains_key("bogus"),
"only strings are markers"
);
let old = r#"{"schema":2,"python":"3.12.4","prefix":"x","externally_managed":false,
"hidden_user_site":null,"dists":[]}"#;
let got = parse_probe(old, Path::new("python.exe"), EnvSource::Registry).expect("parse");
assert!(got.markers.is_empty());
}
#[test]
fn the_probe_reads_metadata_once_per_distribution() {
// `dist.version` and `dist.requires` each re-parse METADATA; on the path every environment
// open pays, asking all three tripled the work. Measured on CPython 3.14 with 64
// distributions: 154 ms before, 118 ms after, the same document either way.
// On the code, not the words: the probe's own comment names both on purpose.
assert!(
PROBE_PY.contains(r#""version": meta.get("Version")"#),
"the version comes from the one parse"
);
assert!(
PROBE_PY.contains(r#"meta.get_all("Requires-Dist")"#),
"the requirements come from the one parse"
);
// And it does not reach for `platform`, whose uname() is a WMI query on Windows.
assert!(!PROBE_PY.contains("import platform"));
}
#[test]
fn the_probe_python_floor_matches_the_document() {
assert_eq!(MIN_PROBE_PYTHON, (3, 10));
@@ -578,4 +1133,37 @@ mod tests {
.expect_err("missing interpreter must fail");
assert_eq!(err.code, Code::EnvInterpreterMissing);
}
#[tokio::test]
async fn an_added_entry_is_checked_again_on_every_listing() {
// The store held a Python when it was added; what it holds now is another program. Refused
// before anything runs it, and still a row — PD-ENV-001 — so it can be removed.
let dir = scratch("relisted");
let added = Candidate {
path: touch(&dir, &exe("notepad")),
source: EnvSource::Manual,
};
let err = probe_listed(&added, &dir.join("data"))
.await
.expect_err("refused");
assert_eq!(err.code, Code::EnvInterpreterMissing);
assert!(
err.message.contains("is not a Python interpreter"),
"{}",
err.message
);
// An entry whose file is gone reads exactly as the probe has always said it.
let gone = Candidate {
path: dir.join("deleted").join(exe("python")),
source: EnvSource::Manual,
};
let err = probe_listed(&gone, &dir.join("data"))
.await
.expect_err("gone");
assert_eq!(
err.message,
format!("no interpreter at {}", gone.path.display())
);
}
}
+75 -7
View File
@@ -88,6 +88,14 @@ pub enum Code {
/// uv emitted a shape the adapter does not recognize (uv newer than PipDock).
#[serde(rename = "PD-ENG-003")]
EngUvShapeUnknown,
/// An engine command ran past its watchdog and was stopped.
///
/// **Raised by PipDock, never classified from stderr.** Its own code because the alternative
/// was `PD-INT-001`, which is what the shared watchdog reported until 1.4.0: an sdist build
/// still compiling after ten minutes is not "a PipDock bug", and in the batch phase that error
/// aborted the whole run — no summary, no per-package retry.
#[serde(rename = "PD-ENG-004")]
EngTimedOut,
/// Fallback for engine failures no classifier matched. Always last.
#[serde(rename = "PD-ENG-999")]
EngUnclassified,
@@ -233,6 +241,7 @@ impl Code {
Self::EngNotFound => "PD-ENG-001",
Self::EngPipTooOld => "PD-ENG-002",
Self::EngUvShapeUnknown => "PD-ENG-003",
Self::EngTimedOut => "PD-ENG-004",
Self::EngUnclassified => "PD-ENG-999",
Self::ResImpossible => "PD-RES-001",
Self::ResPlanStale => "PD-RES-002",
@@ -274,6 +283,7 @@ impl Code {
Self::EngNotFound
| Self::EngPipTooOld
| Self::EngUvShapeUnknown
| Self::EngTimedOut
| Self::EngUnclassified => Area::Eng,
Self::ResImpossible
| Self::ResPlanStale
@@ -310,6 +320,7 @@ impl Code {
Self::EngNotFound,
Self::EngPipTooOld,
Self::EngUvShapeUnknown,
Self::EngTimedOut,
Self::ResImpossible,
Self::ResPlanStale,
Self::ResPlanInFlight,
@@ -410,6 +421,13 @@ static CLASSIFIERS: &[Classifier] = &[
code: Code::BldBackendFailed,
all_of: &["backendunavailable"],
},
// pip 26.3's rendering of the same failure: the `BackendUnavailable` traceback became the
// `backend-unavailable` diagnostic, and its last line, "Failed to build '<name>' when calling
// build backend hook …", is what the generic wheel rule below would otherwise claim.
Classifier {
code: Code::BldBackendFailed,
all_of: &["error: backend-unavailable"],
},
Classifier {
code: Code::BldBackendFailed,
all_of: &["the build backend returned an error"],
@@ -426,11 +444,26 @@ static CLASSIFIERS: &[Classifier] = &[
code: Code::BldWheelFailed,
all_of: &["failed building wheel"],
},
// -- network errors Windows raises as PermissionError -----------------------
// Ahead of the permission rules on purpose. A firewall or AV refusing a socket is
// `PermissionError: [WinError 10013]`, and "network path not found" is `[WinError 53]` — both
// were PD-PRM-001, "use a venv", which is advice about site-packages for a network problem.
Classifier {
code: Code::NetUnreachable,
all_of: &["[winerror 10013]"],
},
Classifier {
code: Code::NetUnreachable,
all_of: &["[winerror 53]"],
},
// -- permissions ---------------------------------------------------------
// Checked before the generic OSError shapes below, which share their prefix.
//
// **The closing bracket is part of every WinError needle.** Python prints `[WinError N]`, and
// without the bracket "winerror 5" also matched 50, 53 and 59 and "winerror 32" matched 321.
Classifier {
code: Code::PrmFileLocked,
all_of: &["winerror 32"],
all_of: &["[winerror 32]"],
},
Classifier {
code: Code::PrmSitePackagesReadOnly,
@@ -438,7 +471,7 @@ static CLASSIFIERS: &[Classifier] = &[
},
Classifier {
code: Code::PrmSitePackagesReadOnly,
all_of: &["winerror 5"],
all_of: &["[winerror 5]"],
},
// -- system --------------------------------------------------------------
Classifier {
@@ -447,7 +480,7 @@ static CLASSIFIERS: &[Classifier] = &[
},
Classifier {
code: Code::SysDiskFull,
all_of: &["winerror 112"],
all_of: &["[winerror 112]"],
},
Classifier {
code: Code::SysPathTooLong,
@@ -530,6 +563,12 @@ static CLASSIFIERS: &[Classifier] = &[
code: Code::EngPipTooOld,
all_of: &["no such option: --report"],
},
// The planner's argv puts `--dry-run` first, and optparse stops at the first option it does
// not know — so a pip below 22.2 says this, not the `--report` line above.
Classifier {
code: Code::EngPipTooOld,
all_of: &["no such option: --dry-run"],
},
Classifier {
code: Code::EngNotFound,
all_of: &["no module named pip"],
@@ -567,6 +606,15 @@ pub fn classify_stderr(stderr: &str) -> Code {
/// Lowercase and collapse every run of whitespace to a single space, so patterns survive the
/// engines' line wrapping and CRLF.
fn normalize(text: &str) -> String {
collapse_whitespace(text).to_lowercase()
}
/// Collapse every run of whitespace — wrapping, CRLF, indentation — to one space, and trim.
///
/// uv hard-wraps its diagnostics mid-sentence, so a literal search for a phrase that spans the
/// wrap point finds nothing. The classifiers above and the plan parser both need this, and had two
/// copies of it.
pub(crate) fn collapse_whitespace(text: &str) -> String {
let mut out = String::with_capacity(text.len());
let mut in_space = false;
for ch in text.chars() {
@@ -577,7 +625,7 @@ fn normalize(text: &str) -> String {
out.push(' ');
}
in_space = false;
out.extend(ch.to_lowercase());
out.push(ch);
}
}
out
@@ -592,7 +640,7 @@ mod tests {
fn every_variant_is_listed_in_all() {
// `ALL` drives the fixture-coverage gate, so a variant missing from it would silently
// escape that gate. There is no derive for "enumerate variants", hence this count check.
assert_eq!(Code::ALL.len(), 34, "add the new variant to Code::ALL");
assert_eq!(Code::ALL.len(), 35, "add the new variant to Code::ALL");
}
#[test]
@@ -685,6 +733,26 @@ mod tests {
assert_eq!(classify_stderr(locked), Code::PrmFileLocked);
}
#[test]
fn a_winerror_number_matches_exactly_and_never_as_a_prefix() {
// "winerror 5" used to match `[WinError 53]` — a network path — and report it as a
// read-only site-packages.
let network_path = r"OSError: [WinError 53] The network path was not found: '\\srv\share'";
assert_eq!(classify_stderr(network_path), Code::NetUnreachable);
let denied = r"ERROR: Could not install packages due to an OSError: [WinError 5] Access is denied: 'C:\Program Files\Python312\Lib\site-packages\x'";
assert_eq!(classify_stderr(denied), Code::PrmSitePackagesReadOnly);
// A firewall refusing the socket is a PermissionError by type and a network problem by
// meaning; the user-facing answer is the network one.
let socket = "PermissionError: [WinError 10013] An attempt was made to access a socket in \
a way forbidden by its access permissions";
assert_eq!(classify_stderr(socket), Code::NetUnreachable);
let not_locked = "OSError: [WinError 321] something else entirely";
assert_ne!(classify_stderr(not_locked), Code::PrmFileLocked);
}
#[test]
fn incidental_mentions_of_yanking_do_not_hijack_a_different_failure() {
// pip prefixes an unrelated resolution failure with "Ignored the following yanked
@@ -739,9 +807,9 @@ mod tests {
#[test]
fn every_documented_code_has_exactly_one_variant() {
// Rust has 33; docs/ERROR-CATALOG.md tabulates 30, because it folds PD-HLT-001..004 into
// Rust has 35; docs/ERROR-CATALOG.md tabulates 32, because it folds PD-HLT-001..004 into
// one row. Pin the number so the next person adding a code has to notice the docs exist.
assert_eq!(Code::ALL.len(), 34);
assert_eq!(Code::ALL.len(), 35);
let wire: HashSet<&str> = Code::ALL.iter().map(|c| c.as_str()).collect();
assert_eq!(
wire.len(),
+25
View File
@@ -20,6 +20,11 @@ pub struct PdError {
/// Tail of the engine's stderr, capped at the 40 lines `docs/ERROR-CATALOG.md` §3 shows.
#[serde(skip_serializing_if = "Option::is_none")]
pub stderr_tail: Option<String>,
/// Set when this error is a run that was **stopped** rather than one that failed: cancelled by
/// its token or killed by its watchdog. Never on the wire -- callers turn it into a skipped
/// step or their own timeout code before anything is shown.
#[serde(skip)]
pub stop: Option<crate::exec::Stop>,
}
impl PdError {
@@ -30,9 +35,29 @@ impl PdError {
code,
message: message.into(),
stderr_tail: None,
stop: None,
}
}
/// Record that the run behind this error was stopped, and why.
#[must_use]
pub const fn with_stop(mut self, stop: crate::exec::Stop) -> Self {
self.stop = Some(stop);
self
}
/// True when the run was stopped by its cancellation token.
#[must_use]
pub fn is_cancelled(&self) -> bool {
self.stop == Some(crate::exec::Stop::Cancelled)
}
/// True when the run was stopped by its watchdog.
#[must_use]
pub const fn is_timeout(&self) -> bool {
matches!(self.stop, Some(crate::exec::Stop::TimedOut(_)))
}
/// Attach an engine stderr tail, truncated to the last `MAX_STDERR_TAIL_LINES` lines.
#[must_use]
pub fn with_stderr(mut self, stderr: impl AsRef<str>) -> Self {
+542 -106
View File
@@ -17,16 +17,52 @@ use std::path::{Path, PathBuf};
use std::process::Stdio;
use std::time::Duration;
use tokio::io::{AsyncBufReadExt, BufReader};
use tokio::io::{AsyncBufReadExt, AsyncRead, BufReader};
use tokio::process::Command as TokioCommand;
use tokio_util::sync::CancellationToken;
use crate::engine::{ProgressEvent, ProgressSink, Stream};
use crate::engine::{EventSink, ProgressEvent, ProgressSink, Stream};
use crate::errors::{Code, PdError, Result};
use crate::model::{ExecMode, PkgName};
/// Default watchdog. Long resolves on a big environment are normal; hangs are not.
pub const DEFAULT_TIMEOUT: Duration = Duration::from_secs(600);
/// Default watchdog, for anything that does not name its own in [`watchdog`].
pub const DEFAULT_TIMEOUT: Duration = watchdog::RESOLVE;
/// Watchdogs by kind of work.
///
/// One 600 s budget used to cover everything, which was wrong in both directions: a hung `py -0p`
/// held the Environments screen for ten minutes, and a source build of scipy -- legitimately slow
/// -- was killed at the same ten. A watchdog is a unit, not a number (CLAUDE.md, from P1-1): each
/// constant here is sized for one kind of operation.
pub mod watchdog {
use std::time::Duration;
/// `pip install` / `uv pip install` / uninstall. Building an sdist can take many minutes.
pub const INSTALL: Duration = Duration::from_secs(30 * 60);
/// A dry-run resolve, including pip's backtracking on a large environment.
pub const RESOLVE: Duration = Duration::from_secs(10 * 60);
/// `list --outdated`, which makes one index request per installed package.
pub const OUTDATED: Duration = Duration::from_secs(10 * 60);
/// Local queries: `list`, `freeze`, `check`, `--version`.
pub const QUERY: Duration = Duration::from_secs(3 * 60);
/// `probe.py` against one interpreter. It reads metadata files and nothing else.
pub const PROBE: Duration = Duration::from_secs(60);
/// Discovery listings: `py -0p`, `uv python list`.
pub const DISCOVERY: Duration = Duration::from_secs(30);
}
/// Why a run ended before its program did.
///
/// Carried on the [`PdError`] such a run returns ([`PdError::stop`]), so a caller asks a typed
/// question. Three modules used to read the *message* back instead -- `"cancelled:"`, `"timed
/// out"` -- each with its own copy of the prefixes `Command::stopped` happened to write.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Stop {
/// The command's [`CancellationToken`] was tripped.
Cancelled,
/// The watchdog fired after this long.
TimedOut(Duration),
}
/// Wait for cancellation, or never, when no token was supplied.
///
@@ -78,6 +114,9 @@ pub struct Command {
env: HashMap<String, String>,
timeout: Duration,
cancel: Option<CancellationToken>,
/// The program is a Python interpreter, so "not found" means the environment is gone
/// (`PD-ENV-001`) rather than that an engine needs installing (`PD-ENG-001`).
interpreter: bool,
}
impl Command {
@@ -91,6 +130,7 @@ impl Command {
env: HashMap::new(),
timeout: DEFAULT_TIMEOUT,
cancel: None,
interpreter: false,
}
}
@@ -99,9 +139,27 @@ impl Command {
/// Use this for **every** `python -m pip …` and `probe.py` call. `PYTHONUTF8=1` covers the
/// interpreter's own text handling and `PYTHONIOENCODING=utf-8` covers the stdio streams pip's
/// vendored `rich` writes through.
///
/// **Not enough on its own for a `-I` run.** Isolated mode implies `-E`, which ignores every
/// `PYTHON*` variable, so `probe.py` must also pass `-X utf8` (see `envs::probe`).
#[must_use]
pub fn python(interpreter: impl Into<PathBuf>) -> Self {
Self::new(interpreter)
let mut cmd = Self::new(interpreter)
.env("PYTHONIOENCODING", "utf-8")
.env("PYTHONUTF8", "1");
cmd.interpreter = true;
cmd
}
/// Invoke a Python **console script** -- vulture, deptry, pip-audit -- with the same mitigation.
///
/// Their `.exe` is a launcher for the tools venv's interpreter, so the variables reach Python
/// exactly as they do for [`Command::python`]. Spawned with [`Command::new`] they were missing:
/// a non-ASCII file name in the user's project could crash vulture's report on cp1252 and read
/// as PD-HLT-002, "the tool stopped with an error".
#[must_use]
pub fn python_tool(exe: impl Into<PathBuf>) -> Self {
Self::new(exe)
.env("PYTHONIOENCODING", "utf-8")
.env("PYTHONUTF8", "1")
}
@@ -156,11 +214,41 @@ impl Command {
}
/// Why a run ended early. Both arms kill the child on the way out.
fn stopped(&self, reason: &str) -> PdError {
PdError::new(
Code::IntUnexpected,
format!("{reason}: {}", self.program.display()),
)
///
/// The message keeps its old wording for the log, but nothing may read it: the typed answer is
/// [`PdError::stop`]. A cancellation keeps `PD-INT-001` because it is never meant to reach a
/// user -- every caller turns a cancelled step into a *skipped* one -- while a timeout is
/// `PD-ENG-004`, which callers on other paths (Code Health, the audit) remap to their own code.
fn stopped(&self, stop: Stop) -> PdError {
tracing::warn!(target: "pipdock::exec", program = %self.program.display(), ?stop, "stopped");
let program = self.program.display();
match stop {
Stop::Cancelled => PdError::new(Code::IntUnexpected, format!("cancelled: {program}")),
Stop::TimedOut(after) => PdError::new(
Code::EngTimedOut,
format!("timed out after {after:?}: {program}"),
),
}
.with_stop(stop)
}
/// Map a failure to *start* the program onto the code whose advice fits.
///
/// Everything used to be `PD-ENG-001`, "install the engine": for a deleted venv's
/// `python.exe` that should be `PD-ENV-001`, and for a command line past Windows' 32,767
/// characters (`ERROR_FILENAME_EXCED_RANGE`, 206) it is a path-length problem.
fn spawn_error(&self, e: &std::io::Error) -> PdError {
const ERROR_FILENAME_EXCED_RANGE: i32 = 206;
let program = self.program.display();
let code = if e.raw_os_error() == Some(ERROR_FILENAME_EXCED_RANGE) {
Code::SysPathTooLong
} else if e.kind() == std::io::ErrorKind::NotFound && self.interpreter {
Code::EnvInterpreterMissing
} else {
Code::EngNotFound
};
tracing::warn!(target: "pipdock::exec", %program, error = %e, "could not start");
PdError::new(code, format!("could not run {program}: {e}"))
}
/// The argv this command would run, for logging and for the bug-report ring buffer.
@@ -201,34 +289,31 @@ impl Command {
/// Run to completion, capturing output. See [`TreeGuard`] for what "stop" means here.
///
/// # Errors
/// `PD-ENG-001` when the program cannot be spawned, `PD-INT-001` when the watchdog fires.
/// `PD-ENG-001` when the program cannot be spawned, `PD-ENG-004` when the watchdog fires.
pub async fn run(&self) -> Result<Output> {
let started = self.logged_start();
// Spawned rather than `.output()`ed, so the child can be put in a job before it is waited
// on. `.output()` owns the child and never lends out a handle.
let child = self.build().spawn().map_err(|e| {
PdError::new(
Code::EngNotFound,
format!("could not run {}: {e}", self.program.display()),
)
})?;
let child = self.build().spawn().map_err(|e| self.spawn_error(&e))?;
let tree = TreeGuard::attach(&child);
let out = tokio::select! {
out = child.wait_with_output() => out,
() = tokio::time::sleep(self.timeout) => {
return Err(self.stopped(&format!("timed out after {:?}", self.timeout)));
return Err(self.stopped(Stop::TimedOut(self.timeout)));
}
() = cancelled(self.cancel.as_ref()) => {
return Err(self.stopped("cancelled"));
return Err(self.stopped(Stop::Cancelled));
}
};
drop(tree);
let out = out.map_err(|e| {
PdError::new(
Code::EngNotFound,
format!("could not run {}: {e}", self.program.display()),
Code::IntUnexpected,
format!("waiting on {} failed: {e}", self.program.display()),
)
})?;
self.logged_exit(started, out.status.code());
Ok(Output {
code: out.status.code(),
stdout: String::from_utf8_lossy(&out.stdout).into_owned(),
@@ -236,6 +321,22 @@ impl Command {
})
}
/// The argv, at INFO: what PipDock ran is the first thing a bug report needs.
fn logged_start(&self) -> std::time::Instant {
tracing::info!(target: "pipdock::exec", argv = ?self.argv(), "spawn");
std::time::Instant::now()
}
fn logged_exit(&self, started: std::time::Instant, code: Option<i32>) {
tracing::info!(
target: "pipdock::exec",
program = %self.program.display(),
?code,
ms = u64::try_from(started.elapsed().as_millis()).unwrap_or(u64::MAX),
"exited"
);
}
/// Run while streaming each output line to `sink`, for the live console drawer.
///
/// Output is still captured and returned, because the parsers need the whole document and the
@@ -252,84 +353,45 @@ impl Command {
// The step index comes from the caller's sink rather than a parameter: an adapter cannot
// know its own position in the plan, which is why every call site used to pass 0.
let step = sink.step;
let mut child = self.build().spawn().map_err(|e| {
PdError::new(
Code::EngNotFound,
format!("could not run {}: {e}", self.program.display()),
)
})?;
let started = self.logged_start();
let mut child = self.build().spawn().map_err(|e| self.spawn_error(&e))?;
// Held until this function returns. Dropping it — which the timeout and cancel arms below
// do by returning — terminates the whole tree, not just `child`.
let _tree = TreeGuard::attach(&child);
let stdout = child.stdout.take();
let stderr = child.stderr.take();
let pump = |reader: Option<tokio::process::ChildStdout>| {
let sink = sink.tx.clone();
let pkg = pkg.clone();
async move {
let mut buf = String::new();
if let Some(r) = reader {
let mut lines = BufReader::new(r).lines();
while let Ok(Some(line)) = lines.next_line().await {
// Send failure means the UI stopped listening; keep capturing regardless
// so the summary and the log are still complete.
let _ = sink.send(ProgressEvent::Line {
step,
pkg: pkg.clone(),
phase,
stream: Stream::Stdout,
line: line.clone(),
});
buf.push_str(&line);
buf.push('\n');
}
}
buf
}
};
let pump_err = |reader: Option<tokio::process::ChildStderr>| {
let sink = sink.tx.clone();
let pkg = pkg.clone();
async move {
let mut buf = String::new();
if let Some(r) = reader {
let mut lines = BufReader::new(r).lines();
while let Ok(Some(line)) = lines.next_line().await {
let _ = sink.send(ProgressEvent::Line {
step,
pkg: pkg.clone(),
phase,
stream: Stream::Stderr,
line: line.clone(),
});
buf.push_str(&line);
buf.push('\n');
}
}
buf
}
let tag = |stream| LineTag {
tx: sink.tx.clone(),
step,
pkg: pkg.clone(),
phase,
stream,
};
let run = async {
let (out, err, status) = tokio::join!(pump(stdout), pump_err(stderr), child.wait());
let (out, err, status) = tokio::join!(
pump(stdout, tag(Stream::Stdout)),
pump(stderr, tag(Stream::Stderr)),
child.wait()
);
(out, err, status)
};
let (stdout, stderr, status) = tokio::select! {
triple = run => triple,
() = tokio::time::sleep(self.timeout) => {
return Err(self.stopped(&format!("timed out after {:?}", self.timeout)));
return Err(self.stopped(Stop::TimedOut(self.timeout)));
}
() = cancelled(self.cancel.as_ref()) => {
return Err(self.stopped("cancelled"));
return Err(self.stopped(Stop::Cancelled));
}
};
let status = status.map_err(|e| {
PdError::new(Code::IntUnexpected, format!("waiting on child failed: {e}"))
})?;
self.logged_exit(started, status.code());
Ok(Output {
code: status.code(),
@@ -339,6 +401,55 @@ impl Command {
}
}
/// Where one stream's lines are sent, and what each is tagged with.
struct LineTag {
tx: EventSink,
step: usize,
pkg: Option<PkgName>,
phase: ExecMode,
stream: Stream,
}
/// Read one stream to its end, forwarding each line to the drawer, and return it whole.
///
/// **Bytes, decoded lossily -- never `lines()`.** tokio's `Lines` returns an error at the first
/// byte that is not UTF-8, and the loop this replaced treated that as end of stream: it stopped
/// reading and dropped the pipe, so the child died on a broken pipe mid-install and the stderr the
/// classifier needed was cut off at that point. MSVC writes its diagnostics in the OEM code page,
/// so a non-English Windows was one failed source build away from it.
async fn pump<R: AsyncRead + Unpin>(reader: Option<R>, tag: LineTag) -> String {
let mut buf = String::new();
let Some(reader) = reader else {
return buf;
};
let mut reader = BufReader::new(reader);
let mut raw = Vec::new();
loop {
raw.clear();
match reader.read_until(b'\n', &mut raw).await {
Ok(0) | Err(_) => break,
Ok(_) => {}
}
let text = String::from_utf8_lossy(&raw);
let line = text.trim_end_matches(['\n', '\r']);
// The engine's own words, at DEBUG: everything a run printed is in the log when asked for
// (`PIPDOCK_LOG=debug`, `--verbose`), and a default log stays readable.
tracing::debug!(target: "pipdock::engine", stream = ?tag.stream, "{line}");
// Send failure means the UI stopped listening; keep capturing regardless so the summary
// and the log are still complete.
let _ = tag.tx.send(ProgressEvent::Line {
step: tag.step,
pkg: tag.pkg.clone(),
phase: tag.phase,
stream: tag.stream,
line: line.to_owned(),
});
buf.push_str(line);
buf.push('\n');
}
buf
}
/// Kills a spawned command **and everything it spawned** when dropped.
///
/// `kill_on_drop` reaches the direct child only, and for an engine that is not enough:
@@ -387,29 +498,125 @@ impl TreeGuard {
}
}
/// Write `contents` to a uniquely named temp file and return its path.
/// A file in the temp directory that is deleted when this is dropped.
///
/// SECURITY §2: `probe.py` is written with a random name per invocation and never installed into
/// the environment. The caller removes it; a leaked file in the temp directory is harmless, an
/// overwritten one would not be.
///
/// # Errors
/// `PD-SYS-002` when the file cannot be written.
pub fn write_temp(prefix: &str, extension: &str, contents: &str) -> Result<PathBuf> {
use std::hash::{BuildHasher as _, RandomState};
/// SECURITY §2: what PipDock hands an interpreter or an engine -- `probe.py`, a requirements file,
/// a freeze for pip-audit -- is written under a fresh random name and never installed anywhere.
/// The name is created with `create_new`, so an existing file is never written through: a leaked
/// temp file is harmless, an overwritten one would not be. (The function this replaced documented
/// that rule and then called `fs::write`, which overwrites.)
#[derive(Debug)]
pub struct TempFile {
path: PathBuf,
}
let dir = std::env::temp_dir();
// RandomState is seeded by the OS per process; hashing a fresh allocation's address plus a
// counter gives a unique-enough name without pulling in a rand dependency.
let nonce = RandomState::new().hash_one(std::time::Instant::now().elapsed().as_nanos());
let path = dir.join(format!("{prefix}-{nonce:016x}.{extension}"));
std::fs::write(&path, contents).map_err(|e| {
PdError::new(
Code::SysDiskFull,
format!("could not write {}: {e}", path.display()),
)
})?;
Ok(path)
impl TempFile {
/// Write `contents` to a new, uniquely named file.
///
/// # Errors
/// `PD-SYS-002` when the temp directory is full, `PD-SYS-001` for a path Windows refuses as too
/// long, `PD-PRM-001` when it is not writable, `PD-INT-001` otherwise.
pub fn create(prefix: &str, extension: &str, contents: &str) -> Result<Self> {
use std::io::Write as _;
let dir = std::env::temp_dir();
let mut last = None;
// A collision needs the same 64-bit nonce twice; the retry is for that theoretical case
// and for a planted file, which `create_new` refuses rather than writes through.
for _ in 0..8 {
let path = dir.join(format!("{prefix}-{:016x}.{extension}", nonce()));
match std::fs::OpenOptions::new()
.write(true)
.create_new(true)
.open(&path)
{
Ok(mut file) => {
return match file.write_all(contents.as_bytes()) {
Ok(()) => Ok(Self { path }),
Err(e) => {
drop(file);
let _ = std::fs::remove_file(&path);
Err(io_error(&path, &e))
}
};
}
Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => last = Some(e),
Err(e) => return Err(io_error(&path, &e)),
}
}
Err(PdError::new(
Code::IntUnexpected,
format!(
"could not create a unique temp file in {}: {}",
dir.display(),
last.map(|e| e.to_string()).unwrap_or_default()
),
))
}
/// Where the file is.
#[must_use]
pub fn path(&self) -> &Path {
&self.path
}
}
impl Drop for TempFile {
fn drop(&mut self) {
// Best effort: a file the OS still holds open (an antivirus scan, say) stays behind,
// which is untidy and harmless.
let _ = std::fs::remove_file(&self.path);
}
}
/// A per-call nonce: the process id, a process-wide counter and the clock, hashed with a
/// `RandomState` (randomly keyed per process). Unique without a `rand` dependency.
fn nonce() -> u64 {
use std::hash::{BuildHasher as _, RandomState};
use std::sync::atomic::{AtomicU64, Ordering};
static COUNTER: AtomicU64 = AtomicU64::new(0);
let count = COUNTER.fetch_add(1, Ordering::Relaxed);
let now = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map_or(0, |d| d.as_nanos());
RandomState::new().hash_one((std::process::id(), count, now))
}
/// Map a filesystem failure onto the catalog code whose advice fits it.
///
/// Shared so the shell stops answering every read or write failure with "not enough free disk
/// space" (`PD-SYS-002`), which it did for permission errors and missing files alike.
#[must_use]
pub fn io_error(path: &Path, e: &std::io::Error) -> PdError {
const ERROR_DISK_FULL: i32 = 112;
const ERROR_FILENAME_EXCED_RANGE: i32 = 206;
let code = match (e.raw_os_error(), e.kind()) {
(Some(ERROR_DISK_FULL), _) | (_, std::io::ErrorKind::StorageFull) => Code::SysDiskFull,
(Some(ERROR_FILENAME_EXCED_RANGE), _) => Code::SysPathTooLong,
(_, std::io::ErrorKind::PermissionDenied | std::io::ErrorKind::ReadOnlyFilesystem) => {
Code::PrmSitePackagesReadOnly
}
_ => Code::IntUnexpected,
};
PdError::new(code, format!("{}: {e}", path.display()))
}
/// [`io_error`] for a file **the user chose** — an export, a saved report, a requirements file —
/// where "PipDock is not allowed to write to this environment" (`PD-PRM-001`) would be the wrong
/// advice. The shell answered every such failure with `PD-SYS-002`, "not enough free disk space",
/// for a read-only folder and a missing file alike (U25).
#[must_use]
pub fn user_file_error(path: &Path, e: &std::io::Error) -> PdError {
const ERROR_SHARING_VIOLATION: i32 = 32;
let code = match (e.raw_os_error(), e.kind()) {
(Some(ERROR_SHARING_VIOLATION), _) => Code::PrmFileLocked,
(_, std::io::ErrorKind::PermissionDenied | std::io::ErrorKind::ReadOnlyFilesystem) => {
Code::PrmSourceReadOnly
}
_ => return io_error(path, e),
};
PdError::new(code, format!("{}: {e}", path.display()))
}
/// Canonicalize an interpreter path for identity purposes.
@@ -418,9 +625,19 @@ pub fn write_temp(prefix: &str, extension: &str, contents: &str) -> Result<PathB
/// — a Chocolatey shim yields `c:\python314\python.exe` where the direct install yields
/// `C:\Python314\python.exe`. `env_hash` is derived from this string (ARCHITECTURE §6), so without
/// case folding one environment would silently split its pins and snapshot history in two.
///
/// **Links are followed — except the one a virtual environment's own interpreter can be.** A venv
/// made with `python -m venv --symlinks` (the default off Windows) has a `python.exe` that links to
/// the Python it was made from, and following it made the venv the same environment as its base:
/// one pin store, one snapshot history, one cached graph, report and audit. Until 1.6.0 nothing in
/// the GUI could list the two apart, so nothing showed it; *Add interpreter…* can, and an
/// independent review of 1.6.0 found what came with it. For an interpreter whose environment has a
/// `pyvenv.cfg`, the folders are resolved and the file's own name is kept. Only such a venv's
/// identity changed: every other path, a copied venv's included, resolves exactly as it did, and a
/// linked venv's pins and snapshots from before stay with the base they were always filed under.
#[must_use]
pub fn canonical_interpreter(path: &Path) -> String {
let resolved = std::fs::canonicalize(path).unwrap_or_else(|_| path.to_path_buf());
let resolved = identity_path(path);
let text = resolved.display().to_string();
// Strip the Windows verbatim prefix canonicalize() adds; it is noise in logs and in the hash.
let text = text.strip_prefix(r"\\?\").unwrap_or(&text).to_owned();
@@ -431,6 +648,21 @@ pub fn canonical_interpreter(path: &Path) -> String {
}
}
/// The path [`canonical_interpreter`] names: every link resolved, but a venv's own interpreter only
/// up to its folder. A venv is recognised by the `pyvenv.cfg` beside `Scripts\` (`bin/` off
/// Windows), which is how Python itself recognises one.
fn identity_path(path: &Path) -> PathBuf {
if let (Some(dir), Some(name)) = (path.parent(), path.file_name())
&& dir
.parent()
.is_some_and(|prefix| prefix.join("pyvenv.cfg").is_file())
&& let Ok(dir) = std::fs::canonicalize(dir)
{
return dir.join(name);
}
std::fs::canonicalize(path).unwrap_or_else(|_| path.to_path_buf())
}
#[cfg(test)]
mod tests {
use super::*;
@@ -699,8 +931,63 @@ mod tests {
// does not become the only one.
let cmd = a_slow_command().timeout(Duration::from_millis(300));
let err = cmd.run().await.expect_err("must time out");
assert_eq!(err.code, Code::IntUnexpected);
assert!(err.message.contains("timed out"), "{}", err.message);
// An engine timeout, not "PipDock hit an internal error" — and said in the type, so no
// caller has to read the message to know.
assert_eq!(err.code, Code::EngTimedOut);
assert!(err.is_timeout(), "{err:?}");
assert!(!err.is_cancelled());
}
#[tokio::test]
async fn a_cancelled_run_says_so_in_its_type() {
let token = CancellationToken::new();
let cmd = a_slow_command().cancel(token.clone());
let handle = tokio::spawn(async move { cmd.run().await });
tokio::time::sleep(Duration::from_millis(200)).await;
token.cancel();
let err = handle
.await
.expect("task joins")
.expect_err("a cancelled run must not report success");
assert!(err.is_cancelled(), "{err:?}");
assert!(!err.is_timeout());
}
#[cfg(windows)]
#[tokio::test]
async fn the_pump_reads_past_bytes_that_are_not_utf8() {
// The bug: tokio's `lines()` errors at the first non-UTF-8 byte, the old loop took that as
// end of stream and dropped the pipe — so everything after it was lost, and a real child
// would die writing to a closed pipe. MSVC prints in the OEM code page, so this is a
// source build on a non-English Windows. `type` writes the bytes back verbatim.
let file = TempFile::create("pd-test-bytes", "txt", "").expect("temp file");
std::fs::write(
file.path(),
b"before\r\nL\xf6sung \xe0 \x81\x8d broken\r\nafter the bad line\r\n",
)
.expect("write raw bytes");
let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel();
let sink = ProgressSink::new(tx, 1, CancellationToken::new());
let out = Command::new("cmd")
.args(["/C", "type", &file.path().display().to_string()])
.run_streaming(&sink, None, ExecMode::Batch)
.await
.expect("the command runs");
drop(sink);
assert!(
out.stdout.contains("after the bad line"),
"output after the invalid bytes was lost: {:?}",
out.stdout
);
let mut lines = 0;
while let Some(event) = rx.recv().await {
if matches!(event, ProgressEvent::Line { .. }) {
lines += 1;
}
}
assert_eq!(lines, 3, "every line reaches the drawer, lossily decoded");
}
#[tokio::test]
@@ -726,13 +1013,83 @@ mod tests {
assert_eq!(err.code, Code::EngNotFound);
}
#[tokio::test]
async fn a_missing_interpreter_is_an_environment_error() {
// A deleted venv's python.exe used to be PD-ENG-001, "install the engine". The engine is
// fine; the environment is gone.
let err = Command::python(r"C:\pipdock\no\such\venv\Scripts\python.exe")
.arg("--version")
.run()
.await
.expect_err("missing interpreter must fail");
assert_eq!(err.code, Code::EnvInterpreterMissing);
}
#[test]
fn temp_files_get_unique_names() {
let a = write_temp("pd-test", "txt", "a").expect("write");
let b = write_temp("pd-test", "txt", "b").expect("write");
assert_ne!(a, b, "two probe writes must not collide");
let _ = std::fs::remove_file(a);
let _ = std::fs::remove_file(b);
fn temp_files_get_unique_names_and_go_away_on_drop() {
let a = TempFile::create("pd-test", "txt", "a").expect("write");
let b = TempFile::create("pd-test", "txt", "b").expect("write");
assert_ne!(a.path(), b.path(), "two probe writes must not collide");
assert_eq!(std::fs::read_to_string(a.path()).expect("read"), "a");
let (pa, pb) = (a.path().to_path_buf(), b.path().to_path_buf());
drop(a);
drop(b);
assert!(
!pa.exists() && !pb.exists(),
"dropping a TempFile removes it"
);
}
#[test]
fn filesystem_failures_carry_the_code_whose_advice_fits() {
use std::io::{Error, ErrorKind};
let p = Path::new(r"C:\x");
assert_eq!(
io_error(p, &Error::from_raw_os_error(112)).code,
Code::SysDiskFull
);
assert_eq!(
io_error(p, &Error::from_raw_os_error(206)).code,
Code::SysPathTooLong
);
assert_eq!(
io_error(p, &Error::from(ErrorKind::PermissionDenied)).code,
Code::PrmSitePackagesReadOnly
);
// A missing file is not "the disk is full", which every shell command used to say.
assert_eq!(
io_error(p, &Error::from(ErrorKind::NotFound)).code,
Code::IntUnexpected
);
}
#[test]
fn a_file_the_user_chose_is_never_blamed_on_the_environment() {
// U25. An export, a saved report or a requirements file is the user's own path, so a
// refusal there is about that folder — not PD-PRM-001's "PipDock may not write to this
// environment", and not PD-SYS-002's full disk.
use std::io::{Error, ErrorKind};
let p = Path::new(r"C:\Users\me\Desktop\requirements.txt");
assert_eq!(
user_file_error(p, &Error::from_raw_os_error(32)).code,
Code::PrmFileLocked,
"ERROR_SHARING_VIOLATION: another program has it open"
);
for kind in [ErrorKind::PermissionDenied, ErrorKind::ReadOnlyFilesystem] {
assert_eq!(
user_file_error(p, &Error::from(kind)).code,
Code::PrmSourceReadOnly,
"{kind:?}"
);
}
// Everything else is what any file failure is.
assert_eq!(
user_file_error(p, &Error::from_raw_os_error(112)).code,
Code::SysDiskFull
);
let missing = user_file_error(p, &Error::from(ErrorKind::NotFound));
assert_eq!(missing.code, Code::IntUnexpected);
assert!(missing.message.contains("requirements.txt"), "{missing}");
}
#[test]
@@ -751,4 +1108,83 @@ mod tests {
let p = canonical_interpreter(Path::new("."));
assert!(!p.starts_with(r"\\?\"), "got {p}");
}
fn identity_scratch(name: &str) -> PathBuf {
let dir = std::env::temp_dir().join(format!("pd-identity-{name}-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
std::fs::create_dir_all(&dir).expect("scratch dir");
dir
}
fn file_at(path: &Path) -> PathBuf {
std::fs::create_dir_all(path.parent().expect("a parent")).expect("parents");
std::fs::write(path, "").expect("write");
path.to_path_buf()
}
/// A file link, or `None` where this machine may not make one (Windows without Developer Mode).
fn file_link(target: &Path, at: &Path) -> Option<()> {
std::fs::create_dir_all(at.parent().expect("a parent")).expect("parents");
#[cfg(windows)]
let made = std::os::windows::fs::symlink_file(target, at);
#[cfg(not(windows))]
let made = std::os::unix::fs::symlink(target, at);
made.ok()
}
/// What the identity was before 1.6.0, for every path it did not mean to change.
fn resolved_fully(path: &Path) -> String {
let text = std::fs::canonicalize(path)
.expect("exists")
.display()
.to_string();
let text = text.strip_prefix(r"\\?\").unwrap_or(&text).to_owned();
if cfg!(windows) {
text.to_lowercase()
} else {
text
}
}
#[test]
fn a_venv_made_with_symlinks_is_its_own_environment() {
let dir = identity_scratch("venv");
let bin = if cfg!(windows) { "Scripts" } else { "bin" };
let exe = if cfg!(windows) {
"python.exe"
} else {
"python"
};
let base = file_at(&dir.join("base").join(exe));
// A copied venv — Windows' default — resolves exactly as before.
let copied = file_at(&dir.join("copied").join(bin).join(exe));
file_at(&dir.join("copied").join("pyvenv.cfg"));
assert_eq!(canonical_interpreter(&copied), resolved_fully(&copied));
assert_eq!(canonical_interpreter(&base), resolved_fully(&base));
let linked = dir.join("linked").join(bin).join(exe);
let Some(()) = file_link(&base, &linked) else {
eprintln!("skipped: this machine cannot create symbolic links");
return;
};
// A link that is not a venv's still resolves: two names for one file are one Python.
let alias = dir.join("alias").join(exe);
file_link(&base, &alias).expect("links work here");
assert_eq!(canonical_interpreter(&alias), canonical_interpreter(&base));
// Before it is a venv, the link is the base; once `pyvenv.cfg` says so, it is itself.
assert_eq!(canonical_interpreter(&linked), canonical_interpreter(&base));
file_at(&dir.join("linked").join("pyvenv.cfg"));
assert_ne!(
canonical_interpreter(&linked),
canonical_interpreter(&base),
"the venv is not the Python it was made from"
);
let folder = resolved_fully(&dir.join("linked").join(bin));
assert_eq!(
canonical_interpreter(&linked),
format!("{folder}{}{exe}", std::path::MAIN_SEPARATOR)
);
}
}
Loaded 100 of 346 files, more files were not shown because too many files have changed in this diff. Show more