[terminal-stylist] Terminal Stylist — Console Output Analysis

[github-actions[bot]]

Terminal Stylist Report — Console Output Analysis

Scope: All non-test .go files under pkg/ · 957 source files scanned
Libraries detected: charm.land/lipgloss/v2, charm.land/huh/v2, charm.land/bubbles/v2/spinner, charm.land/bubbles/v2/progress

---

Summary

The codebase has a mature, well-structured console layer. The pkg/styles/ + pkg/console/ pairing is exemplary: adaptive colors, TTY-gated styling, accessibility support, and clean Format*/Render* naming conventions are all in place. Interactive forms consistently apply the custom Huh theme and accessibility mode. However, a handful of interactive flow files bypass console formatters and use raw fmt.Fprintln for plain-text messages and hardcoded separator characters.

Category	Count
Files using console.Format* / console.Render*	50+
fmt.Fprintln(os.Stderr, console.Format*...) call sites	~1,644
Raw fmt.Fprintln(os.Stderr, ...) without console wrapper	~1,370
Huh form files (huh.NewForm(...).WithTheme(...))	14
Lipgloss direct usage outside pkg/styles/ + pkg/console/	5

---

Lipgloss Analysis

Adaptive Color System — ✅ Excellent

pkg/styles/theme.go implements a custom adaptiveColor type that satisfies color.Color and selects light/dark variants at runtime:

type adaptiveColor struct { Light, Dark color.Color }
func (c adaptiveColor) RGBA() (uint32, uint32, uint32, uint32) {
    if hasDarkBackground { return c.Dark.RGBA() }
    return c.Light.RGBA()
}

• Probes terminal background at init() via lipgloss.HasDarkBackground — safely skipped on Windows (ConPTY crash prevention)
• Light variants use high-contrast, darker saturated colors; dark variants follow the Dracula theme
• Color palette covers all semantic use cases: Error, Warning, Success, Info, Purple, Yellow, Comment, Foreground, Background, Border, TableAltRow
• All pre-configured styles (Error, Warning, Success, Info, etc.) use these adaptive colors

TTY Detection — ✅ Correct

The applyStyle() helper in pkg/console/console.go gates styling on isTTY():

func applyStyle(style lipgloss.Style, text string) string {
    if isTTY() { return style.Render(text) }
    return text
}

This pattern is used consistently throughout all Format* and Render* functions. Direct tty.IsStderrTerminal() calls in CLI files are also used correctly for conditional rendering.

Layout and Table Usage — ✅ Good, with one anti-pattern

• RenderTable() correctly uses lipgloss/table with per-row StyleFunc, zebra-striping, and rounded borders
• RenderComposedSections() uses lipgloss.JoinVertical() in TTY mode, falls back to plain loops in non-TTY
• RenderTitleBox() uses double border + center alignment; RenderErrorBox() uses rounded border with error color; RenderInfoSection() uses left-border emphasis — all with non-TTY fallbacks
• Anti-pattern found: trial_confirmation.go:221 wraps a separator line inside console.FormatInfoMessage():

  fmt.Fprintln(os.Stderr, console.FormatInfoMessage("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"))

  FormatInfoMessage adds a cyan i prefix — semantically wrong for a separator. Use console.RenderTitleBox() instead.

---

Huh Analysis

Theme Integration — ✅ Consistent

pkg/styles/huh_theme.go maps the package's Dracula-inspired palette onto every Huh style token using lipgloss.LightDark(isDark):

• Focused title → primary (purple)
• Selected option → success (green)
• Select cursor / navigation arrows → warning (orange)
• Error indicators → error (red)
• Text cursor → warning; placeholder → comment; prompt prefix → primary
• Blurred base uses HiddenBorder() so inactive fields recede visually

All 14 form-using files consistently apply .WithTheme(styles.HuhTheme).WithAccessible(console.IsAccessibleMode()).

Accessibility — ✅ Comprehensive

console.IsAccessibleMode() checks three signals:

• ACCESSIBLE env var (any value)
• TERM=dumb
• NO_COLOR env var

All Huh forms pass IsAccessibleMode() to WithAccessible(). The spinner additionally checks ACCESSIBLE directly and disables animation entirely.

Non-TTY Fallbacks — ✅ Present in all interactive components

• ConfirmAction() → numbered text list with y/n prompt
• ShowInteractiveList() → numbered text list with integer selection
• PromptSecretInput() → returns error (secret masking not possible outside TTY)
• NewSpinner() → disabled entirely (no-op); messages still printed on StopWithMessage()
• ProgressBar.Update() → returns text percentage strings (50% (512MB/1024MB))

Spinner Bubble Tea Integration — ✅ Correct

