Files
pipdock/docs/ARCHITECTURE.md
T
poli0981andClaude Opus 5 c4fe1c34e6 feat(core): scaffold the Cargo workspace, core crate and CLI surface
Phase 0 scaffold per ARCHITECTURE section 2. Everything compiles; nothing
resolves or mutates yet.

Implemented rather than stubbed, because the spikes need them and they are
the parts the invariants rest on:

- errors/catalog.rs: all 30 launch codes with their wire forms, plus tests
  that the wire codes are unique and match the PD-<AREA>-<NNN> grammar.
  Code::ALL drives the future "no code without fixture" gate.
- model.rs: PkgName::parse does PEP 508 validation and PEP 503
  normalization. This is the only way a name reaches an argv array, which
  makes SECURITY section 2 structural rather than aspirational; the test
  table rejects flags, separators and quoting attempts.
- probe.py: stdlib-only, Python 3.10 floor, per ARCHITECTURE section 4.
- The pip/uv argv builders, with tests asserting one token per argument.
- ExecutionSummary::tally, so the "13 successful, 2 failed" headline is
  derived from the rows rather than accumulated alongside them.

Stubbed with todo!() and a pointer to the milestone that fills them: the
Engine trait impls, discovery, index, graph, snapshot, pins, health.
UvEngine::parse_dry_run stays unimplemented on purpose — SP-1 must pin
uv's text plan format before anything parses it.

Two findings recorded in spikes/README.md:

- probe.py under -I hides user-site packages: 352 dists vs 376 without it
  and 375 from pip list, on a non-venv system Python. Venvs are unaffected.
  The fix trades a documented security control against list accuracy, so
  it is left as an open SP-6 decision rather than settled here.
- Python 3.14 deprecates subscripting absent metadata headers, which wrote
  DeprecationWarning to stderr on most distributions. probe.py now uses
  .get(); the probe must stay stderr-clean because noise reads as
  PD-ENV-003.

rusqlite is held at 0.37: 0.40 pulls libsqlite3-sys 0.38.1, whose build
script needs the unstable cfg_select! and will not build on stable 1.94.1.
Recorded in the ARCHITECTURE version manifest.

cargo fmt, clippy -D warnings and 23 tests are green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-27 17:25:56 +07:00

9.7 KiB
Raw Blame History

PipDock — Architecture

Version 0.1 · 2026-07-17

1. Design principles

  1. One core, two heads. All domain logic lives in pipdock-core (Rust). The Tauri GUI and the clap CLI are thin adapters over the same functions; neither contains business logic.
  2. Explain, don't reimplement. Dependency resolution is always performed by the selected engine (pip or uv) in dry-run mode. PipDock parses and presents; it never computes version resolution itself.
  3. Out-of-band by construction. PipDock ships as a standalone signed binary. It is never installed into a Python environment, so no operation it performs can break its own runtime (G6).
  4. Everything mutating is previewed and snapshotted. No code path may call a mutating engine command without (a) a prior dry-run plan and (b) a pre-execution snapshot.
  5. Subprocess, never shell. Engines are invoked with argv arrays (tokio::process::Command), never through a shell. Package names are validated against the PEP 508 name grammar before ever reaching argv.

2. Repository layout

pipdock/
├─ crates/
│  ├─ pipdock-core/          # domain logic (this is the product)
│  │  ├─ src/engine/         # Engine trait + pip.rs + uv.rs adapters
│  │  ├─ src/envs/           # discovery (PEP 514, py launcher, uv, venv scan), PEP 668
│  │  ├─ src/index/          # PEP 691 name cache, fuzzy search (nucleo), PyPI JSON metadata
│  │  ├─ src/plan/           # PlanRequest → ResolutionReport → ExecutionReport
│  │  ├─ src/graph/          # reverse-dependency graph from env introspection
│  │  ├─ src/snapshot/       # freeze snapshots, diff, minimal-ops rollback
│  │  ├─ src/pins/           # pin store + auto-suggest scoring
│  │  ├─ src/health/         # tools-venv manager, deptry/vulture/ruff runners
│  │  ├─ src/errors/         # error catalog (codes + stderr classifiers)
│  │  └─ src/probe.py        # embedded env-introspection helper (see §4)
│  └─ pipdock-cli/           # clap binary `pipdock`
├─ src-tauri/                # Tauri 2 app (commands + events only)
├─ ui/                       # React 19 + TS + Tailwind 4 + Vite 8 + Zustand + i18next
├─ legal/                    # EULA, Disclaimer, Privacy, Third-Party (public — legal gate links here)
├─ .github/                  # caller workflows into poli0981/.github + issue templates
└─ docs/

Naming conventions: crates pipdock-*; React components prefixed Pd* (PdPackageRow, PdConflictDialog); Tauri identifier com.skullmute.pipdock; CLI binary pipdock.

3. The Engine trait

