Terminal Stylist: Console Output Analysis Report

[github-actions[bot]]

Overview

This report covers a full audit of console output patterns across all non-test Go source files in pkg/ and cmd/. The codebase demonstrates excellent terminal output discipline — a well-layered abstraction stack, proper stream separation, adaptive theming, and thorough accessibility support. Two minor improvement opportunities were identified.

Summary

Metric	Value
console.Format* call sites	~1,413
fmt.Fprintf(os.Stderr, ...) call sites	~1,896
fmt.Println/Printf (stdout structured output)	21
Files using huh interactive forms	15+
Hardcoded ANSI escape sequences	0
Diagnostic messages leaking to stdout	0

Architecture

The output stack is cleanly layered:

pkg/styles/       — Color constants + lipgloss.Style vars + HuhTheme()
    ↓
pkg/console/      — High-level formatters, TTY detection, huh wrappers
    ↓
pkg/cli/*.go      — Command logic using console.Format* + huh forms

No code outside pkg/styles/ and pkg/console/ imports lipgloss directly. This is the correct pattern.

---

✅ Lipgloss Usage — Correct and Well-Structured

Adaptive color system in pkg/styles/theme.go: All 11 semantic colors (Error, Warning, Success, Info, Purple, Yellow, Comment, Foreground, Background, Border, TableAltRow) are defined as compat.AdaptiveColor{Light: ..., Dark: ...} with Dracula-inspired dark values and high-contrast light values.

TTY-aware rendering in pkg/console/console.go:

func applyStyle(style lipgloss.Style, text string) string {
    if isTTY() {
        return style.Render(text)
    }
    return text  // No ANSI codes in pipes/redirects
}

Table rendering uses lipgloss table with RoundedBorder, alternating row styles, and a StyleFunc for per-cell formatting — consistent across all tabular output.

Border styles are defined as package-level singletons (RoundedBorder, NormalBorder, ThickBorder) to avoid repeated allocation.

View full lipgloss style inventory (pkg/styles/theme.go)

• Error, Warning, Success, Info — semantic message styles
• FilePath, LineNumber, ColumnNumber — source location styles
• Bold, Faint, Italic — text emphasis
• RoundedBorder, NormalBorder, ThickBorder — border constants
• ColorError, ColorWarning, ColorSuccess, ColorInfo, ColorPurple, ColorYellow, ColorComment, ColorForeground, ColorBackground, ColorBorder, ColorTableAltRow — raw AdaptiveColor values for custom styles

---

✅ Huh Forms — Comprehensive and Accessible

All 15+ files using huh interactive forms follow the correct pattern:

form := huh.NewForm(formGroups...).
    WithTheme(styles.HuhTheme()).
    WithAccessible(console.IsAccessibleMode())

styles.HuhTheme() maps the full Dracula palette (primary, success, error, warning, comment, fg, bg, border) to all huh field states: focused/blurred, selected/unselected, buttons, text inputs, error indicators.

console.IsAccessibleMode() enables plain-text fallback when ACCESSIBLE, NO_COLOR, or TERM=dumb is set — covers screen readers and CI pipelines automatically.

Form types in use: Select, MultiSelect, Input, Confirm (including EchoModePassword for secrets).

View huh usage by file

File	Forms
pkg/cli/run_interactive.go	Workflow select, param inputs, confirm
pkg/cli/add_interactive_engine.go	Engine select
pkg/cli/add_interactive_auth.go	API key input (password)
pkg/cli/add_interactive_orchestrator.go	Confirm prompt
pkg/cli/add_interactive_schedule.go	Schedule frequency select
pkg/console/input.go	Generic password/secret input
pkg/console/confirm.go	Generic confirmation

---

✅ stdout / stderr Separation — Correct Throughout

All 21 fmt.Println/Printf calls writing to stdout are structured data outputs appropriate for piping:

• JSON exports: health_command.go, status_command.go, list_workflows_command.go, domains_command.go, deps_report.go, run_workflow_execution.go, compile_pipeline.go, trial_command.go
• Single-value outputs: hash_command.go (hash string), checks_command.go (state string)
• Diagram output: tool_graph.go (Mermaid graph), logs_report.go / status_command.go (rendered struct)
• Table output: mcp_list_tools.go, mcp_inspect_mcp.go

All diagnostic messages use fmt.Fprintln(os.Stderr, console.Format*(...)).

---

⚠️ Minor Issues

1. Hardcoded lipgloss.Color in pkg/console/progress.go

The progress bar uses hardcoded hex strings instead of the centralized styles.Color* constants:

// Current — hardcoded:
progress.WithColors(lipgloss.Color("#BD93F9"), lipgloss.Color("#8BE9FD"))
prog.EmptyColor = lipgloss.Color("#6272A4")

// Better — use constants:
progress.WithColors(lipgloss.Color(styles.hexColorPurpleDark), lipgloss.Color(styles.hexColorInfoDark))
// or via AdaptiveColor:
progress.WithColors(styles.ColorPurple, styles.ColorInfo)

The hardcoded values happen to match the Dracula dark palette, but they aren't adaptive — they won't adjust for light-background terminals. Low severity since progress bars are typically used interactively where dark defaults are common, but it breaks the adaptive color contract established elsewhere.

2. Dual lipgloss import in pkg/styles/huh_theme.go

huh_theme.go imports github.com/charmbracelet/lipgloss (v1) while the rest of the styles package uses charm.land/lipgloss/v2. This is necessary because huh v0.8.0 depends on lipgloss v1, not v2. The split is documented implicitly by the two go.mod entries but not explicitly in the file.

Recommendation: Add a comment in huh_theme.go explaining the intentional v1 import:

// Note: huh v0.8.0 depends on charmbracelet/lipgloss v1, not charm.land/lipgloss/v2.
// This file intentionally uses the v1 import to match huh's type expectations.
import "github.com/charmbracelet/lipgloss"

---

Recommendations

Priority	File	Recommendation
Low	pkg/console/progress.go:54,60	Replace hardcoded lipgloss.Color("#...") with styles.ColorPurple, styles.ColorInfo, styles.ColorComment to use adaptive light/dark variants
Low	pkg/styles/huh_theme.go:1	Add comment explaining the intentional lipgloss v1 import (huh compatibility)

No structural changes needed. The console output architecture is sound and internally consistent.

---

References: §23364944234

AI generated by Terminal Stylist · history

• expires on Mar 21, 2026, 10:28 PM UTC

[pelikhan]

/plan

[github-actions[bot]]

🚀 Plan Command has started processing this discussion comment

[github-actions[bot]]

This discussion has been marked as outdated by Terminal Stylist.

A newer discussion is available at Discussion #22199.