Files
pipdock/docs/UI-SPEC.md
T
poli0981andClaude Opus 5 4ab948ac7b feat: implement the two owner decisions from spike week
Requires-Python is now enforced by PipDock, not by the engine.

SP-2 found the engines disagree: scipy 1.7.3 declares >=3.7,<3.11, and on
Python 3.12 pip refuses it while uv plans to install it. G5 promises one
behaviour across heads, so the preview must not change shape because the
user flipped the engine radio. crates/pipdock-core/src/compat.rs screens
every candidate against the environment's version before any engine
command runs; rejects surface as PD-PKG-001 with the required range shown
against the found version.

This does not weaken "explain, don't reimplement" — resolution stays
entirely the engine's. compat.rs only filters candidates the engine should
never have been offered, using the slice of PEP 440 that actually appears
in Requires-Python: comparison, wildcard and compatible-release operators.
Specifiers it cannot parse count as compatible, because PipDock failing to
read metadata must never be the reason an installable package is refused.
Nine tests, including the exact scipy case the spike captured and the
boundary cases where an off-by-one would reject a supported Python.

probe.py keeps -I, and the cost is disclosed rather than hidden.

Isolated mode is what stops a poisoned environment injecting code into the
probe, so it stays; dropping to -E was rejected because a package in user
site is part of the untrusted surface the isolation exists to exclude, and
probing twice was rejected as a second interpreter start per scan for a
non-primary case. Instead probe.py now reports hidden_user_site — the
user-site path when it exists, sits off sys.path and is non-empty, else
null. Verified: the system Python reports the path (352 dists), a venv
reports null. The Installed screen shows a note naming the path only when
it is non-null, so users of the affected case are told exactly what is
missing while everyone else sees nothing.

ERROR-CATALOG PD-PKG-001 changes from a stderr classification to a
PipDock-raised code, because engine stderr cannot support it: pip reports
it as plain "No matching distribution found", indistinguishable from
PD-PKG-002, and uv does not enforce it at all.

Docs updated: ARCHITECTURE 3 and 4, DATA-FLOW 2, SECURITY 2, UI-SPEC 4,
ERROR-CATALOG 2, ROADMAP, CLAUDE.md, spikes/README.md. EN and VI strings
added for both notes.

Two non-blocking questions remain in spikes/README.md: search-ranking
scope for M1, and how to obtain the five error fixtures this machine
cannot produce.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-27 18:38:46 +07:00

8.7 KiB
Raw Blame History

PipDock — UI Specification

Version 0.1 · 2026-07-17 · Direction: dark terminal-tech (owner decision 2026-07)

1. Design intent

PipDock should feel like a precision instrument docked over a terminal — the calm confidence of a good TUI with the affordances of a native app. Not a neon cyberpunk cliché, not a generic admin dashboard: restrained phosphor-green on near-black, monospace where data lives, one accent doing real work. Signature moves: a terminal-style status line pinned to the bottom, a live execution console that streams real engine output, and (P1) a Ctrl+K command palette.

Anti-goals: gradients-everywhere SaaS look, rounded-blob cards, decorative glow. Any glow is functional (focus rings, live-activity pulse) and subtle.

2. Design tokens (Tailwind 4 @theme)

Token Value Use
--color-bg #0A0E0C app background
--color-surface #101612 panels, rows
--color-surface-2 #161E18 hover, elevated
--color-border #1F2B23 hairlines
--color-accent #4ADE80 primary actions, focus, live pulse
--color-accent-dim #22935B secondary accents, links
--color-text #E7F0EA primary text
--color-text-dim #8AA394 secondary text, dimmed up-to-date rows
--color-warn #F5B94A held-back, warnings
--color-danger #F0574F impossible, failures, force actions
--color-info #5BC0DE pinned, informational chips

Type: Inter (UI), JetBrains Mono (package names, versions, console, status line — both OFL-licensed, bundled). Base 14 px, mono data 13 px. Radius 6 px; borders 1 px; shadows minimal. Motion: 120–160 ms ease-out; live-activity pulse on the status-line engine badge during execution; prefers-reduced-motion respected.

3. Layout

