[terminal-stylist] Terminal Stylist Report: Console Output Analysis

[github-actions[bot]]

Summary

This report analyzes console output patterns across the pkg/ directory of github/gh-aw (1,048 non-test Go files scanned). The codebase has a strong, centralized console formatting system with good discipline, though a few areas could benefit from more consistent use of shared helpers.

---

Key Metrics

Pattern	Status
console.* helpers	✅ Widespread and established
lipgloss.* styling	✅ Centralized in pkg/styles/
huh.* forms/prompts	✅ Centralized in pkg/console/
Raw fmt.Print*	⚠️ Widely used, some outside pkg/console/ needs review
Manual ANSI escapes	✅ Confined to pkg/console/ internals

---

Console Package Patterns

pkg/console/console.go is the main normalization layer providing:

• info / success / warning / error / progress / prompt / verbose messages
• TTY-aware styling (ANSI stripped in non-interactive output)
• Table rendering
• Boxed/section layouts
• Formatted error chains

Good patterns:

• Separate stdout/stderr TTY helpers (FormatSuccessMessageStderr, FormatInfoMessageStderr, etc.)
• applyStyleWithTTY prevents ANSI in non-interactive output
• pkg/console/render.go provides reflection-based table/section rendering — a strong reusable pattern

Message Rendering Patterns

Consistent message helpers used broadly across CLI/workflow code:

console.FormatWarningMessage(...)
console.FormatInfoMessage(...)
console.FormatSuccessMessage(...)
console.FormatErrorMessage(...)

These are the right default for all user-facing stderr output. Good examples of correct usage:

• pkg/envutil/envutil.go
• pkg/actionpins/actionpins.go

Raw `fmt` Usage — Appropriate Cases

Raw fmt.* is appropriate and expected in:

• pkg/console/* internals
• JSON/stdout emitters (pkg/cli/forecast_render.go)
• Structured markdown/text renderers (pkg/console/render.go)
• Low-level terminal control (pkg/console/terminal.go, pkg/console/spinner.go)

Raw `fmt` Usage — Candidates for Cleanup

Several files mix raw fmt.Fprintln/Fprintf with console helpers for user-facing stderr output:

File	Issue
pkg/cli/update_display.go	Failed items use raw fmt.Fprintf instead of error/list helpers
pkg/cli/run_interactive.go	Non-TTY fallback uses manual numbered menus duplicating console list behavior
pkg/cli/forecast_render.go	Section labels use raw formatting alongside structured console output
pkg/cli/trial_helpers.go	Some plain spacing/separators remain ad hoc alongside FormatInfoMessage
pkg/console/confirm.go	Non-TTY fallback is manually styled
pkg/console/list.go	Non-TTY fallback is manually styled

Lipgloss Usage Analysis

Centralization: Styles are well-centralized in pkg/styles/theme.go.

Adaptive colors: ✅ Custom adaptiveColor system in pkg/styles/ — good practice.

TTY gating: ✅ pkg/cli/compile_schedule_calendar.go correctly gates lipgloss styling before rendering ANSI.

LightDark usage: ✅ pkg/styles/huh_theme.go uses lipgloss.LightDark(...) for per-render adaptive form theming.

Logger: pkg/logger/logger.go uses adaptive palette-derived styles — consistent with the theme.

Overall: lipgloss usage is disciplined. Adaptive color support is solid.

Huh Forms and Prompts

Central abstraction: pkg/console/prompt_form.go wraps huh.NewForm(...) with:

• Shared styles.HuhTheme
• Accessibility mode

Exported helpers: console.NewInputForm, NewSelectForm, NewConfirmForm

Good patterns found:

• Fuzzy-select enabled in pkg/cli/run_interactive.go
• Password masking in pkg/console/input.go
• Consistent theme/accessibility in interactive flows: pkg/cli/interactive.go, pkg/cli/add_interactive_*, pkg/cli/engine_secrets.go

Manual ANSI Escapes

Manual ANSI usage is intentional, minimal, and confined to console internals:

Location	Usage
pkg/console/terminal.go	\033[H\033[2J (clear screen), \033[K (clear line)
pkg/console/spinner.go	Carriage return / clear-line based redraw loop

This is acceptable low-level terminal control. It should remain confined here.

---

Recommendations

1. Use pkg/console helpers for all user-facing stderr messages outside pkg/console — avoid raw fmt.Fprintf(os.Stderr, ...) for user messages.
2. Clean up mixed-format files: pkg/cli/update_display.go, pkg/cli/run_interactive.go, pkg/cli/forecast_render.go are the highest-priority candidates.
3. Consolidate non-TTY fallbacks in pkg/console/confirm.go and pkg/console/list.go to align with the console helper style.
4. Keep manual ANSI escapes confined to terminal-control primitives only.
5. Continue centralizing styles in pkg/styles/ — the current pattern is strong.
6. Require console.NewForm(...) for new interactive flows to keep theme and accessibility consistent.

References: §29084337300

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• proxy.golang.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "proxy.golang.org"

See Network Configuration for more information.

Generated by 💄 Terminal Stylist · 34.1 AIC · ⌖ 7.56 AIC · ⊞ 5.6K · ◷

• expires on Jul 11, 2026, 1:56 AM UTC-08:00

[github-actions[bot]]

This discussion has been marked as outdated by Terminal Stylist.

A newer discussion is available at Discussion #44921.