Overview

This report audits console output patterns across 595 non-test Go source files in pkg/ and cmd/, covering usage of the console formatting package, Lipgloss (v2), and Huh interactive forms. The codebase demonstrates strong consistency and thoughtful design — diagnostic output reliably goes to stderr, structured data goes to stdout, and Charmbracelet ecosystem libraries are well-integrated. A few minor gaps are identified below.

Summary

Console Package Architecture

The pkg/console/ package is the central styling hub. It exports a rich set of formatting functions with consistent emoji prefixes and TTY-aware styling:

The applyStyle() helper unconditionally gates all styling behind isTTY() — no ANSI codes bleed into non-terminal output. This is excellent practice.

Lipgloss Usage Analysis

✅ Strengths

Adaptive colors throughout: pkg/styles/theme.go defines a complete palette using compat.AdaptiveColor (light/dark variants), covering Error, Warning, Success, Info, Purple, Yellow, and structural colors. These automatically adapt to the terminal background.

// Example: Adaptive color for error messages
ColorError = compat.AdaptiveColor{
    Light: lipgloss.Color("#D73737"), // Darker red for light backgrounds
    Dark:  lipgloss.Color("#FF5555"), // Bright red for dark backgrounds (Dracula)
}

TTY-aware rendering: console.go checks isTTY() or tty.IsStderrTerminal() before all rich rendering — RenderTitleBox, RenderErrorBox, RenderInfoSection, and RenderComposedSections all fall back to plain text gracefully.

Rich layout primitives: The console package uses lipgloss.JoinVertical, double-border boxes, rounded-border boxes, and left-border info sections — all with proper TTY guards.

**lipgloss/table for tabular (redacted) RenderTable uses the charm.land/lipgloss/v2/table package with alternating row colors, a styled header row, and an optional total row.

⚠️ Findings

1. Two lipgloss versions coexist (pkg/styles/huh_theme.go):

pkg/styles/huh_theme.go imports github.com/charmbracelet/lipgloss (v1) while the rest of the codebase uses charm.land/lipgloss/v2. This is intentional and necessary — github.com/charmbracelet/huh v0.8.0 depends on the v1 import path. The theme file bridges the two by mapping charm.land hex constants to v1 lipgloss.AdaptiveColor values. The types are incompatible across versions, so this separation is the correct approach.

2. Hardcoded hex colors in pkg/console/progress.go:

The progress bar uses hardcoded color literals instead of the theme constants:

// Current — bypasses theme system
progress.WithColors(lipgloss.Color("#BD93F9"), lipgloss.Color("#8BE9FD")),
prog.EmptyColor = lipgloss.Color("#6272A4")

These hex values match hexColorPurpleDark, hexColorInfoDark, and hexColorCommentDark defined in pkg/styles/theme.go, but bypass the adaptive system. In light-mode terminals the progress bar will render with dark-theme colors. Consider referencing the theme constants for consistency, or using styles.ColorPurple / styles.ColorInfo when charm.land/bubbles supports adaptive colors.

Huh Interactive Forms Analysis

✅ Strengths

Consistent form structure across all 12 files:
Every form follows the same pattern:

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

Custom theme integration: pkg/styles/huh_theme.go maps the Dracula-inspired palette to all huh field states — focused, blurred, options, buttons, and text inputs — giving forms the same visual identity as the rest of the CLI.

Accessibility mode support: console.IsAccessibleMode() detects ACCESSIBLE, TERM=dumb, or NO_COLOR environment variables. All forms pass this to .WithAccessible(), enabling plain-text mode for screen readers and CI environments.

Context-aware execution: Forms use form.RunWithContext(c.Ctx) (not bare form.Run()), enabling proper Ctrl-C handling and cancellation propagation.

Field types used: Input (with EchoModePassword for secrets), Select, Confirm — appropriate choices for the workflow wizard UX.

⚠️ Findings

3. pkg/cli/mcp_server_http.go uses standard log package:

import "log"
// ...
log.Printf("[REQUEST] %s | %s | %s %s", ...)
log.Printf("[RESPONSE] %s | %s | %s %s | Status: %d | Duration: %v", ...)

This is the only file using the standard log package. The rest of the codebase uses logger.New("pkg:file") (the project's debug logger), which respects DEBUG=* environment variables and avoids cluttering normal output. The HTTP request/response logs will print to stdout unconditionally, which could be noisy in non-debug usage.

Output Routing Compliance

All 20 fmt.Println calls to stdout are intentional structured output (JSON payloads, hashes, Mermaid graphs, state strings) — correct per the codebase's output routing convention. No diagnostic messages were found going to stdout.

Note: mcp_list_tools.go, mcp_inspect_mcp.go, and logs_report.go use fmt.Print(table) / fmt.Print(console.RenderStruct(...)) to stdout. These render formatted tables as primary output (not diagnostic) — acceptable but worth ensuring they're only used in non-JSON output paths.

Recommendations

What the Codebase Does Well

• No hardcoded ANSI escape sequences anywhere in source code
• Full TTY detection — all styling degrades gracefully in CI/pipes
• Adaptive color system with light/dark variants throughout
• Spinner, progress bar, banner, table — rich terminal components all in pkg/console/
• Accessibility first — IsAccessibleMode() consistently applied to every interactive form
• Debug logging separation — pkg/logger for debug output, pkg/console for user output
• Centralized theme — single source of truth for colors, shared between Lipgloss styles and Huh forms

References: §23319713317

AI generated by Terminal Stylist · history

• expires on Mar 20, 2026, 10:29 PM UTC