[terminal-stylist] Console Output Style Analysis — pkg/ Codebase

[github-actions[bot]]

Overview

This report analyzes console output patterns across 891 non-test Go source files in pkg/, with focus on the pkg/cli/ layer (315 files). The codebase uses the Charmbracelet v2 ecosystem: lipgloss/v2, huh/v2, bubbletea/v2, and bubbles/v2.

Overall verdict: The foundational architecture (pkg/console, pkg/styles) is well-designed and comprehensive. Adoption inconsistencies in pkg/cli/ are the primary area for improvement — 145 of 315 cli files (46%) emit raw fmt.Fprintf(os.Stderr, ...) calls that bypass the console styling layer.

Key Metrics

Metric	Value
Total .go source files in pkg/	891
Files in pkg/cli/	315
pkg/cli/ files importing pkg/console	150 (48%)
Files using lipgloss/huh directly	22
Raw fmt.Fprintf/Fprintln to stderr (cli)	579 instances across 145 files
Huh form instances with consistent theme	14+ (100% compliant)
Adaptive color definitions	11 semantic colors

---

Lipgloss Usage Analysis

✅ Strengths

• pkg/styles/theme.go defines a complete Dracula-inspired palette with compat.AdaptiveColor for automatic light/dark adaptation. All 11 semantic colors (ColorError, ColorWarning, ColorSuccess, ColorInfo, ColorPurple, ColorYellow, ColorComment, ColorForeground, ColorBackground, ColorBorder, ColorTableAltRow) use the proper {Light: ..., Dark: ...} form.

• TTY detection is centralized: console.go::applyStyle() gates all styling behind isTTY() (backed by tty.IsStdoutTerminal()), which prevents ANSI codes from leaking into redirected output.

• Table rendering (console.RenderTable) uses lipgloss/table with a per-cell styleFunc that returns lipgloss.NewStyle() (no styling) in non-TTY mode — correct pattern.

• Rich layout components in console.go: RenderTitleBox, RenderErrorBox, RenderInfoSection, and RenderComposedSections all have TTY-aware fallbacks to plain-text alternatives.

• mcp_inspect.go correctly uses charm.land/lipgloss/v2/tree (the Lipgloss tree component) for hierarchical tool/resource output.

• compile_schedule_calendar.go uses intensityStyle() creating custom styles with styles.Color* constants — no hardcoded hex values, proper delegation to the styles package.

ANSI escape sequences in terminal.go

ANSI sequences used for spinner/cursor management are properly isolated in named constants:

ansiClearLine      = "\033[K"
ansiCarriageReturn = "\r"
ansiClearScreen    = "\033[H\033[2J"

These are only used internally by spinner.go and terminal.go — not scattered across the codebase. ✅

⚠️ Areas for Improvement

• compile_schedule_calendar.go::intensityStyle() creates a new lipgloss.NewStyle() on every call. Consider caching these as package-level vars in pkg/styles — e.g., styles.IntensityLow, styles.IntensityMedium, etc.

• console.go::RenderTitleBox and RenderErrorBox create anonymous inline lipgloss.NewStyle() calls. styles.ErrorBox already exists in pkg/styles and could be referenced for DRY consistency.

---

Huh Form Usage Analysis

✅ Strengths — Excellent Consistency

All 14+ huh form instances across the codebase apply the same consistent pattern:

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

Files following this pattern: add_interactive_auth.go, add_interactive_engine.go, add_interactive_git.go, add_interactive_orchestrator.go, add_interactive_schedule.go, add_interactive_workflow.go, run_interactive.go, engine_secrets.go, interactive.go, console/confirm.go, console/input.go, console/list.go.

IsAccessibleMode() checks ACCESSIBLE, TERM=dumb, and NO_COLOR — solid multi-signal accessibility detection.

HuhTheme in pkg/styles/huh_theme.go uses lipgloss.LightDark(isDark) (Lipgloss v2 API) to map the pkg/styles Dracula palette to all huh field states (focused/blurred, selected/unselected, error, navigation indicators, text cursor).

Field type variety

Field Type	Used In
huh.NewConfirm()	console/confirm.go, add_interactive_workflow.go
huh.NewSelect[T]()	add_interactive_schedule.go, add_interactive_git.go, run_interactive.go, console/list.go
huh.NewInput() with EchoModePassword	console/input.go
huh.NewInput() (text)	add_interactive_git.go
Multi-group forms	run_interactive.go (dynamic []*huh.Group slice)

