[terminal-stylist] Console Output Analysis: Patterns, Consistency & Recommendations

[github-actions[bot]]

This report analyzes all Go source files in pkg/ for console output patterns, Lipgloss styling usage, and Huh form implementations.

Summary

• 895 non-test Go files scanned across pkg/
• 202 files use console.* formatter functions — broad, consistent adoption
• 10 files use Lipgloss directly; all properly gated on TTY detection
• 14 files use Huh forms; all apply WithTheme(styles.HuhTheme).WithAccessible(console.IsAccessibleMode())
• 4 files contain minor inconsistencies (unstyled output mixed with styled output)

Key Metrics

Formatter	Usage Count
console.FormatInfoMessage	675
console.FormatWarningMessage	536
console.FormatSuccessMessage	226
console.FormatErrorMessage	69
console.FormatVerboseMessage	69
console.FormatCommandMessage	20
console.RenderTable	28
console.RenderStruct	14

Architecture

The codebase has a well-designed, layered console output architecture:

1. pkg/styles/ — Centralized Dracula-inspired adaptive color palette (11 semantic colors, light/dark variants), pre-built Lipgloss style variables, and a custom HuhTheme that maps the same palette to Huh forms.
2. pkg/console/ — Formatting layer wrapping Lipgloss and Huh. Every rendering function is gated through applyStyle() which checks isTTY() before emitting ANSI sequences.
3. pkg/cli/ — Consumer layer using console.* functions almost exclusively for user-facing output.

Lipgloss Usage Analysis

Files Using Lipgloss Directly

File	Purpose	TTY-Gated?
pkg/console/console.go	Core formatting layer	✅ via applyStyle()
pkg/console/banner.go	ASCII logo display	✅ via applyStyle()
pkg/console/spinner.go	Bubble Tea spinner	✅ tty.IsStderrTerminal()
pkg/styles/theme.go	Color/style definitions	N/A (definitions only)
pkg/styles/huh_theme.go	Huh form theme	N/A (theme definitions)
pkg/logger/logger.go	Log output	✅ conditional
pkg/cli/compile_schedule_calendar.go	Schedule heatmap	✅ explicit isTerminal gate
pkg/cli/status_command.go	Dependency tree output	✅ via console helpers
pkg/cli/mcp_inspect.go	MCP tree view (lipgloss/tree)	✅ via console helpers
pkg/cli/gateway_logs_timeline_render.go	Timeline rendering	✅ via console helpers

Lipgloss Best Practices — Compliance

✅ Adaptive colors — pkg/styles/theme.go uses compat.AdaptiveColor for all 11 semantic colors, with explicit light/dark hex values and a Dracula-inspired dark palette.

✅ TTY detection — applyStyle() in console.go is the single TTY gate for all styled output. pkg/styles/theme.go uses init() to detect dark background and color profile at startup, with a Windows-safe guard.

✅ Consistent border styles — RoundedBorder, NormalBorder, ThickBorder centralized in pkg/styles/.

✅ Table rendering — console.RenderTable() uses lipgloss/table with per-cell styling, alternating rows, header/total row differentiation.

✅ Progressive layout — RenderTitleBox, RenderErrorBox, RenderInfoSection, RenderComposedSections provide compose-and-render patterns with TTY/non-TTY fallbacks.

⚠️ Minor: compile_schedule_calendar.go applies Lipgloss directly (not through console.*) with a local isTerminal variable. The pattern is correct and TTY-gated, but diverges from the package-level applyStyle() helper. Low impact.

⚠️ Minor: compile_stats.go:301-302 calls styles.Error.Render() directly for two fields, while the surrounding code uses console.FormatErrorMessage(). Functionally equivalent but inconsistent.

Huh Form Usage Analysis

Files Using Huh Directly

File	Form Types	Pattern Correct?
pkg/console/confirm.go	huh.NewConfirm	✅ + text fallback for non-TTY
pkg/console/input.go	huh.NewInput (password)	✅ + non-TTY guard
pkg/console/list.go	huh.NewSelect	✅ + numbered list fallback
pkg/cli/add_interactive_engine.go	huh.NewSelect	✅
pkg/cli/add_interactive_auth.go	huh.NewSelect, huh.NewInput	✅
pkg/cli/add_interactive_git.go	huh.NewSelect	✅
pkg/cli/add_interactive_orchestrator.go	huh.NewSelect	✅
pkg/cli/add_interactive_schedule.go	huh.NewSelect, huh.NewInput	✅
pkg/cli/add_interactive_workflow.go	huh.NewInput	✅
pkg/cli/interactive.go	Mixed forms	✅
pkg/cli/run_interactive.go	huh.NewSelect, huh.NewConfirm	✅
pkg/cli/engine_secrets.go	huh.NewInput	✅
pkg/styles/huh_theme.go	Theme definition	N/A

