[terminal-stylist] Terminal Stylist Audit: Console Output Analysis

[github-actions[bot]]

This report analyzes console output patterns across the 728 non-test Go source files in pkg/, focusing on consistency, Lipgloss v2 usage, Huh v2 integration, and adherence to the project's console formatting guidelines.

---

Executive Summary

Category	Finding
Total source files scanned	728
Files using console.* formatters	146
Files using raw fmt.Fprintf(os.Stderr, ...)	57
Files using structured stdout (fmt.Println)	13
Lipgloss adaptive color patterns	✅ Excellent
Huh form integration	✅ Good
TTY detection	✅ Implemented
pkg/workflow/ console compliance	⚠️ Partially
pkg/cli/ console compliance	⚠️ Mixed

---

✅ What's Working Well

Lipgloss v2 Integration (pkg/console/console.go, pkg/styles/theme.go, pkg/console/banner.go)

The console package is a well-engineered Lipgloss v2 integration:

• Adaptive colors — all six semantic color tokens use compat.AdaptiveColor with distinct Light/Dark hex pairs (Dracula palette for dark, muted variants for light), e.g.:

  Error: compat.AdaptiveColor{
      Light: lipgloss.Color(hexColorErrorLight), // Darker red for light
      Dark:  lipgloss.Color(hexColorErrorDark),   // Bright red (Dracula)
  }

• TTY detection — applyStyle() checks tty.IsStdoutTerminal() before applying any Lipgloss rendering, ensuring pipes and redirects receive plain text.
• Rich layout features — RenderTable() uses lipgloss/table with a styleFunc for header vs. data rows, alternating row highlighting, and full border control.
• Box/section rendering — FormatSectionHeader() uses lipgloss.DoubleBorder() with centered alignment; verbose sections use lipgloss.NormalBorder() with left-side only (false, false, false, true).
• 20 files use RenderTable and the advanced layout APIs.

Huh v2 Integration (pkg/console/confirm.go, pkg/console/list.go)

• ShowInteractiveList wraps huh.NewSelect[string]() inside a huh.NewForm/huh.NewGroup, correctly using typed options (huh.Option[string]).
• Confirm() uses huh.NewConfirm() with title/description fields and validation.
• The pkg/cli/add_interactive_*.go wizard files (add_interactive_auth.go, add_interactive_engine.go, add_interactive_git.go, add_interactive_orchestrator.go, add_interactive_schedule.go, add_interactive_secrets.go, add_interactive_workflow.go) compose multi-field Huh forms for the workflow creation wizard.
• pkg/console/spinner.go explicitly documents compatibility with Huh event handling: "events that should be handled by subsequent interactive forms (e.g. huh.Select)".

Structured stdout output (intentional)

The following files correctly send structured data (JSON, hashes, Mermaid graphs, Markdown reports) to stdout, conforming to Unix convention for pipeable output:

File	Output type
audit_cross_run_render.go	Markdown report
audit_diff_render.go	Markdown diff report
checks_command.go	State string
compile_pipeline.go	JSON
deps_report.go	JSON
domains_command.go	JSON
hash_command.go	SHA hash
health_command.go	JSON
list_workflows_command.go	JSON
run_workflow_execution.go	JSON
status_command.go	JSON
tool_graph.go	Mermaid graph
trial_helpers.go	JSON

---

⚠️ Areas for Improvement

1. Raw fmt.Fprintf(os.Stderr, ...) without console formatting

292 raw stderr calls were found outside the console package itself. The most impactful clusters:

pkg/workflow/ — 57 files using raw stderr (not console-formatted)

The pkg/workflow package does import pkg/console (38 files import it), yet several files bypass the formatting layer:

pkg/workflow/cache.go — warning-level messages emitted as raw strings:

// ❌ Current
fmt.Fprintf(os.Stderr, "Warning: Failed to parse cache configuration: %v\n", err)

// ✅ Recommended
fmt.Fprintln(os.Stderr, console.FormatWarningMessage(fmt.Sprintf("Failed to parse cache configuration: %v", err)))

pkg/workflow/claude_logs.go — 6 raw diagnostic calls (mix of errors, info, and debug):

// ❌ Current — diagnostic info mixed with raw prints
fmt.Fprintf(os.Stderr, "Extracted %d JSON entries from mixed format Claude log\n", len(logEntries))

// ✅ Recommended — most of these should use the logger (not stderr at all)
log.Printf("Extracted %d JSON entries from mixed format Claude log", len(logEntries))

Note: claude_logs.go messages appear to be debug diagnostics that should use pkg/logger rather than stderr.

pkg/workflow/mcp_renderer.go:

