Summary

Analysis of all non-test Go source files in pkg/ and cmd/ for console output consistency. Overall, the codebase has a well-designed, centralized styling foundation (pkg/styles, pkg/console) and most CLI commands use it correctly. However, several files bypass the formatting system, creating inconsistent terminal output.

• Total fmt.Print* calls (non-test): ~150
• Properly formatted via console.*: ~100 ✅
• Structured stdout output (JSON/hashes/graphs): ~20 ✅ (correct per guidelines)
• Raw diagnostic output needing improvement: ~30 ⚠️

Architecture Overview

The styling system is well-structured:

• pkg/styles/theme.go — Centralized Lipgloss v2 styles with adaptive colors (light/dark variants using Dracula-inspired dark palette and high-contrast light variants). Provides Error, Warning, Success, Info, FilePath, Progress, Command, Verbose, TableHeader, TableCell, and more.
• pkg/console/console.go — TTY-aware wrappers: FormatSuccessMessage, FormatErrorMessage, FormatInfoMessage, FormatWarningMessage, FormatProgressMessage, FormatCommandMessage, FormatVerboseMessage, FormatListItem, RenderTable (using lipgloss/table).
• pkg/styles/huh_theme.go — Custom HuhTheme mapped to the Dracula palette for interactive forms.
• pkg/console/accessibility.go — IsAccessibleMode() detects ACCESSIBLE, TERM=dumb, or NO_COLOR.

✅ What's Working Well

Console Formatting — Correct Usage

These files consistently use console.Format*Message() with fmt.Fprintln(os.Stderr, ...):

• pkg/cli/logs_metrics.go — Extensive, correct use of Info/Warning/Success formatters (~40 calls)
• pkg/cli/compile_watch.go — All output via console formatters
• pkg/cli/tokens_bootstrap.go — All output via console formatters
• pkg/cli/run_workflow_validation.go — Uses FormatProgressMessage, FormatErrorWithSuggestions
• pkg/cli/compile_orchestrator.go — Correct warning messages

Structured Stdout Output — Correct Pattern

JSON, hashes, and graph output correctly goes to stdout (piping-friendly):

pkg/cli/tool_graph.go          fmt.Println(mermaidGraph)          ✅ mermaid graph
pkg/cli/deps_report.go         fmt.Println(string(jsonData))       ✅ JSON output
pkg/cli/list_workflows_command.go  fmt.Println(string(jsonBytes))  ✅ JSON output
pkg/cli/hash_command.go        fmt.Println(hash)                   ✅ hash output
pkg/cli/compile_pipeline.go    fmt.Println(jsonStr)                ✅ JSON output

Huh Forms — Well Integrated

Interactive forms are properly set up with the custom theme and accessibility support:

// run_interactive.go — correct pattern
form := huh.NewForm(formGroups...).WithTheme(styles.HuhTheme).WithAccessible(console.IsAccessibleMode())

Form fields used: huh.NewInput, huh.NewSelect, huh.NewMultiSelect, huh.NewConfirm, huh.NewText. Console wrappers (confirm.go, input.go, list.go) provide convenient building blocks.

Lipgloss — Properly Centralized

Zero direct lipgloss.* calls outside pkg/styles/ and pkg/console/. All lipgloss usage goes through the centralized style definitions, ensuring consistency. TTY detection is applied via applyStyle() which guards all styling.

⚠️ Areas Needing Improvement

1. Audit Report Renderers — Raw fmt.Printf to stdout

Files: pkg/cli/audit_cross_run_render.go (~60 calls), pkg/cli/audit_diff_render.go (~50 calls)

These files generate Markdown-formatted reports using dozens of raw fmt.Printf/fmt.Println calls to stdout. The markdown tables are formatted manually:

// ❌ Current — manual markdown table formatting
fmt.Printf("| Metric | Value |\n")
fmt.Printf("|--------|-------|\n")
fmt.Printf("| Runs analyzed | %d |\n", report.RunsAnalyzed)

Recommendation: The table sections could be rendered using console.RenderTable when a TTY is detected, with fallback to the current markdown format for pipes/redirects. This would produce styled, aligned tables in interactive terminals. Alternatively, add a --markdown flag that explicitly requests raw markdown output.

// ✅ Suggested — TTY-aware table rendering
if tty.IsStdoutTerminal() {
    fmt.Println(console.RenderTable(console.TableConfig{
        Title:   "Executive Summary",
        Headers: []string{"Metric", "Value"},
        Rows:    summaryRows,
    }))
} else {
    // current markdown output as fallback
}

2. deps_report.go — Manual Emoji Icons Without Console Formatting

File: pkg/cli/deps_report.go (~15 raw stderr calls)

Uses manual emoji and raw fmt.Fprintf(os.Stderr, ...) instead of console formatters:

// ❌ Current
fmt.Fprintf(os.Stderr, "🔴 CRITICAL: Address %d security %s immediately\n", ...)
fmt.Fprintf(os.Stderr, "⚠️  Reduce v0.x exposure from %.0f%% to <30%%\n", v0Percentage)
fmt.Fprintf(os.Stderr, "Total dependencies: %d (%d direct, %d indirect)\n", ...)