The spinner uses tea.WithInput(nil) to avoid consuming stdin that subsequent Huh forms need:

s.program = tea.NewProgram(model, tea.WithOutput(os.Stderr), tea.WithoutRenderer(), tea.WithInput(nil))

Thread-safe lifecycle (mutex + WaitGroup) prevents double-start and deadlock on early stop.

---

Issues and Recommendations

🔴 Medium — Hardcoded separators bypassing layout primitives

Files: add_interactive_orchestrator.go:326,328, deps_report.go:105,107, actionlint.go:121,123,168

// ❌ Current — raw separators not adaptive to TTY width or theme
fmt.Fprintln(os.Stderr, "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("═══════════════════════════════════════"))  // wraps separator in info prefix

// ✅ Recommended — use the existing layout primitive
sections := console.RenderTitleBox("🎉 Addition complete!", 40)
console.RenderComposedSections(sections)

RenderTitleBox already handles TTY vs plain fallback correctly.

---

🔴 Medium — Unformatted instructional text in interactive flows

Files: add_interactive_git.go:60,124,189-191, add_interactive_auth.go:28-31, add_interactive_engine.go:179, add_interactive_orchestrator.go:334,338,343, add_interactive_secrets.go:44

// ❌ Current — plain text without formatting
fmt.Fprintln(os.Stderr, "Please add the secret manually:")
fmt.Fprintln(os.Stderr, "  1. Go to your repository Settings → Secrets and variables → Actions")
fmt.Fprintln(os.Stderr, "Please merge the PR manually from the GitHub web interface.")

// ✅ Recommended
fmt.Fprintln(os.Stderr, console.FormatWarningMessage("Please add the secret manually:"))
fmt.Fprintln(os.Stderr, console.FormatListItem("Go to your repository Settings → Secrets and variables → Actions"))
fmt.Fprintln(os.Stderr, console.FormatWarningMessage("Please merge the PR manually from the GitHub web interface."))

---

🟡 Low — Manual bullet points instead of FormatListItem

Files: add_interactive_orchestrator.go:247, add_interactive_secrets.go:44

// ❌ Current
fmt.Fprintf(os.Stderr, "  • .github/workflows/%s\n", f)
fmt.Fprintf(os.Stderr, "Found %d existing secret(s) (repository + organization)\n", len(c.existingSecrets))

// ✅ Recommended
fmt.Fprintln(os.Stderr, console.FormatListItem(fmt.Sprintf(".github/workflows/%s", f)))
fmt.Fprintln(os.Stderr, console.FormatInfoMessage(fmt.Sprintf("Found %d existing secret(s) (repository + organization)", len(c.existingSecrets))))

---

🟡 Low — Debug-style outputs leaking into add_interactive_workflow.go

Lines: 181, 187, 193-194, 203, 209 — plain fmt.Fprintf(os.Stderr, "Running: gh %s\n", ...), "gh workflow list output: ...", "Looking for workflow...", "Workflow ... found/NOT found in workflow list".

These appear to be development diagnostics that were never converted to use the existing logger (which respects DEBUG/DEBUG_COLORS env vars):

// ❌ Current
fmt.Fprintf(os.Stderr, "Running: gh %s\n", strings.Join(args, " "))
fmt.Fprintf(os.Stderr, "gh workflow list output: %s\n", string(output))

// ✅ Recommended
workflowLog.Printf("Running: gh %s", strings.Join(args, " "))
workflowLog.Printf("gh workflow list output: %s", string(output))

---

Exemplary Patterns to Follow

pkg/cli/trial_confirmation.go is the gold standard for interactive output — it uses RenderTitleBox, RenderInfoSection, and RenderComposedSections correctly, all with proper TTY/plain fallbacks. New interactive flows should follow this file's pattern.

pkg/cli/deps_security.go and pkg/cli/mcp_inspect_mcp.go demonstrate correct console.RenderErrorBox() usage for error states.

---

Next Actions

1. Replace hardcoded ━━━/═══ separators in add_interactive_orchestrator.go, deps_report.go, trial_confirmation.go, and actionlint.go with console.RenderTitleBox() / console.RenderComposedSections() calls
2. Wrap plain instructional text in add_interactive_*.go files with appropriate console.Format*Message() helpers
3. Replace manual bullet points with console.FormatListItem() in add_interactive_orchestrator.go
4. Convert debug fmt.Fprintf calls in add_interactive_workflow.go to use the logger package (gated by DEBUG env var)

References: §28161453108

Generated by 💄 Terminal Stylist · 86.8 AIC · ⌖ 11.6 AIC · ⊞ 5.7K · ◷

• expires on Jun 26, 2026, 1:53 AM UTC-08:00