Terminal Stylist Report: Console Output Analysis

[github-actions[bot]]

This report analyzes console output patterns across 622 Go source files in the pkg/ directory, evaluating consistency, Lipgloss usage, Huh form implementations, and output routing.

---

Summary

Category	Status	Notes
Console package design	✅ Excellent	Lipgloss v2, adaptive colors, TTY detection
Huh form consistency	✅ Good	Theme + accessibility applied consistently
Output routing (stderr/stdout)	✅ Correct	Diagnostic → stderr, structured data → stdout
Lipgloss adaptive colors	✅ Used	Light/dark variants via compat.AdaptiveColor
WASM/non-WASM API parity	⚠️ Gap	3 functions missing from non-WASM console
Inline format inconsistencies	⚠️ Minor	Some diagnostic lines skip console formatting
Markdown report rendering	ℹ️ Opportunity	Could benefit from Lipgloss tables in TTY mode

---

Architecture Overview

The codebase uses a well-structured layered approach to terminal output:

pkg/styles/theme.go          → Centralized colors (Dracula-inspired) via compat.AdaptiveColor
pkg/console/console.go       → Format helpers (FormatInfoMessage, FormatErrorMessage, etc.)
pkg/styles/huh_theme.go      → Huh form theme bridging styles ↔ charmbracelet/lipgloss v1
pkg/tty/tty.go               → TTY detection primitives

Lipgloss version strategy:

