updated plan for sprint 2
This commit is contained in:
148
PLAN.md
148
PLAN.md
@@ -3,45 +3,133 @@
|
|||||||
## Language Choice: Rust
|
## Language Choice: Rust
|
||||||
|
|
||||||
Why Rust for this:
|
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`).
|
- Strong ecosystem for TUIs (`ratatui`, `crossterm`) and system stats (`sysinfo`).
|
||||||
- Good performance and low runtime overhead for frequent refresh loops.
|
- Good performance and low runtime overhead for frequent refresh loops.
|
||||||
|
|
||||||
## Plan
|
---
|
||||||
|
|
||||||
1. Define scope and MVP metrics
|
## Product goals
|
||||||
- CPU usage (total + per core), memory, swap, disk usage, network throughput, process count, uptime.
|
|
||||||
- Target Linux first (then add macOS/Windows support if needed).
|
|
||||||
|
|
||||||
2. Bootstrap project structure
|
### What “good” looks like
|
||||||
- Create a Rust CLI app with modules for `collectors`, `ui`, `state`, and `config`.
|
- **Instant readability**: at-a-glance totals + per-core detail without toggles.
|
||||||
- Add dependencies: `ratatui`, `crossterm`, `sysinfo`, `anyhow`, `clap`, `serde` (optional config).
|
- **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
|
### Core metrics (MVP+)
|
||||||
- Build a polling engine (e.g., 500ms–1s interval) that samples resource metrics.
|
- CPU: **total + per-core bars**, load averages, process count.
|
||||||
- Normalize all values into a shared state model for UI rendering.
|
- Memory: used/total **bar**, swap used/total **bar**.
|
||||||
- Add delta-based metrics (network/disk rates) from successive samples.
|
- 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
|
## Architecture
|
||||||
- Keybindings: quit, pause/resume, change refresh interval, toggle detailed view.
|
|
||||||
- Optional sorting/filtering for top processes view.
|
|
||||||
|
|
||||||
6. Packaging and self-contained build
|
### Modules
|
||||||
- Configure release profile (`lto`, `panic=abort`, `strip`) for small fast binary.
|
- `collectors/`: system sampling + delta/rate calculations (network rates, etc).
|
||||||
- Document build command for optimized executable.
|
- `state/`: normalized app state for rendering (no sysinfo types in UI).
|
||||||
- Optional: static linking strategy for fully portable Linux binary.
|
- `ui/`: layout + widgets (bars, tables, header/footer).
|
||||||
|
- `input/`: keybindings + focus handling.
|
||||||
|
- `config/`: CLI flags + optional persisted config.
|
||||||
|
|
||||||
7. Quality gates
|
### Data model notes
|
||||||
- Unit tests for metric calculations and rate/delta logic.
|
- 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.
|
- 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).
|
|
||||||
|
|||||||
Reference in New Issue
Block a user