[terminal-stylist] Terminal Stylist review: console output, Lipgloss, and Huh consistency

[github-actions[bot]]

Terminal output consistency review

The console layer is fundamentally strong: terminal styling is centralized, destination-aware, adaptive to light/dark backgrounds, and guarded for TTY/color-profile behavior. Huh forms consistently pass through an accessibility-aware wrapper. The main opportunity is to finish migrating several user-facing pkg/cli paths from raw fmt.Fprint* output to the existing pkg/console API, and to give the standalone Work Queue TUI an explicit accessible-mode path.

Assessment: healthy foundation, with targeted consistency and accessibility debt rather than a need for a library rewrite.

Scan metrics

Measure	Result
Non-test Go files scanned under pkg/	1,542
Application/library files (excluding linter testdata)	1,381
Files with direct os.Stdout/os.Stderr fmt.Fprint* calls	273
Direct standard-stream call sites	2,662
Files calling console.*	284
console.* call sites	2,228
Lipgloss import sites	12 files
Huh import sites	17 files
Huh field constructor sites	31
Central console-form wrapper uses	23
Console table/struct render calls	54

The raw fmt count is not itself a defect. A substantial portion intentionally emits JSON, Markdown reports, generated shell snippets, subprocess output, or carefully aligned diagnostics where styling would be incorrect. Linter fixtures were scanned but excluded from application findings.

Highest-value improvements

1. Standardize two raw schema-rendering errors. pkg/cli/mcp_inspect_mcp.go:574 and :588 write Error displaying ... schema directly to stderr, while adjacent messages use console.PrintSectionHeader and console.PrintInfoMessage. Use console.PrintErrorMessage (or the destination-aware formatter) so these errors receive the same prefix, color policy, and non-TTY behavior.
2. Route verbose workflow-status output through the established verbose channel. pkg/cli/add_interactive_workflow.go:122-142 and :242-271 directly print status, failure, and lookup diagnostics. They should use logger for debug-only internals or console.FormatVerboseMessage/a print helper for --verbose user output. The current raw errors are visually inconsistent with errors in the same command.
3. Add an accessibility contract for the Work Queue TUI. pkg/cli/work_command_tui.go:303-325 checks stdin/stdout TTYs but not console.IsAccessibleMode(). The view uses alternate-screen rendering, reverse video, dense side-by-side panels, and frequent refreshes. In accessible mode, either reject with a clear command fallback (state --json / inspect) or provide a linear, non-alt-screen view. Also expose focus/selection/error state with textual markers rather than relying partly on reverse video.
4. Reduce formatting drift in high-volume report renderers. Files such as pkg/cli/audit_diff_render.go, pkg/cli/audit_report_render.go, pkg/cli/audit_cross_run_render.go, and pkg/cli/mcp_inspect_mcp.go contain many direct writes. Their Markdown/JSON output should remain plain, but terminal-mode sections should be built through small destination-aware render helpers. This separates machine output from decorated human output and makes TTY policy reviewable.
5. Prefer print helpers for one-line semantic messages. Where no special writer or error handling is needed, replace fmt.Fprintln(os.Stderr, console.Format...(...)) with console.PrintInfoMessage, PrintWarningMessage, PrintErrorMessage, etc. This removes repeated destination/formatter pairing and makes the existing consolestderr invariant easier to maintain.

Console package findings

What is working well

• pkg/console/console.go applies styles only for the appropriate stdout/stderr TTY and degrades output through colorprofile, honoring terminal capabilities and color environment settings.
• Destination-specific APIs (Format...Stdout, stderr defaults, RenderTableStdout, and RenderTable) avoid styling based on the wrong stream.
• pkg/linters/consolestderr/ statically checks destination/formatter mismatches and offers fixes.
• pkg/console/print.go provides semantic one-line output helpers.
• pkg/console/spinner.go disables animation for non-TTY and accessible environments, prevents concurrent spinner contention, and avoids consuming input intended for later forms.
• pkg/console/terminal.go confines raw ANSI to cursor/screen operations that Lipgloss does not provide and guards them with stderr TTY checks.
• pkg/console/render.go and pkg/console/console.go centralize struct/table rendering rather than duplicating layout logic.

Representative correct consumers

• pkg/cli/update_workflows.go
• pkg/cli/logs_run_processor.go
• pkg/cli/logs_orchestrator_stdin.go
• pkg/cli/audit_render_output.go
• pkg/cli/org_runner.go
• pkg/cli/compile_stats.go
• pkg/cli/mcp_list.go
• pkg/cli/list_workflows_command.go
• pkg/cli/domains_command.go
• pkg/cli/forecast_render.go
• pkg/cli/models_command.go
• pkg/cli/health_command.go
• pkg/cli/mcp_registry_list.go
• pkg/cli/outcomes_history.go
• pkg/cli/logs_format_compact.go

Raw output that should remain raw

