diff --git a/@PLAN.md b/@PLAN.md deleted file mode 100644 index d207203..0000000 --- a/@PLAN.md +++ /dev/null @@ -1,915 +0,0 @@ -# @PLAN — ControlTower (Go TUI) parallel build plan - -This file breaks the project into **independent, parallel tasks** that multiple agents can implement with minimal merge conflicts. - -- Source spec: `PLAN.md` -- **Sub-agent models to use:** - - `anthropic/claude-haiku-4-5-20251001` - - `github-copilot/claude-haiku-4.5` - -## 0) Ground rules (so work composes cleanly) - -### 0.1 File ownership -Each task below “owns” a set of files. Agents should **only modify files they own**, except for the explicit shared-contract files listed next. - -### 0.2 Shared contracts (edit carefully) -These files are the primary integration points; keep them stable and coordinate changes: - -- `internal/model/issue.go` (Issue model + enums) -- `internal/collectors/collector.go` (collector interface + status) -- `cmd/controltower/main.go` (wiring + flags) - -### 0.3 Go module + imports -- Use standard package layout from `PLAN.md`. -- No persistence; acknowledgements are in-memory only. -- Prefer small packages with narrow responsibilities. - -## 1) Proposed repo layout (target) - -- `cmd/controltower/main.go` -- `internal/model/` (Issue + enums) -- `internal/store/` (IssueStore) -- `internal/engine/` (scheduler + concurrency) -- `internal/collectors/collector.go` (shared interface) -- `internal/collectors/host/` (`disk.go`, `mem.go`, `load.go`, `net.go`) -- `internal/collectors/k8s/` (`client.go`, `informers.go`, `issues_*.go`, `rollup.go`, `unreachable.go`) -- `internal/ui/` (`app.go`, `table.go`, `details.go`, `keys.go`, `styles.go`) -- `internal/export/json.go` - -## 2) Integration contracts (must align across tasks) - -### 2.1 Issue model contract -`internal/model.Issue` must support (per `PLAN.md`): - -- Stable `ID` for dedupe -- `Category`, `Priority`, `State` enums -- `Title`, `Details`, `Evidence` (key/value), `SuggestedFix` -- `FirstSeen`, `LastSeen` - -Sorting defaults: -- `Priority` desc → `LastSeen` desc (recency) - -### 2.2 Collector contract -Create `internal/collectors/collector.go` with: - -- `type Collector interface { Name() string; Interval() time.Duration; Collect(ctx context.Context) ([]model.Issue, Status, error) }` -- `type Status` describing health (OK/Degraded/Error + message + last success time) - -Collectors should: -- Be fast; respect context cancellation. -- Return issues that are “currently true” for this tick (the store handles resolve-after). - -### 2.3 Store contract -`IssueStore.Upsert(now, issues)`: -- Dedupes by `Issue.ID` -- Tracks `FirstSeen`/`LastSeen` -- Maintains `State` (Open/Acknowledged/Resolved) -- Resolves only after `resolveAfter` (default 30s) of absence - -Ack/unack should be in-memory and keyed by Issue ID. - -### 2.4 Engine contract -Engine runs all collectors concurrently on their intervals with timeouts: - -- Host collectors: `collector_timeout_fast` (250ms) -- K8s list/poll: `collector_timeout_k8s_list` (2s) - -Engine produces periodic snapshots for UI/export: -- `[]model.Issue` sorted per default -- Collector health summary (Host OK / K8s OK/DEGRADED) - -## 3) Task breakdown (parallelizable) - -Each task includes: scope, owned files, external dependencies, and acceptance checks. - -### Task A — Project scaffold + wiring (1 agent) -**Goal:** create runnable binary, shared contracts, and minimal plumbing. - -- Owns: - - `go.mod`, `go.sum` - - `cmd/controltower/main.go` - - `internal/collectors/collector.go` - - (Optional) `internal/buildinfo/` or version constants -- Provides: - - CLI flag `--export /path/issues.json` (calls exporter and exits) - - Default config constants (refresh interval 1s, resolveAfter 30s, timeouts) - - K8s enabled only if kubeconfig exists (per spec) -- Must not implement heavy logic from other tasks; stub as needed. - -**Acceptance:** `go test ./...` passes; `go run ./cmd/controltower` starts. - ---- - -### Task B — Core model package (1 agent) -**Goal:** implement the type system used everywhere. - -- Owns: - - `internal/model/issue.go` (+ small helper files if needed) -- Implements: - - Enums: `Category`, `Priority`, `State` (stringers / JSON marshal if needed) - - `Issue` struct + helpers: - - `func (p Priority) Weight() int` (for sorting) - - `func (i Issue) Age(now time.Time) time.Duration` - - `func SortIssuesDefault([]Issue)` -- Evidence representation: `map[string]string` (simple, JSON-friendly). - -**Acceptance:** unit tests for sorting + JSON marshalling (if added). - ---- - -### Task C — IssueStore (1 agent) -**Goal:** dedupe, state transitions, resolve-after, flap suppression. - -- Owns: - - `internal/store/store.go` - - `internal/store/store_test.go` -- Needs: - - `resolveAfter` default 30s - - Flap suppression: don’t resolve on a single missed tick - - `Acknowledge(id)`, `Unack(id)` (in-memory only) - - `Snapshot()` returning issues (optionally copy to avoid races) - -**Acceptance:** tests covering: -- Dedup and timestamp updates -- Ack persists while issue present -- Resolve-after triggers only after absence window - ---- - -### Task D — Engine scheduler (1 agent) -**Goal:** concurrency orchestration + snapshot publication. - -- Owns: - - `internal/engine/engine.go` - - `internal/engine/engine_test.go` -- Integrates: - - Collectors from Task E (host) and Task F (k8s) - - Store from Task C - - Produces: - - periodic snapshots (channel or callback) for UI - - immediate refresh on demand (key `r`) -- Concurrency: - - Run collectors on their own tickers - - Per-collector context timeouts - - Track last error/health per collector - -**Acceptance:** deterministic tests with fake collectors verifying: -- timeout handling -- interval scheduling -- merge/upsert calls - ---- - -### Task E — Host collectors MVP (1–2 agents) -Split into sub-tasks to avoid conflicts: - -#### E1 Disk collector -- Owns: `internal/collectors/host/disk.go` (+ tests) -- Reads `/proc/mounts`, uses `statfs`. -- Filters pseudo filesystems. -- Thresholds: - - `P1` if usage or inode usage ≥ 92% - - `P0` if ≥ 98% - -#### E2 Memory + swap collector -- Owns: `internal/collectors/host/mem.go` (+ tests) -- Reads `/proc/meminfo`. -- Applies thresholds in `PLAN.md`. - -#### E3 Load collector -- Owns: `internal/collectors/host/load.go` (+ tests) -- Reads `/proc/loadavg` + CPU count. -- Sustained windows: track 120s rolling window. - -#### E4 Network collector -- Owns: `internal/collectors/host/net.go` (+ tests) -- Reads `/proc/net/route` for default route. -- Reads `/sys/class/net/*/operstate` for “any UP”. -- `P1` if no default route AND any non-loopback UP. - -**Acceptance:** each collector has unit tests using fixture files or temp fakes. - ---- - -### Task F — Kubernetes collector MVP (2 agents recommended) -This is the largest area; split by responsibility. - -#### F1 K8s client + connectivity + unreachable grace -- Owns: - - `internal/collectors/k8s/client.go` - - `internal/collectors/k8s/unreachable.go` -- Responsibilities: - - Build client-go config from kubeconfig current context. - - Connectivity tracking: emit `Kubernetes/P0` only after **10s continuous failure**. - - RBAC errors: emit single `P2` “Insufficient RBAC …” issue per resource. - -#### F2 Informers / polling fallback + issue rules + rollups -- Owns: - - `internal/collectors/k8s/informers.go` - - `internal/collectors/k8s/issues_pods.go` - - `internal/collectors/k8s/issues_nodes.go` - - `internal/collectors/k8s/issues_workloads.go` - - `internal/collectors/k8s/issues_events.go` - - `internal/collectors/k8s/rollup.go` -- Responsibilities: - - Prefer informers (LIST+WATCH caches). - - If watch fails repeatedly, degrade to periodic LIST and emit a `P1` degraded issue. - - High-signal rules per `PLAN.md`. - - Rollups: - - group by `(namespace, reason, kind)` - - if group size ≥ 20 emit rollup issue with samples - - Cap: `k8s.max_issues = 200` after rollups. - -**Acceptance:** -- Unit tests for rule functions (pure logic tests with fake objects) -- Manual run against a cluster (optional) verifies unreachable grace. - ---- - -### Task G — Bubble Tea TUI (2 agents recommended) -Split UI work to reduce merge conflicts. - -#### G1 App model + layout framing -- Owns: - - `internal/ui/app.go` - - `internal/ui/styles.go` -- Responsibilities: - - Header bar (host/time/age/P0..P3 counts/collector health) - - Layout: header + table + details pane - - Wiring to engine snapshot updates (tea.Msg) - -#### G2 Table + details + keybindings -- Owns: - - `internal/ui/table.go` - - `internal/ui/details.go` - - `internal/ui/keys.go` -- Responsibilities: - - Main table columns: `Pri | Cat | Title | Age | State` - - Search `/`, filter `p`/`c`, sort `s`, focus `tab` - - Ack/unack `a` - - Optional: Expand details with `enter` - -**Acceptance:** -- UI runs and remains responsive with 1k synthetic issues. - ---- - -### Task H — Exporter (1 agent) -**Goal:** JSON snapshot export, no persistence. - -- Owns: - - `internal/export/json.go` -- Implements: - - `WriteIssues(path string, issues []model.Issue) error` - - Used by `--export` and (optional) UI hotkey `E` - -**Acceptance:** `--export` writes valid JSON and exits 0. - ---- - -### Task I — End-to-end integration pass (1 agent) -**Goal:** compose all pieces, fix mismatches, and ensure acceptance criteria. - -- Owns (only light edits across packages): - - small wiring fixes in `cmd/controltower/main.go` - - integration tweaks in engine/UI -- Validates: - - Without kubeconfig: app runs, host collectors work - - With kubeconfig but unreachable cluster: `P0` appears only after 10s - - With reachable cluster: issues populate; rollups protect UI - -## 4) 8-agent assignment (recommended) - -This assignment uses exactly **8 agents** and keeps overlaps minimal. For each agent, you can use either model: -- `anthropic/claude-haiku-4-5-20251001` -- `github-copilot/claude-haiku-4.5` - -**Phase 1 (parallel, no blocking):** Agents 1–6 -- **Agent 1 (Scaffold/contracts):** Task A -- **Agent 2 (Model):** Task B -- **Agent 3 (Store):** Task C -- **Agent 4 (Engine):** Task D -- **Agent 5 (Host collectors):** Task E1–E4 (own all `internal/collectors/host/*`) -- **Agent 6 (Exporter):** Task H - -**Phase 2 (parallel, after A+B exist):** Agents 7–8 -- **Agent 7 (Kubernetes collector):** Task F1 + F2 (own all `internal/collectors/k8s/*`) -- **Agent 8 (TUI + integration):** Task G1 + G2 + Task I (UI owns `internal/ui/*`; integration touches wiring only) - -Notes: -- Agent 5 is bundled intentionally to avoid conflicts in `internal/collectors/host/`. -- K8s (Agent 7) is bundled intentionally to avoid informer/client contract churn. -- UI + integration (Agent 8) is bundled so UI/engine message types stay aligned. - -**Start order (min waiting):** -- Start Agents **1–6** immediately. -- Start Agents **7–8** once Agent 1 has created `go.mod` + `internal/collectors/collector.go` and Agent 2 has created `internal/model/issue.go` (so imports compile). - -**Merge order (min conflicts / keep build green):** -1) Agent 1 (scaffold/contracts) — establishes module + shared interfaces -2) Agent 2 (model) — unblocks compilation for most packages -3) Agent 3 (store) + Agent 6 (export) — mostly isolated, compile-time checks -4) Agent 4 (engine) — depends on store/model/contracts -5) Agent 5 (host collectors) — depends on model/contracts; can land anytime after (1,2) -6) Agent 7 (k8s) — depends on model/contracts; may need go.sum updates -7) Agent 8 (UI + integration) — land last; touches wiring and stabilizes API edges - -**If you use a single shared branch:** -- Prefer merging frequently in the above order and rebasing lagging work onto the latest `main`. -- If a shared contract must change, have Agent 1 do the change and notify all other agents. - -## 5) Suggested agent prompts (copy/paste) - -Use each prompt with model `anthropic/claude-haiku-4-5-20251001` or `github-copilot/claude-haiku-4.5`. - -### Prompt template -- Implement only the task scope. -- Touch only owned files. -- Add small unit tests where indicated. -- Keep APIs aligned with the shared contracts. - -#### Agent prompt: Task B (model) -"Implement `internal/model/issue.go` per @PLAN.md §2.1. Add sorting helpers and minimal tests. Do not modify other packages." - -#### Agent prompt: Task C (store) -"Implement `internal/store` IssueStore with dedupe, ack/unack, resolve-after (30s), flap suppression, and tests. Import and use `internal/model`." - -#### Agent prompt: Task D (engine) -"Implement `internal/engine` scheduler running collectors concurrently with per-collector timeouts and health tracking. Provide snapshot publication for UI; add tests with fake collectors." - -#### Agent prompt: Task E1–E4 (host collectors) -"Implement the specified host collector in `internal/collectors/host/*.go` reading Linux proc/sys files as described. Emit Issues with correct IDs/evidence/priority and add small tests using fixtures/mocks." - -#### Agent prompt: Task F1 (k8s base) -"Implement kubeconfig client creation and unreachable grace logic. Emit a single P0 issue only after 10s continuous failure; emit P2 on RBAC denial. Keep rule logic separate." - -#### Agent prompt: Task F2 (k8s rules + rollups) -"Implement informer/polling collector and rule + rollup logic with caps. Keep rule functions testable. Coordinate only via shared contracts." - -#### Agent prompt: Task G1/G2 (UI) -"Implement Bubble Tea UI pieces per @PLAN.md: header/table/details/keybindings. Subscribe to engine snapshots and keep rendering cheap." - -#### Agent prompt: Task H (export) -"Implement JSON exporter used by `--export` and optional UI hotkey. Ensure output includes all Issue fields." - -#### Agent prompt: Task I (integration) -"Integrate all packages, resolve API mismatches, and verify acceptance scenarios. Keep changes minimal and avoid refactors." - -#### Agent prompt: Task J (Help overlay) -"Implement in-app help overlay showing all keybindings. Add `?` key binding in keys.go and create help.go with overlay model and render logic." - -#### Agent prompt: Task K (Direct priority jump) -"Add numeric bindings `0`/`1`/`2`/`3` to jump directly to P0/P1/P2/P3 filter. Keep `p` cycle for `all`." - -#### Agent prompt: Task L (Visual filter indicators) -"Add highlighted style for active filters in header. Apply FilterActive style when pri= or cat= are set." - -#### Agent prompt: Task M (Better empty state) -"Show friendly message 'All systems healthy' when no issues instead of just 'No issues'." - -#### Agent prompt: Task N (Bulk ack all visible) -"Add `A` key to acknowledge all currently visible issues at once. Optimize updates and refresh counts." - -#### Agent prompt: Task O (Page navigation) -"Document page up/down keys already supported by bubbles/table. Ensure they work correctly in Update handler." - -#### Agent prompt: Task P (Home/End jump) -"Add `g`/`G` bindings to jump to first/last row quickly like vim/less." - -#### Agent prompt: Task Q (Vi-style nav) -"Add `j`/`k` bindings as alternatives to arrow keys for down/up navigation." - -#### Agent prompt: Task R (Collector health icons) -"Replace text 'ok=1 deg=0 err=Z' with visual icons (✓ ⚠ ✗). Use lipgloss styles." - -#### Agent prompt: Task S (Issue count warning near cap) -"Add warning indicator in header when approaching 200-issue cap (show at >= 180)." - -#### Agent prompt: Task T (Copy to clipboard) -"Add `y` key to copy SuggestedFix (or Title) to system clipboard. Add atotto/clipboard dependency." - -#### Agent prompt: Task U (Dynamic column width) -"Add `t` key to toggle between compact and wide Title column widths for long issue titles." - -#### Agent prompt: Task V (Age format toggle) -"Add `d` key to toggle between compact (2dm) and relative (2m ago) age formats." - -#### Agent prompt: Task W (Rollup drill-down) -"When rollup issue selected, show 'Affected Issues' list with sample IDs in details pane." - -#### Agent prompt: Task X (Light/dark theme toggle) -"Add `T` key to toggle between light and dark themes. Define two theme sets in styles.go." - -#### Agent prompt: Task Y (Sound/flash on new P0) -"Add terminal bell/flash when P0 count increases (new critical issue detected). Respect NO_BELL env var." - -#### Agent prompt: Task Z (Theme, sound, flash) -"Add theme toggle (`T`) and P0 alert (bell/flash) with env var support. Test with `NO_BELL=1`." - -## 6) Definition of done - -- Meets `PLAN.md` Acceptance Criteria. -- `go test ./...` passes. -- `go run ./cmd/controltower` works without kubeconfig. -- With kubeconfig and unreachable cluster: `P0` only after 10s. -- UI remains responsive under high issue counts (rollups + caps). - -## 7) TUI UX Improvements - -This section defines UX enhancements that improve discoverability, navigation efficiency, and visual clarity. Tasks are designed for **parallel agent execution** (independent file ownership). - -### 7.1 Quick wins (high-impact, low-effort) - -#### Task J — Help overlay -**Goal:** Users can discover all keybindings in-app without external docs. - -**Agent:** 1 (can be same agent that implements Task J in Phase 2) - -**Owned files:** -- `internal/ui/help.go` (new) -- `internal/ui/keys.go` (add `Help` binding, update prompts) -- `internal/ui/app.go` (add help model + view routing) - -**Implementation:** -- Add `Help` key binding (`?`) to `KeyMap` -- Create `help.go` with a `Model` struct: - - List of keybindings by group (Global, Filters, Navigation, Actions) - - `render()` function to display as overlay -- Add `helpRequestedMsg` type in `app.go` to trigger help overlay -- Update `keys.go`: add `Help` binding with help text -- Update `app.go`: - - Add `showHelp bool` field to Model - - Handle `?` key: toggle help overlay (hide table/details) - - Update `View()` to conditionally show help instead of main layout - -**Acceptance:** -- Press `?` shows keybinding list overlay covering main layout -- Press `?` again or `esc` dismisses help -- `go test ./...` passes - ---- - -#### Task K — Direct priority jump (`0`/`1`/`2`/`3`) -**Goal:** Jump directly to P0/P1/P2/P3 filter instead of cycling through all 5 options. - -**Agent:** 1 - -**Owned files:** -- `internal/ui/keys.go` (add numeric bindings) -- `internal/ui/app.go` (update Update handler) - -**Implementation:** -- Add bindings in `keys.go`: - - `PriorityP0: key.NewBinding(key.WithKeys("0"), key.WithHelp("0", "P0 only"))` - - `PriorityP1: key.NewBinding(key.WithKeys("1"), key.WithHelp("1", "P1 only"))` - - `PriorityP2: key.NewBinding(key.WithKeys("2"), key.WithHelp("2", "P2 only"))` - - `PriorityP3: key.NewBinding(key.WithKeys("3"), key.WithHelp("3", "P3 only"))` -- Update `app.go` Update handler: - - Match `keyMatch(msg, m.keys.PriorityP0)` → set `m.filterPri = model.PriorityP0` - - Match `keyMatch(msg, m.keys.PriorityP1)` → set `m.filterPri = model.PriorityP1` - - Match `keyMatch(msg, m.keys.PriorityP2)` → set `m.filterPri = model.PriorityP2` - - Match `keyMatch(msg, m.keys.PriorityP3)` → set `m.filterPri = model.PriorityP3` - - Keep existing `p` cycle behavior for `all` option - -**Acceptance:** -- Pressing `0` shows only P0 issues; `1` shows only P1, etc. -- Pressing `p` cycles through: all → P0 → P1 → P2 → P3 → all → … - ---- - -#### Task L — Visual filter indicators -**Goal:** Make active filters visually obvious in header (highlight vs. plain text). - -**Agent:** 1 - -**Owned files:** -- `internal/ui/styles.go` (add filter highlight style) -- `internal/ui/app.go` (update `renderHeader()`) - -**Implementation:** -- Add style in `styles.go`: - - `FilterActive lipgloss.Style` (e.g., bold + distinct foreground) -- Update `renderHeader()` in `app.go`: - - Apply `FilterActive` style to `pri=` or `cat=` portions when filter is active - - Keep `all` in plain `HeaderVal` style - -**Acceptance:** -- `pri=P1` or `cat=Kubernetes` appears highlighted/colored in header -- `pri=all` or `cat=all` appears in plain text - ---- - -#### Task M — Better empty state -**Goal:** When no issues, show helpful message instead of just “No issues”. - -**Agent:** 1 - -**Owned files:** -- `internal/ui/app.go` (update `applyViewFromSnapshot()`) - -**Implementation:** -- In `applyViewFromSnapshot()` (around row building), when `len(filtered) == 0`: - - Set details content to friendly message: “All systems healthy. No issues detected.” - - Optionally: add hint like “Press `r` to refresh, `/` to search past logs” - -**Acceptance:** -- When snapshot has 0 issues, details pane shows friendly message -- Header still displays correct P0/P1/P2/P3 counts (all 0) - ---- - -#### Task N — Bulk ack all visible -**Goal:** Allow user to acknowledge all currently visible issues at once. - -**Agent:** 1 - -**Owned files:** -- `internal/ui/keys.go` (add bulk ack binding) -- `internal/ui/app.go` (add `AckAllVisible()` method + handler) - -**Implementation:** -- Add binding in `keys.go`: - - `AckAll: key.NewBinding(key.WithKeys("A"), key.WithHelp("A", "ack all visible"))` (shift+a) -- Add method in `app.go`: - - `func (m *Model) AckAllVisible()` - - Iterate over `m.rowsIDs`, call `m.ack(id)` for each - - Optimistically update `issueByID` and table rows -- Update `Update()` handler: - - Match `keyMatch(msg, m.keys.AckAll)` → call `m.AckAllVisible()` - -**Acceptance:** -- Pressing `A` acknowledges all issues currently visible in table -- Header P0/P1/P2/P3 counts remain correct -- `a` still toggles ack/unack for single selected issue - ---- - -### 7.2 Navigation efficiency improvements - -#### Task O — Page navigation (`PgUp`/`PgDn` or `Ctrl+u`/`Ctrl+d`) -**Goal:** Faster scrolling through long issue lists (200+ issues with rollups). - -**Agent:** 1 - -**Owned files:** -- `internal/ui/table.go` (no changes needed; bubbles/table supports page keys by default) - -**Implementation:** -- Bubbles/table already supports standard page keys: - - `pgup`/`pgdn` - - `ctrl+u`/`ctrl+d` - - `home`/`end` -- Ensure these are not overridden in `app.go` Update handler -- Optionally: update help overlay to document these keys - -**Acceptance:** -- PageUp/PageDown jumps 10 rows in table -- Ctrl+u/Ctrl+d jumps half a screen -- Home/End jump to top/bottom - ---- - -#### Task P — Home/End jump (`g`/`G` like vim/less) -**Goal:** Jump to first or last row quickly. - -**Agent:** 1 - -**Owned files:** -- `internal/ui/keys.go` (add bindings) -- `internal/ui/app.go` (add handlers) - -**Implementation:** -- Add bindings in `keys.go`: - - `JumpToTop: key.NewBinding(key.WithKeys("g"), key.WithHelp("g", "jump to first"))` - - `JumpToBottom: key.NewBinding(key.WithKeys("G"), key.WithHelp("G", "jump to last"))` -- Update `app.go`: - - Handle `JumpToTop` → set cursor to 0 - - Handle `JumpToBottom` → set cursor to last row - -**Acceptance:** -- Pressing `g` moves selection to first visible row -- Pressing `G` moves selection to last visible row - ---- - -#### Task Q — Vi-style nav (`j`/`k` in addition to arrows) -**Goal:** Support vim-style navigation for users who prefer hjkl. - -**Agent:** 1 - -**Owned files:** -- `internal/ui/keys.go` (add bindings) -- `internal/ui/app.go` (add handlers) - -**Implementation:** -- Add bindings in `keys.go`: - - `Down: key.NewBinding(key.WithKeys("j"), key.WithHelp("j", "down"))` - - `Up: key.NewBinding(key.WithKeys("k"), key.WithHelp("k", "up"))` -- Update `app.go`: - - Match `Down` and pass to `m.table.Update(msg)` (bubbles/table handles both arrows and j/k) -- Update help overlay to document `j`/`k` as alternatives to arrows - -**Acceptance:** -- `j` moves selection down, `k` moves up -- Arrows continue to work (both styles supported) - ---- - -### 7.3 Visual polish & feedback - -#### Task R — Collector health icons -**Goal:** Replace text “ok=1 deg=0 err=Z” with visual status icons. - -**Agent:** 1 - -**Owned files:** -- `internal/ui/app.go` (update `renderHeader()`) -- `internal/ui/styles.go` (add icon styles if desired) - -**Implementation:** -- Update `renderHeader()` health display: - - Use icon instead of text: - - `✓` for OK - - `⚠` for DEGRADED - - `✗` for ERROR - - Format: `collectors: ✓1 ⚠0 ✗0` -- Optional: use `lipgloss.SetGlyphWidth()` if icons appear misaligned - -**Acceptance:** -- Header shows icon-based collector health (e.g., `collectors: ✓4`) -- Status still readable for screen readers (icons are supplementary) - ---- - -#### Task S — Issue count warning near cap -**Goal:** Warn users when approaching the 200-issue cap (after rollups). - -**Agent:** 1 - -**Owned files:** -- `internal/ui/app.go` (update `renderHeader()`) - -**Implementation:** -- In `renderHeader()`, calculate total issues: `total := p0 + p1 + p2 + p3` -- If `total >= 180` (90% of cap): - - Append warning text to collector health line: ` [~180/200]` - - Use warning color from `styles.Error` -- Only show when near cap; don’t clutter at low counts - -**Acceptance:** -- When near 200 issues, header shows warning indicator -- Below 180 issues, no warning appears - ---- - -#### Task T — Copy to clipboard (`y` on selected issue) -**Goal:** Quick copy of issue ID, Title, or SuggestedFix. - -**Agent:** 1 - -**Owned files:** -- `internal/ui/keys.go` (add binding) -- `internal/ui/app.go` (add handler + clipboard dep if needed) -- `go.mod` (add clipboard dependency) - -**Implementation:** -- Add binding in `keys.go`: - - `Copy: key.NewBinding(key.WithKeys("y"), key.WithHelp("y", "copy to clipboard"))` -- Add dependency in `go.mod` (pick one): - - `github.com/atotto/clipboard` (cross-platform, widely used) - - or use xclip/xsel via `exec.Command` for linux-only (no new dep) -- Update `app.go`: - - On `y` key, copy selected issue’s `SuggestedFix` to clipboard (most useful field) - - Show brief confirmation in details pane: “Copied to clipboard” - -**Acceptance:** -- Pressing `y` copies SuggestedFix (or Title) to system clipboard -- Brief confirmation shown in details pane - ---- - -### 7.4 Nice-to-have (higher effort) - -#### Task U — Dynamic column width -**Goal:** Allow widening Title column on demand for long issue titles. - -**Agent:** 1 - -**Owned files:** -- `internal/ui/keys.go` (add toggle binding) -- `internal/ui/app.go` (add `wideTitle` state + update layout()) - -**Implementation:** -- Add binding in `keys.go`: - - `ToggleWideTitle: key.NewBinding(key.WithKeys("t"), key.WithHelp("t", "toggle wide title"))` -- Add `wideTitle bool` field to Model -- Update `layout()` to compute two widths: - - Normal mode: compact Title width (current behavior) - - Wide mode: allocate more space to Title column -- On `t` toggle, recompute layout and rebuild rows - -**Acceptance:** -- Pressing `t` expands Title column -- Pressing `t` again returns to compact width -- Header shows current state (e.g., `wide=on` or icon) - ---- - -#### Task V — Age format toggle (compact vs. “X ago”) -**Goal:** Switch between “2dm” (compact) and “2m ago” (relative) formats. - -**Agent:** 1 - -**Owned files:** -- `internal/ui/keys.go` (add toggle binding) -- `internal/ui/app.go` (add `ageMode` field + update rendering) - -**Implementation:** -- Add binding in `keys.go`: - - `ToggleAgeFormat: key.NewBinding(key.WithKeys("d"), key.WithHelp("d", "toggle age format"))` -- Add `ageMode AgeMode` field to Model with values: `AgeCompact` (default), `AgeRelative` -- Update `table.go` `formatAge()` or `app.go` wrapper to support both modes -- In `renderHeader()`, keep compact age (0s, Xds, Xdm, Xdh, Xdd) -- In details pane, show full time with relative suffix - -**Acceptance:** -- Default: table shows `2dm`, details shows “2m ago” -- Press `d`: table shows `2m ago`, details show same -- Press `d` again: revert to compact - ---- - -#### Task W — Rollup drill-down in details -**Goal:** When a rollup issue is selected, show the individual issues it aggregates. - -**Agent:** 1 - -**Owned files:** -- `internal/ui/model` (add rollup-specific types) — or keep minimal -- `internal/ui/app.go` (update `renderIssueDetails()` / `setDetailsToSelected()`) - -**Implementation:** -- Add helper `getRollupSamples(iss model.Issue) []string`: - - Parse `iss.Evidence["samples"]` if it exists - - Return list of affected IDs/pod names -- Update `renderIssueDetails()` in `details.go`: - - Detect rollup (e.g., ID starts with `k8s:rollup:` or category=Kubernetes + “rollup” in title) - - Append section: `Affected Issues` with list of sample IDs (up to 10) -- Keep full rollup summary (count, namespace, reason) - -**Acceptance:** -- Selecting a rollup issue shows “Affected Issues: [k8s:pod:default/x, k8s:pod:default/y, …]” in details -- Non-rollup issues show normal details without this section - ---- - -#### Task X — Light/dark theme toggle -**Goal:** Respect user’s theme preference or allow toggling. - -**Agent:** 1 - -**Owned files:** -- `internal/ui/styles.go` (add theme variants) -- `internal/ui/keys.go` (add toggle binding) -- `internal/ui/app.go` (add theme state) -- `cmd/controltower/main.go` (optional env var support) - -**Implementation:** -- Define two theme sets in `styles.go`: - - `LightTheme` (current hardcoded colors) - - `DarkTheme` (inverted/better contrast) -- Add `themeMode ThemeMode` field to Model (`ThemeAuto`, `ThemeLight`, `ThemeDark`) -- Add binding in `keys.go`: - - `ToggleTheme: key.NewBinding(key.WithKeys("T"), key.WithHelp("T", "toggle theme"))` -- Optional: respect `NO_COLOR=1` env var (disable all colors) -- On theme toggle, update `styles := defaultStyles()` to apply selected theme - -**Acceptance:** -- Default theme is current (light-like) -- Pressing `T` toggles light/dark -- `NO_COLOR=1` disables colors entirely - ---- - -#### Task Y — Sound/flash on new P0 -**Goal:** Alert user when critical issues appear. - -**Agent:** 1 - -**Owned files:** -- `internal/ui/app.go` (track P0 count changes + trigger alert) - -**Implementation:** -- Add `lastP0Count int` field to Model -- In `applyViewFromSnapshot()`: - - Compare `p0` with `m.lastP0Count` - - If `p0 > m.lastP0Count`: new critical issues appeared - - Update `m.lastP0Count = p0` -- Add alert function: - - Use bubbletea’s `bell` (terminal bell) or flash: - - Send `tea.BellMsg` on P0 increase - - Optional: check for `NO_BELL=1` env var to disable - -**Acceptance:** -- When P0 count increases, terminal bell/flash occurs (if not disabled) -- P0 decrease or no change does not trigger alert -- `NO_BELL=1` env var suppresses all alerts - ---- - -### 8-agent assignment for UX tasks - -To keep parallelism and avoid conflicts, assign as follows (can be done in Phase 3): - -| Agent | Tasks | Owned Files | Notes | -|-------|-------|--------------|-------| -| **Agent 9** | Task J (Help overlay) | `internal/ui/help.go`, `keys.go`, `app.go` | High discoverability impact | -| **Agent 10** | Tasks K, L, M (Priority jump, visual filters, empty state) | `keys.go`, `styles.go`, `app.go` | Quick navigation wins | -| **Agent 11** | Tasks N, O, P (Bulk ack, page nav, home/end) | `keys.go`, `app.go` | Nav efficiency | -| **Agent 12** | Tasks Q, R (Vi nav, collector health icons) | `keys.go`, `app.go`, `styles.go` | Nav + visual polish | -| **Agent 13** | Tasks S, T, V (Count warning, copy clipboard, dynamic width) | `keys.go`, `app.go`, `go.mod`, `table.go` | Polish + utility | -| **Agent 14** | Tasks W, X (Rollup drill-down, age toggle) | `app.go`, `details.go`, `keys.go` | Details enhancements | -| **Agent 15** | Tasks Y, Z (Theme, sound/flash) | `styles.go`, `app.go`, `keys.go` | Theme + alerts | - -**Execution order (minimal dependencies):** -1. Agents 9–12 run in parallel (all are independent file changes) -2. Agents 13–14 run after 9–12 (may reference new keys/styles) -3. Agent 15 runs after 13–14 (may reference theme from styles) - - ---- - -### 8-agent assignment (UX improvements, parallel) - -| Agent | Tasks | Owned Files | Notes | -|-------|-------|--------------|-------| -| **Agent 9** | Task J (Help overlay) | `internal/ui/help.go`, `keys.go`, `app.go` | High discoverability impact | -| **Agent 10** | Tasks K, L, M (Priority jump, visual filters, empty state) | `keys.go`, `styles.go`, `app.go` | Quick navigation wins | -| **Agent 11** | Tasks N, O, P (Bulk ack, page nav, home/end) | `keys.go`, `app.go` | Nav efficiency | -| **Agent 12** | Tasks Q, R (Vi nav, collector health icons) | `keys.go`, `app.go`, `styles.go` | Nav + visual polish | -| **Agent 13** | Tasks S, T, V (Count warning, copy clipboard, dynamic width) | `keys.go`, `app.go`, `go.mod`, `table.go` | Polish + utility | -| **Agent 14** | Tasks W, X (Rollup drill-down, age toggle) | `app.go`, `details.go`, `keys.go` | Details enhancements | -| **Agent 15** | Tasks Y, Z (Theme, sound/flash) | `styles.go`, `app.go`, `keys.go` | Theme + alerts | - -**Execution order (minimal dependencies):** -1. Agents 9–12 run in parallel (all are independent file changes) -2. Agents 13–14 run after 9–12 (may reference new keys/styles) -3. Agent 15 runs after 13–14 (may reference theme from styles) - -**Coordinated changes:** -- `keys.go` is shared across Agents 9–15; each agent appends new bindings without removing others. -- `app.go` is shared; each agent adds new handlers in disjoint methods to avoid merge conflicts. -- `styles.go` is shared; agents add new styles without modifying existing. -- `details.go` is shared; Agents 13–14 add optional sections. -- `help.go` is new (Task J) and owned entirely by Agent 9. - -#### Agent prompt: Task J (Help overlay) -"Implement in-app help overlay showing all keybindings. Add `?` key in keys.go, create help.go with Model + render() function. Toggle overlay with `?` key and dismiss with `?` or `esc`." - -#### Agent prompt: Task K (Direct priority jump) -"Add numeric bindings `0`/`1`/`2`/`3` in keys.go to jump directly to P0/P1/P2/P3. Keep `p` cycle for `all` option. Update app.go Update handler." - -#### Agent prompt: Task L (Visual filter indicators) -"Add FilterActive style in styles.go (highlight color). Update renderHeader() to apply when pri= or cat= filters are active." - -#### Agent prompt: Task M (Better empty state) -"Show friendly message 'All systems healthy' in applyViewFromSnapshot() when len(filtered) == 0." - -#### Agent prompt: Task N (Bulk ack all visible) -"Add AckAll binding (shift+a) in keys.go. Implement AckAllVisible() method in app.go that iterates rowsIDs and calls ack(). Update handler." - -#### Agent prompt: Task O (Page navigation) -"Document that bubbles/table supports page keys (pgup/pgdn, ctrl+u/ctrl+d). Ensure they are not overridden in app.go Update handler. Add to help overlay." - -#### Agent prompt: Task P (Home/End jump) -"Add `g`/`G` bindings in keys.go. Add handlers in app.go: `g` sets cursor to 0, `G` sets cursor to last row. Add to help overlay." - -#### Agent prompt: Task Q (Vi-style nav) -"Add `j`/`k` bindings in keys.go. Update app.go to pass to table.Update(); bubbles/table handles both arrows and j/k. Update help overlay." - -#### Agent prompt: Task R (Collector health icons) -"Update renderHeader() to use icons (✓ for OK, ⚠ for DEGRADED, ✗ for ERROR) instead of text. Format: 'collectors: ✓1 ⚠0 ✗0'." - -#### Agent prompt: Task S (Issue count warning near cap) -"In renderHeader(), calculate total issues. If total >= 180, append warning '[~180/200]' with error color. Show only when near cap." - -#### Agent prompt: Task T (Copy to clipboard) -"Add `y` binding in keys.go. Add atotto/clipboard to go.mod. On `y` key, copy selected issue's SuggestedFix to clipboard. Show brief confirmation in details." - -#### Agent prompt: Task U (Dynamic column width) -"Add ToggleWideTitle binding (`t`) in keys.go. Add wideTitle bool to Model. Update layout() to compute wide vs compact widths. Toggle with `t` key. Update help overlay." - -#### Agent prompt: Task V (Age format toggle) -"Add ToggleAgeFormat binding (`d`) in keys.go. Add AgeMode field (Compact/Relative) to Model. Update formatAge() or wrapper in app.go to support both modes. Toggle with `d` key." - -#### Agent prompt: Task W (Rollup drill-down) -"Add getRollupSamples() helper to parse Evidence['samples']. Update renderIssueDetails() in details.go to detect rollup and append 'Affected Issues' section with sample IDs." - -#### Agent prompt: Task X (Light/dark theme toggle) -"Define LightTheme and DarkTheme in styles.go. Add themeMode field to Model with Auto/Light/Dark. Add ToggleTheme binding (`T`) in keys.go. Respect NO_COLOR env var." - -#### Agent prompt: Task Y (Sound/flash on new P0) -"Add lastP0Count to Model. In applyViewFromSnapshot(), compare p0 with lastP0Count. If p0 increases, send bubbletea.BellMsg. Check NO_BELL env var." - -#### Agent prompt: Task Z (Theme, sound, flash) -"Combine Task X (theme toggle) and Task Y (P0 alert). Test theme toggle works and P0 bell/flash. Add env var checks for NO_BELL."