[terminal-stylist] Console Output Audit: Patterns & Recommendations

[github-actions[bot]]

This report analyzes console output patterns across pkg/ Go source files (excluding test files), covering Lipgloss styling, Huh forms, TTY detection, and adherence to style guidelines.

---

Summary

Category	Count
Files using console.Format*/Render* correctly	137
Files with raw fmt.Fprintf/Fprintln(os.Stderr)	139
Total fmt.Println/Printf to stdout	161
Files using Huh forms	10

The codebase has a strong foundation: well-designed pkg/console and pkg/styles packages, consistent Huh theming, and proper TTY detection. The main gap is a significant number of raw fmt.Fprintf(os.Stderr, ...) calls bypassing the console formatting layer.

---

✅ Strengths

Lipgloss — Excellent Architecture

pkg/styles/theme.go is a model implementation:

• Adaptive color system via compat.AdaptiveColor — all colors automatically adjust for light/dark terminal backgrounds
• Dracula-inspired dark theme palette with thoughtful light-mode counterparts
• Centralized border definitions (RoundedBorder, NormalBorder, ThickBorder)
• Pre-configured named styles for every use case: Error, Warning, Success, Info, FilePath, Command, Progress, TableHeader, etc.

pkg/console/console.go wraps all Lipgloss usage behind TTY-aware helpers:

func applyStyle(style lipgloss.Style, text string) string {
    if isTTY() {
        return style.Render(text)
    }
    return text  // plain text for pipes/redirects
}

RenderTable uses lipgloss/table with zebra-striping, header/total row differentiation, and graceful TTY-off degradation. RenderComposedSections, RenderTitleBox, RenderErrorBox, and RenderInfoSection all provide consistent layout primitives with TTY detection.

Huh Forms — Consistent and Accessible

All 10 Huh form usages follow best practices:

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

• Custom HuhTheme in pkg/styles/huh_theme.go correctly maps the Dracula palette to every field state (focused, blurred, selected, error)
• WithAccessible(console.IsAccessibleMode()) is applied universally — screen reader support is not an afterthought
• Password inputs consistently use EchoMode(huh.EchoModePassword)
• pkg/console/confirm.go, list.go, and input.go provide convenient wrappers for common form patterns

Structured Output Routing

Structured data correctly goes to stdout:

• JSON output: fmt.Println(string(jsonBytes)) ✅
• Markdown reports (audit_cross_run_render.go): fmt.Printf("| ... |") ✅
• Hashes, graphs: fmt.Println(hash) ✅

---

⚠️ Issues to Address

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

~139 files write to stderr bypassing the console formatting package. Messages lose color, icons (✓ ✗ ⚠ i), and styling context. Examples:

// ❌ pkg/cli/enable.go
fmt.Fprintf(os.Stderr, "Workflow %s is already enabled\n", name)
fmt.Fprintf(os.Stderr, "The following workflows will be %sd:\n", action)
fmt.Fprintf(os.Stderr, "%sd workflow: %s\n", action, t.Name)

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

// ❌ pkg/cli/compile_file_operations.go
fmt.Fprintln(os.Stderr, "Watching for file changes")
fmt.Fprintln(os.Stderr, err.Error())  // raw error, no FormatErrorMessage

// ❌ pkg/cli/add_interactive_secrets.go
fmt.Fprintf(os.Stderr, "Found %d existing secret(s)...\n", len(c.existingSecrets))

Fix pattern:

// ✅ Consistent with style guidelines
fmt.Fprintln(os.Stderr, console.FormatSuccessMessage("Workflow "+name+" is already enabled"))
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("The following workflows will be enabled:"))
fmt.Fprintln(os.Stderr, console.FormatProgressMessage("Watching for file changes"))
fmt.Fprintln(os.Stderr, console.FormatErrorMessage(err.Error()))

Priority files (most impactful):

• pkg/cli/enable.go — ~15 raw stderr calls for workflow enable/disable status
• pkg/cli/deps_security.go — ~8 raw stderr calls for vulnerability advisories
• pkg/cli/deps_outdated.go — raw blank-line spacing to stderr
• pkg/cli/audit.go — file path listings without FormatLocationMessage
• pkg/cli/compile_file_operations.go — watch mode messages

2. Missing FormatLocationMessage wrapper

pkg/styles/theme.go defines a Location style (bold orange) but pkg/console/console.go doesn't expose a FormatLocationMessage helper. File path listings in audit.go use raw fmt.Fprintf:

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

// ✅ Would benefit from:
// console.FormatLocationMessage(path) — parallels FormatCommandMessage

3. Blank-line spacing via raw fmt.Fprintln(os.Stderr, "")

deps_outdated.go, deps_security.go, and update_container_pins.go use fmt.Fprintln(os.Stderr, "") for vertical spacing rather than a spacing utility. This is minor but adds inconsistency.

---

Recommendations

Recommendation 1: Sweep raw stderr calls in high-traffic commands

Prioritize enable.go and deps_security.go for a formatting pass. Each call should map to the most semantically appropriate helper:

Raw message type	Console formatter
"Successfully Xd workflow"	FormatSuccessMessage
"Already enabled/disabled"	FormatInfoMessage
"Will be Xd:" list	FormatInfoMessage + FormatListItem
File path listings	FormatLocationMessage (to be added)
Watch mode status	FormatProgressMessage
Error output	FormatErrorMessage

Recommendation 2: Add FormatLocationMessage to pkg/console

The Location style exists in pkg/styles but has no corresponding FormatLocationMessage in pkg/console/console.go. Add:

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

This would clean up file-path listing patterns in audit.go and similar commands.

Recommendation 3: Consider a spacing helper for vertical whitespace

Replace scattered fmt.Fprintln(os.Stderr, "") with a simple helper:

// PrintSeparator prints a blank line to stderr for visual separation
func PrintSeparator() {
    fmt.Fprintln(os.Stderr, "")
}

This is low-priority but would make spacing intent explicit.

Recommendation 4: Evaluate Huh forms for remaining interactive prompts

run_interactive.go and some add_wizard_command.go paths may still use bufio.Scanner or raw terminal reads. Given the existing Huh infrastructure and HuhTheme, these could be upgraded to proper form fields for consistent styling and accessibility.

---

Overall Assessment

The console output architecture is well-designed and modern. The pkg/styles + pkg/console + pkg/tty layered approach correctly separates concerns. Lipgloss adaptive colors are properly implemented for both light and dark terminals. Huh form integration is exemplary — themed, accessible, and consistently applied.

The primary gap is adoption coverage: ~139 files still bypass the console layer for stderr writes. A targeted sweep of the highest-traffic commands (enable.go, deps_security.go, compile_file_operations.go) would meaningfully improve output consistency.

References:

• §25164390973

Generated by Terminal Stylist · ● 473.1K · ◷

• expires on May 1, 2026, 12:11 PM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-05-01T12:11:00.190Z.

Closed by Workflow