docs: Add interpreter… in the specs, ACCESSIBILITY.md and the privacy policy

PRD P0-1, UI-SPEC §4, CLI-SPEC (env add/remove, their JSON, --env's new
refusal), CLI-GUIDE, ERROR-CATALOG (PD-ENV-001's new cases, and the
first button its advice ever had) and TESTING's golden count. SECURITY
§2 claimed for two milestones that interpreter paths were canonicalized
before use while the only check was existence; it now describes the
validator that makes it true. PRD also records P0-9's first-run uv
detection, P1-7 and P2 as not planned in maintenance mode.

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

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5.5 committed 2026-11-21 23:22:12 +07:00
1 parent 9f9efbba79
commit cfa5b4e1be
10 files changed
+52 -24

No files matched your search

+3 -3
View File
@@ -18,9 +18,9 @@ dist-ssr/
# Environments (test venvs created by the integration suite / spikes) # Environments (test venvs created by the integration suite / spikes)
.venv/ .venv/
venv/ venv/
# Scratch venvs for verifying by hand. Note that the GUI will only ever *see* one named exactly # Scratch venvs for verifying by hand. Discovery only *finds* one named exactly `.venv`, `venv`,
# `.venv`, `venv`, `env` or `.env` in the working directory — `envs::venv_scan` matches that fixed # `env` or `.env` in the working directory (`envs::venv_scan`'s fixed list); a suffixed one here has
# list and `env_add_manual` (Browse…) is still owed — so a suffixed one here is CLI-only. # to be added — Add interpreter… in the GUI, `pipdock env add` in the CLI.
/.venv-*/ /.venv-*/
__pycache__/ __pycache__/
*.py[cod] *.py[cod]
+10 -4
View File
@@ -46,7 +46,8 @@ never removed.
| `Esc` | Close a dialog, the palette or the console drawer; inside a package row, return to the row | | `Esc` | Close a dialog, the palette or the console drawer; inside a package row, return to the row |
When the screen changes — a new tab, a plan's preview, its summary, the dependency view — focus When the screen changes — a new tab, a plan's preview, its summary, the dependency view — focus
moves to the new screen's heading. When a dialog, the palette or the console drawer closes, focus moves to the new screen's heading. So it does when *Remove from list* takes away the row whose
button you pressed (1.6.0). When a dialog, the palette or the console drawer closes, focus
returns to what opened it. A button that is busy after you press it stays where focus is. Every returns to what opened it. A button that is busy after you press it stays where focus is. Every
confirmation that removes, forces or rewrites something opens with focus on **Cancel**. confirmation that removes, forces or rewrites something opens with focus on **Cancel**.
@@ -60,6 +61,10 @@ The full map and the reasoning behind it are in [`docs/UI-SPEC.md`](docs/UI-SPEC
- Dialogs are named by their heading and described by their body. - Dialogs are named by their heading and described by their body.
- A run announces its progress ("3 of 15 complete") once, not once per output line. Search - A run announces its progress ("3 of 15 complete") once, not once per output line. Search
announces that it is searching, how many results came back, and when nothing matched. announces that it is searching, how many results came back, and when nothing matched.
- On Environments, adding or removing an interpreter is said in a status line ("Added … to the
list."). *Remove from list* is named with the path it removes, beginning with the words on the
button. The file picker *Add interpreter…* opens is Windows' own dialog, with Windows' own
accessibility.
- Error messages are announced when they appear, and carry a code (`PD-XXX-000`) you can quote. - Error messages are announced when they appear, and carry a code (`PD-XXX-000`) you can quote.
- The interface is in English and Vietnamese, and the document language follows the one in use. - The interface is in English and Vietnamese, and the document language follows the one in use.
@@ -103,9 +108,10 @@ Honesty about this matters more than a long list.
**Not tested, and said so rather than implied:** **Not tested, and said so rather than implied:**
- **Narrator has not been run again on 1.5.0.** That release changed what a screen reader hears in - **Narrator has not been run again on 1.5.0 or 1.6.0.** 1.5.0 changed what a screen reader hears
several places (see the [changelog](changelog/1.x.md)). Those changes were checked against the in several places (see the [changelog](changelog/1.x.md)), and 1.6.0 added *Add interpreter…* and
accessibility tree, which says what is exposed — not against speech, which is what you hear. *Remove from list*. Those were checked against the accessibility tree, which says what is
exposed — not against speech, which is what you hear.
- **NVDA and JAWS** have not been used with PipDock at all. Reports from people who use them are - **NVDA and JAWS** have not been used with PipDock at all. Reports from people who use them are
especially welcome. especially welcome.
- **Each Windows contrast theme by hand.** Forced colours were emulated; the four built-in themes - **Each Windows contrast theme by hand.** Forced colours were emulated; the four built-in themes
+13 -1
View File
@@ -86,7 +86,19 @@ the per-user site-packages directory — so its package count can be lower than
is non-null exactly when that applies, and null inside a venv. See SECURITY §2. is non-null exactly when that applies, and null inside a venv. See SECURITY §2.
**`venv_scan` matches exactly four directory names**: `.venv`, `venv`, `env`, `.env`. A virtual **`venv_scan` matches exactly four directory names**: `.venv`, `venv`, `env`, `.env`. A virtual
environment called anything else is invisible to `env list`, and you have to name it with `--env`. environment called anything else is not discovered — name it with `--env` for one command, or put
it on the list for good (the GUI's *Add interpreter…* writes the same list):
```powershell
pipdock env add D:\work\scraper\myenv
```
It appears in `env list` after discovery's own rows, with `source: "manual"`, and in the GUI's
Environments screen. `pipdock env remove D:\work\scraper\myenv` takes it off again; nothing on disk
is touched, and its pins and snapshots stay for the day it comes back. Since 1.6.0 a path you give
`--env`, `env use` or `env add` must be named like a Python interpreter (`python.exe`,
`python3.exe`, `python3.12.exe`) and must not be one of PipDock's own venvs, or it is refused
with PD-ENV-001 before anything runs it.
Make one the default so you can stop typing `--env`: Make one the default so you can stop typing `--env`:
+7 -3
View File
@@ -27,7 +27,7 @@
**Which environment.** In order: **Which environment.** In order:
1. `--env` — an interpreter, or an environment directory whose `Scripts\python.exe` is used; 1. `--env` — an interpreter, or an environment directory whose `Scripts\python.exe` is used; refused with PD-ENV-001 unless it is named like a Python interpreter and outside PipDock's own venvs (SECURITY §2);
2. the default `pipdock env use` stored. If its interpreter is gone, stderr says `` warning: the default environment (<path>) no longer exists; `pipdock env use` sets another `` and the search goes on; 2. the default `pipdock env use` stored. If its interpreter is gone, stderr says `` warning: the default environment (<path>) no longer exists; `pipdock env use` sets another `` and the search goes on;
3. the first of `.venv`, `venv`, `env`, `.env` in the working directory that holds an interpreter. 3. the first of `.venv`, `venv`, `env`, `.env` in the working directory that holds an interpreter.
@@ -38,8 +38,10 @@ Nothing found is PD-ENV-001 (exit 3), naming all three ways. Only `env use` writ
## 3. Commands ## 3. Commands
```text ```text
pipdock env list # discovered envs, sources, PEP 668 flags pipdock env list # discovered envs, then the added ones; sources, PEP 668 flags
pipdock env use <path> # set the default env (§2) pipdock env use <path> # set the default env (§2)
pipdock env add <path> # add an interpreter or env dir to the list (the GUI's Add interpreter…)
pipdock env remove <path> # take an added one off the list; nothing on disk changes
pipdock list [--outdated] # installed packages, from the probe; --outdated asks the index pipdock list [--outdated] # installed packages, from the probe; --outdated asks the index
pipdock search <query> [--limit n] # local fuzzy index search (n defaults to 20) pipdock search <query> [--limit n] # local fuzzy index search (n defaults to 20)
pipdock info <pkg> # cached PyPI metadata pipdock info <pkg> # cached PyPI metadata
@@ -139,8 +141,10 @@ An error's exit is derived from its code's area (`run::exit_for`) rather than wr
| `snapshot create` | The new snapshot's `SnapshotMeta` | | `snapshot create` | The new snapshot's `SnapshotMeta` |
| `snapshot list` | `[SnapshotMeta]` | | `snapshot list` | `[SnapshotMeta]` |
| `snapshot diff` | `Diff`, as a rollback with this engine would see it; the lines no index can restore are printed in text mode only | | `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: `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 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 use` | The `PyEnv` that is now the default |
| `env add` | The added interpreter as one `env list` element, `source: "manual"` |
| `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]` | | `list` | `[Dist]`, from the probe; with `--outdated`, `[OutdatedDist]` |
| `search` | `[Hit]` | | `search` | `[Hit]` |
| `info` | `{meta: PackageMeta, freshness: Freshness}` | | `info` | `{meta: PackageMeta, freshness: Freshness}` |
+1 -1
View File
@@ -10,7 +10,7 @@
| Code | Detection (stderr/context pattern) | Cause | User action (EN; VI mirrored in locale files) | | 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") | env deleted or moved | Re-scan environments; remove stale entry | | 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-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-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-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 | | 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 |
+5 -3
View File
@@ -39,7 +39,7 @@ PipDock's thesis: **don't reimplement the resolver — explain it.** Wrap pip/uv
| # | Feature | Notes | | # | Feature | Notes |
|---|---|---| |---|---|---|
| P0-1 | Environment discovery & switcher | PEP 514 registry + `py -0p` + `uv python list` + known venv dirs + manual browse. Recents persisted. **Manual browse is not built:** `env_add_manual` is the one command still owed (`NOT_YET`), so a venv is found only as a `.venv`, `venv`, `env` or `.env` in the working directory, or named with the CLI's `--env`. **Recents:** the CLI's `env use` default is stored and, since 1.4.0, honoured; the GUI's selection lasts for the session. | | P0-1 | Environment discovery & switcher | PEP 514 registry + `py -0p` + `uv python list` + known venv dirs + manual browse. Recents persisted. **Manual browse shipped in 1.6.0**, the last command `NOT_YET` held: *Add interpreter…* on Environments (and `pipdock env add`) puts any `python.exe` on a list stored in `index.db` and shown after discovery's own, and *Remove from list* (`env remove`) takes it off. Before it the GUI saw a venv only as a `.venv`, `venv`, `env` or `.env` in its working directory — the install folder, for an installed app — so almost no project venv was reachable from the GUI. **Recents:** the CLI's `env use` default is stored and, since 1.4.0, honoured; the GUI's selection lasts for the session. |
| P0-2 | PEP 668 guard | Detect `EXTERNALLY-MANAGED`; block by default with explanation; explicit opt-in override only. **The override works since 1.4.0.** It saved and nothing read it, so turning it on changed nothing — and the guard decided on whatever the caller last cached, while the rollback flow had no guard at all. Every mutating flow now decides on a fresh probe; turning the override on asks first, and a chip is shown wherever it applies (SECURITY §3). | | P0-2 | PEP 668 guard | Detect `EXTERNALLY-MANAGED`; block by default with explanation; explicit opt-in override only. **The override works since 1.4.0.** It saved and nothing read it, so turning it on changed nothing — and the guard decided on whatever the caller last cached, while the rollback flow had no guard at all. Every mutating flow now decides on a fresh probe; turning the override on asks first, and a chip is shown wherever it applies (SECURITY §3). |
| P0-3 | Installed list | Per-env; up-to-date rows dimmed; outdated rows badged and mirrored into Updates tab. | | P0-3 | Installed list | Per-env; up-to-date rows dimmed; outdated rows badged and mirrored into Updates tab. |
| P0-4 | Updates flow | Group dry-run resolve → preview diff → 3-way conflict choices → two-phase execution → `pip check` post-verify → summary report. **Three parts of this worked only from 1.4.0:** *Force latest* was recorded and never read, so a forced resolve was the held-back one again — it now forces, and the preview names what it breaks before anything runs (DISCLAIMER §2); a post-run check that could not run reported `ok`, and now says it could not; and PipDock enforces `Requires-Python` itself (hard invariant 10), where PD-PKG-001 had never been raised. | | P0-4 | Updates flow | Group dry-run resolve → preview diff → 3-way conflict choices → two-phase execution → `pip check` post-verify → summary report. **Three parts of this worked only from 1.4.0:** *Force latest* was recorded and never read, so a forced resolve was the held-back one again — it now forces, and the preview names what it breaks before anything runs (DISCLAIMER §2); a post-run check that could not run reported `ok`, and now says it could not; and PipDock enforces `Requires-Python` itself (hard invariant 10), where PD-PKG-001 had never been raised. |
@@ -47,7 +47,7 @@ PipDock's thesis: **don't reimplement the resolver — explain it.** Wrap pip/uv
| P0-6 | Bulk uninstall + reverse-dep guard | Warn "removing X breaks Y, Z" before execution; `--force` override. | | P0-6 | Bulk uninstall + reverse-dep guard | Warn "removing X breaks Y, Z" before execution; `--force` override. |
| P0-7 | Pins | Per-env pin list; pinned packages excluded from *Select all*; lock icon in lists. | | P0-7 | Pins | Per-env pin list; pinned packages excluded from *Select all*; lock icon in lists. |
| P0-8 | Snapshots & rollback | Auto snapshot (freeze + metadata) before every batch; diff view; minimal-ops rollback. | | P0-8 | Snapshots & rollback | Auto snapshot (freeze + metadata) before every batch; diff view; minimal-ops rollback. |
| P0-9 | Engine setting (pip / uv) | Auto-detect uv on first run; switch any time in Settings; engine badge in status bar. **Auto-detect is not implemented, and is owed** (audit backlog X19): a fresh install drives pip (`Settings::default`). `settings.rs` places the detection in Settings, as a choice made where it can be seen, rather than in a read of an empty store — and the CLI follows the stored setting rather than probing `PATH` — but nothing in Settings makes it yet. What exists since 1.4.0 is the half it needs: Settings shows each engine's version for the selected environment beside its radio, *not found* when it is not installed. | | P0-9 | Engine setting (pip / uv) | Auto-detect uv on first run; switch any time in Settings; engine badge in status bar. **Auto-detect is not implemented, and is owed** (audit backlog X19): a fresh install drives pip (`Settings::default`). `settings.rs` places the detection in Settings, as a choice made where it can be seen, rather than in a read of an empty store — and the CLI follows the stored setting rather than probing `PATH` — but nothing in Settings makes it yet. What exists since 1.4.0 is the half it needs: Settings shows each engine's version for the selected environment beside its radio, *not found* when it is not installed. | **Not planned (maintenance mode, 1.6.0)**: the owner decided on 2026-11-21 that the half which exists — Settings shows each engine and its version, and switching is one click — is enough, and a first-run prompt is a new surface rather than a fix.
| P0-10 | pip upkeep | Show pip version per env; one-click `python -m pip install --upgrade pip`. | | P0-10 | pip upkeep | Show pip version per env; one-click `python -m pip install --upgrade pip`. |
| P0-11 | Code Health tab | deptry + vulture + ruff from PipDock's isolated tools env; report + safe `ruff --fix`. (Promoted to v1 by owner decision 2026-07.) | | P0-11 | Code Health tab | deptry + vulture + ruff from PipDock's isolated tools env; report + safe `ruff --fix`. (Promoted to v1 by owner decision 2026-07.) |
| P0-12 | CLI core parity | env / list / search / install / update / uninstall / pin / snapshot / doctor / health. JSON output. | | P0-12 | CLI core parity | env / list / search / install / update / uninstall / pin / snapshot / doctor / health. JSON output. |
@@ -66,10 +66,12 @@ PipDock's thesis: **don't reimplement the resolver — explain it.** Wrap pip/uv
| P1-4 | **Partly shipped, 1.1.0.** Cache manager | Shows and clears **PipDock's own** disk usage: snapshots, the Code Health tools venv and, since 1.2.0, the Security tab's audit venv. Logs (1.4.0) are not a target — the sweep keeps 14 days and nothing more, and Settings' Logs row says where they are. `index.db` is reported but not clearable — it holds settings, pins and the consent record in the same file, so "clear the cache" must never take them. **The engine caches (`pip cache`, `uv cache`) are not covered** and are a separate item: they belong to the engine, live outside `%LOCALAPPDATA%\PipDock\`, and purging them is a subprocess rather than a file delete. | | P1-4 | **Partly shipped, 1.1.0.** Cache manager | Shows and clears **PipDock's own** disk usage: snapshots, the Code Health tools venv and, since 1.2.0, the Security tab's audit venv. Logs (1.4.0) are not a target — the sweep keeps 14 days and nothing more, and Settings' Logs row says where they are. `index.db` is reported but not clearable — it holds settings, pins and the consent record in the same file, so "clear the cache" must never take them. **The engine caches (`pip cache`, `uv cache`) are not covered** and are a separate item: they belong to the engine, live outside `%LOCALAPPDATA%\PipDock\`, and purging them is a subprocess rather than a file delete. |
| P1-5 | **Shipped 1.1.0.** Command palette | Ctrl+K fuzzy action launcher (terminal-tech signature feature). | | P1-5 | **Shipped 1.1.0.** Command palette | Ctrl+K fuzzy action launcher (terminal-tech signature feature). |
| P1-6 | **Shipped 1.3.0.** Dependency view | "Who holds this back" for a selected package: the focused package between its dependents and its dependencies, each edge carrying the specifier written on it, each neighbour clickable to re-centre, plus the two transitive counts and any requirement nothing installed satisfies. **Not a node-link diagram, and that is a measurement rather than a shortcut** — on a 352-package environment a depth-1 neighbourhood is a median of 7 nodes but depth 2 is a median of 172 and exceeds 60 for 212 of 352 packages, and there are over 2000 distinct paths from `setuptools` to a root. So it is drawn at depth 1, depth is navigated by re-centring, and the transitive answer is a count. Added no runtime dependency. | | P1-6 | **Shipped 1.3.0.** Dependency view | "Who holds this back" for a selected package: the focused package between its dependents and its dependencies, each edge carrying the specifier written on it, each neighbour clickable to re-centre, plus the two transitive counts and any requirement nothing installed satisfies. **Not a node-link diagram, and that is a measurement rather than a shortcut** — on a 352-package environment a depth-1 neighbourhood is a median of 7 nodes but depth 2 is a median of 172 and exceeds 60 for 212 of 352 packages, and there are over 2000 distinct paths from `setuptools` to a root. So it is drawn at depth 1, depth is navigated by re-centring, and the transitive answer is a count. Added no runtime dependency. |
| P1-7 | Scheduled check | Optional background outdated-check with toast (no auto-apply, ever). | | P1-7 | **Not planned (maintenance mode, 1.6.0).** Scheduled check | Optional background outdated-check with toast (no auto-apply, ever). Every prerequisite is absent — no toast, no notification, autostart or tray plugin, nothing on a timer, no surface for a background failure (ROADMAP) — and the persona it serves already has the CLI in Task Scheduler, a recipe CLI-SPEC ships. Building it would be one plugin and a permanent background process for one line of text. |
### P2 — later ### P2 — later
**Not planned while PipDock is in maintenance mode (from 1.6.0).** Kept as the record of what was considered; CONTRIBUTING.md says what is taken instead.
| # | Feature | Notes | | # | Feature | Notes |
|---|---|---| |---|---|---|
| P2-1 | macOS / Linux builds | Tauri makes this near-free; test matrix is the real cost. | | P2-1 | macOS / Linux builds | Tauri makes this near-free; test matrix is the real cost. |
+1 -1
View File
@@ -12,7 +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. - 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. - **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. - **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) or an explicit user file-pick; they are canonicalized and existence-checked (PD-ENV-001) before use. - 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` or `python3.12.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.
- `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. - `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. - **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). - 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).
+1 -1
View File
@@ -64,7 +64,7 @@ IPC is mocked at the typed wrapper layer (`ui/src/test/ipc.ts`, a factory each t
### L4 — CLI (assert_cmd + insta) ### L4 — CLI (assert_cmd + insta)
Goldens over the real binary. There is no mocked core — this line promised one, and the CLI has no seam to mock at (`golden.rs` says why) — so what is goldened is everything deterministic without an interpreter: every command's and subcommand's help, which is the flag contract scripts read; the JSON and human error envelope; and `pipdock schema <T>` for every type in `SCHEMA_TYPES`, plus the unknown-type list — **68 snapshots at 1.4.0**. The exit-code table is asserted for the rows reachable without an interpreter (0, 2 and 3); L2 asserts the ones it can reach. A golden diff is a behaviour change: re-bless deliberately, never reflexively. Goldens over the real binary. There is no mocked core — this line promised one, and the CLI has no seam to mock at (`golden.rs` says why) — so what is goldened is everything deterministic without an interpreter: every command's and subcommand's help, which is the flag contract scripts read; the JSON and human error envelope; and `pipdock schema <T>` for every type in `SCHEMA_TYPES`, plus the unknown-type list — **70 snapshots at 1.6.0** (68 at 1.4.0; `env add` and `env remove` brought two). The exit-code table is asserted for the rows reachable without an interpreter (0, 2 and 3); L2 asserts the ones it can reach. A golden diff is a behaviour change: re-bless deliberately, never reflexively.
**Not covered by a committed test**, though this line claimed both: TTY versus non-TTY prompting, and `--json` payloads checked against `pipdock schema`'s output. CLI-SPEC §6's one-document `--json` rule was verified for 1.4.0 by driving the real binary through every path (ROADMAP), not by a test that stays. **Not covered by a committed test**, though this line claimed both: TTY versus non-TTY prompting, and `--json` payloads checked against `pipdock schema`'s output. CLI-SPEC §6's one-document `--json` rule was verified for 1.4.0 by driving the real binary through every path (ROADMAP), not by a test that stays.
+8 -4
View File
@@ -88,14 +88,18 @@ record of what PipDock ran, which outlives the window. The **console drawer** sl
## 4. Screens ## 4. Screens
**Environments.** Auto-discovered list (source chip: registry / py launcher / uv / venv / manual) with Python version, package count and pip version; PEP 668 envs carry a red `MANAGED` chip and a line pointing at a virtual environment instead. Actions: *Use*, *Open* (the detail view below), *Rescan*, and *Upgrade pip* when pip is below the planner's floor (§5). **Environments.** Auto-discovered list (source chip: registry / py launcher / uv / venv / manual) with Python version, package count and pip version; PEP 668 envs carry a red `MANAGED` chip and a line pointing at a virtual environment instead. Actions: *Use*, *Open* (the detail view below), *Rescan*, *Add interpreter…*, *Remove from list* on a row it added, and *Upgrade pip* when pip is below the planner's floor (§5).
**This line used to promise three things the screen does not have.** A managed environment is not **This line used to promise three things the screen does not have.** A managed environment is not
*disabled*: it can be selected and read, and a change to it is refused with PD-ENV-002 by the flow — *disabled*: it can be selected and read, and a change to it is refused with PD-ENV-002 by the flow —
decided on a fresh probe since 1.4.0, not on whatever the row last cached — unless the Settings decided on a fresh probe since 1.4.0, not on whatever the row last cached — unless the Settings
override is on. *Browse…* is still owed: `env_add_manual` is the one command left in `NOT_YET`, so an override is on. *Browse…* shipped in 1.6.0 as **Add interpreter…**, beside *Rescan* and as the empty state's one
environment is found only by discovery — the registry, the `py` launcher, `uv python list`, and a action (§7): a native picker filtered to `.exe`, then `env_add_manual`, which refuses anything not
`.venv`, `venv`, `env` or `.env` in the working directory. And there is no star-as-default: the 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,
`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 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. CLI's `env use` stores a default, honoured since 1.4.0; the GUI does not read it.
+3 -3
View File
@@ -1,6 +1,6 @@
# PipDock — Privacy Policy # PipDock — Privacy Policy
*Version 1.2 · Effective 2026-10-17 · Governing language: English.* *Version 1.3 · Effective 2026-11-21 · Governing language: English.*
## 1. The short version ## 1. The short version
@@ -13,7 +13,7 @@ All application data lives under `%LOCALAPPDATA%\PipDock\data\` and never leaves
| Data | Purpose | | Data | Purpose |
|---|---| |---|---|
| Settings (engine, locale, thresholds, consent record) | app configuration | | Settings (engine, locale, thresholds, consent record) | app configuration |
| Environment list, package index cache, and the Python versions each release supports | discovery, instant search, and refusing a version your Python cannot run | | Environment list — including the paths of interpreters you add with *Add interpreter…* or `pipdock env add`, kept until you remove them — package index cache, and the Python versions each release supports | discovery, instant search, and refusing a version your Python cannot run |
| Snapshots (package lists of your environments) | rollback | | Snapshots (package lists of your environments) | rollback |
| Pins | update exclusions | | Pins | update exclusions |
| PipDock's own tool environments (`tools\`, `audit\`) | running deptry, vulture and ruff for Code Health, and pip-audit for the Security tab; reinstalled on demand, clearable in Settings | | PipDock's own tool environments (`tools\`, `audit\`) | running deptry, vulture and ruff for Code Health, and pip-audit for the Security tab; reinstalled on demand, clearable in Settings |
@@ -51,4 +51,4 @@ Privacy questions: email <contact@poli0981.dev>, or open a discussion or issue a
## Tóm tắt Tiếng Việt (tham khảo) ## Tóm tắt Tiếng Việt (tham khảo)
PipDock **không thu thập bất kỳ dữ liệu nào**: không telemetry, không analytics, không tài khoản. Mọi dữ liệu (cài đặt, cache chỉ mục, snapshot, môi trường công cụ riêng của PipDock, log ghi lại các lệnh đã chạy) nằm trong `%LOCALAPPDATA%\PipDock\data\` trên máy bạn; xóa thư mục `data\` là xóa sạch — **đừng xóa thư mục cha**, vì chính chương trình được cài ở đó và xóa nó là gỡ luôn ứng dụng. Ứng dụng **chỉ** kết nối tới pypi.org (dữ liệu gói); PipDock không tự cập nhật nên không bao giờ gọi về GitHub. Một vài nút giao URL cho trình duyệt của bạn mở (github.com, docs.astral.sh, osv.dev, poli0981.dev) — đó là trình duyệt truy cập, sau khi bạn bấm. Nút báo lỗi chỉ mở form GitHub đã điền sẵn — không gì được gửi đi cho tới khi bạn tự xem lại và bấm gửi. Liên hệ: <contact@poli0981.dev>. PipDock **không thu thập bất kỳ dữ liệu nào**: không telemetry, không analytics, không tài khoản. Mọi dữ liệu (cài đặt, cache chỉ mục, đường dẫn các trình thông dịch bạn tự thêm, snapshot, môi trường công cụ riêng của PipDock, log ghi lại các lệnh đã chạy) nằm trong `%LOCALAPPDATA%\PipDock\data\` trên máy bạn; xóa thư mục `data\` là xóa sạch — **đừng xóa thư mục cha**, vì chính chương trình được cài ở đó và xóa nó là gỡ luôn ứng dụng. Ứng dụng **chỉ** kết nối tới pypi.org (dữ liệu gói); PipDock không tự cập nhật nên không bao giờ gọi về GitHub. Một vài nút giao URL cho trình duyệt của bạn mở (github.com, docs.astral.sh, osv.dev, poli0981.dev) — đó là trình duyệt truy cập, sau khi bạn bấm. Nút báo lỗi chỉ mở form GitHub đã điền sẵn — không gì được gửi đi cho tới khi bạn tự xem lại và bấm gửi. Liên hệ: <contact@poli0981.dev>.