#[async_trait]
pub trait Engine: Send + Sync {
    fn id(&self) -> EngineId;                       // Pip | Uv
    async fn info(&self, env: &PyEnv) -> EngineInfo;          // version, availability
    async fn list_installed(&self, env: &PyEnv) -> Result<Vec<Dist>>;
    async fn list_outdated(&self, env: &PyEnv) -> Result<Vec<OutdatedDist>>;
    async fn resolve(&self, env: &PyEnv, req: &PlanRequest) -> Result<ResolutionReport>;
    async fn install(&self, env: &PyEnv, specs: &[PinnedSpec], mode: ExecMode,
                     sink: EventSink) -> Result<StepResult>;
    async fn uninstall(&self, env: &PyEnv, names: &[PkgName], sink: EventSink) -> Result<StepResult>;
    async fn check(&self, env: &PyEnv) -> Result<CheckReport>;      // pip check / uv pip check
    async fn upgrade_pip(&self, env: &PyEnv) -> Result<StepResult>; // pip engine only; uv returns Unsupported
}

Key model types:

  • PlanRequest — the user's intent: { upgrades: Vec<PkgName>, installs: Vec<Spec>, strategy: Compatible | ForceLatest(per-pkg overrides) }.
  • ResolutionReport — normalized output of the dry-run: { changes: Vec<Change>, held_back: Vec<HeldBack{ pkg, resolved, latest, blockers: Vec<Blocker{by, constraint}> }>, impossible: Option<ImpossibleDetail>, 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.

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.

4. Environment introspection: probe.py

Rust cannot cheaply read a foreign env's installed metadata. PipDock embeds a single-file, stdlib-only helper (probe.py, ~150 lines, no third-party imports) executed as <env-python> probe.py --json, printing one JSON document:

{ "python": "3.12.4", "prefix": "...", "externally_managed": false,
  "dists": [ { "name": "requests", "version": "2.32.3",
               "requires_dist": ["urllib3<3,>=1.21.1", "..."],
               "requires_python": ">=3.8" } ] }

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

  • Name index: PyPI Simple Index in PEP 691 JSON form → SQLite (index.db, table names(name, normalized)), refreshed manually or every 7 days. Fuzzy search runs in Rust (nucleo matcher) over the normalized column; target < 50 ms per keystroke.
  • Metadata on demand: GET https://pypi.org/pypi/<name>/json → summary, latest version, requires-python, license, project URLs. Cached in meta_cache with 24 h TTL. Strict HTTPS, no redirects off pypi.org.
  • Offline: search still works over the cached index; metadata panel shows a cached/offline badge.

6. Storage (%LOCALAPPDATA%\PipDock\)

config.json          # settings: engine, locale, thresholds, consent {docsHash, timestamp}
index.db             # SQLite: names, meta_cache, envs(recent), pins(env_hash, pkg, mode, reason)
snapshots/<envhash>/<iso-ts>.freeze.txt + .meta.json
tools/.venv/         # Code Health tools env (see CODE-HEALTH-SPEC)
logs/pipdock.<date>.log   # tracing rolling files, 14-day retention

env_hash = SHA-256 of the canonicalized interpreter path. Snapshot .meta.json records trigger (which plan), engine, package count, and app version.

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.

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).

8. Execution model (two-phase)

Given a confirmed ResolutionReport (see DATA-FLOW §3 for the state machine):

  1. Phase A — batch fast path: one engine invocation installing the full pinned set. Fast (especially uv) and atomic-ish. If it exits 0 → done.
  2. Phase B — isolation pass: on Phase-A failure, re-run per package (<engine> install pkg==ver) sequentially in resolver-report order, collecting individual StepResults. Failures are classified via the error catalog and do not stop the loop (owner requirement: skip and continue).
  3. Post-run: engine.check(); summary aggregates Phase A/B results + check findings.

Uninstalls are always sequential (cheap) with the reverse-dep guard evaluated once up front against the full removal set.

9. Frontend architecture

Zustand stores: useEnvStore, usePlanStore, useIndexStore, useSettingsStore, useHealthStore. All engine data enters via typed IPC wrappers (ui/src/ipc/*.ts) mirroring the Rust types (generated with specta/tauri-specta to prevent drift). No component calls invoke directly. i18next with en/vi JSON catalogs (see I18N.md). Styling via Tailwind 4 tokens defined in UI-SPEC.

10. Version manifest (verified 2026-07; re-verify at implementation)

Component Version policy
Tauri 2.10.x (latest 2.x line) + tauri-plugin-updater
Rust latest stable toolchain, pinned via rust-toolchain.toml
React / TypeScript 19.x / latest stable
Vite / Tailwind 8.1.x (Rolldown line) / 4.x
Node (dev only) 24 LTS (Active LTS; EOL 2028-04)
pip engine ≥ 24.0 supported; latest is 26.1.x. --dry-run --report requires ≥ 22.2 — PipDock offers to upgrade older pips before first plan.
uv engine latest stable (0.9.x line at writing); minimum pinned after SP-1
Managed Pythons 3.10 – 3.14 (3.9 is EOL)
Windows 10 (1809+) / 11; WebView2 Evergreen assumed present; longPathAware manifest enabled
rusqlite held at 0.37 (libsqlite3-sys 0.35). 0.40 pulls libsqlite3-sys 0.38.1, whose build script uses the unstable cfg_select! and therefore does not compile on stable Rust 1.94.1. Revisit when the toolchain advances.

Dependabot + cargo audit + npm audit in CI keep this table honest (RELEASE-CI.md §2).