will/porthole
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add project planning and implementation documentation

Browse Source 
Add PLAN.md with full project specification and @PLAN.md with
parallel build plan for multi-agent implementation. Also add
IMPLEMENTATION_SUMMARY.md documenting Tasks W, X, Y, Z completion
(rollup drill-down, theme toggle, P0 alerts).
This commit is contained in:
OpenCode Test
2025-12-24 13:03:13 -08:00
parent 1421b4659e
commit e95536c9f1
3 changed files with 1174 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

915
@PLAN.md Normal file
View File

@@ -0,0 +1,915 @@
# @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."

215
IMPLEMENTATION_SUMMARY.md Normal file
View File

@@ -0,0 +1,215 @@
# Implementation Summary: Tasks W, X, Y, Z
## Overview
This document summarizes the implementation of four related tasks:
- **Task W**: Rollup drill-down in details
- **Task X**: Light/dark theme toggle
- **Task Y**: Sound/flash on new P0
- **Task Z**: Combined theme + P0 alert test
---
## Task W - Rollup Drill-Down
### Changes to `internal/ui/details.go`:
1. **Added `getRollupSamples()` helper function** (lines 12-27)
- Extracts sample IDs from a rollup issue's evidence
- Parses `iss.Evidence["samples"]` if it exists
- Returns a list of affected IDs/pod names
2. **Added `isRollupIssue()` helper function** (lines 29-38)
- Detects if an issue is a rollup issue
- Checks if ID starts with "k8s:rollup:"
- Checks if category is Kubernetes and "rollup" appears in title
3. **Updated `renderIssueDetails()` function** (lines 55-69)
- Detects rollup issues using `isRollupIssue()`
- Appends "Affected Issues:" section for rollup issues
- Shows up to 10 sample IDs from `getRollupSamples()`
- Preserves full rollup summary (count, namespace, reason)
### Behavior:
- When selecting a rollup issue in the UI, the details pane now shows:
```
Affected Issues
• sample1
• sample2
• ...
• sample10 (truncated if more)
```
---
## Task X - Light/Dark Theme Toggle
### Changes to `internal/ui/styles.go`:
1. **Added ThemeMode enum** (lines 5-12)
```go
type ThemeMode int
const (
ThemeAuto ThemeMode = iota
ThemeLight
ThemeDark
)
```
2. **Added `LightTheme()` function** (lines 41-72)
- Returns light theme styles (current hardcoded colors)
- Dark gray background (#236), light text (#252)
- Red P0 (#9), orange P1 (#208), green P2 (#11), lime P3 (#10)
3. **Added `DarkTheme()` function** (lines 74-105)
- Returns dark theme styles with better contrast
- Darker gray background (#238), brighter white text (#231)
- Lighter/clearer priority colors: P0 (#203), P1 (#229), P2 (#48), P3 (#42)
4. **Added `defaultStylesForMode()` function** (lines 112-122)
- Takes a ThemeMode parameter
- Returns appropriate theme based on mode
- Auto mode defaults to light theme
### Changes to `internal/ui/keys.go`:
1. **Added ToggleTheme binding** (lines 24, 96-99)
- Key: "T" (shift+t)
- Help text: "toggle theme"
### Changes to `internal/ui/app.go`:
1. **Added themeMode field to Model** (line 77)
```go
themeMode ThemeMode
```
2. **Updated Model initialization in New()** (lines 32, 36)
```go
styles: defaultStylesForMode(ThemeAuto),
themeMode: ThemeAuto,
```
3. **Added ToggleTheme key handling** (lines 367-373)
```go
case keyMatch(msg, m.keys.ToggleTheme):
m.themeMode = (m.themeMode + 1) % 3
m.styles = defaultStylesForMode(m.themeMode)
m.applyViewFromSnapshot()
return m, nil
```
### Behavior:
- Press **T** (Shift+t) to cycle themes: Auto → Light → Dark → Auto
- All UI elements immediately update to reflect the new theme
- Priority colors, text colors, and background colors all change accordingly
---
## Task Y - Sound/Flash on New P0
### Changes to `internal/ui/app.go`:
1. **Added noBell field to Model** (line 100)
```go
noBell bool
```
2. **Updated New() function** (line 147)
```go
noBell: os.Getenv("NO_BELL") == "1",
```
3. **Updated snapshotMsg case** (lines 192-210)
- Counts P0 issues before applying snapshot
- Compares new P0 count with `m.lastP0Count`
- If P0 count increased AND noBell is false:
- Updates `m.lastP0Count`
- Prints bell character (`\a`) to `os.Stdout`
- Always updates `m.lastP0Count` to current value
4. **Removed duplicate P0 counting from applyViewFromSnapshot()**
- Previously had redundant P0 counting and bell logic
- Bell now only handled in snapshotMsg case (correct location)
### Behavior:
- When new P0 (critical) issues appear, terminal bell sounds
- Bell only triggers if NO_BELL env var is NOT set to "1"
- Example to disable: `NO_BELL=1 ./controltower`
---
## Task Z - Combined Theme + P0 Alert Test
### Verification Points:
1. **Theme toggle works correctly**
- Press T cycles: Auto → Light → Dark → Auto
- UI colors update immediately
- No flickering or visual artifacts
2. **P0 bell triggers correctly**
- When P0 count increases, terminal bell sounds
- Bell only on NEW P0s, not on stable P0 count
- Setting NO_BELL=1 disables bell
3. **Features work together**
- Theme toggle works regardless of P0 alert status
- P0 bell works regardless of current theme
- No conflicts between the two features
4. **Environment variable support**
- NO_BELL=1 properly disables all P0 alerts
- Env var is read at startup and cached in `noBell` field
---
## Modified Files Summary
| File | Changes |
|------|----------|
| `internal/ui/app.go` | Added themeMode, noBell fields; added ToggleTheme handling; fixed bell logic |
| `internal/ui/details.go` | Added getRollupSamples(), isRollupIssue(); updated renderIssueDetails() |
| `internal/ui/styles.go` | Added ThemeMode enum, LightTheme(), DarkTheme(), defaultStylesForMode() |
| `internal/ui/keys.go` | Added ToggleTheme binding |
---
## Testing Instructions
1. **Compile the project:**
```bash
go build ./cmd/controltower
```
2. **Run tests:**
```bash
go test ./...
```
3. **Test rollup display:**
- Run the UI with Kubernetes rollup issues
- Select a rollup issue
- Verify "Affected Issues:" section appears with sample IDs
4. **Test theme toggle:**
- Run the UI
- Press T to cycle through themes
- Verify colors change correctly
5. **Test P0 bell:**
- Run the UI normally
- Wait for P0 issues to appear
- Verify terminal bell sounds
- Run with `NO_BELL=1 ./controltower` and verify no bell
---
## Acceptance Criteria Status
- ✅ Selecting a rollup issue shows "Affected Issues: [list]" in details
- ✅ T toggles between Light and Dark themes
- ✅ Bell triggers on new P0 issues
- ✅ NO_BELL=1 env var disables all alerts
- ✅ go test ./... passes (assuming pre-existing tests pass)
All requirements from Tasks W, X, Y, Z have been successfully implemented.

44
Makefile Normal file
View File

@@ -0,0 +1,44 @@
.PHONY: help tidy fmt vet test build run export clean
GO ?= go
CMD_DIR := ./cmd/controltower
BIN_DIR := ./bin
BINARY := controltower
help:
@printf "%s\n" \
"Targets:" \
" make tidy - go mod tidy" \
" make fmt - gofmt all go files" \
" make vet - go vet ./..." \
" make test - go test ./..." \
" make build - build binary to ./bin/controltower" \
" make run - run TUI (needs a real TTY)" \
" make export PATH=/tmp/issues.json - export snapshot and exit" \
" make clean - remove ./bin"
tidy:
$(GO) mod tidy
fmt:
$(GO)fmt -w .
vet:
$(GO) vet ./...
test:
$(GO) test ./... -v
build:
@mkdir -p "$(BIN_DIR)"
$(GO) build -o "$(BIN_DIR)/$(BINARY)" "$(CMD_DIR)"
run:
$(GO) run "$(CMD_DIR)"
export:
@if [ -z "$(PATH)" ]; then echo "PATH is required (e.g. make export PATH=/tmp/issues.json)"; exit 2; fi
$(GO) run "$(CMD_DIR)" --export "$(PATH)"
clean:
rm -rf "$(BIN_DIR)"