[terminal-stylist] Terminal styling audit: Go console output, Lipgloss, and Huh

[github-actions[bot]]

Overview

Scanned all 1,812 non-test Go files in the repository, with 1,792 files under pkg/ as the primary analysis area. The codebase has a strong central terminal UI foundation: pkg/console provides TTY-aware formatting, pkg/styles centralizes adaptive colors, and interactive forms consistently flow through a shared Huh wrapper.

The main opportunity is migration, not redesign: a substantial set of CLI and workflow paths still writes human-facing status, warning, and report text directly with fmt.Fprint*, bypassing the shared severity, TTY, width, and accessibility behavior.

Key metrics and findings

Area	Result
Non-test Go files scanned	1,812
Non-test Go files under pkg/	1,792
Files containing fmt.Print* / fmt.Fprint* patterns	387
Files referencing console.*	292
Files referencing Lipgloss	9
Files referencing Huh	18
Direct stdout/stderr fmt.Fprint* sites under pkg/ not wrapping console.*	843 across 123 files
Raw ANSI usage	Confined primarily to pkg/console, plus ANSI detection/removal utilities
Serena diagnostics on representative console/style/form files	No diagnostics

The 843 direct-write sites are not all defects. Machine-readable JSON, Markdown output, pass-through subprocess output, blank-line layout, and generated content should often remain raw. The actionable subset is human-facing severity/status text and manually aligned terminal reports.

What is working well

• Central TTY-aware styling: pkg/console/console.go returns plain text when the target stream is not a TTY and degrades color based on the terminal environment when styling is enabled.
• Adaptive light/dark palette: pkg/styles/theme.go defines paired light/dark colors and selects them through a shared adaptive color implementation.
• Reusable tables: console.RenderTable uses lipgloss/table, bounded rendering, centralized borders, totals, and TTY-aware styling rather than ad hoc spacing.
• Accessible Huh integration: pkg/console/prompt_form.go constructs forms with styles.HuhTheme and .WithAccessible(...); pkg/cli/interactive.go also supplies a non-TTY text-prompt path.
• Well-structured forms: the workflow builder groups basic configuration, capabilities, network/security, and instructions into separate Huh groups, uses appropriate Select, MultiSelect, and Text fields, and validates workflow intent.
• Secret handling: password inputs use huh.EchoModePassword.
• ANSI containment: cursor-control sequences are centralized in pkg/console/terminal.go and pkg/console/prompt_form.go, rather than scattered through commands.
• Clear severity vocabulary: the console package exposes error, warning, info, success, progress, command, prompt, verbose, section, list, and table formatting APIs.

Representative strong implementations:

• pkg/console/console.go
• pkg/console/prompt_form.go
• pkg/console/input.go
• pkg/console/list.go
• pkg/styles/theme.go
• pkg/styles/huh_theme.go
• pkg/cli/interactive.go
• pkg/cli/run_interactive.go
• pkg/cli/forecast_render.go

Priority improvements

1. Standardize remaining raw warnings and errors. These paths emit severity text directly and should use console formatters or the existing namespace logger as appropriate:

   • pkg/workflow/cache_steps.go:23
   • pkg/workflow/push_to_pull_request_branch.go:128
   • pkg/workflow/mcp_renderer.go:114
   • pkg/workflow/compiler_orchestrator_engine.go:302-308
   • pkg/cli/mcp_inspect_mcp.go:577,591

   Preferred pattern:

   fmt.Fprintln(os.Stderr, console.FormatWarningMessageStderr(message))

   Avoid severity encoded manually in the string:

   fmt.Fprintf(os.Stderr, "Warning: failed to parse configuration: %v\n", err)

2. Move parser internals from unconditional stderr to debug logging. pkg/workflow/claude_logs.go already declares claudeLogsLog, but several parse fallbacks and extraction counters use raw fmt.Fprintf(os.Stderr, ...). These messages look diagnostic rather than user-actionable and should use pkg/logger so normal command output remains quiet. User-actionable failures can remain console warnings/errors.

