[go-fan] Go Module Review: briandowns/spinner

[github-actions[bot]]

🐹 Go Fan Report: briandowns/spinner

Module Overview

The github.com/briandowns/spinner module is a simple and elegant terminal spinner library that provides visual feedback during long-running operations. It offers 90+ character sets, customizable colors, dynamic message updates, and automatic TTY detection—perfect for CLI applications like gh-aw.

Current Version: v1.23.2 (Latest as of January 2025!)

Full Module Details

Key Features

• 90+ Character Sets: Wide variety of animations (arrows, dots, braille, progress bars)
• Color Support: Full color palette with foreground/background options
• Text Attributes: Bold, italic, underline support
• Prefix/Suffix: Add contextual text before/after spinner
• Dynamic Updates: Change message, speed, or charset while running
• Direction Control: Reverse animation direction
• TTY Detection: Built-in terminal detection
• Final Message: Display completion message when stopped
• Writer Control: Configure output destination (stdout/stderr)
• Status Checking: Query if spinner is active
• Enable/Disable: Toggle spinner on/off programmatically

Repository Stats

• GitHub: https://github.com/briandowns/spinner
• Stars: 2.3k+
• Status: Actively maintained
• License: Apache 2.0

Current Usage in gh-aw

The project uses spinner excellently through a custom SpinnerWrapper implementation that:

✅ Automatically detects TTY environments using go-isatty
✅ Provides conditional behavior (no-op when not in terminal)
✅ Uses consistent styling (braille dots, 100ms speed, cyan color)
✅ Supports dynamic message updates

Usage Pattern Implementation

SpinnerWrapper Design

Located in pkg/console/spinner.go, the wrapper provides:

type SpinnerWrapper struct {
    spinner *spinner.Spinner
    enabled bool
}

Methods:

• NewSpinner(message) - Creates spinner with TTY detection
• Start() - Begins animation (if enabled)
• Stop() - Stops animation
• UpdateMessage(message) - Updates display text
• IsEnabled() - Checks if spinner is active

Configuration

• Character Set: CharSet[14] (braille dots: ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏)
• Speed: 100ms per frame
• Color: Cyan
• Output: stdout

Usage Across Codebase

The spinner appears in 9 locations providing feedback for:

1. Network Operations (5 locations)

   • Fetching workflow runs with pagination
   • Fetching servers from MCP registry
   • Fetching specific MCP server info
   • Fetching workflow status
   • Fetching runs by ref

2. Download Operations (1 location)

   • Downloading run artifacts

3. Cancellation Operations (2 locations)

   • Cancelling workflow runs
   • Cancelling runs via lock file

4. Retry Operations (1 location)

   • Waiting for workflow run to appear

Import Count: 1 file (pkg/console/spinner.go)
Files Using SpinnerWrapper: 6 files across pkg/cli/

Research Findings

Recent Updates

The spinner module has been actively maintained with important recent improvements:

v1.23.2 (January 20, 2025) - Current version! 🎉

• Bug fix: Removed problematic format method call

v1.23.1 (June 2024) - Security & Dependency Improvements

• 🔒 Fixed CVE-2022-29526 security vulnerability
• 📦 Consolidated IsTerminal() dependencies - Switched from github.com/mattn/go-isatty to golang.org/x/term
• This change is significant for gh-aw!

v1.22.0 (February 2023)

• Multi-line spinner string support

v1.21.0 (February 2023)

• Improved ANSI sequence handling for better color rendering

Best Practices from Maintainers

Recommended Usage Patterns

1. Use stderr for CLI tools:

   s := spinner.New(spinner.CharSets[14], 100*time.Millisecond,
       spinner.WithWriter(os.Stderr))

   This allows piping/redirecting output without spinner interference.

2. Add final messages:

   s.FinalMSG = "✓ Complete!\n"

   Provides clear completion feedback to users.

3. Let library handle TTY detection:
   The library has built-in TTY detection when using WithWriter(), so manual checks may be redundant.

4. Use dynamic updates for progress:

   s.Suffix = fmt.Sprintf(" Processing... (%d/%d)", current, total)

Improvement Opportunities

🏃 Quick Wins

1. Remove Redundant go-isatty Dependency

Impact: ⭐⭐⭐ (Immediate dependency reduction)

Issue: gh-aw uses github.com/mattn/go-isatty for TTY detection, but as of spinner v1.23.1, the library itself switched to golang.org/x/term.

Benefit:

• Reduce dependency count
• Align with spinner's internal implementation
• Follow upstream best practices

Location: pkg/console/spinner.go:7-8

Change:

// Before
import "github.com/mattn/go-isatty"
enabled := isatty.IsTerminal(1)

// After - Option A: Use term directly
import "golang.org/x/term"
enabled := term.IsTerminal(int(os.Stdout.Fd()))

// After - Option B: Let spinner handle it
s := spinner.New(charset, delay, spinner.WithWriter(os.Stderr))

2. Use Writer Configuration Instead of Manual TTY Check

Impact: ⭐⭐ (Code simplification)

Issue: SpinnerWrapper manually checks TTY and conditionally creates spinner.

Opportunity: Spinner library handles TTY detection internally with the WithWriter() functional option.

Benefit: Cleaner code, leverage library's built-in TTY detection logic.

✨ Feature Opportunities

3. Add Final Messages on Completion

Impact: ⭐⭐⭐⭐ (Significantly improves UX)

Feature: Use the FinalMSG property to show success/completion messages when operations finish.

Benefit: Clear visual feedback that operations completed successfully.

Examples:

• "✓ Downloaded artifacts successfully!"
• "✓ Cancelled 3 workflow runs"
• "✓ Fetched 50 workflow runs"