Password masking (EchoMode(huh.EchoModePassword)) is used in console/input.go for secret entry — correct security practice. ✅

⚠️ Areas for Improvement

• console/confirm.go does not check TTY before creating the huh form, unlike console/list.go which guards with tty.IsStderrTerminal(). A non-TTY environment calling ConfirmAction will attempt interactive rendering.

• run_interactive.go builds dynamic []*huh.Group slices for multi-step workflows. Consider adding field-level validation where inputs have clear constraints.

---

Console Package Coverage Analysis

✅ Well-Designed Abstraction

pkg/console provides a comprehensive set of format helpers covering all common message types (error chain, success, info, warning, command, progress, verbose, list, section header, table, struct reflection, title/error/info boxes).

❌ Raw Output Bypassing Console (145 of 315 cli files)

579 raw fmt.Fprintf(os.Stderr, ...) / fmt.Fprintln(os.Stderr, ...) calls in pkg/cli do not use the console package. Key patterns:

Pattern 1 — Unstyled user-facing messages (most impactful)

// add_interactive_workflow.go
fmt.Fprintf(os.Stderr, "Checking workflow status (attempt %d/5) for: %s\n", i+1, workflowName)
fmt.Fprintf(os.Stderr, "Status check error: %v\n", err)
fmt.Fprintln(os.Stderr, "Updating local branch (this may take a few seconds)...")
fmt.Fprintln(os.Stderr, "Finished updating local branch.")

Better expressed as console.FormatProgressMessage / console.FormatVerboseMessage / console.LogVerbose.

Pattern 2 — Manual list formatting (fix_command.go: 35 raw calls alongside 21 console calls)

fmt.Fprintf(os.Stderr, "    • %s\n", codemodName)   // raw bullet
fmt.Fprintf(os.Stderr, "  %s\n", console.FormatInfoMessage(codemod.Name))  // mixed

console.FormatListItem(codemodName) already exists for this purpose.

Pattern 3 — Manual separators (actionlint.go)

separator := strings.Repeat("━", 60)
fmt.Fprintf(os.Stderr, "\n%s\n", separator)
fmt.Fprintf(os.Stderr, "%s\n", console.FormatInfoMessage("Actionlint Summary"))

console.FormatSectionHeader() or console.RenderTitleBox() exist for this pattern.

Pattern 4 — Instruction text without styling (trial_confirmation.go, add_interactive_auth.go)

fmt.Fprintln(os.Stderr, "Please navigate to a git repository or initialize one with:")
fmt.Fprintf(os.Stderr, "     a. Execute %s\n", workflowName)

console.RenderInfoSection() provides the proper left-border callout styling for instructional blocks.

Files with highest raw fmt stderr usage

File	Approximate raw fmt calls
fix_command.go	35
add_interactive_git.go	10+
add_interactive_workflow.go	15+
update_container_pins.go	7
update_actions.go	5
actionlint.go	6
trial_confirmation.go	5

---

Recommendations

High Impact

1. Replace unstyled progress/status messages in add_interactive_workflow.go with console.FormatProgressMessage / console.LogVerbose(verbose, ...) — improves visual consistency for the most user-visible interactive flow.

2. Replace manual bullet points in fix_command.go with console.FormatListItem() — the function exists and is already used elsewhere in the same file.

3. Replace manual separators in actionlint.go with console.FormatSectionHeader() or console.RenderTitleBox() — eliminates the hardcoded strings.Repeat("━", 60).

Medium Impact

4. Add TTY guard to console/confirm.go matching the pattern in console/list.go — prevents huh from attempting interactive rendering in non-TTY environments.

5. Replace plain instruction text blocks in trial_confirmation.go and add_interactive_auth.go with console.RenderInfoSection() for consistent left-border callout styling.

6. vscode_config.go: fmt.Fprintf(os.Stderr, "Settings file already exists at %s\n", settingsPath) → console.FormatInfoMessage().

Low Impact / Cleanup

7. Cache intensityStyle() variants in pkg/styles as pre-configured vars to avoid style allocation on every calendar render call.

8. RenderTitleBox/RenderErrorBox in console.go create inline lipgloss styles — reference the existing styles.ErrorBox var for DRY consistency.

---

References: §27130449179

Generated by 💄 Terminal Stylist · 687 AIC · ⌖ 14.5 AIC · ⊞ 21.3K · ◷

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

[github-actions[bot]]

This discussion has been marked as outdated by Terminal Stylist.

A newer discussion is available at Discussion #38079.