Overview

This report analyzes console output patterns across 597 Go source files in pkg/ using the Charmbracelet ecosystem (Lipgloss + Huh). The codebase has a mature, well-structured terminal styling architecture with some areas that could benefit from more consistent use of the console formatting package.

Overall Assessment: ✅ Strong foundation — the console package is thoughtfully designed with adaptive colors, TTY detection, accessibility support, and a custom Huh theme. Most CLI files use console formatters correctly. The primary improvement opportunity is migrating ~500 remaining bare fmt.Fprintf(os.Stderr) calls in CLI files to use the console formatting package.

Summary

Lipgloss Analysis

✅ Strengths

Adaptive Color System (pkg/styles/theme.go)

• All colors use compat.AdaptiveColor with both Light and Dark variants — automatically adapts to terminal background.
• Inspired by the Dracula theme for dark mode; uses high-contrast colors for light mode.
• 11 semantic color roles: Error, Warning, Success, Info, Purple, Yellow, Comment, Foreground, Background, Border, TableAltRow.

TTY-Aware Styling (pkg/console/console.go)

• applyStyle() helper checks isTTY() before applying Lipgloss renders — prevents ANSI codes in pipes/redirects.
• Spinner and progress indicators correctly disable themselves when not in a TTY.

Centralized Styling

• No direct Lipgloss imports in CLI command files — all styling goes through pkg/styles and pkg/console packages.
• Clear separation of concerns: styles defines the palette, console applies it to user messages.

⚠️ Areas for Improvement

pkg/styles/huh_theme.go uses github.com/charmbracelet/lipgloss (v1)

The Huh theme file imports github.com/charmbracelet/lipgloss (v1) while the rest of the codebase uses charm.land/lipgloss/v2. This is documented as intentional (huh v0.8.0 depends on lipgloss v1), but creates a dual-import situation. The comment in the file explains this correctly — no action needed, but worth monitoring when huh upgrades to lipgloss v2.

FormatLocationMessage and FormatCountMessage missing in non-WASM build

These two functions are defined only in pkg/console/console_wasm.go but have no counterpart in pkg/console/console.go. Since they aren't currently used in non-WASM code, there's no immediate breakage, but adding them would complete the format function surface area:

// Suggested additions to pkg/console/console.go
func FormatLocationMessage(message string) string {
    return applyStyle(styles.FilePath, "📁 "+message)
}

func FormatCountMessage(message string) string {
    return applyStyle(styles.Info, "📊 "+message)
}

Huh Forms Analysis

✅ Strengths

Consistent Theme Application — All 16 form instances apply the same pattern:

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

Files using this pattern correctly:

• run_interactive.go (3 forms)
• interactive.go (3 forms)
• add_interactive_*.go (5 files, 6 forms)
• engine_secrets.go (3 forms)
• pkg/console/input.go and confirm.go

Custom Theme (pkg/styles/huh_theme.go)

• Builds on huh.ThemeBase() and applies the Dracula-inspired palette consistently.
• Handles Focused, Blurred, and Group styles.
• Cursor, placeholder, and prompt use distinct warning/primary/comment colors.

Accessibility Mode (pkg/console/accessibility.go)

• Respects ACCESSIBLE, TERM=dumb, and NO_COLOR environment variables.
• All forms pass WithAccessible(console.IsAccessibleMode()).

⚠️ Areas for Improvement

Field Validation Missing in Several Forms

Several Huh forms in add_interactive_*.go collect user input without .Validate() callbacks. For example:

// In add_interactive_auth.go — missing validation
huh.NewInput().
    Title("Enter your API key").
    Value(&b.APIKey)
// Should add: .Validate(func(s string) error { if s == "" { return errors.New("API key required") } return nil })

Adding validation improves UX by providing inline errors rather than failing later in the workflow.

No Description on several Select fields

Some huh.NewSelect calls in add_interactive_engine.go and run_interactive.go lack .Description() text to guide users:

// Current
huh.NewSelect[string]().Title("Choose engine")

// Better
huh.NewSelect[string]().
    Title("Choose engine").
    Description("The AI engine that will execute your workflow steps")

Bare fmt.Fprintf(os.Stderr) — Priority Files

These files have the most bare stderr calls that could benefit from console formatting:

Key Patterns to Migrate

1. Info messages without FormatInfoMessage (most common):

// Current (pkg/cli/mcp_list_tools.go:76)
fmt.Fprintf(os.Stderr, "Available MCP servers: ")
fmt.Fprintf(os.Stderr, "%s\n", strings.Join(serverNames, ", "))

// Better
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("Available MCP servers: "+strings.Join(serverNames, ", ")))

2. Success message in interactive.go:293:

// Current
fmt.Fprintf(os.Stderr, "Created new workflow: %s\n", destFile)

// Better (matches pattern in commands.go:77)
fmt.Fprintln(os.Stderr, console.FormatSuccessMessage("Created new workflow: "+destFile))

3. Advisory details in deps_security.go — Summary/URL/patched-version lines could use FormatListItem:

// Current
fmt.Fprintf(os.Stderr, "    %s", adv.Summary)
fmt.Fprintf(os.Stderr, "    %s\n", adv.URL)

// Better
fmt.Fprintln(os.Stderr, console.FormatListItem(adv.Summary))
fmt.Fprintln(os.Stderr, console.FormatCommandMessage(adv.URL))

4. Count/domain summary in domains_command.go:194:

// Current
fmt.Fprintf(os.Stderr, "\n%d allowed, %d blocked\n", len(allowedDomains), len(blockedDomains))

// Better
fmt.Fprintln(os.Stderr, console.FormatInfoMessage(fmt.Sprintf("%d allowed, %d blocked", len(allowedDomains), len(blockedDomains))))

Recommendations

Priority 1 — Quick Wins (single-line changes)

1. pkg/cli/interactive.go:293 — Replace bare success message with console.FormatSuccessMessage.
2. pkg/cli/mcp_list_tools.go:76,78,133,135 — Wrap 4 bare info messages with console.FormatInfoMessage.
3. pkg/cli/domains_command.go:194 — Wrap count summary with console.FormatInfoMessage.

Priority 2 — Multi-line blocks (moderate effort)

4. pkg/cli/preconditions.go — Convert 27 instruction-line blocks to use console.FormatInfoMessage and console.FormatCommandMessage for actionable steps.
5. pkg/cli/deps_security.go — Use console.FormatListItem for advisory detail indentation.
6. pkg/workflow/compiler.go — Consider adopting console.FormatWarningMessage inside formatCompilerMessage for consistency.

Priority 3 — Architectural (design decisions needed)

7. Add FormatLocationMessage and FormatCountMessage to non-WASM console.go — Complete the format function surface area.
8. Add .Validate() callbacks to Huh form fields in add_interactive_*.go for better UX.
9. Add .Description() to Select fields in engine and run interactive forms.

Non-Issues (intentionally raw output)

• pkg/cli/shell_completion.go — Completion scripts must be raw text for shell eval.
• pkg/cli/copilot_setup.go:281-290 — YAML snippet output intentionally preserves raw indentation.
• pkg/workflow/claude_logs.go — Debug-level diagnostics; using logger.New() pattern would be cleaner.
• Empty fmt.Fprintln(os.Stderr) calls for blank-line spacing — acceptable for visual layout.

References:

• §23390068210

AI generated by Terminal Stylist · history

• expires on Mar 22, 2026, 10:27 PM UTC