feat: Stage 1 scaffold — config, API client, placeholder TUI

Sets up the full project structure following the hactl/gokapi-tui architecture: strict Elm-pattern Bubbletea TUI, YAML config at ~/.config/terdut-tui/config.yaml, REST API client with Bearer auth, self-update via GitHub Releases, and a three-section tab placeholder (Alerts / Schedule / Users) that verifies server connectivity on startup.
2026-05-21 13:28:13 +02:00
commit 55ee64530b
14 changed files with 849 additions and 0 deletions
@@ -0,0 +1,68 @@
+# terdut-tui
+
+TUI client for [terdut-server](https://github.com/terdut-server), a Prometheus Alertmanager receiver and on-call scheduler.
+
+## Tech stack
+
+- Go 1.25+
+- [Bubbletea](https://github.com/charmbracelet/bubbletea) — TUI framework (strict Elm architecture)
+- [Lipgloss](https://github.com/charmbracelet/lipgloss) — styles (all in `internal/tui/styles.go`, never inline)
+- [Bubbles](https://github.com/charmbracelet/bubbles) — table, textinput, help components
+
+## Project layout
+
+```
+main.go                      CLI entry point: flags, config load, health check, start TUI
+internal/api/client.go       REST API client — one method per endpoint
+internal/config/config.go    Config loader (~/.config/terdut-tui/config.yaml)
+internal/tui/                Bubbletea UI
+  model.go                   Model struct, mode/section constants, Init(), tea.Cmd constructors
+  update.go                  Update() — dispatch only, no API calls inline
+  view.go                    View() — pure rendering
+  keys.go                    keyMap (bubbles/key pattern)
+  styles.go                  All lipgloss styles
+internal/updater/updater.go  Self-update via GitHub Releases
+```
+
+## Architecture rules
+
+1. **Never call API inside `Update()`** — return `tea.Cmd` instead; the runtime runs it async.
+2. **`View()` is pure** — no side effects, no state mutations.
+3. **All state in `Model`** — no globals.
+4. **All styles in `styles.go`** — never use lipgloss inline in `view.go`.
+
+## Config
+
+Location: `~/.config/terdut-tui/config.yaml`
+
+```yaml
+server_url: https://terdut.example.com
+api_key: <64-char hex key>
+refresh_interval: 30  # seconds, optional, default 30
+```
+
+The API key is a one-time secret generated by terdut-server (`POST /api/users/{id}/api-keys`).
+
+## Running
+
+```bash
+go run .
+go run . --version
+go run . --self-update
+```
+
+## Building
+
+```bash
+go build -ldflags="-X main.version=v0.1.0" -o terdut-tui .
+```
+
+## Development stages
+
+| Stage | Feature |
+|-------|---------|
+| 1 | Scaffold, config, health check, placeholder TUI |
+| 2 | Alert dashboard with auto-refresh and stats |
+| 3 | Alert detail: acknowledge, comment, statistics charts |
+| 4 | On-call schedule calendar view |
+| 5 | User management and API key lifecycle |