// ✅ Suggested
fmt.Fprintln(os.Stderr, console.FormatErrorMessage(fmt.Sprintf("CRITICAL: Address %d security %s immediately", ...)))
fmt.Fprintln(os.Stderr, console.FormatWarningMessage(fmt.Sprintf("Reduce v0.x exposure from %.0f%% to <30%%", v0Percentage)))
fmt.Fprintln(os.Stderr, console.FormatInfoMessage(fmt.Sprintf("Total dependencies: %d (%d direct, %d indirect)", ...)))

3. mcp_inspect_inspector.go — Inconsistent Mixed Usage

File: pkg/cli/mcp_inspect_inspector.go (~8 raw stderr calls)

The same file uses console.FormatInfoMessage in some places and raw fmt.Fprintf(os.Stderr, ...) in others:

// ✅ Used correctly in some places
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("Starting stdio MCP servers..."))

// ❌ Inconsistent in other places
fmt.Fprintf(os.Stderr, "  • %s (%s)\n", config.Name, config.Type)
fmt.Fprintf(os.Stderr, "\n📡 %s (%s):\n", config.Name, config.Type)
fmt.Fprintf(os.Stderr, "  Container: %s\n", config.Container)

The MCP server details block (lines 158–173) should use console formatters or the console.RenderTable function.

4. remove_command.go — List Items Without FormatListItem

File: pkg/cli/remove_command.go (~6 calls)

List items bypass console.FormatListItem:

// ❌ Current
fmt.Fprintf(os.Stderr, "  %-20s - %s\n", name, workflowName)
fmt.Fprintf(os.Stderr, "  %s (compiled workflow)\n", filepath.Base(lockFile))

// ✅ Suggested
fmt.Fprintln(os.Stderr, console.FormatListItem(fmt.Sprintf("%-20s - %s", name, workflowName)))
fmt.Fprintln(os.Stderr, console.FormatListItem(fmt.Sprintf("%s (compiled workflow)", filepath.Base(lockFile))))

5. run_interactive.go — Manual Fallback Prompt Bypasses Huh

File: pkg/cli/run_interactive.go (lines 213–217)

A non-interactive fallback prompt uses raw fmt.Fprintf to stderr when the form library isn't available:

// ❌ Current — no console formatting, manual numbering
fmt.Fprintf(os.Stderr, "\nSelect a workflow to run:\n\n")
for i, wf := range workflows {
    fmt.Fprintf(os.Stderr, "  %d) %s\n", i+1, wf.Name)
}
fmt.Fprintf(os.Stderr, "\nSelect (1-%d): ", len(workflows))

This code path should use console.FormatPromptMessage for the prompt and console.FormatListItem for items.

6. devcontainer.go — Plain Messages Without Formatting

File: pkg/cli/devcontainer.go (lines 165, 192)

// ❌ Current
fmt.Fprintf(os.Stderr, "Updated existing devcontainer at %s\n", devcontainerPath)
fmt.Fprintf(os.Stderr, "Created new devcontainer at %s\n", devcontainerPath)

// ✅ Suggested
fmt.Fprintln(os.Stderr, console.FormatSuccessMessage(fmt.Sprintf("Updated existing devcontainer at %s", devcontainerPath)))
fmt.Fprintln(os.Stderr, console.FormatSuccessMessage(fmt.Sprintf("Created new devcontainer at %s", devcontainerPath)))

7. observability_insights.go — Manual Icon/Format Pattern

File: pkg/cli/observability_insights.go (lines 340–343)

// ❌ Current
fmt.Fprintf(os.Stderr, "  %s %s [%s]\n", icon, insight.Title, insight.Category)
fmt.Fprintf(os.Stderr, "     %s\n", insight.Summary)
fmt.Fprintf(os.Stderr, "     Evidence: %s\n", insight.Evidence)

These insight entries follow the same pattern as console formatters but don't benefit from TTY-aware styling or color coding based on severity.

Lipgloss Opportunities

Table Rendering in Audit Reports

The audit_cross_run_render.go and audit_diff_render.go files generate multiple markdown tables. The console.RenderTable function (backed by lipgloss/table) already exists and supports:

• Zebra striping (alternating row colors)
• Rounded borders
• TTY-aware rendering (plain text fallback for pipes)
• Adaptive colors

Using console.RenderTable for the summary/metrics tables would improve terminal readability while preserving pipe-safe markdown output via a fallback.

CountMessage Format Function

The pkg/styles package has a Count style (bold cyan) but pkg/console/console.go is missing a corresponding FormatCountMessage wrapper. Several files could use this for numeric statistics:

// Suggested addition to pkg/console/console.go
func FormatCountMessage(message string) string {
    return applyStyle(styles.Count, "# ") + message
}

Huh Forms Recommendations

Accessible Mode Consistency

run_interactive.go:317 correctly uses .WithAccessible(console.IsAccessibleMode()), but add_interactive_auth.go:45 and add_interactive_workflow.go:104 do not set .WithAccessible(). All forms should include this option.

// ✅ Consistent accessible mode
form := huh.NewForm(...).WithTheme(styles.HuhTheme).WithAccessible(console.IsAccessibleMode())

Non-Interactive Fallback

The manual fmt.Scanf fallback in run_interactive.go (lines 213-254) could be replaced with console.IsAccessibleMode() check plus a simpler console.ShowInteractiveList call, leveraging the accessible mode built into Huh forms.

Priority Summary

References:

• §24030865029

Generated by Terminal Stylist · ● 1.1M · ◷

• expires on Apr 7, 2026, 12:03 PM UTC