Implementation: Add to SpinnerWrapper:

func (s *SpinnerWrapper) StopWithMessage(msg string) {
    if s.enabled && s.spinner != nil {
        s.spinner.FinalMSG = msg + "\n"
        s.spinner.Stop()
    }
}

Impact: Improves UX across all 9 spinner usage locations!

4. Leverage Writer Control for Better Output Redirection

Impact: ⭐⭐⭐ (Improves pipeline compatibility)

Feature: Configure spinner to write to os.Stderr instead of os.Stdout.

Benefit:

• Allows piping/redirecting actual command output without spinner interference
• Follows CLI best practices
• Recommended in spinner documentation

Best Practice: Progress indicators should go to stderr, actual output to stdout.

Example:

gh-aw logs download > output.txt  # Output goes to file, spinner stays in terminal

5. Use Progress Indicators with Dynamic Updates

Impact: ⭐⭐⭐ (Better user experience)

Current State: Only listWorkflowRunsWithPagination updates messages dynamically.

Opportunity: Use UpdateMessage() in more locations to show progress:

• Download progress: "Downloading... (45% - 2.3MB/5.1MB)"
• Cancellation count: "Cancelling runs... (3/10 completed)"
• Retry attempts: "Waiting for run... (attempt 2/5)"

Locations: downloadRunArtifacts, cancelWorkflowRuns, getLatestWorkflowRunWithRetry

📐 Best Practice Alignment

6. Consistent Error Handling for Color Setting

Impact: ⭐ (Better debugging)

Current: _ = s.spinner.Color("cyan") ignores errors.

Improvement: While ignoring is acceptable (fallback to default works), consider:

• Debug logging when color fails
• Fallback color selection
• Better visibility into terminal color support issues

7. Consider Disable/Enable Toggle API

Impact: ⭐ (Optional refinement)

Feature: v1.19.0+ added Enable() and Disable() methods.

Current: SpinnerWrapper uses boolean flag and nil checks.

Trade-off: Current approach works well; this is an optional refinement for code clarity.

🔧 General Improvements

8. Centralize Spinner Configuration

Impact: ⭐⭐ (Customization flexibility)

Observation: All spinners use same configuration:

• CharSet[14] (braille dots)
• 100ms speed
• Cyan color

Opportunity: Make these configurable via environment variables or config file:

GH_AW_SPINNER_STYLE=dots
GH_AW_SPINNER_COLOR=green
GH_AW_SPINNER_SPEED=80

Benefit: Allow users to customize spinner appearance to their preference.

9. Add Context-Aware Spinner Messages

Impact: ⭐⭐ (Better feedback)

Current: Most messages are static strings.

Opportunity: Include more operational context:

• Timing: "Fetching workflows... (3s elapsed)"
• Counts: "Processing items... (47/100)"
• Status: "Waiting for run... (checking every 5s)"

10. Consider Spinner Character Set Variations

Impact: ⭐ (Visual polish)

Current: Always uses CharSet[14] (braille dots).

Opportunity: Use different character sets for different operation types:

• Progress bars (CharSet[36]) for downloads with % completion
• Arrows (CharSet[9]) for quick API calls
• Dots (CharSet[26]) for waiting/polling operations
• Current braille (CharSet[14]) for general operations

Recommendations

Priority 1: Remove go-isatty Dependency ⚡

Effort: Low | Impact: High | Risk: Low

The spinner library moved away from go-isatty in v1.23.1. We should follow suit!

Action: Update pkg/console/spinner.go to either:

• Use golang.org/x/term.IsTerminal() directly (matches spinner's approach)
• Let spinner handle TTY detection via WithWriter(os.Stderr) option

Why now: Already on v1.23.2, this aligns with current best practices.

Priority 2: Add Final Messages ✨

Effort: Medium | Impact: Very High | Risk: Low

Add completion messages so users see clear success/error states.

Action: Extend SpinnerWrapper with StopWithMessage() method and add success messages to all 9 usage locations.

User Experience:

⠋ Downloading artifacts for run 12345...
✓ Downloaded 3 artifacts successfully (2.4MB)

Priority 3: Use Stderr for Spinner Output 📝

Effort: Low | Impact: Medium | Risk: Low

Configure spinners to write to stderr for better pipeline compatibility.

Action: Add spinner.WithWriter(os.Stderr) to spinner initialization.

Benefit: Users can redirect output while still seeing progress in terminal.

Priority 4: Enhance Progress Feedback 📊

Effort: Medium-High | Impact: High | Risk: Low

Add dynamic progress updates to long-running operations.

Action: Use UpdateMessage() to show:

• Download percentages and speeds
• Cancellation progress counts
• Retry attempt numbers
• Elapsed time for slow operations

Next Steps

1. Quick Win: Update pkg/console/spinner.go to remove go-isatty dependency
2. Enhancement: Add FinalMSG support to SpinnerWrapper with new StopWithMessage() method
3. Improvement: Configure stderr output via WithWriter(os.Stderr) for better piping
4. Polish: Add dynamic progress messages to download and cancellation operations

---

Module summary saved to: specs/mods/spinner.md

Generated by: Go Fan 🐹
Review Date: 2025-11-29
Module Version: v1.23.2

AI generated by Go Fan

[pelikhan]

/plan

[github-actions[bot]]

🎉 Yo ho ho! Plan Command found the treasure and completed successfully! ⚓💰

[github-actions[bot]]

⚓ Avast! This discussion be marked as outdated by Go Fan.
🗺️ A newer treasure map awaits ye at Discussion #5271.
Fair winds, matey! 🏴‍☠️