diff --git a/CLAUDE.md b/CLAUDE.md index e214a42..4b4a00f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -27,6 +27,18 @@ The design is fully specified. Read in this order; do not invent behaviour that Two more that follow from them: every user-visible failure carries exactly one catalog code, and a failed package never aborts a batch (skip-and-continue, then a `"13 successful, 2 failed"` summary). +## What the spikes proved (read `spikes/README.md` before writing an adapter) + +6. **Every plan must restate the full installed set as explicit requirements.** `install -U ` + ignores installed packages' constraints in **both** engines and will break them at exit 0. +7. **Every pip invocation needs `PYTHONIOENCODING=utf-8` + `PYTHONUTF8=1`.** Without it + `--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. +10. **PipDock enforces `Requires-Python` itself** (`src/compat.rs`) — the engines disagree, and the + preview must not depend on which one is selected. + ## Conventions - Crates `pipdock-*`; React components prefixed `Pd` (`PdPackageRow`, `PdConflictDialog`) diff --git a/crates/pipdock-core/src/compat.rs b/crates/pipdock-core/src/compat.rs new file mode 100644 index 0000000..469d037 --- /dev/null +++ b/crates/pipdock-core/src/compat.rs @@ -0,0 +1,294 @@ +//! Requires-Python enforcement. +//! +//! **Owner decision 2026-07-27 (spike SP-2).** The engines disagree: given `scipy==1.7.3`, which +//! declares `Requires-Python >=3.7,<3.11`, pip refuses it on Python 3.12 while uv plans to install +//! it. PipDock therefore enforces Requires-Python **itself**, so the preview is the same whichever +//! engine is selected. A candidate this module rejects never reaches an engine command, and is +//! reported as `PD-PKG-001` with the required range shown against the environment's version. +//! +//! This is a deliberately narrow slice of PEP 440: enough to evaluate a `Requires-Python` +//! specifier set against a concrete interpreter version, and nothing more. Resolution itself is +//! still the engine's job (ARCHITECTURE §1.2) — this only filters candidates the engine should +//! never have been offered. + +use crate::errors::{Code, PdError, Result}; + +/// A release version as an ordered list of numeric segments, e.g. `3.12.4` → `[3, 12, 4]`. +/// +/// Only the release segment matters here. Pre-release, post-release and local segments are +/// ignored: no interpreter PipDock manages is identified by them, and `Requires-Python` specifiers +/// in the wild do not use them meaningfully. +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] +pub struct PyVersion(Vec); + +impl PyVersion { + /// Parse a dotted numeric version. + /// + /// # Errors + /// Returns `PD-ENV-003` when the string is not a dotted sequence of numbers — that can only + /// come from a broken `probe.py` reading, which is exactly what that code means. + pub fn parse(raw: &str) -> Result { + // Trim any pre/post/local suffix: "3.14.0rc1" -> "3.14.0". + let release: &str = raw + .split(['a', 'b', 'r', 'c', 'd', 'p', '+', '-']) + .next() + .unwrap_or(""); + let trimmed = release.trim_end_matches('.'); + if trimmed.is_empty() { + return Err(PdError::new( + Code::EnvProbeFailed, + format!("bad version: {raw:?}"), + )); + } + let mut parts = Vec::new(); + for segment in trimmed.split('.') { + let n: u32 = segment + .parse() + .map_err(|_| PdError::new(Code::EnvProbeFailed, format!("bad version: {raw:?}")))?; + parts.push(n); + } + Ok(Self(parts)) + } + + /// Compare against `other`, treating missing trailing segments as zero so `3.12` == `3.12.0`. + fn cmp_padded(&self, other: &Self) -> std::cmp::Ordering { + let len = self.0.len().max(other.0.len()); + for i in 0..len { + let a = self.0.get(i).copied().unwrap_or(0); + let b = other.0.get(i).copied().unwrap_or(0); + match a.cmp(&b) { + std::cmp::Ordering::Equal => {} + other_ord => return other_ord, + } + } + std::cmp::Ordering::Equal + } + + /// True when `self` starts with every segment of `prefix` — the `==3.9.*` / `!=3.9.*` rule. + fn has_prefix(&self, prefix: &Self) -> bool { + prefix.0.len() <= self.0.len() && self.0[..prefix.0.len()] == prefix.0[..] + } +} + +impl std::fmt::Display for PyVersion { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + let parts: Vec = self.0.iter().map(u32::to_string).collect(); + f.write_str(&parts.join(".")) + } +} + +/// Why a candidate was rejected, or that it was accepted. +#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)] +#[serde(tag = "kind", rename_all = "kebab-case")] +pub enum Compatibility { + /// The candidate may be offered to the engine. + Compatible, + /// The candidate declares a `Requires-Python` this interpreter does not satisfy. + /// + /// Both fields are shown to the user, per `docs/ERROR-CATALOG.md` PD-PKG-001's "shows required + /// range vs env version". + RequiresPython { + /// The specifier exactly as the package declared it. + required: String, + /// The interpreter's version. + found: String, + }, + /// The specifier could not be parsed. + /// + /// Treated as compatible by [`check`] — an unreadable specifier is PipDock's problem, not the + /// user's, and refusing an installable package would be the worse failure. + Unparseable { + /// The specifier that could not be read. + specifier: String, + }, +} + +impl Compatibility { + /// True when the candidate may proceed. + #[must_use] + pub fn is_ok(&self) -> bool { + !matches!(self, Self::RequiresPython { .. }) + } +} + +/// Evaluate a `Requires-Python` specifier set against an interpreter version. +/// +/// `requires_python` is the raw metadata value, e.g. `">=3.7,<3.11"`. `None` or empty means the +/// package declares no constraint, which is always compatible. +/// +/// Unknown or malformed specifiers yield [`Compatibility::Unparseable`], which +/// [`Compatibility::is_ok`] treats as passing: blocking an install because PipDock could not read +/// a specifier would turn a metadata oddity into a broken feature. +#[must_use] +pub fn check(requires_python: Option<&str>, env_version: &PyVersion) -> Compatibility { + let Some(spec) = requires_python.map(str::trim).filter(|s| !s.is_empty()) else { + return Compatibility::Compatible; + }; + + for clause in spec.split(',') { + let clause = clause.trim(); + if clause.is_empty() { + continue; + } + match satisfies_clause(clause, env_version) { + Some(true) => {} + Some(false) => { + return Compatibility::RequiresPython { + required: spec.to_owned(), + found: env_version.to_string(), + }; + } + None => { + return Compatibility::Unparseable { + specifier: spec.to_owned(), + }; + } + } + } + Compatibility::Compatible +} + +/// `Some(true|false)` when the clause was understood, `None` when it was not. +fn satisfies_clause(clause: &str, env: &PyVersion) -> Option { + use std::cmp::Ordering::{Equal, Greater, Less}; + + // Longest operators first: `>=` must not be read as `>`. + let (op, rest) = ["===", "==", "!=", ">=", "<=", "~=", ">", "<"] + .iter() + .find_map(|op| clause.strip_prefix(*op).map(|rest| (*op, rest.trim())))?; + + // Wildcards are only meaningful for == and !=. + let is_wildcard = rest.ends_with(".*"); + let bare = if is_wildcard { + rest.trim_end_matches(".*") + } else { + rest + }; + let target = PyVersion::parse(bare).ok()?; + + Some(match op { + "==" | "===" if is_wildcard => env.has_prefix(&target), + "!=" if is_wildcard => !env.has_prefix(&target), + "==" | "===" => env.cmp_padded(&target) == Equal, + "!=" => env.cmp_padded(&target) != Equal, + ">=" => matches!(env.cmp_padded(&target), Greater | Equal), + "<=" => matches!(env.cmp_padded(&target), Less | Equal), + ">" => env.cmp_padded(&target) == Greater, + "<" => env.cmp_padded(&target) == Less, + "~=" => { + // PEP 440 compatible release: >= target, and equal on all but the last segment. + if target.0.len() < 2 { + return None; // `~=3` is invalid per PEP 440. + } + let prefix = PyVersion(target.0[..target.0.len() - 1].to_vec()); + matches!(env.cmp_padded(&target), Greater | Equal) && env.has_prefix(&prefix) + } + _ => return None, + }) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn v(s: &str) -> PyVersion { + PyVersion::parse(s).unwrap_or_else(|e| panic!("{s}: {e}")) + } + + #[test] + fn the_scipy_case_from_sp2() { + // The exact divergence that prompted this module: scipy 1.7.3 declares >=3.7,<3.11. + // pip refuses it on Python 3.12; uv planned to install it. PipDock refuses, both engines. + let got = check(Some(">=3.7,<3.11"), &v("3.12.10")); + assert_eq!( + got, + Compatibility::RequiresPython { + required: ">=3.7,<3.11".into(), + found: "3.12.10".into() + } + ); + assert!(!got.is_ok()); + + // ...and accepts it on an interpreter that does satisfy the range. + assert_eq!( + check(Some(">=3.7,<3.11"), &v("3.10.13")), + Compatibility::Compatible + ); + } + + #[test] + fn no_constraint_is_always_compatible() { + for spec in [None, Some(""), Some(" ")] { + assert_eq!( + check(spec, &v("3.12")), + Compatibility::Compatible, + "{spec:?}" + ); + } + } + + #[test] + fn boundary_comparisons_pad_missing_segments() { + // ">=3.8" must accept exactly 3.8.0 — an off-by-one here would reject a supported Python. + assert!(check(Some(">=3.8"), &v("3.8.0")).is_ok()); + assert!(check(Some(">=3.8"), &v("3.8")).is_ok()); + assert!(!check(Some(">=3.8"), &v("3.7.17")).is_ok()); + + // "<3.11" must reject exactly 3.11.0 and accept 3.10.x. + assert!(!check(Some("<3.11"), &v("3.11.0")).is_ok()); + assert!(check(Some("<3.11"), &v("3.10.99")).is_ok()); + } + + #[test] + fn wildcard_clauses() { + assert!(!check(Some("!=3.9.*"), &v("3.9.7")).is_ok()); + assert!(check(Some("!=3.9.*"), &v("3.10.0")).is_ok()); + assert!(check(Some("==3.12.*"), &v("3.12.4")).is_ok()); + assert!(!check(Some("==3.12.*"), &v("3.13.0")).is_ok()); + } + + #[test] + fn compatible_release_operator() { + // ~=3.7 means >=3.7, ==3.* + assert!(check(Some("~=3.7"), &v("3.12")).is_ok()); + assert!(!check(Some("~=3.7"), &v("4.0")).is_ok()); + assert!(!check(Some("~=3.7"), &v("3.6")).is_ok()); + // ~=3.7.2 means >=3.7.2, ==3.7.* + assert!(check(Some("~=3.7.2"), &v("3.7.9")).is_ok()); + assert!(!check(Some("~=3.7.2"), &v("3.8.0")).is_ok()); + assert!(!check(Some("~=3.7.2"), &v("3.7.1")).is_ok()); + } + + #[test] + fn multiple_clauses_must_all_hold() { + let spec = Some(">=3.8,!=3.9.*,<4"); + assert!(check(spec, &v("3.8.1")).is_ok()); + assert!(!check(spec, &v("3.9.18")).is_ok()); + assert!(check(spec, &v("3.12.0")).is_ok()); + assert!(!check(spec, &v("4.0.0")).is_ok()); + } + + #[test] + fn unreadable_specifiers_do_not_block_the_user() { + // PipDock failing to read metadata must never be the reason an installable package is + // refused — that would turn a metadata oddity into a broken feature. + let got = check(Some(">=3.8 or maybe 3.9"), &v("3.12")); + assert!(matches!(got, Compatibility::Unparseable { .. })); + assert!(got.is_ok()); + } + + #[test] + fn prerelease_interpreter_versions_parse_to_their_release() { + assert_eq!(v("3.14.0rc1"), v("3.14.0")); + assert_eq!(v("3.15.0b4"), v("3.15.0")); + assert!(check(Some(">=3.14"), &v("3.14.0rc1")).is_ok()); + } + + #[test] + fn malformed_versions_are_rejected_with_the_probe_code() { + for bad in ["", "abc", "3..4", "3.x", "."] { + let err = PyVersion::parse(bad).expect_err(&format!("{bad:?} must be rejected")); + assert_eq!(err.code, Code::EnvProbeFailed, "{bad:?}"); + } + } +} diff --git a/crates/pipdock-core/src/engine/uv.rs b/crates/pipdock-core/src/engine/uv.rs index d55dfdd..c0b5811 100644 --- a/crates/pipdock-core/src/engine/uv.rs +++ b/crates/pipdock-core/src/engine/uv.rs @@ -156,6 +156,7 @@ mod tests { prefix: r"C:\proj\.venv".into(), python_version: "3.12.4".into(), externally_managed: false, + hidden_user_site: None, source: crate::model::EnvSource::VenvScan, }; let err = UvEngine diff --git a/crates/pipdock-core/src/lib.rs b/crates/pipdock-core/src/lib.rs index da9bddd..e069bed 100644 --- a/crates/pipdock-core/src/lib.rs +++ b/crates/pipdock-core/src/lib.rs @@ -23,6 +23,7 @@ #![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))] +pub mod compat; pub mod engine; pub mod envs; pub mod errors; @@ -34,6 +35,7 @@ pub mod pins; pub mod plan; pub mod snapshot; +pub use compat::{Compatibility, PyVersion}; pub use errors::{Code, PdError, Result}; pub use model::{Dist, EngineId, OutdatedDist, PkgName, PyEnv, Version}; diff --git a/crates/pipdock-core/src/model.rs b/crates/pipdock-core/src/model.rs index bf390af..28cc245 100644 --- a/crates/pipdock-core/src/model.rs +++ b/crates/pipdock-core/src/model.rs @@ -67,10 +67,26 @@ pub struct PyEnv { /// PEP 668 marker present. When true, mutation is blocked unless the user enabled the /// Settings override (`PD-ENV-002`, SECURITY §3). pub externally_managed: bool, + /// User site-packages directory that `probe.py -I` is hiding, when there is one. + /// + /// Owner decision 2026-07-27 (SP-6): the probe keeps running isolated, so on a non-venv + /// system Python it reports fewer distributions than `pip list` does. `Some` means packages + /// really are hidden and the Installed screen shows a note naming this path; `None` — always + /// the case inside a venv — means the listing is complete. + #[serde(default)] + pub hidden_user_site: Option, /// Where this env came from. pub source: EnvSource, } +impl PyEnv { + /// True when the installed listing is known to be incomplete, so the UI must say so. + #[must_use] + pub fn listing_is_partial(&self) -> bool { + self.hidden_user_site.is_some() + } +} + /// A PEP 503-normalized distribution name. /// /// Constructing one is the *only* way a package name reaches an argv array, which is what makes diff --git a/crates/pipdock-core/src/probe.py b/crates/pipdock-core/src/probe.py index eb67922..9ae9fd9 100644 --- a/crates/pipdock-core/src/probe.py +++ b/crates/pipdock-core/src/probe.py @@ -70,6 +70,38 @@ def _externally_managed() -> bool: return any(os.path.isfile(p) for p in candidates) +def _hidden_user_site() -> str | None: + """Return the user site-packages path when it exists but is NOT on this run's sys.path. + + Owner decision 2026-07-27 (spike SP-6): PipDock keeps running the probe with -I, because + isolated mode is what stops a poisoned environment injecting code into it (SECURITY section 2). + The cost is that -I also disables user site-packages, so on a non-venv system Python the probe + reports fewer distributions than `pip list` does -- measured at 352 vs 375 on the dev machine. + + Rather than warn always, report the path only when packages really are being hidden, so the UI + can show an accurate note instead of a permanent disclaimer. Returns None inside a venv (no + user site applies) and None when the directory is absent or empty. + """ + if sys.prefix != sys.base_prefix: + return None # venv: user site does not apply + try: + import site + + user_site = site.getusersitepackages() + except Exception: # noqa: BLE001 - absence of a user site is not an error + return None + if not user_site or not os.path.isdir(user_site): + return None + if user_site in sys.path: + return None # not hidden: it is already being read + try: + if not os.listdir(user_site): + return None # exists but empty: nothing is being hidden + except OSError: + return None + return user_site + + def _dists() -> list[dict[str, object]]: """Read installed distribution metadata. @@ -126,6 +158,8 @@ def main(argv: list[str] | None = None) -> int: "executable": sys.executable, "is_venv": sys.prefix != sys.base_prefix, "externally_managed": _externally_managed(), + # Non-null means -I is hiding packages that pip would list; the UI shows a note. + "hidden_user_site": _hidden_user_site(), "dists": _dists(), } except Exception as exc: # noqa: BLE001 - the core turns this into PD-ENV-003 diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 82d9c60..1ab1b09 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -60,6 +60,12 @@ Key model types: - `ResolutionReport` — normalized output of the dry-run: `{ changes: Vec, held_back: Vec }>, impossible: Option, raw: String }`. **Both adapters must emit this same shape** — this is the whole point of the trait. The pip adapter fills it from `--dry-run --report` JSON; the uv adapter from its dry-run plan output (format pinned during spike SP-1; fixtures under `crates/pipdock-core/tests/fixtures/`). - `Blocker` computation: the engine's report says *what* was held back; *who* is responsible comes from cross-referencing the reverse-dependency graph (§4) with each blocker's `Requires-Dist` constraints. If attribution is ambiguous, show constraints without a culprit rather than guessing. +### Requires-Python is enforced by PipDock, not the engine + +**Owner decision 2026-07-27 (spike SP-2).** The two engines disagree: `scipy==1.7.3` declares `Requires-Python >=3.7,<3.11`, and on Python 3.12 pip refuses it while uv plans to install it. Since G5 promises one behavior across heads, the preview must not change shape because the user flipped the engine radio — so `pipdock-core` evaluates `Requires-Python` itself in `src/compat.rs`, before any candidate reaches an engine command, and reports rejects as `PD-PKG-001` with the required range against the environment's version. + +This does not violate "explain, don't reimplement" (§1.2): resolution is still entirely the engine's. `compat.rs` only filters candidates the engine should never have been offered, using a narrow slice of PEP 440 — the comparison, wildcard and compatible-release operators as they appear in `Requires-Python`. Specifiers it cannot parse are treated as **compatible**, because PipDock failing to read metadata must never be the reason an installable package is refused. + ### Engine selection `Settings.engine ∈ {pip, uv}`. First run: probe `uv --version` on PATH → preselect uv if present, else pip; user can change any time. The status bar always shows the active engine. Per-env override is P2. @@ -70,11 +76,14 @@ Rust cannot cheaply read a foreign env's installed metadata. PipDock embeds a si ```json { "python": "3.12.4", "prefix": "...", "externally_managed": false, + "is_venv": true, "hidden_user_site": null, "dists": [ { "name": "requests", "version": "2.32.3", "requires_dist": ["urllib3<3,>=1.21.1", "..."], "requires_python": ">=3.8" } ] } ``` +`hidden_user_site` is non-null only when `-I` is actually hiding packages from the listing — see SECURITY §2 for the decision and the UI note it drives. + From `requires_dist` the core builds the **reverse-dependency graph** used by: held-back attribution, uninstall guard, and pin auto-suggest. The helper is written to a temp file per invocation and never installed into the env. Compatibility floor: Python 3.10 (uses `importlib.metadata` only). ## 5. Index & metadata diff --git a/docs/DATA-FLOW.md b/docs/DATA-FLOW.md index 948a7a9..491ecbe 100644 --- a/docs/DATA-FLOW.md +++ b/docs/DATA-FLOW.md @@ -15,11 +15,18 @@ ## 2. Shared preamble (all mutating flows) ```text -[Select env] → probe.py → env facts (python ver, PEP 668, dist metadata) +[Select env] → probe.py -I → env facts (python ver, PEP 668, hidden_user_site, dist metadata) │ ├─ EXTERNALLY-MANAGED detected → BLOCKED banner (PD-ENV-002) │ └─ explicit override in Settings → proceed with persistent warning chip + ├─ hidden_user_site non-null → Installed screen shows the partial-listing note + │ (not a block; see SECURITY §2) └─ ok → flow continues; reverse-dep graph built from probe data + +Every candidate is then screened against the environment's Python version by +pipdock-core (ARCHITECTURE §3): incompatible ones are dropped from the plan with +PD-PKG-001 before any engine command runs, so the preview is identical under pip +and uv even though the engines themselves disagree. ``` ## 3. Update flow (state machine) diff --git a/docs/ERROR-CATALOG.md b/docs/ERROR-CATALOG.md index f347738..bed7caf 100644 --- a/docs/ERROR-CATALOG.md +++ b/docs/ERROR-CATALOG.md @@ -21,7 +21,7 @@ | PD-BLD-001 | `Microsoft Visual C++ 14.0 or greater is required` | missing MSVC build tools | Install VS Build Tools, or prefer a wheel-providing version | | PD-BLD-002 | `error in pyproject.toml` / `Backend … failed` / `metadata-generation-failed` | broken sdist build backend | Try previous version; report upstream (owner's example case) | | PD-BLD-003 | `error: Microsoft Visual C++`-absent + `Failed building wheel` generic | sdist-only build failed | Same as above; details in log | -| PD-PKG-001 | `No matching distribution found` + requires-python mismatch in metadata | package needs different Python | Shows required range vs env version | +| PD-PKG-001 | **Raised by PipDock before the engine runs** — `crates/pipdock-core/src/compat.rs` evaluates the candidate's `Requires-Python` against the env's version. (Engine stderr is not a reliable signal: pip reports it as plain `No matching distribution found`, indistinguishable from PD-PKG-002, and uv does not enforce it at all.) | package needs different Python | Shows required range vs env version | | PD-PKG-002 | `No matching distribution found` (plain) | name/version typo or yanked | Check spelling/version; `pipdock info ` | | PD-PKG-003 | `File was already yanked` / yanked marker | yanked release requested | Pick a non-yanked version | | PD-PKG-004 | hash mismatch / `THESE PACKAGES DO NOT MATCH THE HASHES` | corrupted download | Purge engine cache (P1 UI; CLI: engine cache purge) and retry | diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 4757e55..4913aa3 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -17,7 +17,7 @@ The entire architecture stands on assumptions that must be verified on a real ma | SP-5 | Answered by SP-1 | **No engine reports held-back items at all.** Resolved version, latest version and blocker must all be derived by PipDock — for pip as much as for uv, contrary to ARCHITECTURE §3's implication. | | SP-6 | Answered | `uv python list` returns downloadable entries and duplicate shims; `env_hash` **must lowercase** the interpreter path on Windows or pins and snapshots split in two. `probe.py -I` hides 24 user-site packages on a system Python — open decision. Microsoft Store Python still unverified. | -Four open questions for the owner are listed at the end of `spikes/README.md`; M1 should not start until at least the Requires-Python and `-I` decisions are made, since both change adapter behaviour. +**Both adapter-behaviour questions were decided 2026-07-27** and are implemented: PipDock enforces `Requires-Python` itself so the preview is engine-independent (`crates/pipdock-core/src/compat.rs`, ARCHITECTURE §3), and `probe.py` keeps `-I` while reporting `hidden_user_site` so the Installed screen can disclose the gap accurately (SECURITY §2). Two non-blocking questions remain at the end of `spikes/README.md`: search ranking scope, and how to obtain the five error fixtures this machine cannot produce. | # | Spike | Question to answer | Exit criterion | |---|---|---|---| diff --git a/docs/SECURITY.md b/docs/SECURITY.md index 4c12a4d..3658f1e 100644 --- a/docs/SECURITY.md +++ b/docs/SECURITY.md @@ -12,6 +12,7 @@ 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. - Interpreter paths come only from discovery (registry/launcher/uv) or an explicit user file-pick; they are canonicalized and existence-checked (PD-ENV-001) before use. - `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. + - **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). ## 3. PEP 668 policy (protecting the system Python) diff --git a/docs/UI-SPEC.md b/docs/UI-SPEC.md index cf5b4bf..a7b7f4b 100644 --- a/docs/UI-SPEC.md +++ b/docs/UI-SPEC.md @@ -51,7 +51,7 @@ Sidebar is icon+label, collapsible to icons. Status line (mono) always shows env **Environments.** Auto-discovered list (source chip: registry / py launcher / uv / manual) with python version and package count; PEP 668 envs carry a red `MANAGED` chip and a disabled state explaining PD-ENV-002. Actions: *Browse…*, *Rescan*, star-as-default. -**Installed.** Virtualized table: name (mono) · version · latest · size · chips. Up-to-date rows use `--color-text-dim` (owner's "dimmed" requirement); outdated rows show an `UPDATE` badge; pinned rows a 🔒 `--color-info` chip. Row actions: pin/unpin, uninstall, details. Multi-select via checkboxes; bulk action bar appears on selection. +**Installed.** Virtualized table: name (mono) · version · latest · size · chips. When the env's `hidden_user_site` is non-null (non-venv system Pythons only — see SECURITY §2), an inline `--color-info` note above the table says user-account packages are not listed and names the path; it is informational, never a block, and never appears for a venv. Up-to-date rows use `--color-text-dim` (owner's "dimmed" requirement); outdated rows show an `UPDATE` badge; pinned rows a 🔒 `--color-info` chip. Row actions: pin/unpin, uninstall, details. Multi-select via checkboxes; bulk action bar appears on selection. **Updates.** Same table filtered to outdated, badge count in sidebar. Header: *Select all* (excludes pinned; shows "3 pinned excluded"), *Update selected*. After resolve → **Preview panel** replaces the table: three grouped sections — *Will upgrade* (A `1.2 → 2.0`), *New dependencies*, *Needs decision* (held-back in `--color-warn` with one-line blocker sentence; impossible in `--color-danger`). Each needs-decision row hosts a segmented control: **Keep compatible · Skip · Force latest** (Force opens an inline confirm naming what breaks). Footer: `Confirm (n changes)` / `Back`. diff --git a/spikes/README.md b/spikes/README.md index 82327c3..de00510 100644 --- a/spikes/README.md +++ b/spikes/README.md @@ -249,11 +249,15 @@ bites non-venv system Pythons — and `C:\Python314` reports `externally_managed blocks PipDock from managing it. The remaining 376 vs 375 gap is likely a shadowed distribution that `importlib.metadata` reports twice and pip de-duplicates by normalized name. -**Open decision** — it trades a documented security control against list accuracy: +**DECIDED 2026-07-27 (owner): keep `-I`, and disclose the gap.** Dropping to `-E` was rejected — +a package in user site is part of the untrusted surface the isolation exists to exclude. Probing +twice was rejected as a second interpreter start per scan for a non-primary case. -- keep `-I` and show a "user-site packages not shown" note on non-venv environments; or -- drop to `-E` (ignore `PYTHONPATH` only, keep user site); or -- probe twice and reconcile, at the cost of a second interpreter start per scan. +Implemented: `probe.py` now reports `hidden_user_site`, the user-site path when it exists, is off +`sys.path` and is non-empty, and `null` otherwise. Verified: the system Python reports the path +(352 dists), a venv reports `null`. `PyEnv::listing_is_partial()` exposes it, and the Installed +screen shows a note naming the path only when it is non-null, so the disclosure is accurate rather +than a permanent disclaimer. See SECURITY §2 and UI-SPEC §4. ### Python 3.14 metadata deprecation (fixed) @@ -268,13 +272,23 @@ detected-and-explained before v1.0. --- -## Open questions for the owner +## Decisions -1. **Requires-Python divergence (SP-2).** pip refuses `scipy==1.7.3` on Python 3.12; uv plans it. - Should PipDock enforce Requires-Python itself so the preview is engine-independent, or show - each engine's own verdict? -2. **`probe.py -I` (SP-6).** Which of the three options above? -3. **Search ranking (SP-3).** Confirm that an exact/prefix boost over nucleo's score is in scope - for M1 rather than deferred — the Search screen is unusable without it. -4. **`PD-BLD-001` fixture (SP-2).** Capture on a clean VM, or ship a labelled synthetic fixture? - `docs/TESTING.md` §2 requires a fixture per code before ship. +**1. Requires-Python — DECIDED 2026-07-27: PipDock enforces it itself.** (SP-2: pip refuses +`scipy==1.7.3` on Python 3.12; uv plans it.) The preview must not change shape because the user +flipped the engine radio, so `crates/pipdock-core/src/compat.rs` screens every candidate against +the environment's version before any engine command runs, and rejects surface as `PD-PKG-001` with +the required range against the found version. Unparseable specifiers count as **compatible** — +PipDock failing to read metadata must never be why an installable package is refused. See +ARCHITECTURE §3, ERROR-CATALOG PD-PKG-001, DATA-FLOW §2. + +**2. `probe.py -I` — DECIDED 2026-07-27: keep `-I`, disclose the gap.** See SP-6 above. + +## Still open + +1. **Search ranking (SP-3).** Confirm that an exact/prefix boost over nucleo's score is in scope + for M1 rather than deferred — the Search screen is unusable without it (`requests-ntlm` ranks + above `requests`). +2. **`PD-BLD-001` fixture (SP-2).** Capture on a clean VM, or ship a labelled synthetic fixture? + `docs/TESTING.md` §2 requires a fixture per code before ship. Same question for `PD-NET-002`, + `PD-PRM-002`, `PD-SYS-001` and `PD-SYS-002`, none of which this machine can produce. diff --git a/ui/src/locales/en/common.json b/ui/src/locales/en/common.json index b0b6476..5fefbb2 100644 --- a/ui/src/locales/en/common.json +++ b/ui/src/locales/en/common.json @@ -32,6 +32,11 @@ "copyLog": "Copy full log", "reportBug": "Report bug" }, + "env": { + "partialListing": "Packages installed for your user account are not shown here.", + "partialListingDetail": "PipDock reads this environment in isolated mode, which skips {{path}}. Virtual environments are unaffected.", + "requiresPython": "Needs Python {{required}} — this environment is {{found}}." + }, "phase0": { "heading": "Phase 0 — scaffold", "body": "The shell, design tokens and locale catalogs are in place. Screens land in M2, after the Phase 0 spikes answer how each engine reports its dry-run plan.", diff --git a/ui/src/locales/vi/common.json b/ui/src/locales/vi/common.json index ef6659e..8e7d8ba 100644 --- a/ui/src/locales/vi/common.json +++ b/ui/src/locales/vi/common.json @@ -32,6 +32,11 @@ "copyLog": "Sao chép toàn bộ nhật ký", "reportBug": "Báo lỗi" }, + "env": { + "partialListing": "Các gói cài riêng cho tài khoản của bạn không hiển thị ở đây.", + "partialListingDetail": "PipDock đọc môi trường này ở chế độ cách ly nên bỏ qua {{path}}. Môi trường ảo không bị ảnh hưởng.", + "requiresPython": "Cần Python {{required}} — môi trường này là {{found}}." + }, "phase0": { "heading": "Giai đoạn 0 — dựng khung", "body": "Khung ứng dụng, design token và các catalog ngôn ngữ đã sẵn sàng. Các màn hình sẽ có ở M2, sau khi các spike của Giai đoạn 0 trả lời được cách từng engine báo cáo kế hoạch dry-run.",