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

[github-actions[bot]]

This audit analyzes console output patterns across 668 Go source files in pkg/ and cmd/, covering Lipgloss styling, Huh interactive forms, and the console formatting package.

Overview

The codebase demonstrates excellent overall console architecture with a well-structured pkg/console and pkg/styles packages built on the Charmbracelet ecosystem. The console formatting API is heavily adopted (1,189+ usages) and provides consistent, accessible output. There are targeted areas where raw fmt.Fprintf(os.Stderr, ...) calls bypass the formatting system.

---

✅ Lipgloss Usage — Well Implemented

pkg/styles/theme.go provides a centralized Dracula-inspired adaptive color system:

• Proper adaptive colors: All 11 semantic colors use compat.AdaptiveColor{Light: ..., Dark: ...} for automatic light/dark terminal adaptation
• Named semantic styles: styles.Error, styles.Warning, styles.Success, styles.Info, styles.FilePath, styles.LineNumber, styles.Comment — pre-configured lipgloss.NewStyle() values
• Consistent borders: Three border definitions (RoundedBorder, NormalBorder, ThickBorder) with documented usage guidelines
• No hardcoded ANSI: Zero raw escape sequences; color is always expressed through lipgloss

pkg/console/console.go uses Lipgloss correctly throughout:

• applyStyle(style, text) helper gates all styling on TTY detection (tty.IsStdoutTerminal())
• lipgloss/table with styleFunc for zebra-striped, rounded-border tables
• lipgloss.JoinVertical for composing multi-section panels
• Double-border title boxes and normal-border left-accent info sections

pkg/console/banner.go:

• Purple-colored ASCII art logo using lipgloss.NewStyle().Bold(true).Foreground(styles.ColorPurple)
• Printed to stderr (correct)

Lipgloss usage inventory

File	Pattern	Notes
pkg/styles/theme.go	Adaptive color definitions	✅ Full adaptive system
pkg/console/console.go	lipgloss/table, boxes, sections	✅ TTY-gated
pkg/console/banner.go	lipgloss.NewStyle() for logo	✅ Correct
pkg/console/spinner.go	Bubble Tea + adaptive color	✅ Accessible

---

✅ Huh Interactive Forms — Consistently Applied

All 9 CLI files that use huh directly apply the full theme/accessibility chain:

huh.NewForm(...).WithTheme(styles.HuhTheme).WithAccessible(console.IsAccessibleMode())

pkg/styles/huh_theme.go — custom HuhTheme function:

• Maps the entire pkg/styles Dracula palette to every huh visual element
• Uses lipgloss.LightDark(isDark) to derive per-variable light/dark values
• Covers focused/blurred states, select selectors, multiselect, text inputs, cursor, buttons, and group headers

pkg/console/confirm.go, input.go, list.go — library wrappers:

• ConfirmAction, PromptSecretInput, ShowInteractiveList all use styles.HuhTheme + accessibility
• input.go and list.go check tty.IsStderrTerminal() before entering interactive mode
• list.go provides a graceful non-TTY text fallback

Files using huh directly (all compliant)

File	Fields Used	Theme Applied
pkg/cli/add_interactive_auth.go	Select	✅
pkg/cli/add_interactive_engine.go	Select with descriptions	✅
pkg/cli/add_interactive_git.go	Select, multi-step	✅
pkg/cli/add_interactive_orchestrator.go	Multi-field form	✅
pkg/cli/add_interactive_schedule.go	Input, Select	✅
pkg/cli/add_interactive_workflow.go	Input	✅
pkg/cli/engine_secrets.go	Password Input ×3	✅
pkg/cli/interactive.go	Multi-field forms	✅
pkg/cli/run_interactive.go	Dynamic form groups	✅

---

⚠️ Console Formatting — High Adoption with Gaps

The console package provides 17 Format* functions, well-distributed across the codebase:

Function	Usages in pkg/cli/
FormatInfoMessage	579
FormatWarningMessage	408
FormatSuccessMessage	194
FormatVerboseMessage	65
FormatErrorMessage	57
FormatSectionHeader	43
FormatCommandMessage	20
FormatNumber	20

Gaps — Raw stderr writes without console formatting:

~371 fmt.Fprintf(os.Stderr, ...) calls with content that bypass the console formatting system. Top offenders:

Top files with unformatted stderr output

