docs: reconcile the IPC command list, and say where installed packages come from

ARCHITECTURE §7 listed 26 commands as prose with `a|b|c` groupings, which made the
count ambiguous enough that Stage 1 added `app_info` and `plan_decide` without anyone
noticing the doc had gone stale. `ui/src/ipc/index.ts` said "there are 26 of them"
while its own COMMANDS array held 28.

Rewritten as a table of 32 with a return type and a purpose per row, and a line saying
that a command not listed there does not exist. The four genuinely new names are the
ones M2 already needs and had nowhere to be written down: `engine_info` (Settings shows
a detected version per engine, and nothing returned `EngineInfo`), `index_refresh`,
`snapshot_create` (§7 had only list|diff|rollback), and `report_bug_url` — built in
Rust so it cannot drift from `pipdock self report-bug`.

DATA-FLOW §7's "List installed" row claimed both engines' `list --format=json`. Neither
head has ever called it: `pipdock list` reads probe.py, and `pkg_list` will too. The
probe carries Requires-Dist, which `list --format=json` drops, and which the reverse-dep
graph, the uninstall guard and blocker attribution are all built from — so reading the
engine there would hand the Installed screen a different package set than the guard
that protects it. `Engine::list_installed` still exists; only `resolve()` calls it, for
SP-1's guard set.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-08-04 15:34:33 +07:00
1 parent d7da4d72e2
commit 8270ea64dc
3 files changed
+49 -7

No files matched your search