3. Migrate manual terminal tables and aligned reports selectively. Good candidates include:

   • pkg/cli/experiments_analyze_statistics.go
   • pkg/cli/audit_cross_run_render.go
   • pkg/cli/deps_report.go
   • pkg/cli/remove_command.go

   These contain fixed-width %20s/%-45s layouts and Unicode separators that can wrap poorly in narrow terminals. Prefer console.RenderTable with a maximum width, while retaining raw Markdown and JSON renderers for machine-oriented output.

4. Create shared section/list helpers for narrative command output. pkg/cli/add_interactive_orchestrator.go, pkg/cli/preconditions.go, pkg/cli/enable.go, and pkg/cli/fix_command.go assemble headings, bullets, separators, and blank lines manually. Using FormatSectionHeader, FormatListItem, FormatCommandMessage, and composed sections would make TTY and non-TTY rendering consistent.

5. Use shared Lipgloss style tokens in the work-queue TUI. pkg/cli/work_command_tui_view.go correctly uses Lipgloss layout and responsive breakpoints, but defines a local ASCII border and mostly monochrome focus state. Consider shared border/style tokens for focused panels, status, warnings, disabled actions, and selection. Keep an ASCII/no-color presentation for accessibility and compatibility.

6. Review NO_COLOR versus accessibility semantics. pkg/console/accessibility.go treats NO_COLOR as full Huh accessible mode. NO_COLOR conventionally requests color suppression, not necessarily a different interaction model. Consider separating:

   • color capability (NO_COLOR), and
   • screen-reader/nonvisual form mode (ACCESSIBLE, TERM=dumb, or explicit configuration).

Lipgloss assessment

Detailed Lipgloss findings

• The palette is centralized and adaptive rather than hardcoding terminal ANSI colors at call sites.
• Background probing is isolated in pkg/styles/theme.go, and stdout formatting is degraded according to terminal capabilities.
• Table rendering appropriately uses lipgloss/table; expanding this approach to manually aligned CLI reports would improve narrow-terminal behavior.
• pkg/cli/work_command_tui_view.go uses MaxWidth, MaxHeight, horizontal joins, viewport thresholds, and an alternate screen appropriately. Shared semantic style tokens would improve visual consistency with the rest of the CLI.
• Manual ANSI sequences are limited to operations Lipgloss does not directly replace well, such as cursor save/restore and clearing inline form space. This is an appropriate exception, provided it remains TTY-gated as it is today.

Huh assessment

Detailed Huh findings

• All production huh.NewForm construction is centralized through console.NewForm, which applies the repository theme and accessibility setting.
• Forms use field types appropriately: selects for exclusive choices, multi-selects for capabilities, text for workflow intent, confirm for irreversible or consequential actions, and password echo mode for credentials.
• Validation exists on the important free-text and dynamic input paths, including workflow intent and run inputs.
• Cancellation is normalized through console.IsCancelled, improving consistent Ctrl-C/Esc handling.
• The explicit non-TTY scanner fallback in pkg/cli/interactive.go is a strong accessibility and automation pattern. Consider extracting its select/multi-select rendering into pkg/console so other commands can reuse the same fallback behavior.
• If NO_COLOR is decoupled from accessible mode, Huh can remain interactive while rendering without color for users who only request color suppression.

Suggested migration order

1. Replace the small set of raw severity-prefixed messages in pkg/workflow and MCP inspection.
2. Convert claude_logs.go parser diagnostics to the namespace logger.
3. Introduce reusable console helpers for narrative sections and non-TTY prompts.
4. Migrate one manually aligned report at a time to console.RenderTable, preserving separate JSON/Markdown output paths.
5. Add semantic shared styles for the work-queue TUI and verify no-color/accessibility rendering.

References:

• §40658533444

Generated by 💄 Terminal Stylist · pi · gpt56 · ~82 AIC · ⌖ ~18 AIC · ⊞ 8.3K · ◷

• expires on Oct 29, 2026, 12:51 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-10-29T08:51:06.183Z.

Closed by Workflow