• Primary: charm.land/lipgloss/v2 with charm.land/lipgloss/v2/compat for adaptive colors
• Huh-only: github.com/charmbracelet/lipgloss (v1) isolated to pkg/styles/huh_theme.go (required by huh's type system)

---

✅ What's Working Well

1. Adaptive Color System

pkg/styles/theme.go defines 10 semantic compat.AdaptiveColor pairs covering all CLI use cases:

ColorError   = compat.AdaptiveColor{Light: "#D73737", Dark: "#FF5555"}   // Dracula red
ColorSuccess = compat.AdaptiveColor{Light: "#27AE60", Dark: "#50FA7B"}   // Dracula green
ColorInfo    = compat.AdaptiveColor{Light: "#2980B9", Dark: "#8BE9FD"}   // Dracula cyan
// ... 7 more

Light mode uses saturated/darker colors; dark mode uses Dracula theme bright colors. This ensures readability across both terminal themes.

2. TTY-Aware Styling

The applyStyle() guard in console.go is consistently applied to all styled output:

func applyStyle(style lipgloss.Style, text string) string {
    if isTTY() {
        return style.Render(text)
    }
    return text  // Plain text in non-TTY (pipes, CI, etc.)
}

RenderTable, RenderTitleBox, RenderErrorBox, and RenderInfoSection all check isTTY() / IsStderrTerminal() before applying Lipgloss layout.

3. Console Message Formatting Usage

The console.* functions are widely used — 553 calls to console.FormatInfoMessage alone:

Function	Call Count
FormatInfoMessage	553
FormatWarningMessage	392
FormatSuccessMessage	188
FormatVerboseMessage	61
FormatErrorMessage	57
LogVerbose	38
FormatSectionHeader	36
RenderTable	27
FormatCommandMessage	20
FormatProgressMessage	13
RenderStruct	12

4. Correct Output Routing

All 14 files using fmt.Println/fmt.Printf to stdout are printing structured data (not diagnostics):

• JSON output: compile_pipeline.go, status_command.go, health_command.go, run_workflow_execution.go, domains_command.go, list_workflows_command.go, deps_report.go, trial_command.go
• Hash output: hash_command.go
• Mermaid graph: tool_graph.go
• Markdown reports: audit_cross_run_render.go, audit_diff_render.go
• Struct rendering: logs_report.go, status_command.go (via console.RenderStruct)

This correctly allows piping and redirection without mixing diagnostic noise.

5. Huh Forms — Consistent Configuration

All 10+ Huh form usages apply the same configuration pattern:

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

IsAccessibleMode() checks ACCESSIBLE, TERM=dumb, and NO_COLOR environment variables, ensuring the forms degrade gracefully in CI/screen-reader environments.

PromptSecretInput and add_interactive_auth.go correctly use huh.EchoModePassword and .Validate() for secure inputs.

6. Error Rendering

FormatError() implements Rust-inspired error rendering with:

• File path highlighting (purple)
• Line/column context with source code snippets
• ^ pointer underlining the error token
• Hint messages in info color

FormatErrorChain() intelligently unwraps fmt.Errorf("%w", ...) chains, displaying each level with proper indentation.

---

⚠️ Issues & Recommendations

Issue 1: API Gap Between WASM and Non-WASM Console

Three functions exist in pkg/console/console_wasm.go but are absent from pkg/console/console.go:

Function	Wasm	Non-Wasm	Usage
FormatLocationMessage	✅	❌	0 callers
FormatCountMessage	✅	❌	0 callers
FormatListHeader	✅	❌	0 callers

These functions are currently unused so there is no runtime issue, but the API asymmetry is a latent inconsistency. If a caller ever uses these on a non-WASM build (e.g., referencing console.FormatLocationMessage in CLI code), it will fail to compile.

Recommendation: Add the missing implementations to console.go:

// FormatLocationMessage formats a file/directory location message
func FormatLocationMessage(message string) string {
    return applyStyle(styles.Location, "📁 ") + message
}

// FormatCountMessage formats a count/metric message
func FormatCountMessage(message string) string {
    return applyStyle(styles.Count, "📊 ") + message
}

// FormatListHeader formats a section header for a list
func FormatListHeader(header string) string {
    return applyStyle(styles.ListHeader, header)
}

Note: styles.Location (bold orange) already exists in pkg/styles/theme.go. styles.Count and styles.ListHeader also already exist.

---

Issue 2: Plain fmt.Fprintf for Inline Diagnostics in audit_report_render.go

Line 936:

fmt.Fprintf(os.Stderr, "  Prompt Size:       %s chars\n", console.FormatNumber(analysis.PromptSize))

This mixes the console.FormatNumber helper with raw fmt.Fprintf, bypassing the bullet/icon formatting that other diagnostic lines in the same file use. Nearby lines all use fmt.Fprintln(os.Stderr, console.FormatXMessage(...)).

Recommendation: Use a consistent pattern:

fmt.Fprintln(os.Stderr, console.FormatInfoMessage(
    fmt.Sprintf("Prompt Size: %s chars", console.FormatNumber(analysis.PromptSize)),
))

---

Issue 3: audit_cross_run_render.go and audit_diff_render.go — Raw Markdown Tables to Stdout

These two render files output GitHub Flavored Markdown to stdout for piping into issues/PRs. They use raw fmt.Printf to construct pipe-delimited tables:

fmt.Printf("| Metric | Value |\n")
fmt.Printf("|--------|-------|\n")
fmt.Printf("| Runs analyzed | %d |\n", report.RunsAnalyzed)

This is intentionally correct for their primary use case (piped Markdown). However, when consumed interactively in a terminal, the raw Markdown is unrendered.

Opportunity: Consider adding a TTY-aware rendering path using console.RenderTable():

if tty.IsStdoutTerminal() {
    // Rich Lipgloss table for interactive use
    fmt.Print(console.RenderTable(console.TableConfig{...}))
} else {
    // GitHub Flavored Markdown for piping
    fmt.Printf("| Metric | Value |\n")
    // ...
}

This would match the pattern already used by RenderTitleBox and RenderErrorBox in console.go.

---

Issue 4: Optional — Huh Form Validation Coverage

Most interactive wizard forms (add_interactive_engine.go, add_interactive_git.go, add_interactive_orchestrator.go, add_interactive_schedule.go) do not use .Validate() on their input fields. The auth form and engine_secrets.go forms do use validation.

For user-facing forms collecting structured data (engine names, repository paths, schedule expressions), adding .Validate() would prevent silent failures downstream.

Example pattern (from add_interactive_auth.go):

huh.NewInput().
    Title("GitHub Token").
    Validate(func(s string) error {
        if len(s) == 0 {
            return errors.New("token cannot be empty")
        }
        return nil
    }).
    Value(&token)

---

Files Summary

Files with excellent console formatting compliance (sample)

These files consistently use console.* formatters for all diagnostic output:

• pkg/cli/add_command.go
• pkg/cli/compile_file_operations.go
• pkg/cli/compile_orchestrator.go
• pkg/cli/compile_post_processing.go
• pkg/cli/mcp_list.go
• pkg/cli/mcp_inspect_list.go
• pkg/cli/audit_report_render.go (mostly, see Issue 2)
• pkg/cli/deps_outdated.go
• pkg/cli/pr_command.go

Files outputting structured data to stdout (correct pattern)

These files output structured data (JSON/hash/graph) to stdout per Unix conventions:

• pkg/cli/audit_cross_run_render.go — Markdown report
• pkg/cli/audit_diff_render.go — Markdown diff
• pkg/cli/compile_pipeline.go — JSON output
• pkg/cli/deps_report.go — JSON output
• pkg/cli/domains_command.go — JSON output
• pkg/cli/hash_command.go — Hash output
• pkg/cli/health_command.go — JSON output
• pkg/cli/list_workflows_command.go — JSON output
• pkg/cli/logs_report.go — Struct rendering
• pkg/cli/run_workflow_execution.go — JSON output
• pkg/cli/status_command.go — JSON + struct rendering
• pkg/cli/tool_graph.go — Mermaid graph
• pkg/cli/trial_command.go — JSON output

---

Recommendations Priority

Priority	Action
Low	Add FormatLocationMessage, FormatCountMessage, FormatListHeader to console.go to close WASM/non-WASM API gap
Low	Fix audit_report_render.go:936 inline fmt.Fprintf to use console formatting
Informational	Consider TTY-aware rich rendering in audit_cross_run_render.go and audit_diff_render.go
Informational	Add .Validate() to wizard form inputs for better UX

References:

• §23847430517

AI generated by Terminal Stylist · history

• expires on Apr 2, 2026, 12:07 PM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Terminal Stylist.

A newer discussion is available at Discussion #24088.