// ❌ Current
fmt.Fprintf(os.Stderr, "Error generating custom MCP configuration for %s: %v\n", toolName, err)

// ✅ Recommended
fmt.Fprintln(os.Stderr, console.FormatErrorMessage(fmt.Sprintf("Error generating custom MCP configuration for %s: %v", toolName, err)))

pkg/cli/ — Notable raw stderr clusters

pkg/cli/enable.go — 12 raw stderr calls for status messages:

// ❌ Current
fmt.Fprintf(os.Stderr, "Workflow %s is already enabled\n", name)
fmt.Fprintf(os.Stderr, "The following workflows will be %sd:\n", action)

// ✅ Recommended
fmt.Fprintln(os.Stderr, console.FormatInfoMessage(fmt.Sprintf("Workflow %s is already enabled", name)))
fmt.Fprintln(os.Stderr, console.FormatInfoMessage(fmt.Sprintf("The following workflows will be %sd:", action)))

pkg/cli/deps_security.go — raw line-by-line printing instead of table or formatted output:

// ❌ Current
fmt.Fprintln(os.Stderr, line)
fmt.Fprintf(os.Stderr, "    %s", adv.Summary)

// ✅ Recommended — use console.RenderTable for advisory listing

pkg/cli/audit.go — log file paths printed as raw indented list:

// ❌ Current
fmt.Fprintf(os.Stderr, "  - %s (full job log)\n", jobLogPath)

// ✅ Recommended
fmt.Fprintln(os.Stderr, console.FormatListItem(fmt.Sprintf("%s (full job log)", jobLogPath)))

2. Diagnostic messages in pkg/workflow/ that belong in the logger

Several fmt.Fprintf(os.Stderr, ...) calls in pkg/workflow/ emit detailed diagnostic information (token counts, JSON parse attempts, line-skipping notices) that are better suited for the pkg/logger debug infrastructure:

// ❌ Current — always prints to stderr
fmt.Fprintf(os.Stderr, "Extracted from Claude result payload: tokens=%d, cost=%.4f, turns=%d\n", ...)
fmt.Fprintf(os.Stderr, "Skipping invalid JSON line: %s\n", trimmedLine)

// ✅ Recommended — only visible with DEBUG=workflow:claude_logs
var log = logger.New("workflow:claude_logs")
log.Printf("Extracted from Claude result payload: tokens=%d, cost=%.4f, turns=%d", ...)
log.Printf("Skipping invalid JSON line: %s", trimmedLine)

3. Missing FormatCountMessage and FormatLocationMessage usage

The console package exposes FormatCountMessage and FormatLocationMessage but they are underutilized — only 20 files use the advanced format functions combined. Many places that render counts or file paths use raw strings.

---

Recommendations

Priority	Recommendation
🔴 High	Migrate diagnostic messages in pkg/workflow/claude_logs.go from fmt.Fprintf(os.Stderr, ...) to pkg/logger calls — they're debug-only information that should be gated behind DEBUG=workflow:*.
🟠 Medium	Replace raw fmt.Fprintf(os.Stderr, "Warning: ...") in pkg/workflow/cache.go and pkg/workflow/mcp_renderer.go with console.FormatWarningMessage / console.FormatErrorMessage.
🟠 Medium	Standardize pkg/cli/enable.go status messages using console.FormatInfoMessage and console.FormatSuccessMessage for visual consistency with other CLI commands.
🟡 Low	Consider using console.RenderTable in pkg/cli/deps_security.go to display security advisories as a formatted table rather than line-by-line printing.
🟡 Low	Add FormatLocationMessage usage for file path output in pkg/cli/audit.go to improve visual hierarchy when listing log file paths.
🟢 Informational	The audit render files (audit_cross_run_render.go, audit_diff_render.go) use raw fmt.Printf for Markdown output — this is intentional and correct since these are structured document outputs for piping/saving.

---

Architecture Observations

The pkg/console package is a solid foundation:

• Charmbracelet ecosystem fully integrated: Lipgloss v2 + Huh v2 + Bubble Tea (spinner)
• Adaptive theming done correctly — no hardcoded ANSI sequences
• TTY-aware rendering throughout
• The Huh wizard (add_interactive_*.go) shows good multi-step form composition patterns

The primary gap is inconsistent adoption in lower-level packages (pkg/workflow/) where console formatting was not applied during initial implementation. A targeted pass over pkg/workflow/cache.go, pkg/workflow/claude_logs.go, and pkg/workflow/mcp_renderer.go would resolve the most visible cases.

---

References:

• §25052124795

Generated by Terminal Stylist · ● 704.1K · ◷

• expires on Apr 29, 2026, 12:19 PM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Terminal Stylist.

A newer discussion is available at Discussion #29103.