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:
1 parent
d7da4d72e2
commit
8270ea64dc
3 files changed
+49
-7
No files matched your search
+38
-2
@@ -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
@@ -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
@@ -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]
|
||||
|
||||
Reference in new issue
Block a user