Terminal Stylist Audit: Console Output Consistency Analysis

[github-actions[bot]]

This report covers all non-test Go source files in pkg/ and cmd/ — scanning for console output patterns, Lipgloss styling, and Huh form usage. Run triggered by workflow §23743626795.

---

Summary

The codebase is in strong shape for terminal output consistency. The pkg/console package is comprehensive and widely adopted, with 1,319 uses of console formatting functions. Lipgloss and Huh are properly integrated with TTY detection and adaptive colors. A small number of files bypass console formatting for stderr writes — detailed below.

Category	Status
Console formatting adoption	✅ 1,319 usages
Lipgloss TTY detection	✅ Correct (via applyStyle())
Adaptive colors	✅ compat.AdaptiveColor in pkg/styles
Huh forms — theme consistency	✅ All 16 forms use WithTheme + WithAccessible
Stdout vs stderr routing	✅ Structured output to stdout; diagnostics to stderr
Unformatted stderr writes	⚠️ ~30 instances across 7 files

---

Lipgloss Usage

Library: charm.land/lipgloss/v2 (current major version) with charm.land/lipgloss/v2/table.

Strengths:

• applyStyle() in pkg/console/console.go wraps all styling with a TTY gate — ANSI codes are suppressed when output is piped
• compat.AdaptiveColor{Light: ..., Dark: ...} used throughout pkg/styles/theme.go for full light/dark terminal support
• Rich rendering primitives: RenderTitleBox, RenderErrorBox, RenderInfoSection, RenderComposedSections, RenderTable, FormatError (Rust-like compiler errors with source context)

Known version split (by design):
pkg/styles/huh_theme.go must import github.com/charmbracelet/lipgloss (v1) because charmbracelet/huh depends on v1. This is correctly documented in the file and is not a bug — it's a transitional state until huh upgrades to v2.

---

Huh Form Usage

16 form instances found across 9 files. All are consistent:

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

• styles.HuhTheme() maps the Dracula-inspired CLI palette to huh field styles (focus, blur, buttons, inputs, selects)
• console.IsAccessibleMode() respects the GH_ACCESSIBLE environment variable
• TTY guard in pkg/console/input.go correctly rejects non-TTY environments before showing interactive prompts
• Field types used: Confirm, Select[string], Input (plain + password-masked), multi-group forms
• Validation callbacks implemented in password forms

Files: add_interactive_auth.go, add_interactive_engine.go, add_interactive_git.go, add_interactive_orchestrator.go, add_interactive_schedule.go, add_interactive_workflow.go, engine_secrets.go, interactive.go, run_interactive.go

---

Unformatted Stderr Writes (Improvement Opportunities)

The following files write to os.Stderr directly without going through console formatting helpers. These are non-critical but inconsistent with the rest of the codebase.

pkg/cli/compile_watch.go — 5 raw writes

// Line 107
fmt.Fprintln(os.Stderr, "Press Ctrl+C to stop watching.")

// Line 123, 141
fmt.Fprintln(os.Stderr, "Watching for file changes")

// Line 125
fmt.Fprintln(os.Stderr, "🔨 Initial compilation of all workflow files...")

// Line 227
fmt.Fprintln(os.Stderr, "\n🛑 Stopping watch mode...")

Adjacent lines already use console.FormatInfoMessage and console.FormatProgressMessage. These should be consistent:

fmt.Fprintln(os.Stderr, console.FormatInfoMessage("Press Ctrl+C to stop watching."))
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("Watching for file changes"))
fmt.Fprintln(os.Stderr, console.FormatProgressMessage("Initial compilation of all workflow files..."))
fmt.Fprintln(os.Stderr, console.FormatWarningMessage("Stopping watch mode..."))

pkg/cli/mcp_inspect_inspector.go — 8 raw writes

// Line 76 — list item without formatting
fmt.Fprintf(os.Stderr, "  • %s (%s)\n", config.Name, config.Type)

// Line 158 — section header without formatting  
fmt.Fprintf(os.Stderr, "\n📡 %s (%s):\n", config.Name, config.Type)