Huh Best Practices — Compliance

✅ Consistent theming — All 16 Huh NewForm() calls apply .WithTheme(styles.HuhTheme). The HuhTheme function maps the full Dracula palette to focused/blurred/group states.

✅ Accessibility mode — All forms apply .WithAccessible(console.IsAccessibleMode()). The IsAccessibleMode() function checks ACCESSIBLE, TERM=dumb, and NO_COLOR.

✅ Non-TTY fallbacks — confirm.go and list.go detect !tty.IsStderrTerminal() and fall back to plain numbered text prompts, preventing crashes in CI/piped environments.

✅ Password masking — input.go uses huh.EchoModePassword with non-empty validation.

✅ Context propagation — add_interactive_engine.go uses .RunWithContext(c.Ctx) for cancellable forms.

✅ Validation — Password input has explicit non-empty validation; select fields use huh.Option typed values.

Inconsistencies Found

1. Unstyled Warning Message — pkg/workflow/push_to_pull_request_branch.go:117

// Current — unstyled:
fmt.Fprintf(os.Stderr, "Warning: invalid if-no-changes value %s, using default warn\n", ifNoChangesStr)

// Should be:
fmt.Fprintln(os.Stderr, console.FormatWarningMessage(fmt.Sprintf("invalid if-no-changes value %q, using default warn", ifNoChangesStr)))

This is the only raw Warning: string emitted to stderr without using console.FormatWarningMessage().

2. Bare Bullet Points Without Styling — pkg/cli/fix_command.go:333,338

// Current — no styling on bullet lines:
fmt.Fprintf(os.Stderr, "    • %s\n", codemodName)

// Consider:
fmt.Fprintln(os.Stderr, console.FormatListItem(codemodName))

The parent line uses console.FormatSuccessMessage/FormatWarningMessage but the codemod name sub-items use raw fmt.Fprintf.

3. Redundant Warning Symbol — pkg/cli/fix_command.go:336

// Current — double warning symbol when rendered:
fmt.Fprintf(os.Stderr, "%s\n", console.FormatWarningMessage("⚠ "+fileName))
// Renders: "⚠ ⚠ filename" in TTY

// Should be:
fmt.Fprintf(os.Stderr, "%s\n", console.FormatWarningMessage(fileName))

FormatWarningMessage already prepends ⚠ — the extra symbol creates duplication.

4. Unstyled Failure Detail — pkg/cli/update_display.go:27

// Current:
fmt.Fprintf(os.Stderr, "  %s: %s\n", failure.Name, failure.Error)

// Surrounding code uses console helpers; consider:
fmt.Fprintln(os.Stderr, console.FormatListItem(fmt.Sprintf("%s: %s", failure.Name, failure.Error)))

5. status_command.go:276 Writes to Stdout

fmt.Print(console.RenderStruct(statuses))

All other RenderStruct calls use fmt.Fprint(os.Stderr, ...). The status command explicitly writes the structured output to stdout, which is correct for machine-readable output — but warrants a comment to clarify the intentional stdout vs stderr choice.

Recommendations

Priority: Low — The codebase already has a mature, consistent console output system. The following are small polish items:

1. Fix the unstyled warning in push_to_pull_request_branch.go:117 to use console.FormatWarningMessage() — this is the only raw Warning: string bypassing the console formatter.

2. Remove redundant ⚠ from fix_command.go:336 — FormatWarningMessage("⚠ "+fileName) produces a double warning symbol in TTY.

3. Extend FormatListItem to sub-items in fix_command.go:333,338 and update_display.go:27 for visual consistency with the rest of the formatted output.

4. Document the stdout intent in status_command.go:276 — a brief comment explaining why fmt.Print (stdout) is used instead of fmt.Fprint(os.Stderr, ...) would prevent future confusion.

References: §27198166974

Generated by 💄 Terminal Stylist · 540.5 AIC · ⌖ 15 AIC · ⊞ 21.4K · ◷

• expires on Jun 10, 2026, 2:00 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-06-10T10:00:43.298Z.

Closed by Workflow