[terminal-stylist] Terminal Stylist Report: Console Output Analysis (pkg/, non-test Go)

[github-actions[bot]]

Terminal Stylist Analysis: Console Output Patterns in pkg/

Scanned 1354 Go source files under pkg/ (excluding _test.go) and focused on user-facing terminal output, styling, and prompt patterns.

Executive Summary

• Console output is partially standardized: many CLI paths use pkg/console helpers (FormatInfoMessage, FormatWarningMessage, spinners, tables), but raw fmt.Print* usage remains very high and inconsistent.
• Styling foundations are strong: pkg/styles centralizes Lipgloss styles with adaptive light/dark behavior and a shared Huh theme.
• Interactive prompts are well-structured in key flows and use Huh with themed forms, but there are opportunities to tighten accessibility defaults and validation consistency across entry points.
• Main risk area: direct fmt.Print* calls in rendering/report paths can bypass consistent severity formatting and make output behavior diverge across TTY/non-TTY contexts.

Findings by Pattern

1) fmt.Print* usage (high volume)

• Matches found: 3620
• Concentrated in render/report and workflow-memory files.
• Top files by count include:
  • pkg/cli/audit_diff_render.go
  • pkg/cli/audit_cross_run_render.go
  • pkg/workflow/drive_memory.go
  • pkg/cli/mcp_inspect_mcp.go
  • pkg/workflow/cache_memory.go

Assessment

• A significant portion is likely internal string-building or structured output assembly, which can be fine.
• However, several direct writes to stdout/stderr in CLI layers should be normalized through pkg/console wrappers for consistent prefixes, styles, and TTY-aware rendering semantics.

2) console.* usage (good baseline, mixed adoption)

• Matches found: 2185
• Commonly used in operational CLI paths, e.g. logs download/cache and run/update flows.
• Positive examples:
  • Severity helpers: console.FormatInfoMessage, console.FormatWarningMessage, console.FormatSuccessMessage, console.FormatVerboseMessage
  • UX helpers: console.NewSpinner, table rendering via console.RenderTable

Assessment

• This is the right direction and shows a mature abstraction layer.
• Inconsistent adoption alongside raw fmt.Fprintln/fmt.Printf creates style drift.

3) Lipgloss usage (good architecture)

• Matches found: 110
• Core style definitions are centralized in:
  • pkg/styles/theme.go
  • pkg/styles/huh_theme.go
  • consumed by pkg/console/*

Strengths observed

• Centralized style tokens and borders (RoundedBorder, NormalBorder, etc.).
• Adaptive color model for light/dark contexts.
• TTY-aware style application in pkg/console/console.go with color-profile degradation.
• Separation of style definitions from rendering logic is clean and maintainable.

Improvement opportunities

• Ensure all user-visible tables/lists route through shared table/list helpers rather than ad hoc text layout.
• Prefer style token reuse over local one-off style construction outside style/console packages.

4) Huh usage (solid interactive foundation)

• Matches found: 127
• Main usage appears in:
  • pkg/cli/interactive.go
  • pkg/cli/add_interactive_*.go
  • pkg/console/prompt_form.go

Strengths observed

• Shared styles.HuhTheme integration indicates deliberate visual consistency.
• Interactive workflows are decomposed into dedicated files by concern.

Improvement opportunities

• Standardize field-level validation patterns across all add/run interactive variants.
• Confirm accessibility mode behavior is consistently respected when prompts render in non-ideal terminals.
• Consolidate repetitive prompt wiring into helper constructors where possible.

Good Patterns (Examples)

• pkg/console/console.go
  • TTY-sensitive styling via applyStyle* helpers.
  • Environment-aware color degradation to honor terminal capabilities.
• pkg/styles/theme.go
  • Centralized style/color definitions with adaptive light/dark strategy.
• pkg/styles/huh_theme.go
  • Unified Huh theme mapped from shared palette for cohesive UX.
• pkg/cli/logs_download.go
  • Frequent use of console.Format*Message and spinner helpers for status output.

Needs Improvement (Examples)

• High-fmt.Print* renderer/report files should be audited for direct user-facing output normalization:
  • pkg/cli/audit_diff_render.go
  • pkg/cli/audit_cross_run_render.go
  • pkg/cli/audit_report_render.go
  • pkg/cli/mcp_inspect_mcp.go
  • pkg/workflow/drive_memory.go

Recommendations (Prioritized)

1. Define and enforce an output contract

   • In CLI packages, all end-user status/error/success messages should go through pkg/console severity helpers.
   • Reserve raw fmt.* for internal string formatting only.

2. Perform a targeted normalization sweep

   • Start with top 10 files by fmt.Print* count and classify each call as:
     • internal buffer formatting (keep), or
     • user-facing write (migrate to console helper).

3. Unify table/list rendering

   • Route table-like output through shared console.RenderTable/list utilities.
   • Avoid manual alignment and separator composition where helper APIs exist.

4. Formalize TTY-safe output policy

   • Document: style only through console/style helpers, never raw ANSI.
   • Ensure non-TTY paths remain plain, parseable text.

5. Huh form consistency pass

   • Build reusable validation and prompt field constructors for repeated flows (add_interactive_*, run_interactive).
   • Verify accessibility defaults and keyboard behavior consistency.

Suggested Follow-up Work Items

• Add a lightweight static check (or lint script) flagging direct fmt.Print* in pkg/cli/ except approved render internals.
• Create a small migration checklist for output call-site conversions.
• Add documentation snippets showing canonical output patterns for:
  • info/warn/error messages,
  • spinner lifecycle,
  • table/list rendering,
  • Huh themed forms with validation.

Scope Notes

• This analysis intentionally covered only .go files under pkg/ and excluded _test.go files.
• No code changes were made.

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• ab.chatgpt.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "ab.chatgpt.com"

See Network Configuration for more information.

Generated by 💄 Terminal Stylist · codex · gpt53codex · 11.4 AIC · ⌖ 4.83 AIC · ⊞ 14.4K · ◷

• expires on Sep 9, 2026, 12:50 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-09-09T08:50:52.622Z.

Closed by Workflow