[terminal-stylist] Terminal Stylist Audit — Console Output Analysis

[github-actions[bot]]

Overview

The gh-aw codebase demonstrates mature, well-structured terminal output with a well-established console formatting layer, modern Charmbracelet ecosystem usage (charm.land/lipgloss/v2 and charm.land/huh/v2), and strong adherence to the stderr/stdout routing conventions.

Run: §24994209506

---

Summary Statistics

Metric	Count
Go source files importing pkg/console	182
Files using console.Format* helpers	175
Files using fmt.Fprintf/fmt.Fprintln (stderr)	226
Files with fmt.Println/fmt.Printf (stdout structured data)	14
Files using Lipgloss directly	4 (pkg/console/, pkg/styles/)
Files using Huh forms	13

---

✅ Strengths

Console Formatting Package

pkg/console/console.go provides a rich, well-documented API:

• Typed message formatters: FormatSuccessMessage, FormatInfoMessage, FormatWarningMessage, FormatErrorMessage, FormatCommandMessage, FormatProgressMessage, FormatPromptMessage, FormatVerboseMessage, FormatListItem
• Structured rendering: RenderTable, RenderTitleBox, RenderErrorBox, RenderInfoSection, RenderComposedSections, FormatSectionHeader
• Rust-like error formatting: FormatError with file:line:col positions, context lines, and hints
• TTY detection: applyStyle conditionally applies Lipgloss styling — styles are silently stripped in pipes/redirects

Lipgloss v2 (charm.land/lipgloss/v2)

pkg/styles/theme.go and pkg/console/console.go use Lipgloss v2 correctly:

• Adaptive colors: Uses compat.AdaptiveColor with explicit Light/Dark hex variants for each semantic color (Error, Warning, Success, Info, Purple, Yellow, Comment, Foreground, Background, Border, TableAltRow)
• Dracula-inspired dark palette with corresponding accessible light-mode variants
• TTY-gated rendering: applyStyle(style, text) returns plain text when not in a TTY
• Table support: Uses charm.land/lipgloss/v2/table for structured table output

Huh v2 (charm.land/huh/v2 — charm.land fork)

13 files use Huh v2, with excellent integration:

• Custom theme (pkg/styles/huh_theme.go): HuhTheme maps the pkg/styles Dracula palette to every Huh component — focused/blurred borders, selectors, options, buttons, text input cursor/placeholder/prompt — using lipgloss.LightDark() for adaptive colors
• Accessibility support: All form instantiations call .WithAccessible(IsAccessibleMode()) for screen-reader-friendly fallback
• TTY detection: pkg/console/list.go falls back to a numbered text list with fmt.Fprintf(os.Stderr, ...) for non-TTY environments
• Centralized wrappers: pkg/console/confirm.go, pkg/console/list.go, pkg/console/input.go abstract huh.NewForm behind named helpers (ConfirmAction, ShowInteractiveList, PromptSecretInput) so call sites get consistent theme and accessibility settings automatically
• Field coverage: Confirm, Select, Input (with EchoModePassword for secrets) are all used

Stdout / Stderr Routing

All 14 files using fmt.Println/fmt.Printf to stdout output structured data (JSON bytes, Mermaid graphs, Markdown audit reports, hash strings, state strings) — consistent with the documented Unix convention of routing structured data to stdout for piping/redirection.

---

⚠️ Minor Observations

1. Render files use bare fmt.Print* for Markdown/structured output (expected, but undocumented)

pkg/cli/audit_cross_run_render.go and pkg/cli/audit_diff_render.go use fmt.Println/fmt.Printf for Markdown table rows. This is intentional (Markdown output for human-readable reports) and aligns with the "structured output → stdout" convention, but neither file has a comment explaining the choice. A brief header comment would improve maintainability.

// Writes a Markdown-formatted report to stdout for human-readable display.
// Diagnostic messages (progress, errors) go to stderr via console.Format*.

2. styles/theme.go usage examples use fmt.Println (comment-only, not runtime)

Lines 39–46 of pkg/styles/theme.go show fmt.Println(styles.Error.Render(...)) in doc comments. These are illustrative examples — not actual runtime calls. However, callers following these examples may send styled output to stdout instead of stderr. Consider updating the doc examples to use fmt.Fprintln(os.Stderr, ...).

3. No huh.Text (multi-line) or huh.FilePicker usage found

The current interactive forms cover Confirm, Select, and Input fields. Workflows that prompt for multi-line content (e.g., workflow descriptions) currently use sequential Input fields. huh.NewText() would provide a better UX for multi-line text entry. This is an enhancement opportunity, not a defect.

4. console.go isTTY() checks stdout, not stderr

isTTY() in pkg/console/console.go calls tty.IsStdoutTerminal(), but all formatted messages are written to os.Stderr. Callers use fmt.Fprintln(os.Stderr, console.FormatXxx(...)). Styling based on stdout TTY state is technically correct for most terminals (stdout and stderr share the same TTY), but an explicit tty.IsStderrTerminal() check would be more semantically accurate for messages written to stderr.

---

Recommendations

Priority	Recommendation	Effort
Low	Add a comment to audit_cross_run_render.go / audit_diff_render.go explaining stdout Markdown output	Trivial
Low	Update styles/theme.go doc example to use fmt.Fprintln(os.Stderr, ...)	Trivial
Low	Consider huh.NewText() for multi-line workflow description prompts	Small
Low	Align isTTY() in console.go to check stderr terminal state	Small

---

Conclusion

The codebase is in excellent shape for terminal output consistency. The console formatting layer is comprehensive and widely adopted, Lipgloss v2 adaptive colors are used correctly, Huh v2 forms have a consistent custom theme with accessibility support, and the stdout/stderr routing convention is followed throughout. The observations above are minor polish items — no systemic issues were found.

References:

• §24994209506

Generated by Terminal Stylist · ● 495.1K · ◷

• expires on Apr 28, 2026, 12:16 PM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Terminal Stylist.

A newer discussion is available at Discussion #28934.