Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
fdc51a8f2a | ||
|
|
2303aa2c7e | ||
|
|
807d9bf839 | ||
|
|
bb056c511d | ||
|
|
2539950cd5 | ||
|
|
a85242db1a | ||
|
|
567142901f | ||
|
|
e15d1637b0 | ||
|
|
11a643777b | ||
|
|
957343c07b | ||
|
|
b0b5d5e25c | ||
|
|
f21329b1f8 | ||
|
|
38e0226878 | ||
|
|
39be719b22 | ||
|
|
61e5e26c4e | ||
|
|
cfa5b4e1be | ||
|
|
9f9efbba79 | ||
|
|
c9128e479e | ||
|
|
ab16742989 | ||
|
|
ccae96dbeb | ||
|
|
efee3ca8d9 | ||
|
|
90fdfb3a2a | ||
|
|
7ee00893a7 | ||
|
|
f9c5001dc4 | ||
|
|
2df161cb36 | ||
|
|
95e45d7acc | ||
|
|
5aa4da87f4 | ||
|
|
4732f05197 | ||
|
|
3e2c5e1a07 | ||
|
|
d016b80014 | ||
|
|
885bca416c | ||
|
|
a5fc204de8 | ||
|
|
f1bab20306 | ||
|
|
6b70580b91 | ||
|
|
567b0ae8fa | ||
|
|
9754b95e66 | ||
|
|
2329d55298 | ||
|
|
17031c871d | ||
|
|
093ea4fce4 | ||
|
|
df1ad1518d | ||
|
|
d8ef9c4e99 | ||
|
|
8cc0323c59 | ||
|
|
0112b000ec | ||
|
|
41ab1e8085 | ||
|
|
aaa97f1b02 | ||
|
|
56ba7dcadd | ||
|
|
0085eae1ca | ||
|
|
2f6ad04967 | ||
|
|
4a617722d6 | ||
|
|
a3146895a0 | ||
|
|
3d45f2e936 | ||
|
|
57ed5756c4 | ||
|
|
283605a4a0 | ||
|
|
8c5f7e0b95 | ||
|
|
87dcb3452f | ||
|
|
6cd7e99385 | ||
|
|
7124227262 | ||
|
|
42f227c1aa | ||
|
|
310436552c | ||
|
|
25f0269631 | ||
|
|
12bf723daa | ||
|
|
7c6a506652 | ||
|
|
4da4c0f3ec | ||
|
|
8e4b87e4ab | ||
|
|
73e65303ca | ||
|
|
a9f476a2ae | ||
|
|
040571c7f7 | ||
|
|
77ca18cc33 | ||
|
|
b7fa16a281 | ||
|
|
f4cf9e4959 | ||
|
|
535b4c8707 | ||
|
|
545e86bd31 | ||
|
|
e2e75f63fb | ||
|
|
6ff2a10631 | ||
|
|
3cfb8f82ec | ||
|
|
5d63b31098 | ||
|
|
f9984fa4fb | ||
|
|
7e6ad52b4f | ||
|
|
53dedf8625 | ||
|
|
c0301fa3e8 | ||
|
|
8b18dc4795 | ||
|
|
d2993bbd7d | ||
|
|
80b2cee9e7 | ||
|
|
6559ebcc84 | ||
|
|
3e4f3d0243 | ||
|
|
8ddb2317f4 | ||
|
|
9409a82e84 | ||
|
|
2b4681954b | ||
|
|
2b07d4057b | ||
|
|
91a846c0fd | ||
|
|
d9c62ec6c9 | ||
|
|
1af0ec127b | ||
|
|
2300b637a9 | ||
|
|
f770e9c85f | ||
|
|
02cc17d95d | ||
|
|
8609518a37 | ||
|
|
6ef677bc01 | ||
|
|
c58fcac523 | ||
|
|
4ddec61ebb | ||
|
|
bf2947b6c3 | ||
|
|
3152c55eaa |
No files matched your search
+25
-6
@@ -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.
|
||||
|
||||
@@ -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. …"
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
@@ -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
|
||||
@@ -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
@@ -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
@@ -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]
|
||||
@@ -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))
|
||||
@@ -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 }
|
||||
@@ -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)
|
||||
})
|
||||
@@ -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
|
||||
@@ -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.
|
||||
#
|
||||
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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 }}
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
@@ -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/*
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
@@ -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)
|
||||
|
||||
File diff suppressed because it is too large.
Load diff
@@ -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/).
|
||||
@@ -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).
|
||||
@@ -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
@@ -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
File diff suppressed because it is too large.
Load diff
+6
-3
@@ -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"
|
||||
|
||||
@@ -1,14 +1,16 @@
|
||||
# PipDock
|
||||
|
||||
[](https://github.com/poli0981/pipdock/actions/workflows/ci-rust.yml)
|
||||
[](https://github.com/poli0981/pipdock/actions/workflows/ci-node.yml)
|
||||
[](https://github.com/poli0981/pipdock/actions/workflows/codeql.yml)
|
||||
[](https://github.com/poli0981/pipdock/releases)
|
||||
[](https://github.com/poli0981org/pipdock/actions/workflows/ci-rust.yml)
|
||||
[](https://github.com/poli0981org/pipdock/actions/workflows/ci-node.yml)
|
||||
[](https://github.com/poli0981org/pipdock/actions/workflows/codeql.yml)
|
||||
[](https://github.com/poli0981org/pipdock/releases)
|
||||
[](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.
|
||||
@@ -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.
|
||||
|
||||
@@ -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"] }
|
||||
@@ -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
|
||||
}
|
||||
@@ -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");
|
||||
|
||||
|
||||
+605
-188
File diff suppressed because it is too large.
Load diff
@@ -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(©);
|
||||
let copy_arg = copy.to_string_lossy().into_owned();
|
||||
code_of(&[
|
||||
"--log-file",
|
||||
©_arg,
|
||||
"list",
|
||||
"--env",
|
||||
"C:/definitely/not/here",
|
||||
]);
|
||||
let log = std::fs::read_to_string(©).expect("--log-file wrote its copy");
|
||||
let _ = std::fs::remove_file(©);
|
||||
|
||||
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"]));
|
||||
|
||||
@@ -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
|
||||
@@ -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"
|
||||
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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.
|
||||
|
||||
@@ -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"),
|
||||
|
||||
@@ -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");
|
||||
|
||||
@@ -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());
|
||||
}
|
||||
}
|
||||
@@ -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");
|
||||
}
|
||||
}
|
||||
@@ -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")
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -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:?}");
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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(¬epad, &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(¬hing),
|
||||
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())
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -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(),
|
||||
|
||||
@@ -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
@@ -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
Reference in new issue
Block a user