diff --git a/.cursor/BUGBOT.md b/.cursor/BUGBOT.md deleted file mode 100644 index 6c5e51e..0000000 --- a/.cursor/BUGBOT.md +++ /dev/null @@ -1,6 +0,0 @@ -# Bugbot review guidance -## Autonomy, cross-repo, and history (reviewers) - -- **Autonomy first:** Prefer review feedback that keeps agents unblocked. Ask for repository splits or extra ceremony only when risk truly warrants it. -- **Multi-repo efforts:** A change may be intentionally split across repositories; read the PR body for links to sibling PRs before calling the work incomplete for only touching one repo. -- **Force-push:** Never suggest force-push as a silent or automatic fix. If history rewrite is raised, require clear **user-visible** justification: **why** it is proposed, **blast radius** and effects on others and CI, and why non-destructive options are insufficient—default to safer paths. diff --git a/docs/superpowers/specs/2026-04-19-tui-status-log-export-design.md b/docs/superpowers/specs/2026-04-19-tui-status-log-export-design.md new file mode 100644 index 0000000..9e5ab9a --- /dev/null +++ b/docs/superpowers/specs/2026-04-19-tui-status-log-export-design.md @@ -0,0 +1,82 @@ +# Design: TUI status strip, log panel, and export (git-rain) + +**Date:** 2026-04-19 +**Status:** Draft → implementation plan next (after maintainer review) +**Cross-reference:** Behavior goals match **`git-fire`** `docs/superpowers/specs/2026-04-19-tui-status-log-export-design.md`; keep these documents aligned on UX contract. **Implementation order:** `git-fire` first, then port to `git-rain`. + +## Problem + +When the Bubble Tea terminal UI is active, users want **live status** (symbols/emojis) and an optional **log surface** that can be **viewed and exported**, without weakening **first-class auditability**. IT/compliance and **AI agents** rely on **machine-parseable** session evidence; casual users mostly want a calm TUI. + +## Goals (v1) + +1. **Status strip** shows **short, live** phase indicators driven **only** by **structured session events** (same information model as persisted JSONL), not by ad hoc “reporting” prose or issue templates. +2. **Log panel** (toggle): shows a **bounded in-memory view** derived from those same structured events (and optionally lines explicitly admitted from subprocess output—default **minimal**: prefer structured lines first). +3. **Persistence:** **git-rain** aligns with **git-fire**’s session contract: JSON lines of the same **`LogEntry`** semantics (`git-fire` `internal/executor/logger.go`), written under **`UserCacheDir()/git-rain/logs/`** (same layout pattern as `git-fire` uses for `git-fire/logs/`). Until that logger exists in rain, adding it is part of this workstream; do not invent a divergent on-disk format. +4. **Export (user-initiated, simple):** + - **Plain-text** export of the **visible / ring-buffer** view for humans (paste, tickets, chat). + - **Evidence path:** expose **session JSONL path** (open folder / copy path)—no coupling to GitHub markdown, partner reports, or other “reporting” pipelines. +5. **Parity with git-fire:** same **behavior contract** (keys, panel semantics, export semantics, structured-event-driven status, **TUI-then-CLI** split for real work). Visual theming may differ. + +## Non-goals (v1) + +- **Headless daemon / cron / interval runner** attached to the same UX (deferred; same JSONL contract should make a later phase easier). +- **New shared Go module** between rain and fire (avoid release coupling); optional **short written contract** (glyph meanings + keys) duplicated or cross-linked in READMEs. +- **git-harness** as mandatory runtime dependency of the TUI (no v1 coupling). Later: optional adapter from JSONL or live events to harness JSON for CI. +- **Second on-disk log format** as canonical (no parallel “truth” besides JSONL). + +## Architecture + +### Phased UX: TUI first, then CLI work (must preserve) + +Current **git-rain** behavior (`runRainTUIStream` in `cmd/root.go`): **Bubble Tea** runs for **repo discovery / selection** (streaming). When the user confirms, the program **exits the TUI**, returns to the **normal terminal buffer**, prints **Selected repositories:**, then calls **`runRainOnRepos`** for sync/fetch work on **plain stdout/stderr** — not inside a second full-screen TUI. + +**git-fire** follows the same split (`runFireStream` → planner/runner); see cross-reference above. + +**Requirement:** v1 design **must not** move post-selection sync/fetch execution into a mandatory full-screen TUI. In-TUI status strip + log panel apply to the **selection / scan** phase (and any other TUI surfaces we already use); **post-TUI execution stays CLI-shaped** as today so agents, pipes, and IT log collection keep working. A future phase may add optional live progress for the runner; that is **out of v1** unless it remains opt-in and does not replace this path. + +**CLI-only / non-interactive flows:** unchanged — no requirement to show the TUI for users who configure or invoke without the selector. + +### Single event model, two projections + +- **Source of truth on disk:** JSON lines of `LogEntry` (same schema as git-fire). +- **In-memory:** append each `LogEntry` to a **ring buffer** for the TUI log panel, **in lockstep** with the write to the session file. +- **Status strip:** renders **only** from **structured fields** (e.g. latest `level`, `action`, `repo`, truncated `description`, duration on success). **No** separate string channel for status text; glyphs map from `(level, action)` (or a small enum derived at log site). + +### Three audiences (explicit) + +| Audience | Primary surface | +|----------|-----------------| +| Casual user | Emoji/symbol status strip + minimal noise | +| Operator | Toggle log panel, plain-text export of buffer | +| IT / automation / AI agents | Session JSONL path + stable `LogEntry` JSON fields; sanitization rules unchanged | + +### Export vs reporting + +- **Export** = evidence and operator convenience (`.txt` from buffer, path to JSONL). +- **Reporting** = anything shaped for an external audience (issues, PR narratives, bots). **Not** generated as the only export path; no hard coupling in v1. + +## git-fire + +- **Lead implementation** lives in **git-fire**; **git-rain** ports the **interaction contract** (`internal/ui` patterns already parallel Bubble Tea + lipgloss). +- Shared **semantic** table for status glyphs (documented; exact Unicode may differ by theme). + +## Testing + +- **git-testkit / integration:** assert **session file exists**, **each line is valid JSON**, and **expected actions** appear after a controlled dry run or smoke scenario where applicable. +- **git-harness:** no v1 requirement; optional future mapping from JSONL lines to `cli-protocol.json` ops for headless parity. + +## Risks / mitigations + +- **Drift** between rain and fire: mitigate with **cross-linked specs** and mirrored tests where cheap. +- **Subprocess noise:** default minimal tee into panel; expand later if needed. +- **Performance:** ring buffer max lines + avoid re-reading whole JSONL file on every keystroke; status strip updates on new events only. + +## Open items for implementation plan (not blockers for this design) + +- Exact **keybinding** and **default ring size** (product decision during plan). +- Whether **plain-text export** includes a one-line header (version, session path)—recommended for support. + +## Approval + +Design agreed in session 2026-04-19: minimalist v1, JSONL canonical (aligned with git-fire), status strip **fully driven** by structured log events, log panel + export decoupled from reporting, **TUI-then-CLI** preserved for **git-rain** (`runRainTUIStream` → `runRainOnRepos`).