File	Raw writes	Category
pkg/cli/audit_report_render.go	176	Blank-line separators (acceptable)
pkg/cli/mcp_inspect_mcp.go	41	Emoji-prefixed raw output
pkg/cli/engine_secrets.go	32	Mixed (most use console)
pkg/cli/audit_cross_run_render.go	29	Markdown report to stdout ✅
pkg/cli/preconditions.go	27	User-facing instruction strings
pkg/cli/add_interactive_workflow.go	22	Progress updates
pkg/cli/shell_completion.go	21	Instruction text
pkg/cli/deps_report.go	20	Report tables
pkg/cli/copilot_setup.go	19	Setup instructions
pkg/cli/enable.go	12	Status messages

Notable anti-patterns found:

pkg/cli/preconditions.go — User-facing messages as plain strings:

// ❌ Current
fmt.Fprintln(os.Stderr, "Please run the following command to authenticate:")
fmt.Fprintln(os.Stderr, "You can still add workflows, but they won't run until Actions is enabled.")
fmt.Fprintln(os.Stderr, "Agentic workflows require GitHub-owned actions to run.")

// ✅ Recommended
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("Please run the following command to authenticate:"))
fmt.Fprintln(os.Stderr, console.FormatWarningMessage("You can still add workflows, but they won't run until Actions is enabled."))

pkg/cli/mcp_inspect_mcp.go — Manual emoji formatting instead of console functions:

// ❌ Current
fmt.Fprintf(os.Stderr, "📋 **Name:** %s\n", foundTool.Name)
fmt.Fprintf(os.Stderr, "✅ **Status:** Allowed\n")
fmt.Fprintf(os.Stderr, "🚫 **Status:** Not allowed\n")

// ✅ Recommended — use console.FormatSuccessMessage / FormatWarningMessage
// and consider console.RenderTable or console.RenderStruct for structured output

pkg/cli/enable.go — Status/progress messages without formatting:

// ❌ Current
fmt.Fprintf(os.Stderr, "Workflow %s is already enabled\n", name)
fmt.Fprintf(os.Stderr, "The following workflows will be %sd:\n", action)

// ✅ Recommended
fmt.Fprintln(os.Stderr, console.FormatInfoMessage(fmt.Sprintf("Workflow %s is already enabled", name)))
fmt.Fprintln(os.Stderr, console.FormatProgressMessage(fmt.Sprintf("The following workflows will be %sd:", action)))

---

✅ Correct Stdout Usage

Files that output structured data to stdout are following the correct pattern:

File	Output type	Verdict
pkg/cli/hash_command.go	Hash string	✅ stdout correct
pkg/cli/audit_cross_run_render.go	Markdown report	✅ stdout correct
pkg/cli/audit_diff_render.go	Markdown diff	✅ stdout correct
pkg/cli/tool_graph.go	Mermaid graph	✅ stdout correct
pkg/cli/domains_command.go	Domain list	✅ stdout correct

---

Recommendations

Priority 1 — User-Facing Instruction Text (preconditions.go)

pkg/cli/preconditions.go contains 15+ user-visible strings describing required user actions. These are high-value targets since they appear during auth failures and permission errors:

• Replace fmt.Fprintln(os.Stderr, "...") with console.FormatInfoMessage or console.FormatWarningMessage
• Use console.FormatCommandMessage for inline command examples

Priority 2 — MCP Inspect Output (mcp_inspect_mcp.go)

The mcp inspect tool output uses manual emoji+markdown formatting. This could be refactored to:

• Use console.RenderStruct with console struct tags for the tool detail view
• Use console.RenderTable for the tool list
• Replace status emojis with console.FormatSuccessMessage/FormatWarningMessage

Priority 3 — Enable Command Status (enable.go)

enable.go mixes formatted and unformatted output. Standardize with:

• console.FormatInfoMessage for status updates
• console.FormatSuccessMessage for completion messages
• console.FormatListItem for the workflow list

Positive Patterns to Continue

• WithTheme(styles.HuhTheme).WithAccessible(console.IsAccessibleMode()) — applied consistently on all forms
• applyStyle(style, text) TTY gating — should be followed for any new Lipgloss usage
• pkg/console wrappers (ConfirmAction, PromptSecretInput, ShowInteractiveList) — should be preferred over direct huh usage for simple single-field cases

---

References:

• §24397744853

Generated by Terminal Stylist · ● 2.1M · ◷

• expires on Apr 15, 2026, 12:09 PM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Terminal Stylist.

A newer discussion is available at Discussion #26416.