fix: what an independent review of 1.6.0 found

A venv made with --symlinks is run and stored as itself, not as the base
Python its python.exe links to: validate_interpreter returned the
canonical path, so `--env .venv update --all --yes` would have changed
the system Python. Canonicalizing now only decides where a link leads
and whether it is PipDock's own; a link to another program is refused,
and a Microsoft Store alias (os error 1920) is judged by its own path.

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

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

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5.5 committed 2026-11-21 23:22:12 +07:00
1 parent a85242db1a
commit 2539950cd5
18 files changed
+638 -102

No files matched your search

+7 -2
View File
@@ -6,7 +6,11 @@
# - 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.
# 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.
@@ -51,7 +55,8 @@ jobs:
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.event != 'pull_request_target' ||
github.event.workflow_run.name == 'Triage')
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
+19
View File
@@ -232,6 +232,25 @@ driving the installed build:
- **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. `envHash`
follows links for the same reason, so nothing that must tell a venv from its base may key on it.
- **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:
- **A venv is never externally managed**, and `sysconfig.get_path("stdlib")` inside one resolves to
+3
View File
@@ -30,6 +30,9 @@ from being developed to being maintained. ([#119](https://github.com/poli0981org
`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.
- **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
+34 -13
View File
@@ -217,8 +217,8 @@ pub async fn select_env(opts: &GlobalOpts) -> Result<PyEnv> {
/// CLI-SPEC §2 and `--env`'s own help text: `--env` wins; then the default `env use` set; then a
/// `.venv` in the working directory. The default was written by `env use` and read by nothing, so
/// `env use` reported success and every later command ignored it (X3). A default whose interpreter
/// is gone is said on stderr and skipped, rather than failing a command the user ran somewhere a
/// `.venv` would have answered.
/// is gone, or that [`envs::validate_interpreter`] refuses, is said on stderr and skipped, rather
/// than failing a command the user ran somewhere a `.venv` would have answered.
///
/// Returns the probe, not just the `PyEnv`, so a command that needs the listing does not probe a
/// second time — `list` did, and paid twice on every invocation (X28).
@@ -238,12 +238,23 @@ pub async fn select(opts: &GlobalOpts) -> Result<envs::ProbeResult> {
if let Some(default) = stored {
let interpreter = PathBuf::from(&default.interpreter);
if interpreter.is_file() {
return envs::probe(&interpreter, EnvSource::Manual).await;
// Checked like `--env`: a default written by 1.5.0 or earlier never was, and the file
// may have changed since. Refused, it is skipped with a warning, as a gone one is.
match envs::validate_interpreter(&interpreter, &app_data_dir()) {
Ok(checked) => return envs::probe(&checked, EnvSource::Manual).await,
Err(e) => eprintln!(
"warning: the default environment is not used: {}; `pipdock env use` sets \
another",
e.message
),
}
} else {
eprintln!(
"warning: the default environment ({}) no longer exists; `pipdock env use` sets \
another",
default.interpreter
);
}
eprintln!(
"warning: the default environment ({}) no longer exists; `pipdock env use` sets another",
default.interpreter
);
}
let cwd = std::env::current_dir().unwrap_or_default();
@@ -274,9 +285,13 @@ pub async fn env_list(opts: &GlobalOpts) -> Result<Exit> {
.collect();
let candidates = envs::scan_with(&manual).await;
// Through `probe_listed`, as the GUI's `env_scan` goes: an added entry is checked again before
// it runs, because what it was when added says nothing about what it is now.
let app_data = app_data_dir();
let mut rows = Vec::new();
for Candidate { path, source } in candidates {
let probed = envs::probe(&path, source).await;
for candidate in candidates {
let probed = envs::probe_listed(&candidate, &app_data).await;
let Candidate { path, source } = candidate;
rows.push((path, source, probed));
}
@@ -1043,7 +1058,9 @@ fn env_json(path: &Path, source: EnvSource, probed: &envs::ProbeResult) -> serde
/// `pipdock env add <path>` — the GUI's *Add interpreter…* (PRD P0-1).
///
/// Validated, probed, then stored, so the list never gains an entry that was refused or broken on
/// arrival. `--json` prints the entry exactly as `env list --json` will.
/// arrival. `--json` prints the entry in the shape of an `env list --json` element — not always the
/// element `env list` will show, which takes the discovered source and spelling when discovery also
/// finds the interpreter.
///
/// # Errors
/// `PD-ENV-001` when the path is missing, not named like a Python interpreter, or one of PipDock's
@@ -1079,19 +1096,23 @@ pub async fn env_add(opts: &GlobalOpts, path: &Path) -> Result<Exit> {
/// "not on the list" for the one case it exists for — found by its own test. Not being on the list
/// is not an error: the list is what was asked about, and it is right.
///
/// What was typed is made absolute first — `env add .venv` stores an absolute path, so `env remove
/// .venv` has to compare one, and a relative path never matched (independent review, 1.6.0).
///
/// # Errors
/// `PD-INT-001` when the store cannot be read or written.
pub fn env_remove(opts: &GlobalOpts, path: &Path) -> Result<Exit> {
let store = Store::open(&app_data_dir())?;
let interpreter = envs::interpreter_in(path);
let candidates = [interpreter.clone(), envs::venv_interpreter(path)];
let absolute = |p: PathBuf| std::path::absolute(&p).unwrap_or(p);
let interpreter = absolute(envs::interpreter_in(path));
let candidates = [interpreter.clone(), absolute(envs::venv_interpreter(path))];
let entry = store.manual_envs()?.into_iter().find(|m| {
candidates
.iter()
.any(|c| m.env_hash == envs::env_hash(c) || same_path(&m.interpreter, c))
});
let removed = match &entry {
Some(m) => store.remove_manual_env(&m.env_hash)?,
Some(m) => store.remove_manual_env(&m.env_hash, &m.interpreter)?,
None => false,
};
let shown = entry.map_or_else(|| interpreter.display().to_string(), |m| m.interpreter);
+103
View File
@@ -4,6 +4,7 @@
//! 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.
@@ -126,3 +127,105 @@ fn an_entry_whose_file_is_gone_is_listed_with_its_error_and_removed_by_its_path(
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}");
}
+160 -21
View File
@@ -239,14 +239,25 @@ pub async fn scan_with(manual: &[PathBuf]) -> Vec<Candidate> {
/// 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 canonical paths, or `..` would walk past it.
/// quietly break. The check is on resolved paths too, or `..` or a link would walk past it.
///
/// Returns the canonical path without Windows' verbatim prefix, which is what is stored and shown.
/// **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())));
@@ -258,24 +269,40 @@ pub fn validate_interpreter(path: &Path, app_data: &Path) -> Result<PathBuf> {
path.display()
)));
}
let canonical = path
.canonicalize()
.map(crate::health::project::plain)
let absolute = std::path::absolute(path)
.map(plain)
.map_err(|e| refuse(format!("cannot read {}: {e}", path.display())))?;
for own in [
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),
] {
if let Ok(own) = own.canonicalize().map(crate::health::project::plain)
&& canonical.starts_with(&own)
{
return Err(refuse(format!(
"{} is one of PipDock's own environments, which it manages itself",
path.display()
)));
}
]
.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(canonical)
Ok(absolute)
}
/// `python`, `python3` or `python3.12`, with `.exe` on Windows; any case. A version may end in `t`,
@@ -438,11 +465,17 @@ pub async fn scan_reporting(
/// 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`], which follows links: a venv made with `--symlinks` would otherwise
/// collapse into the base interpreter its `python.exe` points at, and the venv a person added would
/// never be listed.
fn merge_manual(found: BTreeMap<String, Candidate>, manual: &[PathBuf]) -> Vec<Candidate> {
let mut seen: std::collections::HashSet<String> = found.keys().cloned().collect();
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(canonical_interpreter(path)) {
if seen.insert(listing_key(path)) {
out.push(Candidate {
path: path.clone(),
source: EnvSource::Manual,
@@ -452,6 +485,45 @@ fn merge_manual(found: BTreeMap<String, Candidate>, manual: &[PathBuf]) -> Vec<C
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
@@ -703,7 +775,7 @@ mod tests {
}
#[test]
fn a_python_is_accepted_and_comes_back_canonical_and_plain() {
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");
@@ -712,10 +784,44 @@ mod tests {
"no verbatim prefix: {}",
got.display()
);
assert_eq!(
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,
crate::health::project::plain(python.canonicalize().expect("canonical"))
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]
@@ -1024,4 +1130,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())
);
}
}
+50 -5
View File
@@ -310,7 +310,12 @@ impl Store {
///
/// Adding one that is already there keeps its place and its date — the list is in the order
/// things were added, and adding again is not a new addition — but takes the path as given
/// this time, which is the canonical one [`crate::envs::validate_interpreter`] returned.
/// this time, which is the absolute one [`crate::envs::validate_interpreter`] returned, links
/// left alone.
///
/// Keyed by `env_hash`, which follows links, so a `--symlinks` venv and its base interpreter
/// are one entry here: added after the base, the venv replaces it. Only an added base and an
/// added venv of it meet this; the backlog records it with the rest of that identity.
///
/// # Errors
/// `PD-INT-001` when the write fails.
@@ -357,12 +362,21 @@ impl Store {
/// pins, snapshots and Health folder keyed to the same `env_hash` stay, ready for the day it
/// is added — or discovered — again.
///
/// **Matched by identity or by the stored path**, case-insensitively for the path. An
/// interpreter whose file is gone can no longer be canonicalized into the identity it was added
/// under — on a network share the two spellings differ (`\\server\share` against
/// `UNC\server\share`) — and that entry, listed with PD-ENV-001, is exactly the one a person
/// wants removed. By hash alone, removing it reported success and the next scan brought it back.
///
/// # Errors
/// `PD-INT-001` when the write fails. `Ok(false)` when it was not on the list.
pub fn remove_manual_env(&self, env_hash: &str) -> Result<bool> {
pub fn remove_manual_env(&self, env_hash: &str, interpreter: &str) -> Result<bool> {
let removed = self
.conn
.execute("DELETE FROM manual_envs WHERE env_hash = ?1", [env_hash])
.execute(
"DELETE FROM manual_envs WHERE env_hash = ?1 OR lower(interpreter) = lower(?2)",
rusqlite::params![env_hash, interpreter],
)
.map_err(|e| PdError::new(Code::IntUnexpected, format!("manual env store: {e}")))?;
Ok(removed > 0)
}
@@ -612,11 +626,17 @@ mod tests {
.expect("and Health's folder");
assert!(
store.remove_manual_env("h").expect("remove"),
!store
.remove_manual_env("other", r"D:\elsewhere\python.exe")
.expect("remove"),
"neither the identity nor the path matches"
);
assert!(
store.remove_manual_env("h", "unused").expect("remove"),
"it was there"
);
assert!(
!store.remove_manual_env("h").expect("again"),
!store.remove_manual_env("h", "unused").expect("again"),
"and is not now"
);
assert!(store.manual_envs().expect("read").is_empty());
@@ -630,4 +650,29 @@ mod tests {
"keyed data outlives the entry"
);
}
#[test]
fn a_gone_interpreter_is_removed_by_its_stored_path_when_its_identity_moved() {
// Added while the file was there, under the identity its canonical path hashed to; once the
// file is gone the row's identity is the hash of the stored text, which on a network share
// is spelled differently. The stored path, in any case, still matches.
let store = Store::in_memory().expect("open");
store
.add_manual_env(
"hash-of-unc-spelling",
r"\\server\share\proj\Scripts\python.exe",
"2026-11-02T00:00:00Z",
)
.expect("add");
assert!(
store
.remove_manual_env(
"hash-of-the-stored-text",
r"\\SERVER\share\proj\Scripts\python.exe"
)
.expect("remove"),
"matched by the path"
);
assert!(store.manual_envs().expect("read").is_empty());
}
}
+4 -4
View File
@@ -169,10 +169,10 @@ This table is the surface. A command that is not listed here does not exist; add
| Command | Returns | Purpose |
|---|---|---|
| `app_info` | `AppInfo` | PipDock's version, and the hash of the legal documents this build ships against. |
| `env_scan` | `EnvRow[]` | Discover environments, streaming `scan-progress`. A probe failure is reported on its own row, never fatal to the scan. Carries `pipVersion` and `healthProject`, both read before the probe loop so the store guard is never held across a probe. Probes run four at a time (they ran in series until 1.4.0), each under its own 60 s watchdog, so one hung interpreter costs its own row; rows keep discovery order. |
| `env_add_manual` | `EnvRow` | Add an interpreter chosen through *Add interpreter…* (*Browse…*, PRD P0-1) to the list `env_scan` appends to discovery, and return its row (1.6.0; the last entry `NOT_YET` held). `envs::validate_interpreter` first — an existing file named like Python, not one of PipDock's own venvs — then the probe, then the store, so a refused or broken interpreter is never listed. The row carries the canonical path that is stored. |
| `env_remove_manual` | `boolean` | Take an added interpreter off that list, by `envHash`; `false` when it was not on it. Touches nothing on disk, and leaves the pins, snapshots and Health folder keyed to it. |
| `env_probe` | `EnvRow` | Probe one interpreter without persisting it. Takes an optional `source`: absent means manual, and a **refresh must pass the row's own**, or the row comes back relabelled `manual`. A `manual` path is validated as `env_add_manual` validates one. Fills every field `env_scan` does, because `upgradePip` replaces the row wholesale. |
| `env_scan` | `EnvRow[]` | Discover environments, streaming `scan-progress`. A probe failure is reported on its own row, never fatal to the scan. Carries `pipVersion` and `healthProject`, both read before the probe loop so the store guard is never held across a probe. Probes run four at a time (they ran in series until 1.4.0), each under its own 60 s watchdog, so one hung interpreter costs its own row; rows keep discovery order. An added interpreter is validated again before its probe (`envs::probe_listed`, which `pipdock env list` shares): what it was when added says nothing about what a link points at now. |
| `env_add_manual` | `EnvRow` | Add an interpreter chosen through *Add interpreter…* (*Browse…*, PRD P0-1) to the list `env_scan` appends to discovery, and return its row (1.6.0; the last entry `NOT_YET` held). `envs::validate_interpreter` first — an existing file named like Python, not one of PipDock's own venvs — then the probe, then the store, so a refused or broken interpreter is never listed. The row carries the path that is stored: absolute, links left alone — a `--symlinks` venv's `python.exe` *is* the venv, and its target is the base interpreter. The frontend merges the row by that path, not by `envHash`, which follows links. |
| `env_remove_manual` | `boolean` | Take an added interpreter off that list, by the path its row shows; `false` when it was not on it. The path, not `envHash`: for a file that is gone the hash is recomputed from the stored text and can differ from the one it was added under, so removal by hash reported success while the entry stayed. Touches nothing on disk, and leaves the pins, snapshots and Health folder keyed to it. |
| `env_probe` | `EnvRow` | Probe one interpreter without persisting it. Takes an optional `source`: absent means manual, and a **refresh must pass the row's own**, or the row comes back relabelled `manual`. A `manual` path is validated as `env_add_manual` validates one — a check on what the webview *says*, not an enforcement point (SECURITY §2, backlog X36-b). Fills every field `env_scan` does, because `upgradePip` replaces the row wholesale. |
| `env_export` | `string` | Write the environment's `Engine::freeze` document to a user-chosen path and return it (PRD P1-3). Byte for byte, with no formatter: a freeze *is* a requirements file, and a constraints file is the same body under a different name. Rust-side for `health_save_report`'s reason — `dialog:allow-save` asks for a path and grants no `fs`. |
| `requirements_read` | `ParsedRequirements` | Read a `requirements.txt` into install specs **and whatever it could not use**. The skipped lines are the point: an include or an editable install means the file asks for something PipDock will not do, and the user has to see that before a preview claims to represent their file. |
| `pkg_list` | `Dist[]` | Installed distributions, read from `probe.py` rather than the engine — see §4 and DATA-FLOW §7. |
+1 -1
View File
@@ -143,7 +143,7 @@ An error's exit is derived from its code's area (`run::exit_for`) rather than wr
| `snapshot diff` | `Diff`, as a rollback with this engine would see it; the lines no index can restore are printed in text mode only |
| `env list` | An array, one object per discovered interpreter and then per added one (`source: "manual"`, 1.6.0): `interpreter`, `source`, `python`, `externallyManaged`, `hiddenUserSite`, `packages` (a count), `envHash`, `pipVersion` — or `interpreter`, `source` and `error: {code, message}` for one that could not be probed, without failing the rest |
| `env use` | The `PyEnv` that is now the default |
| `env add` | The added interpreter as one `env list` element, `source: "manual"` |
| `env add` | The added interpreter in the shape of one `env list` element, `source: "manual"`. When discovery also finds that interpreter, `env list` shows it under the discovered source and spelling instead, and the added entry waits unseen |
| `env remove` | `{interpreter, removed}` — `removed` is false when it was not on the list, which is not an error (exit 0) |
| `list` | `[Dist]`, from the probe; with `--outdated`, `[OutdatedDist]` |
| `search` | `[Hit]` |
+1 -1
View File
@@ -10,7 +10,7 @@
| Code | Detection (stderr/context pattern) | Cause | User action (EN; VI mirrored in locale files) |
|---|---|---|---|
| PD-ENV-001 | interpreter path missing/not executable — checked before the probe, and since 1.4.0 also a failed spawn of an interpreter that is not there (it read as PD-ENG-001, "install the engine"). Since 1.6.0 also a path a person supplied that `envs::validate_interpreter` refuses: not named like a Python interpreter, or inside PipDock's own tools or audit venv | env deleted or moved; the wrong file picked | Re-scan environments; remove stale entry — *Remove from list* on an added row (1.6.0), the first time this advice had a button |
| PD-ENV-001 | interpreter path missing/not executable — checked before the probe, and since 1.4.0 also a failed spawn of an interpreter that is not there (it read as PD-ENG-001, "install the engine"). Since 1.6.0 also a path a person supplied that `envs::validate_interpreter` refuses: not named like a Python interpreter (or a link to something that is not), or inside PipDock's own tools or audit venv — checked when it is added, again on every listing, and for the CLI's stored default when it is used | env deleted or moved; the wrong file picked | Re-scan environments; remove stale entry — *Remove from list* on an added row (1.6.0), the first time this advice had a button |
| PD-ENV-002 | **Raised by PipDock** on the fresh probe every mutating flow starts with (`flow::preamble`, DATA-FLOW §2): the `EXTERNALLY-MANAGED` marker beside the stdlib, never inside a venv — before any engine command. With the Settings override on, a flow raises it only for pip 23.0, which enforces PEP 668 and has no `--break-system-packages` (it arrived in 23.0.1); pip upkeep refuses a managed Python whatever the setting (DATA-FLOW §7). The `externally-managed-environment` stderr rule is a backstop | PEP 668 protected Python | Use a virtual env; system override only via Settings (discouraged) |
| PD-ENV-003 | probe.py non-zero / unparseable; `ModuleNotFoundError` in engine stderr | broken env metadata | Open logs; recreate the venv. A venv under a folder with non-ASCII characters no longer lands here: since 1.4.0 the probe runs under `-X utf8` (ARCHITECTURE §4) |
| PD-ENG-001 | engine binary not found: a program that cannot be started (uv not on PATH), `No module named pip`, or `ensurepip` failing to rebuild pip. A missing *interpreter* is PD-ENV-001 and an over-long command line PD-SYS-001 — both were this code before 1.4.0 | pip/uv missing | Install engine or switch engine in Settings |
+61
View File
@@ -1389,6 +1389,9 @@ starting a slice**: several are cheaper inside a slice that touches the same fil
| — | `pipdock-cli` `apply_fix`; `health::fix::dirty` | `health --fix --yes` outside a git repository proceeds: `dirty` answers `None` for a clean tree and for no repository alike | Needs a three-way answer from `dirty`, which the GUI's `health_dirty` shares |
| — | `pipdock-cli` | On a terminal, an impossible package is skipped at the prompt without the engine's explanation; `report-bug` points at a log excerpt the CLI never attaches; `uninstall --json --force` warns about "the breakage above", which JSON mode never printed | Small CLI copy fixes |
| X36/U55 | `src-tauri/src/commands.rs:425-467,1189-1214,1350-1377` | Save and export accept any path the webview names, and overwrite a sibling without asking | The picker is the only caller today; defence in depth, not a reachable hole |
| X36-b | `src-tauri/src/commands.rs` — every command taking a `PyEnv` (`pkg_list`, `pip_upgrade`, `deps_graph`, `plan_resolve`, `health_run`, `audit_run`, `engine_info`…) and `env_probe` | The interpreter a `PyEnv` names is run as the webview hands it back, and `env_probe` validates only a path the webview calls `manual` | Found by 1.6.0's independent review; predates it. The paths come from `env_scan`, which checks added entries itself, so this is defence in depth against a compromised webview — a `validate_interpreter` per command, its own change |
| — | `envs::env_hash`; `store` `manual_envs` | A venv made with `--symlinks` has its base interpreter's identity, because `env_hash` follows links: it shares the base's pins, snapshots and Health folder, discovery collapses the two into one row, and `manual_envs`, keyed by the hash, holds one of an added base and an added venv of it | Windows makes such a venv only with Developer Mode or as administrator. An identity that stops at the link is a new `env_hash`, so a migration of everything keyed by the old one |
| — | `exec.rs:633` `canonical_interpreter` | An interpreter on a share hashes as `unc\server\share\…`: the verbatim prefix `\\?\` is stripped, `\\?\UNC\` is not | Correcting it changes the identity — and orphans the pins and snapshots — of every interpreter on a share |
| — | `envs/mod.rs:131-138`, `engine/parse.rs:103-108`, `exec.rs:367-375`, `pins/mod.rs:85-89`, `store/mod.rs:253`, `index/mod.rs:144,448` | Failures that are dropped without a log line (a probe error entry, an unreadable pin row, a Job Object that would not attach…) | The log exists now; each wants a `tracing::warn!` and a look at whether it should surface |
| — | `PIP_MIN_VERSION_FOR_REPORT`, `UV_MIN_VERSION`, `probe_supported`, `MIN_PROBE_PYTHON` | Declared floors nothing enforces | Enforcing them is a user-visible refusal and wants its own copy and test |
| L56 | `audit.rs:165-168` | An audit's package count includes skipped packages | Cosmetic |
@@ -1688,6 +1691,64 @@ Tauri's configuration all assume the root now. And `pr-mode` is off in `qodana.y
had put it back on: 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 changed.
## 1.6.0 — *Add interpreter…* — **2026-11-21**
One slice: PRD P0-1's manual browse, the last command `NOT_YET` held, shipped as **Add
interpreter…** on Environments and `pipdock env add` / `env remove` in the CLI, over one new table.
With it the project moved to maintenance mode (the next section), and the org move above ships in
the same version. [#120](https://github.com/poli0981org/pipdock/pull/120).
**What shipped** (the changelog has it by reader):
| Piece | What |
|---|---|
| Core | `envs::validate_interpreter`, the one check a person's path passes: an existing file named like Python (`python3.14t.exe` included), leading to one, and not inside PipDock's own venvs — run and stored as given, made absolute. `envs::probe_listed` checks an added entry again before every listing probes it |
| Store | Schema v5, `manual_envs(env_hash, interpreter, added_at)` — apart from the CLI's `envs` recents, which has no source column. Adding again keeps an entry's place |
| Discovery | Added entries come after discovery's own and never shadow it. One whose file is gone is still listed, with `PD-ENV-001`, because that is the row a person needs in order to remove it |
| IPC | `env_add_manual`, `env_remove_manual`; `NOT_YET` is empty |
| GUI | *Add interpreter…* beside *Rescan*, as the empty state's one action and in `Ctrl+K`; *Remove from list* on added rows; a status line mounted before its words; focus to the heading when the focused row goes |
| CLI | `env add`, `env remove`; `env list` shows what was added; `--env`, `env use` and the stored default are validated |
| Maintenance | `triage.yml` over a tested `.github/scripts/triage.cjs`, the wording issue form, CONTRIBUTING's scope |
**What running found:**
- The first name rule refused the free-threaded `python3.14t.exe`, which the python.org installer
puts beside `python.exe` and the registry lists — found by running `env list` against the owner's
own Pythons, not by any test.
- `env remove <dir>` answered "not on the list" for a deleted venv — the one case it exists for —
because `interpreter_in` resolves only what is there. Found by its own test.
- Qodana for JS flagged a non-ASCII identifier in `triage.cjs`; renamed.
- The installed build — the release dry run's NSIS installer, a scratch `LOCALAPPDATA`, driven over
CDP: the legal gate once on a fresh profile; an interpreter added, rescanned, updated and rolled
back in a scratch venv named `myproj-env` outside the working directory; the entry kept across a
restart; the venv deleted and its `PD-ENV-001` row removed from the keyboard, focus to the
heading; `env list` and `env remove` agreeing with the screen. **Windows' own file picker was not
driven**: screen control was declined, and a release build's `__TAURI_INTERNALS__` cannot be
patched to stub it, so every add went through `envAddManual` with a path — the call the picker's
result makes.
**What an independent review found** once the suites and that smoke were green, reading the diff
cold and reproducing with a scratch `LOCALAPPDATA` and the debug CLI. Every fix has a test that was
seen to fail first:
| # | Severity | Found | Now |
|---|---|---|---|
| 1 | High | `validate_interpreter` returned the canonical path, and every caller ran and stored it. A `--symlinks` venv's `python.exe` is a link to its base, so `env use <venv>` stored `C:\Python315\python.exe` (reproduced) and `--env .venv update --all --yes` would have changed the system Python; the GUI merged the added venv into the registry row by `envHash` and selected that. The name check looked at the link while the target was stored, so a `python.exe` linking to `notepad.exe` stored `notepad.exe` | The path made absolute is run and stored, links left alone; canonicalizing only decides where a link leads and whether it is PipDock's own. The UI merges and removes by path |
| 2 | Medium | A Microsoft Store Python was refused: an app-execution alias reports `is_file()` and fails `canonicalize()` with os error 1920, so `--env` and `env use`, which worked in 1.5.0, would have exited 3 | Judged by its own path when it cannot be resolved, as `canonical_interpreter` always fell back |
| 3 | Medium | Not an enforcement point over IPC, while SECURITY §2 and `env_probe`'s doc said it was: `env_probe` checks only a path the webview calls `manual`, and every `PyEnv` command runs `env.interpreter` unchecked. Stored entries, and the CLI's default from 1.5.0, were probed unchecked too | Both sentences corrected. Added entries are checked again on every listing (`probe_listed`, both heads), the stored default when it is used. The IPC exposure predates 1.6.0: backlog X36-b |
| 4 | Low–Medium | *Remove from list* announced success while the entry stayed, for an entry on a share whose file was gone: the row's `envHash` was recomputed from the stored text, while the identity it was added under had been hashed from `UNC\server\share\…` | Removed by the path the row shows; the store matches either |
| 5 | Low–Medium | Re-adding a venv deleted and made again kept the broken row and selected it — a row with no `env`, which nothing loads packages for | The fresh row replaces it and is selected |
| 6 | Low | Removing during a scan: the scan had read the list first, so its result brought the row back while the status line said it was gone | Each waits for the other; *Remove from list* is busy while a scan runs |
| 7 | Low | `env remove .venv` never matched what `env add .venv` stored | The typed path is made absolute first |
| — | — | `env add --json` was documented as printing the entry "exactly as" `env list` would, untrue when discovery also finds it; a Triage failure on a pull request reached no channel | Wording; `notify.yml` reports Triage's `pull_request_target` runs |
Reviewed and found sound: `triage.yml`'s handling of a stranger's pull request (the base branch's
scripts only, no expression reaching a shell, writes that start no runs), who it can close, the
v4→v5 migration, the store guard, and the copy in both catalogues.
**Left, in the backlog with a reason each:** X36-b, the `PyEnv` commands' trust in the webview's
path; a `--symlinks` venv sharing its base's identity; the identity of an interpreter on a share.
## Maintenance mode — from 1.6.0
**PipDock is maintained rather than developed from 1.6.0 on** (owner decision, 2026-11-21, with the
+2 -2
View File
@@ -12,11 +12,11 @@ PipDock's job is to run package managers against local environments. The realist
- Package names are validated against the PEP 508 name grammar (`^[A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?$` after normalization) and version specs against PEP 440 before entering argv; anything else is rejected client-side with PD-PKG-002.
- **The version half has been true only since 1.4.0.** Names always went through `PkgName`; versions were plain strings, so a dock-bay entry of `2.0 ; python_version<'0'` reached argv as one token pip read as a requirement whose marker is false — a silent no-op install. `pep440` is now the one place that says what a version and a specifier set may look like, and every way text arrives passes through it: install specs from either head, imported requirements, the IPC types that carry them, and the installed versions the guard set restates.
- **Requirements and constraints reach an engine as files** (`-r <file>`, `-c <file>`) since 1.4.0: restating the installed set one argv entry per package (SP-1) passed Windows' 32,767-character command line at about 1,300 packages. The files hold exactly the tokens argv held — rendered `PinnedSpec`s and validated `Spec`s — and, like `probe.py` and the pins handed to pip-audit, each is an `exec::TempFile`: a fresh random name created with `create_new`, so an existing file is never written through, and deleted on drop.
- Interpreter paths come only from discovery (registry/launcher/uv/venv scan) or from a person — *Add interpreter…*, `pipdock env add`, `env use`, `--env`. **A path from a person goes through `envs::validate_interpreter` before anything runs it** (since 1.6.0; this line claimed it for two milestones while the only check was existence): it must be an existing file named `python.exe`, `python3.exe`, `python3.12.exe` or the free-threaded `python3.14t.exe`, so the probe — which executes the file — cannot be pointed at another program; it must not be inside PipDock's own tools or audit venv, compared canonically so `..` cannot walk past; and it is stored canonical, without the verbatim prefix. Each refusal is PD-ENV-001. The picker that suggests a path is not the check: `env_add_manual` and a `manual` `env_probe` validate whatever the webview names.
- Interpreter paths come only from discovery (registry/launcher/uv/venv scan) or from a person — *Add interpreter…*, `pipdock env add`, `env use`, `--env`. **A path from a person goes through `envs::validate_interpreter` before anything runs it** (since 1.6.0; this line claimed it for two milestones while the only check was existence): it must be an existing file named `python.exe`, `python3.exe`, `python3.12.exe` or the free-threaded `python3.14t.exe`, so the probe — which executes the file — cannot be pointed at another program, and **where it leads** is checked too, so a `python.exe` that links to another program is refused; it must not be inside PipDock's own tools or audit venv, compared canonically so `..` or a link cannot walk past. It is **run and stored as given, made absolute, with its links left alone**: a venv made with `--symlinks` has a `python.exe` that links to its base interpreter, and only running the link finds the venv — the first 1.6.0 build stored the canonical path, so `--env .venv` acted on the base Python. A Microsoft Store app-execution alias, which Windows will not resolve (os error 1920), is judged by its own path. Each refusal is PD-ENV-001. The picker that suggests a path is not the check; `env_add_manual` is, an added entry is checked again on every listing (`envs::probe_listed`, in both heads), and the CLI checks the stored `env use` default when it uses it. **What this is not is an enforcement point against the webview**: `env_probe` checks only a path the webview *says* is manual, and every command taking a `PyEnv` runs `env.interpreter` as the webview hands it back from `env_scan` — the trust backlog X36 records, which predates 1.6.0. An independent review of 1.6.0 found this bullet saying otherwise, the second time it has said more than the code.
- `probe.py` is stdlib-only, written to a temp file with a random name, executed with `-I` (isolated mode: ignores `PYTHONPATH`, user site) so a poisoned env cannot inject code into the probe — and with `-X utf8`, because `-I` implies `-E`, which also discards invariant 7's `PYTHONUTF8`/`PYTHONIOENCODING`: until 1.4.0 a venv under a folder named in Vietnamese crashed the probe.
- **Owner decision 2026-07-27 (spike SP-6): `-I` stays, and the cost is disclosed rather than hidden.** Isolated mode also disables user site-packages, so on a *non-venv* system Python the probe sees fewer distributions than `pip list` does — measured at 352 vs 375 on the reference machine. Virtual environments, the primary target, have no user site and are unaffected. The probe therefore reports `hidden_user_site`: the user-site path when it exists, is off `sys.path`, and is non-empty; `null` otherwise. Only when it is non-null does the Installed screen show a note naming the path (`env.partialListing`), so the disclosure is accurate rather than a permanent disclaimer. Dropping to `-E` was rejected: a package in user site is part of the untrusted surface the isolation exists to exclude.
- Child processes run with inherited user privileges only; PipDock never elevates in v1 (PD-PRM-001 blocks instead — elevation broker is P2 with its own review).
- The Code Health **project folder** is a user file-pick that becomes the working directory of three subprocesses and, with `--fix`, the target of a write. It is canonicalized and existence-checked like an interpreter path, and a folder resolving inside `%LOCALAPPDATA%\PipDock\data\tools` is refused — rewriting the tools venv would break Health itself.
- The Code Health **project folder** is a user file-pick that becomes the working directory of three subprocesses and, with `--fix`, the target of a write. It is canonicalized and existence-checked, and a folder resolving inside `%LOCALAPPDATA%\PipDock\data\tools` is refused — rewriting the tools venv would break Health itself.
- `git` is the one PATH-resolved program PipDock runs with a **user-controlled** working directory (the dirty-tree check). Windows' legacy `CreateProcess` search order would make a `git.exe` planted in a cloned repository win; **verified by planting one** — Rust's `Command` does its own resolution and does not search the current directory. Re-check if the process layer changes. A repository can also name a program for `git status` to run — `core.fsmonitor` in its own `.git/config`, which a project folder downloaded rather than cloned brings with it — so asking "is it safe to write here" would have run it. The check has been `git -c core.fsmonitor=false --no-optional-locks status …` since 1.4.0; a command-line `-c` wins over every config file.
## 3. PEP 668 policy (protecting the system Python)
+4 -1
View File
@@ -98,7 +98,10 @@ action (§7): a native picker filtered to `.exe`, then `env_add_manual`, which r
named like a Python interpreter or inside PipDock's own venvs before it runs it, and selects the row
it adds. An added row carries the `manual` chip and **Remove from list** — kept even when its file
is gone, so the `PD-ENV-001` row can be removed — and the outcome is said in a `role="status"`
line mounted before its words. Discovery is unchanged: the registry, the `py` launcher,
line mounted before its words. Both are busy while a scan runs, and a scan waits for either: a scan
that read the list before the change would undo it. An added row is matched to the list by its
path, never by `envHash`, which follows links — a venv made with `--symlinks` is listed beside the
base Python it links to, not merged into it. Discovery is unchanged: the registry, the `py` launcher,
`uv python list`, and a `.venv`, `venv`, `env` or `.env` in the working directory. And there is no star-as-default: the
selection lasts for the session, and a rescan keeps it or falls back to the first usable row. The
CLI's `env use` stores a default, honoured since 1.4.0; the GUI does not read it.
+33 -19
View File
@@ -116,14 +116,17 @@ pub struct EnvRow {
pub error: Option<WireError>,
}
/// One listed candidate as a row. Through [`envs::probe_listed`], so an added interpreter is checked
/// again before it runs, exactly as `pipdock env list` checks it.
async fn probe_row(
path: std::path::PathBuf,
source: EnvSource,
candidate: envs::Candidate,
health_project: Option<String>,
app_data: &std::path::Path,
) -> EnvRow {
let env_hash = envs::env_hash(&path);
let interpreter = path.display().to_string();
match envs::probe(&path, source).await {
let env_hash = envs::env_hash(&candidate.path);
let interpreter = candidate.path.display().to_string();
let source = candidate.source;
match envs::probe_listed(&candidate, app_data).await {
Ok(probed) => EnvRow {
interpreter,
source,
@@ -216,12 +219,10 @@ pub async fn env_scan(
for (index, candidate) in candidates.into_iter().enumerate() {
let folder = folders.remove(&envs::env_hash(&candidate.path));
let gate = std::sync::Arc::clone(&gate);
let app_data = state.app_data.clone();
probes.spawn(async move {
let _permit = gate.acquire_owned().await.ok();
(
index,
probe_row(candidate.path, candidate.source, folder).await,
)
(index, probe_row(candidate, folder, &app_data).await)
});
}
let mut rows = Vec::new();
@@ -252,8 +253,11 @@ pub async fn env_scan(
/// source the row already had.
///
/// A path the webview names as `manual` is checked by [`envs::validate_interpreter`] before the
/// probe runs it, as `env_add_manual` checks one: discovery found the others where Python puts
/// interpreters, and only a manual path can name anything at all.
/// probe runs it, as `env_add_manual` checks one. That is a check on what the **webview says**, not
/// an enforcement point: a webview that names another source skips it, and every command taking a
/// `PyEnv` runs `env.interpreter` unchecked — the trust in the webview's paths that backlog X36
/// records, which predates *Add interpreter…*. An independent review of 1.6.0 found this sentence
/// claiming more than that, as SECURITY §2 did.
///
/// # Errors
/// `PD-ENV-001` when there is no usable interpreter there, `PD-ENV-003` when the probe output
@@ -293,10 +297,11 @@ pub async fn env_probe(
/// Add an interpreter the person picked with *Browse…* to the list, and return its row (PRD P0-1).
///
/// Validated, probed, then stored — in that order, so the list never gains an entry that was
/// refused or broken on arrival. The row carries the canonical path, which is what is stored and
/// what the next `env_scan` returns, so the screen does not change under the user's eyes. Adding
/// one already listed — by discovery or by an earlier *Browse…* — is not an error: the row comes
/// back, and the frontend merges it by `envHash`.
/// refused or broken on arrival. The row carries the path made absolute with its links left alone
/// (a `--symlinks` venv's `python.exe` is the venv; its target is the base), which is what is stored
/// and what the next `env_scan` returns, so the screen does not change under the user's eyes.
/// Adding one already listed — by discovery or by an earlier *Browse…* — is not an error: the row
/// comes back, and the frontend merges it by that path, not by `envHash`, which follows links.
///
/// # Errors
/// `PD-ENV-001` when the file is missing, is not named like a Python interpreter, or is one of
@@ -331,15 +336,24 @@ pub async fn env_add_manual(
})
}
/// Take an interpreter off the list *Browse…* put it on. Nothing on disk is touched, and its pins,
/// snapshots and Health folder stay keyed to it for the day it is added again.
/// Take an interpreter off the list *Add interpreter…* put it on, by the path its row shows.
/// Nothing on disk is touched, and its pins, snapshots and Health folder stay keyed to it for the
/// day it is added again.
///
/// The path rather than the row's `envHash`: for an interpreter whose file is gone — the row that
/// most needs removing — the identity is recomputed from the stored text and can differ from the
/// one it was added under, and removing by hash then reported success while the entry stayed.
///
/// # Errors
/// `PD-INT-001` when the store cannot be written. `false` when it was not on the list.
#[tauri::command]
pub async fn env_remove_manual(state: tauri::State<'_, AppState>, env_hash: String) -> Wire<bool> {
pub async fn env_remove_manual(
state: tauri::State<'_, AppState>,
interpreter: String,
) -> Wire<bool> {
let hash = envs::env_hash(std::path::Path::new(&interpreter));
let store = state.store.lock().await;
Ok(store.remove_manual_env(&env_hash)?)
Ok(store.remove_manual_env(&hash, &interpreter)?)
}
/// [`envs::validate_interpreter`], off the async workers: it reads the file system, which
+7 -3
View File
@@ -219,9 +219,13 @@ export const envProbe = (interpreter: string, source?: EnvSource): Promise<EnvRo
export const envAddManual = (interpreter: string): Promise<EnvRow> =>
invoke('env_add_manual', { interpreter })
/** Take an added interpreter off that list. Nothing on disk is touched. `false` if it was not on it. */
export const envRemoveManual = (envHash: string): Promise<boolean> =>
invoke('env_remove_manual', { envHash })
/**
* Take an added interpreter off that list, by the path its row shows. Nothing on disk is touched;
* `false` if it was not on it. The path, not the `envHash`: an interpreter whose file is gone gets
* its identity recomputed from the stored text, which can differ from the one it was added under.
*/
export const envRemoveManual = (interpreter: string): Promise<boolean> =>
invoke('env_remove_manual', { interpreter })
/**
* Everything installed in `env` — the Installed table.
+104 -6
View File
@@ -2,8 +2,10 @@
* *Add interpreter…* and *Remove from list* — PRD P0-1's manual browse (1.6.0).
*
* The store half and the screen half, because the seam between them is where this app's bugs have
* lived (CLAUDE.md, `PdPlanPanel`): the store merges by `envHash` and the screen renders by
* interpreter path, and a test of either alone would not see the two disagree.
* lived (CLAUDE.md, `PdPlanPanel`). Both key on the interpreter **path**: the first version merged
* and removed by `envHash`, which follows links — so a venv made with `--symlinks` merged into the
* base Python it points at, and *Remove from list* took every row sharing the hash with it. An
* independent review of 1.6.0 found both, and the cases below are the ones it named.
*/
import { act, fireEvent, render, screen, waitFor } from '@testing-library/react'
@@ -89,7 +91,8 @@ describe('the store', () => {
})
it('does not list an interpreter twice when discovery already has it', async () => {
// The same environment under the registry's spelling: one row, the discovered one, selected.
// The same file in another case — Windows paths are case-insensitive: one row, the
// discovered one, under the spelling the next scan will list, selected.
vi.mocked(ipc.pickOpenFile).mockResolvedValueOnce(DISCOVERED.interpreter)
vi.mocked(ipc.envAddManual).mockResolvedValueOnce({
...ADDED,
@@ -105,6 +108,62 @@ describe('the store', () => {
expect(state.selected).toBe(DISCOVERED.interpreter)
})
it('lists a venv made with --symlinks beside the base Python it links to, and selects the venv', async () => {
// Its `python.exe` is a link to the base, so the two share an `envHash`. Merging on the hash
// selected the base: the next update would have changed the system's Python, not the venv's.
const linked: EnvRow = { ...ADDED, envHash: DISCOVERED.envHash }
vi.mocked(ipc.pickOpenFile).mockResolvedValueOnce(linked.interpreter)
vi.mocked(ipc.envAddManual).mockResolvedValueOnce(linked)
useEnvStore.setState({ rows: [DISCOVERED], selected: DISCOVERED.interpreter })
await useEnvStore.getState().addManual('Choose one')
const state = useEnvStore.getState()
expect(state.rows).toEqual([DISCOVERED, linked])
expect(state.selected).toBe(linked.interpreter)
})
it('replaces a broken row when its venv is made again, and selects the working one', async () => {
const fresh: EnvRow = {
interpreter: GONE.interpreter,
source: 'manual',
envHash: GONE.envHash,
env: {
interpreter: GONE.interpreter,
prefix: 'E:\\gone',
pythonVersion: '3.13.9',
externallyManaged: false,
hiddenUserSite: null,
source: 'manual',
},
}
vi.mocked(ipc.pickOpenFile).mockResolvedValueOnce(GONE.interpreter)
vi.mocked(ipc.envAddManual).mockResolvedValueOnce(fresh)
useEnvStore.setState({ rows: [DISCOVERED, GONE], selected: DISCOVERED.interpreter })
await useEnvStore.getState().addManual('Choose one')
const state = useEnvStore.getState()
expect(state.rows).toEqual([DISCOVERED, fresh])
expect(state.rows[1]?.error).toBeUndefined()
expect(state.selected).toBe(GONE.interpreter)
})
it('takes the spelling Rust stored when an added interpreter is added again', async () => {
// `add_manual_env` rewrites the stored text, so the next scan lists the new spelling; a row
// kept under the old one would leave the selection naming a row that is about to be renamed.
const respelled: EnvRow = { ...ADDED, interpreter: ADDED.interpreter.toLowerCase() }
vi.mocked(ipc.pickOpenFile).mockResolvedValueOnce(respelled.interpreter)
vi.mocked(ipc.envAddManual).mockResolvedValueOnce(respelled)
useEnvStore.setState({ rows: [DISCOVERED, ADDED], selected: ADDED.interpreter })
await useEnvStore.getState().addManual('Choose one')
const state = useEnvStore.getState()
expect(state.rows).toEqual([DISCOVERED, respelled])
expect(state.selected).toBe(respelled.interpreter)
})
it('keeps a refused path off the list and shows why', async () => {
const refused: PdError = {
code: 'PD-ENV-001',
@@ -140,9 +199,11 @@ describe('the store', () => {
openFor: ADDED.interpreter,
})
await useEnvStore.getState().removeManual(ADDED.envHash)
await useEnvStore.getState().removeManual(ADDED.interpreter)
expect(ipc.envRemoveManual).toHaveBeenCalledWith(ADDED.envHash)
// By the path the row shows: for a file that is gone, the hash Rust would recompute from the
// stored text can differ from the one it was added under, and removing by it never matched.
expect(ipc.envRemoveManual).toHaveBeenCalledWith(ADDED.interpreter)
const state = useEnvStore.getState()
expect(state.rows).toEqual([DISCOVERED])
expect(state.selected).toBe(DISCOVERED.interpreter)
@@ -153,10 +214,29 @@ describe('the store', () => {
it('leaves the selection alone when another row is removed', async () => {
useEnvStore.setState({ rows: [DISCOVERED, GONE], selected: DISCOVERED.interpreter })
await useEnvStore.getState().removeManual(GONE.envHash)
await useEnvStore.getState().removeManual(GONE.interpreter)
expect(useEnvStore.getState().selected).toBe(DISCOVERED.interpreter)
expect(useEnvStore.getState().rows).toEqual([DISCOVERED])
})
it('removes only the row it was asked about when another shares its envHash', async () => {
const linked: EnvRow = { ...ADDED, envHash: DISCOVERED.envHash }
useEnvStore.setState({ rows: [DISCOVERED, linked], selected: DISCOVERED.interpreter })
await useEnvStore.getState().removeManual(linked.interpreter)
expect(useEnvStore.getState().rows).toEqual([DISCOVERED])
})
it('refuses to remove while a scan runs, and to scan while a removal runs', async () => {
// A scan that read the list before the removal was written would bring the row back.
useEnvStore.setState({ rows: [DISCOVERED, ADDED], scanning: true })
await useEnvStore.getState().removeManual(ADDED.interpreter)
expect(ipc.envRemoveManual).not.toHaveBeenCalled()
expect(useEnvStore.getState().rows).toEqual([DISCOVERED, ADDED])
useEnvStore.setState({ scanning: false, removingManual: ADDED.interpreter })
await useEnvStore.getState().scan()
expect(ipc.envScan).not.toHaveBeenCalled()
})
})
describe('the screen', () => {
@@ -197,6 +277,24 @@ describe('the screen', () => {
for (const button of removes) expect(button).not.toHaveAttribute('data-destructive')
})
it('makes Remove from list busy while a scan runs, without taking focus from it', () => {
const removeManual = vi.fn()
useEnvStore.setState({ rows: [ADDED], scanning: true, scan: vi.fn(), removeManual })
render(<PdEnvironments />)
const remove = screen.getByRole('button', { name: `Remove from list: ${ADDED.interpreter}` })
expect(remove).toHaveAttribute('aria-disabled', 'true')
expect(remove).not.toBeDisabled()
fireEvent.click(remove)
expect(removeManual).not.toHaveBeenCalled()
act(() => {
useEnvStore.setState({ scanning: false })
})
fireEvent.click(remove)
expect(removeManual).toHaveBeenCalledWith(ADDED.interpreter)
})
it('says what was added in a status region that was there before the words', () => {
useEnvStore.setState({ rows: [DISCOVERED], scan: vi.fn() })
render(<PdEnvironments />)
+2 -2
View File
@@ -44,12 +44,12 @@ function SourceChip({ row }: { row: EnvRow }) {
function RemoveButton({ row }: { row: EnvRow }) {
const { t } = useTranslation()
const removeManual = useEnvStore((s) => s.removeManual)
const busy = useEnvStore((s) => s.removingManual !== null)
const busy = useEnvStore((s) => s.removingManual !== null || s.scanning)
return (
<button
type="button"
onClick={() => {
if (!busy) void removeManual(row.envHash)
if (!busy) void removeManual(row.interpreter)
}}
aria-disabled={busy}
// The visible words first, then the path: the name contains what is on the button.
+43 -22
View File
@@ -185,20 +185,24 @@ interface EnvState {
* *Add interpreter…* (PRD P0-1): ask for a `python.exe`, put it on the list, select it.
*
* `title` arrives localized — `@/ipc` has no `t`. Cancelling the picker changes nothing. The new
* row is merged **by `envHash`**, not by path: Rust returns the canonical path it stored, and the
* same interpreter may already be listed under the spelling discovery found. Pins and snapshots
* key on the hash, so a second row would split nothing — it would only show one environment
* twice. Refused while a scan runs: the scan read the list before this add wrote to it, and its
* result would replace `rows` without the new one.
* row is merged **by its path, case-insensitively**, not by `envHash`: the hash follows links, so
* a venv made with `--symlinks` shares its base interpreter's, and merging on it selected the
* base Python in place of the venv a person had just added. A listed row with the same path is
* kept only when discovery found it and it works; one this list put there, or one that is
* *broken* — a venv deleted and made again — is replaced by the row Rust returned and selected.
* Refused while a scan runs: the scan read the list before this add wrote to it, and its result
* would replace `rows` without the new one.
*/
addManual: (title: string) => Promise<void>
/** Which added interpreter is being taken off the list, by `envHash`. */
/** Which added interpreter is being taken off the list, by its path. */
removingManual: string | null
/**
* Take an added interpreter off the list. Nothing on disk is touched. A selected or opened row
* that goes is deselected or closed; selection falls back as a rescan's would.
* Take an added interpreter off the list, by its path. Nothing on disk is touched. A selected or
* opened row that goes is deselected or closed; selection falls back as a rescan's would.
* Refused while a scan runs, for the add's reason the other way round: a scan that read the list
* before the removal would bring the row back.
*/
removeManual: (envHash: string) => Promise<void>
removeManual: (interpreter: string) => Promise<void>
/** What the last add or removal did, for the screen's status region — a path, or null. */
manualNotice: { kind: 'added' | 'removed'; path: string } | null
@@ -338,6 +342,12 @@ const NO_SNAPSHOTS = {
diffLoading: 'idle' as LoadState,
}
/** Whether two interpreter paths name the same file as a listing compares them — Windows paths are
* case-insensitive (CLAUDE.md, invariant 9), and the app ships for Windows only. */
function samePath(a: string, b: string): boolean {
return a.toLowerCase() === b.toLowerCase()
}
/** Recompute the joined view from the three raw responses. */
function joined(dists: Dist[], outdated: OutdatedDist[], pins: Pin[]) {
const { rows, orphanOutdated } = joinRows(dists, outdated, pins)
@@ -363,9 +373,10 @@ export const useEnvStore = create<EnvState>((set, get) => ({
// expensive thing the app can do twice. `PdEnvironments` has started two on every mount since
// Stage 1 — StrictMode runs effects twice in development — which was invisible because both
// produce the same rows.
// Nor while an *Add interpreter…* is in flight: a scan that read the list before the add wrote
// to it would replace `rows` without the row the add is about to append.
if (get().scanning || get().addingManual) return
// Nor while an *Add interpreter…* or a *Remove from list* is in flight: a scan that read the
// list before the change was written would replace `rows` without the added row, or with the
// removed one.
if (get().scanning || get().addingManual || get().removingManual !== null) return
set({ scanning: true, error: null })
try {
const rows = await envScan()
@@ -435,13 +446,22 @@ export const useEnvStore = create<EnvState>((set, get) => ({
}
const row = await envAddManual(picked)
set((state) => {
const listed = state.rows.find((r) => r.envHash === row.envHash)
const interpreter = listed?.interpreter ?? row.interpreter
const listed = state.rows.find((r) => samePath(r.interpreter, row.interpreter))
// A healthy discovered row keeps its place and its spelling, which is what the next scan
// lists. Anything else under this path — an earlier *Add interpreter…*, whose stored text
// Rust has just rewritten, or a row broken because its venv was deleted and made again —
// gives way to the row Rust returned, or the selection names a row the next scan renames.
const keep = listed !== undefined && listed.error === undefined && listed.source !== 'manual'
const interpreter = keep ? listed.interpreter : row.interpreter
let rows: EnvRow[]
if (listed === undefined) rows = [...state.rows, row]
else if (keep) rows = state.rows
else rows = state.rows.map((r) => (r === listed ? row : r))
return {
rows: listed === undefined ? [...state.rows, row] : state.rows,
rows,
addingManual: false,
manualNotice: { kind: 'added', path: interpreter },
...(state.selected === interpreter ? {} : { selected: interpreter, ...NO_PACKAGES }),
...(keep && state.selected === interpreter ? {} : { selected: interpreter, ...NO_PACKAGES }),
}
})
} catch (e) {
@@ -449,15 +469,16 @@ export const useEnvStore = create<EnvState>((set, get) => ({
}
},
removeManual: async (envHash) => {
if (get().removingManual !== null) return
set({ removingManual: envHash, error: null })
removeManual: async (interpreter) => {
const { removingManual, scanning } = get()
if (removingManual !== null || scanning) return
set({ removingManual: interpreter, error: null })
try {
await envRemoveManual(envHash)
await envRemoveManual(interpreter)
set((state) => {
const gone = state.rows.find((r) => r.envHash === envHash)
const gone = state.rows.find((r) => r.interpreter === interpreter)
if (gone === undefined) return { removingManual: null }
const rows = state.rows.filter((r) => r.envHash !== envHash)
const rows = state.rows.filter((r) => r !== gone)
const deselect = state.selected === gone.interpreter
return {
rows,