┌──────────────────────────────────────────────────────────────┐
│ ⌂ PipDock      [env: .venv (Py 3.12) ▾]        [engine: uv]  │  top bar
├───────────┬──────────────────────────────────────────────────┤
│ Environments        │                                        │
│ Installed           │                                        │
│ Updates (7)         │              content area              │
│ Search              │                                        │
│ Pins                │                                        │
│ Health              │                                        │
│ Security (P1)       │                                        │
│ Settings            │                                        │
├───────────┴──────────────────────────────────────────────────┤
│ ▸ .venv · Py 3.12.4 · uv 0.9.x · idle            log ⌄  ⚠ 0  │  status line
└──────────────────────────────────────────────────────────────┘

Sidebar is icon+label, collapsible to icons. Status line (mono) always shows env · python · engine · state, plus a log-drawer toggle. The console drawer slides up over the status line during execution, streaming plan-progress lines with per-package section markers; collapsible, never modal.

4. Screens

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

Search. Search field autofocused; results stream under 50 ms per keystroke from the local index. Result row: name · summary (from cached metadata) · latest · INSTALLED ✓/UPDATE chip when applicable · [Add]. Right detail panel: description, requires-python, license, links. Queue ("dock bay") docks along the right edge as a slim column of added packages with editable version fields and Install (n).

Pins. Pin list with reason field; (P1) auto-suggest section: "urllib3 — 12 packages depend on it. Pin?".

Snapshots (surfaced under Environments → env detail): timeline of snapshots with trigger label, diff viewer (added/removed/changed in mono), Rollback… with its own preview per DATA-FLOW §8.

Health. Project-folder picker (persisted per env) → run panel with three result tabs (deptry / vulture / ruff) per CODE-HEALTH-SPEC; Fix with ruff gated behind explicit confirm listing file count.

Settings. Engine (pip/uv radio + detected versions), locale (EN/VI), thresholds (pin auto-suggest count, snapshot retention), index refresh, PEP 668 override (off by default, scary copy), Open logs folder, Legal & About (links to GitHub legal docs + re-open legal gate).

Legal gate (first run). Modal listing the five documents with GitHub links and a summarized disclaimer sentence; single checkbox "I have read and accept" → Continue. Decline exits the app. Consent stored with docs-version hash; hash bump re-triggers the gate.

5. Click budgets (owner ceiling: 5)

Flow Clicks Path
Update everything 4 Updates → Select all → Update → Confirm (app auto-scans on env open)
Update everything, 1 conflict kept compatible 4 default choice needs no extra click
Install one package 4 + typing Search (autofocus) → result [Add] → Install → Confirm
Uninstall one package 3 Installed row ⋮ → Uninstall → Confirm
Rollback last snapshot 4 Env detail → snapshot → Rollback → Confirm
Switch engine 3 Settings → engine radio → (auto-saved) back
Run Code Health 3 Health → Run (folder persisted) → view

6. Component inventory (prefix Pd)

PdSidebar, PdStatusLine, PdEnvSwitcher, PdPackageTable (virtualized), PdPackageRow, PdBadge, PdPreviewDiff, PdConflictRow (segmented 3-way), PdDockBay (queue), PdConsoleDrawer, PdSummarySheet, PdSnapshotTimeline, PdHealthReport, PdLegalGate, PdEmptyState, PdOfflineBanner.

7. States & feedback

  • Loading: skeleton rows in surface-2, never spinners longer than 300 ms without text.
  • Empty states: one mono glyph + one sentence + one action (e.g. Updates empty: ▸ all packages up to date).
  • Offline: banner chip in top bar; search works (local index), metadata panel shows cached-at timestamp.
  • Errors: inline with catalog code, human message (localized), and Details expanding stderr tail. Toasts only for background completions.
  • Destructive confirms (Force latest, uninstall with breakage, PEP 668 override) use --color-danger primary buttons and require the dialog's default focus to be Cancel.

8. Keyboard & accessibility

Full keyboard traversal: Ctrl+1..8 sidebar tabs, / focuses search, Space toggles row selection, Ctrl+A select-all-visible, Enter primary action, Esc closes drawers. Contrast: all text tokens meet WCAG AA on their surfaces (verified in the design-token test); focus ring 2 px accent, never removed. Screen-reader labels on all icon buttons; live region announces execution progress summaries ("13 of 15 complete"). Windows high-contrast mode: tokens fall back to system colors.