+38 -2
View File
@@ -106,8 +106,44 @@ logs/pipdock.<date>.log # tracing rolling files, 14-day retention
## 7. Tauri IPC surface
Commands (all `async`, all returning `Result<T, PdError>` where `PdError` carries a catalog code):
`env_scan`, `env_add_manual`, `env_probe`, `pkg_list`, `pkg_outdated`, `index_search`, `pkg_metadata`, `plan_resolve`, `plan_execute`, `plan_cancel`, `uninstall_guard`, `uninstall_execute`, `pin_list|add|remove`, `snapshot_list|diff|rollback`, `health_run`, `health_fix`, `settings_get|set`, `logs_tail`, `pip_upgrade`, `legal_consent_get|set`.
Commands return `Result<T, PdError>` where `PdError` carries a catalog code, and are `async` except `app_info`, which is a compile-time constant. Each is a **thin** wrapper over a `pipdock_core` function — a wrapper that starts making decisions is logic the CLI will not inherit, and G5 promises the two heads never diverge.
This table is the surface. A command that is not listed here does not exist; adding one means amending this section in the same commit. It was written as a prose list of 26 with `a|b|c` groupings, which made the count ambiguous and let two Stage 1 additions land undocumented — hence the table.
| 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. |
| `env_add_manual` | `EnvRow` | Persist an interpreter chosen through *Browse…*. |
| `env_probe` | `EnvRow` | Probe one interpreter without persisting it. |
| `pkg_list` | `Dist[]` | Installed distributions, read from `probe.py` rather than the engine — see §4 and DATA-FLOW §7. |
| `pkg_outdated` | `OutdatedDist[]` | Outdated distributions, via the configured engine. |
| `index_search` | `Hit[]` | Fuzzy search over the in-memory name index. |
| `index_refresh` | `RefreshReport` | Re-download the PEP 691 name index. |
| `pkg_metadata` | `PackageMeta` | Cached PyPI metadata for the details panel, with its freshness. |
| `plan_resolve` | `FlowStep` | Begin an update or install flow: dry-run resolve, then derive held-back items. |
| `plan_decide` | `FlowStep` | Apply the user's 3-way conflict decisions and re-resolve. |
| `plan_execute` | `ExecutionSummary` | Take the snapshot, then run the two-phase execution (§8). |
| `plan_cancel` | `()` | Trip the running plan's cancellation token. |
| `uninstall_guard` | `GuardReport` | Reverse-dependency check over a removal set. |
| `uninstall_execute` | `ExecutionSummary` | Snapshot, then remove. |
| `pin_list` | `Pin[]` | Pins for an environment. |
| `pin_add` | `()` | Add or replace a pin. |
| `pin_remove` | `bool` | Remove a pin; reports whether one existed. |
| `snapshot_list` | `SnapshotMeta[]` | Snapshots for an environment. |
| `snapshot_create` | `SnapshotMeta` | Take a snapshot on demand, outside any plan. |
| `snapshot_diff` | `Diff` | The environment against a snapshot. |
| `snapshot_rollback` | `ExecutionSummary` | Restore a snapshot — itself snapshotted first, per DATA-FLOW §8. |
| `health_run` | `CheckReport` | Run the Code Health tools against a project folder. |
| `health_fix` | `ExecutionSummary` | Apply the gated `ruff` fix. |
| `engine_info` | `EngineInfo[]` | Detected version and availability per engine. Settings shows both, so this returns both. |
| `pip_upgrade` | `ExecutionSummary` | Upgrade pip itself in the selected environment. |
| `settings_get` | `Settings` | Read stored settings. |
| `settings_set` | `Settings` | Persist settings, returning what was actually stored rather than what was sent. |
| `legal_consent_get` | `ConsentState` | Whether the legal gate can be skipped for this build's documents. |
| `legal_consent_set` | `Consent` | Record acceptance. |
| `logs_tail` | `string[]` | Tail of the in-memory log ring buffer, for the console drawer. |
| `report_bug_url` | `string` | Prefilled GitHub issue URL (ERROR-CATALOG §4). Built in Rust so it cannot drift from `pipdock self report-bug`. **Nothing is ever sent automatically.** |
Events (Tauri event channel): `plan-progress { step, pkg, phase, line }` streams live subprocess output to the in-app console; `scan-progress`; `health-progress`. Long operations are cancellable: `plan_cancel` kills the current child process group and marks remaining steps `Skipped(UserCancelled)` — already-completed steps stay applied (snapshot covers full revert).
+3 -1
View File
@@ -100,7 +100,7 @@ Rendered as: **"13 successful, 2 failed, 1 skipped"** with an expandable row per
| Operation | pip (`<py> -m pip …`) | uv (`uv pip … --python <py>`) | Adapter notes |
|---|---|---|---|
| List installed | `list --format=json` | `list --format=json` | shapes differ slightly; normalize to `Dist` |
| List installed | *(not used — see below)* | *(not used — see below)* | `Engine::list_installed` exists and normalizes both shapes to `Dist`, but only `resolve()` calls it, to build SP-1's guard set |
| List outdated | `list --outdated --format=json` | `list --outdated --format=json` | uv output pinned in SP-1 fixtures |
| Dry-run resolve | `install -U --dry-run --quiet --report -` (JSON to stdout) | `uv pip install -U --dry-run` (**text plan; no stable JSON report**) | uv adapter parses text; exact format frozen via SP-1 fixtures + snapshot tests |
| Install pinned | `install pkg==v [--no-deps in Phase A per-report set]` | `uv pip install pkg==v` | Phase A passes the full pinned set in one call |
@@ -109,6 +109,8 @@ Rendered as: **"13 successful, 2 failed, 1 skipped"** with an expandable row per
| Freeze (snapshots) | `freeze --all` | `uv pip freeze` | pip's `--all` includes pip/setuptools; record engine in snapshot meta |
| Upgrade pip | `install -U pip` | *(n/a — surface "pip upkeep" only when pip engine active or pip present in env)* | |
**Neither head lists installed packages through the engine.** `pipdock list` and `pkg_list` both read `probe.py` instead, because the probe carries `Requires-Dist` — which `list --format=json` does not report, and which the reverse-dependency graph, the uninstall guard and blocker attribution are all built from. Reading the engine here would give the Installed screen a different package set than the guard that protects it. The `-I` trade-off this buys is documented in ARCHITECTURE §4 and surfaced as `hidden_user_site`.
Version floors: pip ≥ 22.2 for `--dry-run --report` (offer in-app pip upgrade when older); uv minimum pinned after SP-1.
## 8. Rollback flow
+8 -4
View File
@@ -7,8 +7,8 @@
*
* Data types are generated from the Rust definitions into `./generated.ts` by
* `cargo run -p xtask -- bindings`, and `cargo test` fails while that file is stale. Command
* *signatures* are not derivable from a schema, so the wrappers below are hand-written — there are
* 26 of them and each has one caller.
* *signatures* are not derivable from a schema, so the wrappers below are hand-written, one per
* entry in `COMMANDS`.
*/
import { invoke } from '@tauri-apps/api/core'
@@ -27,6 +27,7 @@ export const COMMANDS = [
'pkg_list',
'pkg_outdated',
'index_search',
'index_refresh',
'pkg_metadata',
'plan_resolve',
'plan_decide',
@@ -38,16 +39,19 @@ export const COMMANDS = [
'pin_add',
'pin_remove',
'snapshot_list',
'snapshot_create',
'snapshot_diff',
'snapshot_rollback',
'health_run',
'health_fix',
'engine_info',
'pip_upgrade',
'settings_get',
'settings_set',
'logs_tail',
'pip_upgrade',
'legal_consent_get',
'legal_consent_set',
'logs_tail',
'report_bug_url',
] as const
export type Command = (typeof COMMANDS)[number]