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

[github-actions[bot]]

Overview

This report analyzes console output patterns across 1,061 non-test Go source files in pkg/, evaluating consistency, Lipgloss styling, and Huh form usage.

Key Metrics

Metric	Value
Total non-test Go files scanned	1,061
Console package exports	40+ functions
Lipgloss style variables	28 exported styles
Adaptive color pairs	11
Files using huh forms	11+
Raw fmt.Print* to stdout	~3 files
Manual ANSI escape codes	1 file (terminal.go only)

Overall Assessment: ✅ Highly Consistent

The codebase demonstrates excellent discipline in console output. A dedicated pkg/console/ package provides a full abstraction layer that is widely and consistently used. Raw fmt.Print* and manual ANSI codes are minimal and intentional.

---

Console Package Architecture

pkg/console/ is the central output hub exporting:

Formatting functions (all TTY-aware, return string):

• FormatSuccessMessage, FormatInfoMessage, FormatWarningMessage, FormatErrorMessage, FormatProgressMessage, FormatPromptMessage, FormatVerboseMessage
• FormatListItem, FormatListHeader, FormatSectionHeader, FormatCommandMessage
• FormatError(CompilerError) — full error box with context lines and position
• FormatErrorWithSuggestions(msg, []string) — error + suggestion bullets
• FormatErrorChain(err) — unwraps and formats error chain
• Number/size helpers: FormatNumber, FormatTokens, FormatFileSize

Rendering functions:

• RenderTable(TableConfig) — full styled table
• RenderTitleBox, RenderErrorBox, RenderInfoSection, RenderComposedSections
• RenderStruct(v any) — reflection-based renderer using console: struct tags
• RenderTree(root TreeNode) — hierarchical tree output

Interactive functions (all route through huh forms):

• ConfirmAction, PromptSecretInput, PromptInput, PromptInputWithValidation
• ShowInteractiveList, PromptSelect, PromptMultiSelect
• NewForm, NewInputForm, NewSelectForm, NewConfirmForm, RunForm

TTY utilities:

• ClearScreen, ClearLine, ShowWelcomeBanner, PrintBanner
• IsAccessibleMode — reads GH_AW_ACCESSIBLE=1 env for screen reader support
• NewSpinner, NewProgressBar, NewIndeterminateProgressBar

All Format*Stderr variants use a dedicated stderr TTY check, ensuring correct style-stripping when output is piped.

Lipgloss Usage Analysis

Theme Definition (pkg/styles/theme.go)

Adaptive Colors — 11 adaptive pairs using Dracula-inspired palette:

Name	Light	Dark
Error	deep red	#FF5555
Warning	amber	#FFB86C
Success	forest green	#50FA7B
Info	teal	#8BE9FD
Purple	indigo	#BD93F9
Yellow	warm yellow	#F1FA8C

Colors are resolved once at startup via lipgloss.HasDarkBackground probe (Windows skips probe to avoid ConPTY crashes).

28 Exported Style Variables: Error, Warning, Success, Info, FilePath, LineNumber, ContextLine, Highlight, Location, Command, Progress, Prompt, Count, Verbose, ListHeader, ListItem, TableHeader, TableCell, TableTotal, TableTitle, TableBorder, ServerName, ServerType, ErrorBox, Header, TreeEnumerator, TreeNode, ScheduleCalendarEmpty/Low/Medium/High/Critical.

Border patterns in use:

• DoubleBorder() — title boxes (centered)
• NormalBorder() left-only — info section accent
• RoundedBorder — error boxes
• HiddenBorder() — blurred huh form fields

TTY Safety

pkg/console/console.go has explicit applyStyle / applyStyleWithTTY helpers that strip Lipgloss styles when not writing to a TTY, preventing ANSI leakage in pipes and redirects. pkg/console/colorprofile_writer.go similarly provides an io.Writer that strips ANSI for non-TTY stderr.

Manual ANSI Escape Codes

Only two constants in pkg/console/terminal.go:

• ansiClearScreen = "\033[H\033[2J"
• ansiClearLine = "\033[K"

These are justified: they perform terminal control operations (cursor/screen clear) that have no Lipgloss equivalent. ✅

Huh Form Usage Analysis

Form Architecture

All huh form usage is gated through pkg/console/prompt_form.go:

func NewForm(groups ...*huh.Group) *huh.Form

This wrapper automatically applies HuhTheme and WithAccessible(IsAccessibleMode()), ensuring every interactive prompt is:

1. Styled consistently with the Dracula palette
2. Accessible-mode-aware (GH_AW_ACCESSIBLE=1)

Field Types Used

Type	Where	Count
huh.NewInput()	auth, git, secrets, run interactive	8+
huh.NewInput().EchoMode(EchoModePassword)	engine_secrets, console/input	3+
huh.NewSelect[T]()	schedule, engine, git, run interactive, list	6+
huh.NewMultiSelect[string]()	tools & network options in main wizard	2
huh.NewText()	workflow description in main wizard	1
huh.NewConfirm()	orchestrator, workflow, run, console/confirm	5+
huh.NewGroup(...)	main wizard, run interactive	4+

Theme Integration (pkg/styles/huh_theme.go)

Custom HuhTheme huh.ThemeFunc extends huh.ThemeBase(isDark) with full Dracula-palette overrides for all focused/blurred states, using lipgloss.LightDark(isDark) for per-render dynamic resolution — correctly handling runtime terminal background changes.

All 15+ style targets are covered: Focused.Title, SelectSelector, SelectedOption/Prefix, UnselectedOption/Prefix, FocusedButton, BlurredButton, TextInput.Cursor/Placeholder/Prompt, etc.

---

Files Using Raw fmt.Print* to Stdout

Only 3 files use direct stdout printing (all intentional):

File	Line	Reason
pkg/cli/view_command.go	168	view command output — correct to use stdout
pkg/cli/logs_report.go	551	fmt.Print(console.RenderStruct(...)) — structured data to stdout
pkg/cli/status_command.go	288	fmt.Print(console.RenderStruct(...)) — structured data to stdout

All other output is routed to stderr via console.FormatXxx() wrappers. ✅

---

Recommendations

✅ No Critical Issues Found

The codebase follows best practices throughout. Specific minor improvements:

1. logs_report.go and status_command.go wrap RenderStruct in fmt.Print — consider a dedicated console.PrintStruct(v any) helper to make stdout-vs-stderr intent explicit and avoid callers needing to know fmt.Print vs fmt.Fprintln.

2. pkg/console/terminal.go ANSI constants — these are currently unexported and used only within the package. Document them with a comment explaining why Lipgloss is not used (terminal control ops vs styling), to prevent future contributors from replacing them with Lipgloss calls unnecessarily.

3. lipgloss.HasDarkBackground probe — the Windows skip (shouldProbeTerminalBackground) is a good defensive pattern. Consider documenting the Windows ConPTY issue with a link to the upstream Lipgloss issue for maintainability.

4. huh.NewSelect .WithFiltering(true) — used in run_interactive.go but not in other select fields. Consider enabling filtering consistently for all select forms with more than ~5 options to improve usability.

5. PromptSelect and PromptMultiSelect are marked as wasm stubs — ensure there is a non-wasm path and that callers handle non-interactive environments gracefully.

---

References:

• [§29240308354](https://github.com/github/gh-aw/actions/runs/29240308354)

Generated by 💄 Terminal Stylist · 63.2 AIC · ⌖ 5.43 AIC · ⊞ 5.6K · ◷

• expires on Jul 14, 2026, 1:54 AM UTC-08:00