// Lines 162–173 — key-value pairs without formatting
fmt.Fprintf(os.Stderr, "  Container: %s\n", config.Container)
fmt.Fprintf(os.Stderr, "  Command: %s\n", config.Command)
// etc.

console.FormatListItem() exists precisely for the bullet-point pattern:

fmt.Fprintln(os.Stderr, console.FormatListItem(fmt.Sprintf("%s (%s)", config.Name, config.Type)))

The configuration details block could be rendered with console.RenderInfoSection() for visual consistency.

pkg/cli/observability_insights.go — 4 raw writes

// Lines 336–341
fmt.Fprintf(os.Stderr, "  %s %s [%s]\n", icon, insight.Title, insight.Category)
fmt.Fprintf(os.Stderr, "     %s\n", insight.Summary)
if insight.Evidence != "" {
    fmt.Fprintf(os.Stderr, "     Evidence: %s\n", insight.Evidence)
}

This builds its own icon+title+category layout that bypasses console formatting entirely. A structured approach using console.FormatSectionHeader and console.FormatListItem would be more consistent.

pkg/cli/devcontainer.go — 2 raw writes

// Line 164
fmt.Fprintf(os.Stderr, "Updated existing devcontainer at %s\n", devcontainerPath)

// Line 191
fmt.Fprintf(os.Stderr, "Created new devcontainer at %s\n", devcontainerPath)

These are success messages that should use console.FormatSuccessMessage:

fmt.Fprintln(os.Stderr, console.FormatSuccessMessage(fmt.Sprintf("Updated existing devcontainer at %s", devcontainerPath)))

pkg/cli/deps_report.go — 8 raw writes

Lines 112–163 mix console-formatted and raw stderr writes within the same render functions. The raw writes output numeric summary lines like "Total dependencies: %d (%d direct, %d indirect)\n" — these could use console.FormatInfoMessage or the RenderTable helper for tabular summary data.

pkg/cli/update_display.go — 1 raw write

// Line 27 — nested under FormatErrorMessage header but uses raw format
fmt.Fprintf(os.Stderr, "  %s: %s\n", failure.Name, failure.Error)

Should use console.FormatListItem(failure.Name + ": " + failure.Error) to match the list items rendered for successes on line 18.

pkg/cli/add_interactive_auth.go — 1 raw write

// Line 28
fmt.Fprintln(os.Stderr, "Please navigate to a git repository or initialize one with:")

Should use console.FormatInfoMessage or console.FormatWarningMessage.

---

Stdout Output (Correct Patterns)

The following files use fmt.Println / fmt.Printf to stdout — all are intentionally outputting structured/piped data:

File	Output type	Assessment
audit_cross_run_render.go	Markdown report	✅ Intentional stdout for piping
audit_diff_render.go	Markdown diff	✅ Intentional stdout for piping
checks_command.go:413	Machine-readable state string	✅ Correct stdout
compile_pipeline.go, deps_report.go	JSON	✅ Correct stdout
domains_command.go, health_command.go	JSON	✅ Correct stdout
hash_command.go	Hash string	✅ Correct stdout
list_workflows_command.go	JSON	✅ Correct stdout
run_workflow_execution.go, status_command.go	JSON	✅ Correct stdout
tool_graph.go	Mermaid graph	✅ Correct stdout
trial_command.go	JSON	✅ Correct stdout

---

Recommendations

1. High value, low effort: Fix the 5 raw writes in compile_watch.go — the surrounding code already uses console formatting and the inconsistency is visually noticeable when watching files
2. Medium effort: Standardize mcp_inspect_inspector.go config display using RenderInfoSection for the detailed server block
3. Low effort: devcontainer.go, update_display.go, and add_interactive_auth.go are each 1–2 line fixes
4. Design consideration: observability_insights.go has a custom multi-line layout that doesn't map cleanly to a single console helper — consider a new console.RenderInsight(icon, title, category, summary, evidence string) helper if this pattern repeats

No architectural changes are needed. The Lipgloss and Huh integration is excellent and the console package is a well-designed abstraction.

---

References: §23743626795

AI generated by Terminal Stylist · history

• expires on Mar 31, 2026, 12:08 PM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Terminal Stylist.

A newer discussion is available at Discussion #23683.