• JSON and scalar stdout (run_workflow_execution.go, models_command.go, health_command.go, hash_command.go, and similar command contracts).
• Markdown report emitters in audit rendering.
• Generated shell/completion snippets in shell_completion.go.
• Subprocess stdout/stderr passthrough.
• Intentional blank lines and terminal progress carriage-return rendering.

These paths should not be styled because ANSI or semantic prefixes would corrupt machine-readable or copy/paste output.

Lipgloss analysis

Good patterns

• pkg/styles/theme.go defines a shared semantic palette with adaptive light/dark colors and reusable border/style tokens.
• pkg/styles/huh_theme.go uses lipgloss.LightDark against the same palette, preventing theme divergence.
• Tables use lipgloss/table, width-aware wrapping, centralized borders, and TTY-aware style functions.
• pkg/cli/compile_schedule_calendar.go explicitly suppresses rich rendering for non-terminal and accessible output.
• pkg/cli/work_command_tui_view.go uses Lipgloss width/height measurement and responsive one/two-column layouts instead of byte-length padding.
• Manual ANSI sequences are limited to cursor control in pkg/console/terminal.go and pkg/console/prompt_form.go; they are not being used as a substitute for color/style APIs.

Recommendations

• Keep all new colors and borders in pkg/styles; avoid introducing one-off hardcoded colors.
• In the Work Queue TUI, move border and state styles into shared semantic tokens. Keep the current ASCII border as a useful compatibility option, but add explicit visual/text styles for focused, selected, warning, and error states.
• Preserve plain output when redirected. The current console renderers do this correctly; new renderers should accept a destination or writer rather than assuming stdout.
• Avoid converting Markdown report tables to lipgloss/table: Markdown is an output format, not terminal layout. Use Lipgloss tables only in human terminal mode.

Huh and interactive UX analysis

Good patterns

• pkg/console/prompt_form.go is the sole direct huh.NewForm site. It applies styles.HuhTheme, WithAccessible(console.IsAccessibleMode()), terminal checks, and consistent cleanup.
• CLI code uses console.NewForm, NewInputForm, NewSelectForm, and NewConfirmForm rather than constructing unthemed forms.
• Password inputs use huh.EchoModePassword in pkg/cli/engine_secrets.go and pkg/console/input.go.
• Selects use filtering where option lists can grow, and workflow input fields attach validation where schema constraints require it.
• Cancellation is normalized through console.IsCancelled, allowing callers to distinguish user aborts from failures.

Recommendations

• Retain the centralized form wrappers; do not allow direct huh.NewForm use in pkg/cli.
• Consider a lightweight analyzer or review check enforcing the wrapper invariant, analogous to consolestderr.
• Replace selectWorkflowNonInteractive's manual numbered prompt (pkg/cli/run_interactive.go:199-218) with a shared console text-select helper, or require interactive stdin explicitly. A “non-TTY” path that immediately calls fmt.Scanf can be confusing in redirected/closed-input environments.
• Ensure validation errors describe the correction, not only the invalid value. Existing validator sites are appropriately limited because select/confirm fields generally do not need custom validation.
• For the standalone Bubble Tea TUI, document keyboard alternatives in the initial/linear view and provide an accessible-mode behavior as described above.

Examples of preferred migrations

Inconsistent

fmt.Fprintf(os.Stderr, "Error displaying input schema: %v\n", err)

Preferred

console.PrintErrorMessage(fmt.Sprintf("Failed to display input schema: %v", err))

Inconsistent verbose output

if c.Verbose {
    fmt.Fprintf(os.Stderr, "Checking workflow status (attempt %d/5) for: %s\n", attempt+1, workflowName)
}

Preferred

if c.Verbose {
    console.PrintVerboseMessage(fmt.Sprintf(
        "Checking workflow status (attempt %d/5) for: %s",
        attempt+1,
        workflowName,
    ))
}

If a verbose print helper is intentionally not added, use the destination-aware verbose formatter with stderr. For implementation-only diagnostics, prefer the existing namespace logger instead.

Suggested next actions

• P1: Fix raw schema errors and workflow-status verbose/error output.
• P1: Define and test accessible-mode behavior for work-queue tui.
• P2: Introduce writer-oriented semantic print helpers (or consistently use existing print helpers) and migrate one high-volume renderer at a time.
• P2: Add a static check preventing direct huh.NewForm construction outside pkg/console.
• P3: Document which commands intentionally emit plain Markdown/JSON so future style cleanups do not add ANSI to machine output.

Analysis note

Serena project activation succeeded, but its Go semantic operations could not initialize because the analysis service reported unavailable language runtimes. Per the tool's stop instruction, no semantic workaround was attempted; the complete non-test .go inventory was instead scanned with repository-local file and pattern analysis, followed by targeted source review.

References: §38537843211

Generated by 💄 Terminal Stylist · pi · gpt56 · 105.8 AIC · ⌖ 24.4 AIC · ⊞ 7.4K · ◷

• expires on Oct 15, 2026, 12:55 AM UTC-08:00