From 4a9dc1d565d1705814dba1c840b2b609f1aeeee1 Mon Sep 17 00:00:00 2001 From: DCreason Date: Wed, 18 Feb 2026 19:28:56 -0600 Subject: [PATCH] updated plan for sprint 2 --- PLAN.md | 148 ++++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 118 insertions(+), 30 deletions(-) diff --git a/PLAN.md b/PLAN.md index f2cbfc6..932002b 100644 --- a/PLAN.md +++ b/PLAN.md @@ -3,45 +3,133 @@ ## Language Choice: Rust Why Rust for this: -- Produces a single static-ish native binary easily (great for self-contained executables). +- Produces a single native binary easily (great for self-contained executables). - Strong ecosystem for TUIs (`ratatui`, `crossterm`) and system stats (`sysinfo`). - Good performance and low runtime overhead for frequent refresh loops. -## Plan +--- -1. Define scope and MVP metrics -- CPU usage (total + per core), memory, swap, disk usage, network throughput, process count, uptime. -- Target Linux first (then add macOS/Windows support if needed). +## Product goals -2. Bootstrap project structure -- Create a Rust CLI app with modules for `collectors`, `ui`, `state`, and `config`. -- Add dependencies: `ratatui`, `crossterm`, `sysinfo`, `anyhow`, `clap`, `serde` (optional config). +### What “good” looks like +- **Instant readability**: at-a-glance totals + per-core detail without toggles. +- **htop-like process view by default**: sortable, scrollable, fast. +- **Responsive layout**: works on narrow terminals without becoming unusable. +- **Low flicker + smooth updates**: stable layout, minimal reflow between ticks. +- **Beautiful defaults**: clean spacing, consistent borders, and clear hierarchy. -3. Implement data collection layer -- Build a polling engine (e.g., 500ms–1s interval) that samples resource metrics. -- Normalize all values into a shared state model for UI rendering. -- Add delta-based metrics (network/disk rates) from successive samples. +### Core metrics (MVP+) +- CPU: **total + per-core bars**, load averages, process count. +- Memory: used/total **bar**, swap used/total **bar**. +- Disk: per-mount **bars** (used/total) + optional IO rate later. +- Network: RX/TX rate (small footprint) + totals in a compact detail pane. +- Uptime + refresh interval. -4. Build TUI layout and rendering -- Header: host info, uptime, refresh rate. -- Main panes: CPU, memory/swap, disk, network. -- Footer/help bar with keybindings. -- Add responsive layout for small terminal sizes. +--- -5. Add interaction model -- Keybindings: quit, pause/resume, change refresh interval, toggle detailed view. -- Optional sorting/filtering for top processes view. +## Architecture -6. Packaging and self-contained build -- Configure release profile (`lto`, `panic=abort`, `strip`) for small fast binary. -- Document build command for optimized executable. -- Optional: static linking strategy for fully portable Linux binary. +### Modules +- `collectors/`: system sampling + delta/rate calculations (network rates, etc). +- `state/`: normalized app state for rendering (no sysinfo types in UI). +- `ui/`: layout + widgets (bars, tables, header/footer). +- `input/`: keybindings + focus handling. +- `config/`: CLI flags + optional persisted config. -7. Quality gates -- Unit tests for metric calculations and rate/delta logic. +### Data model notes +- Keep a **ring buffer** of the last N samples for rate calculations and future sparklines. +- Store both **instant values** (CPU%, mem used) and **derived values** (RX KiB/s). +- Separate “current tick state” from “UI selection state” (process selection, sort, scroll). + +--- + +## UI / UX layout (target default) + +### Default screen (htop-inspired) +- **Header (1 line):** hostname, uptime, refresh interval, procs, load(1m/5m/15m). +- **Top section (CPU):** + - First row: **Total CPU bar** + total %. + - Next rows: **Per-core bars** (wrap to multiple rows on wide terminals; collapse to fewer rows on narrow terminals). +- **Middle section:** + - **Memory bar** (used/total + %), **Swap bar** (used/total + %). + - **Disk bars**: one row per mount (or top N by usage), showing used/total + %. +- **Bottom section (Process table, default on):** + - Columns: PID, CPU%, MEM%, RSS, STATE, USER (optional), COMMAND (truncated). + - Scrolling + selection highlight. +- **Right sidebar (small): Network** + - Compact: RX rate, TX rate (e.g., “RX 5.6 KiB/s | TX 5.7 KiB/s”). + - Optional detail toggle: totals, interface name(s). + +### Visual design guidelines (be specific) +- **Consistent padding** inside blocks (at least 1 cell margin). +- **Fewer heavy borders**: prefer thin borders + whitespace hierarchy. +- **Aligned numbers**: right-align percentages and sizes; fixed-width columns where possible. +- **Bars** + - Use `Gauge`-style bars with labels like `59% 2.3 GiB / 3.8 GiB`. + - Clamp + smooth values slightly to avoid jitter (optional). +- **Color & emphasis** + - One accent color for active focus/selection. + - Subtle dim styling for labels; brighter for values. + - Avoid rainbow; keep it calm and readable. + +### Responsiveness rules +- Narrow terminals: + - Collapse per-core section to fewer rows (or show top K cores + “+N more”). + - Reduce disk mounts shown to top N; hide least relevant columns in process table (e.g., USER). + - Keep process table visible unless terminal is extremely small (then show summary-only mode). + +--- + +## Interaction model (baseline) +- `q` quit +- `p` pause/resume +- `+` / `-` change refresh interval +- `Tab` switch focus (summary panes ↔ process table) +- Process table: + - `↑/↓` move selection, `PgUp/PgDn` scroll + - `c` sort by CPU, `m` sort by MEM, `p` sort by PID + - `/` filter (optional, can land after MVP) +- `d` toggle detail panes (e.g., expanded network / disk details) + +--- + +## Delivery plan (sprints) + +### Sprint 0 (done) +- Basic Rust program compiles and shows core resource usage. +- Responsive layout baseline exists. + +### Sprint 1 (next): “Better default screen” +**Goal:** The default view matches the desired htop-like workflow. +- [ ] Show **process list by default** (table + selection + scrolling). +- [ ] Keep existing **total CPU** but add **per-core bars** by default. +- [ ] Convert **memory**, **swap**, and **disk** to **bars** with used/total labels. +- [ ] Make **network section smaller** (compact sidebar or single-row block). +- [ ] Visual polish pass: spacing, alignment, consistent borders, calmer palette. +- [ ] Add stable refresh loop (avoid flicker; only redraw when needed). + +**Acceptance criteria** +- At 80×24 terminal, user can see: total CPU + some per-cores, memory bar, at least 1–2 disk bars, and a usable process table. +- Process table supports scrolling and at least one sort (CPU). + +### Sprint 2: “Interaction + quality” +- [ ] Full sort options (CPU/MEM/PID) + stable sorting. +- [ ] Focus handling + keybinding help footer. +- [ ] Optional filter/search in process table. +- [ ] Delta/rate correctness tests (network rates, refresh tick stability). +- [ ] Add config via CLI flags (refresh interval, hide/show panes). + +### Sprint 3: “Nice-to-haves” +- [ ] Sparklines (CPU/mem/net history) using ring buffer. +- [ ] Per-process drilldown (open files, threads) where supported. +- [ ] Alerts (threshold highlights) + optional logging/export. +- [ ] Packaging: release profile, strip, optional static linking notes. + +--- + +## Quality gates +- Unit tests for delta/rate logic and formatting helpers. - Smoke test for startup/render loop. -- Run `clippy` and `fmt` checks. +- `cargo fmt`, `cargo clippy` clean. +- Manual QA on terminal sizes: 80×24, 100×30, ultrawide. -8. Delivery -- Provide binary + README with usage, keybindings, and supported platforms. -- Include known limitations and next-step roadmap (alerts, historical sparklines, per-process drilldown).