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

[github-actions[bot]]

🐹 Go Fan Report: github.com/briandowns/spinner

The gh-aw project demonstrates excellent usage of the spinner library with a clean wrapper abstraction and proper best practices. Already on the latest version (v1.23.2) with perfect dependency alignment.

Module Overview

The github.com/briandowns/spinner library provides a simple, flexible terminal spinner for Go applications. It offers 90+ character sets, full color support, and cross-platform terminal compatibility. The library is actively maintained with 2.3k+ stars and regular updates.

Current Version: v1.23.2 (January 2025)
Latest Version: v1.23.2 ✓

Current Usage in gh-aw

Implementation Pattern

The project wraps the spinner in a custom SpinnerWrapper type at pkg/console/spinner.go:11 that provides:

• Automatic disabling in non-TTY environments via tty.IsStderrTerminal()
• Stderr output (best practice for progress indicators)
• Clean API: NewSpinner(), Start(), Stop(), UpdateMessage(), StopWithMessage()

Usage Statistics

• Files: 9 files use the spinner
• Instances: 11 spinners across the codebase
• Primary Use Cases: Network operations (GitHub API calls), artifact downloads, workflow fetching

Key Locations

1. pkg/cli/workflows.go:68 - Fetching workflow status
2. pkg/cli/run_command.go:543 - Waiting for workflow runs
3. pkg/cli/run.go:19,66 - Cancelling workflow runs (2×)
4. pkg/cli/status_command.go:402 - Fetching workflow runs for ref
5. pkg/cli/logs_download.go:277 - Downloading artifacts
6. pkg/cli/logs.go:887,1155 - Batch artifact downloads with progress (2×)
7. pkg/cli/mcp_registry.go:83,270 - Fetching MCP server data (2×)

Current Pattern (Consistent Across Project)

spinner := console.NewSpinner("Fetching data...")
if !verbose {
    spinner.Start()
}
// ... perform operation ...
spinner.Stop()

Research Findings

Recent Updates (v1.23.1 → v1.23.2)

v1.23.2 (January 2025):

• Internal cleanup: Remove format method call ([claude-test] Code flows like water #163)
• No API changes, zero impact on gh-aw

v1.23.1 (January 2024) - Important!:

• Consolidated to golang.org/x/term for IsTerminal() ([claude-test] Actions flow like streams #156)
• Removed github.com/mattn/go-isatty dependency
• Perfect alignment: gh-aw already uses golang.org/x/term at pkg/tty/tty.go:6!
• This change reduces the dependency tree and aligns with Go ecosystem standards

Previous Notable Releases:

• v1.22.0 (May 2023): Security fix for CVE-2022-29526
• v1.21.0 (Jan 2023): ANSI sequence width calculation (Implement pull-request output type with enhanced security and update documentation #147)
• v1.20.0 (Dec 2022): Multi-line spinner support ([copilot] output pull request #146)
• v1.19.0 (Jul 2022): Enable/Disable toggle methods ([claude-test] Pull request not found #144)

Best Practices from Repository

The spinner maintainers recommend:

1. ✅ Use WithWriter(os.Stderr) for stderr output - allows piping stdout
2. ✅ Use WithWriterFile() instead of WithWriter() for proper terminal detection
3. ✅ Always check terminal before starting spinner
4. ✅ Set FinalMSG for completion feedback
5. Multi-line messages are supported but may wrap on narrow terminals
6. Windows CMD/PowerShell automatically disable colors (not Windows Terminal)

Key Features Available

1. 90+ character sets - Extensive animation variety
2. Full color support - Foreground, background, attributes (bold, italic, etc.)
3. Custom writers - WithWriter() and WithWriterFile() options
4. Terminal detection - Automatic ANSI prevention in pipes/redirects
5. Final messages - Display completion status with FinalMSG
6. Dynamic updates - Change speed, charset, messages mid-spin
7. Multi-line support - Display multi-line status messages
8. Enable/Disable toggle - Runtime control (v1.19.0+)
9. Callbacks - PreUpdate and PostUpdate hooks
10. Thread-safe - Mutex-protected for concurrent access
11. LastOutput - Exposed for scrolling output scenarios
12. Windows support - Proper CMD, PowerShell, Windows Terminal handling

Improvement Opportunities

🏃 Quick Wins

1. Use WithWriterFile Instead of WithWriter

Location: pkg/console/spinner.go:27

Current:

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

Recommended:

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

Why: WithWriterFile() enables the spinner library's internal terminal detection via isRunningInTerminal(). This provides defense-in-depth alongside your existing TTY check.

Impact: Minor code change, better alignment with library design patterns.

2. Add Success/Error Completion Symbols

Context: Community feedback (issue #159) requests visual completion indicators.

Enhancement:

// Add to pkg/console/spinner.go

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

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

Usage Example:

// In CLI commands
if err != nil {
    spinner.StopError("Failed to fetch workflows")
    return err
}
spinner.StopSuccess("Workflows fetched successfully")

Benefit: Better UX with visual success/failure feedback. This pattern is seen in popular CLI tools (kubectl, gh, docker).

Impact: Small addition (~15 lines), significant UX improvement.

3. Extract Spinner Configuration Constants

Context: All spinner instances use the same hardcoded values.

Enhancement:

// pkg/console/spinner.go
const (
    DefaultCharSet = 14  // ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏
    DefaultDelay   = 100 * time.Millisecond
    DefaultColor   = "cyan"
)

// Use in NewSpinner()
s.spinner = spinner.New(
    spinner.CharSets[DefaultCharSet], 
    DefaultDelay, 
    spinner.WithWriterFile(os.Stderr),
)

Benefit: Single source of truth for spinner styling. Easy to change globally or add themed variants.

Impact: Minor refactoring, improves maintainability.

✨ Feature Opportunities

1. Leverage PreUpdate Callbacks for Automatic Progress

Available: Since initial release
Not Currently Used: Would eliminate manual UpdateMessage() calls

Use Case: Batch artifact downloads in logs.go:891

Current Pattern:

var completedCount int64
// Manual updates scattered through code
spinner.UpdateMessage(fmt.Sprintf("Downloading artifacts... (%d/%d)", completed, total))

Enhanced Pattern:

var completedCount int64
spinner := console.NewSpinner("")
if !verbose {
    // Automatic updates on every spinner frame
    spinner.spinner.PreUpdate = func(s *spinner.Spinner) {
        completed := atomic.LoadInt64(&completedCount)
        s.Suffix = fmt.Sprintf(" Downloading artifacts... (%d/%d completed)", completed, totalRuns)
    }
    spinner.Start()
}

Benefit:

• Cleaner code - progress updates happen automatically
• Real-time feedback on every spinner frame (~100ms)
• No need to manually call UpdateMessage()

Impact: Improves code quality and user experience for progress-tracking operations.

2. Add Enable/Disable Toggle Support

Available Since: v1.19.0 (July 2022)
Not Currently Used: Methods exist but aren't leveraged

Potential Use Case: Dynamic verbose mode toggling

Enhancement:

// Add to SpinnerWrapper
func (s *SpinnerWrapper) Toggle(enabled bool) {
    if s.spinner != nil {
        if enabled {
            s.spinner.Enable()
        } else {
            s.spinner.Disable()
        }
        s.enabled = enabled
    }
}

Benefit: Runtime control without recreating spinner instances. Could enable SIGUSR1 signal to toggle verbose mode during long operations.

Impact: Minor API addition, enables advanced usage patterns.

3. Consider Different CharSets for Operation Types

Current: All spinners use CharSet 14 (braille dots: ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏)

Enhancement: Use different visual styles for different operation types:

• Waiting (network calls): CharSet 14 (current, braille dots)
• Progress (downloads): CharSet 35 (progress bar: █▒▒▒▒▒▒▒▒▒)
• Processing (compilation): CharSet 9 (classic: |/-)

Example:

// For download operations with progress
func NewProgressSpinner(msg string) *SpinnerWrapper {
    // ... similar to NewSpinner but with CharSets[35]
}

Benefit: Visual distinction helps users understand operation type at a glance.

Impact: Optional enhancement, adds variety to UI.

📐 Best Practice Alignment

Current Strengths ✓

The gh-aw project already follows spinner best practices:

1. ✅ Stderr output: Spinners write to stderr, allowing stdout piping
2. ✅ TTY detection: Proper tty.IsStderrTerminal() check before starting
3. ✅ Clean abstraction: SpinnerWrapper prevents library coupling
4. ✅ Consistent lifecycle: Start/Stop pattern used throughout
5. ✅ Verbose mode: Respects --verbose flag to disable spinners
6. ✅ Proper color: Cyan color provides good visibility
7. ✅ Final messages: Uses StopWithMessage() for completion feedback

Error Handling Note

Current: _ = s.spinner.Color("cyan") at pkg/console/spinner.go:29

This is acceptable - "cyan" is a valid color, so the error will never occur. The silent ignore is fine for known-valid inputs. No action needed.

🔧 General Improvements

1. Document Spinner vs. Progress Bar Guidelines

Context: gh-aw correctly uses spinners for indefinite waits.

Recommendation: Document the decision criteria:

• Spinners: Indefinite waits (network calls, waiting for workflow start)
• Progress bars: Definite progress (downloading N artifacts with known count)

Current usage: Already correct! All spinners are for operations with unknown duration.

2. Show Retry Attempts in Spinner Messages

Location: run_command.go:546 - retry loop for workflow runs

Enhancement:

for attempt := 0; attempt < maxRetries; attempt++ {
    if spinner != nil && attempt > 0 {
        spinner.UpdateMessage(fmt.Sprintf(
            "Waiting for workflow run... (attempt %d/%d)", 
            attempt+1, maxRetries,
        ))
    }
    // ... retry logic ...
}

Benefit: Users know the operation is retrying, not hung.

Impact: Better transparency during potentially slow operations.

3. Enhance Test Coverage

Current: spinner_test.go has basic tests that verify no panics.

Recommended Additions:

• Test TTY vs. non-TTY behavior (spinner enabled/disabled)
• Test message updates during active spin
• Test FinalMSG rendering
• Test Enable()/Disable() toggling
• Test color setting edge cases

Benefit: Ensure wrapper behavior is reliable across all scenarios.

Impact: Improve test coverage for the console package.

Open Issues Analysis (Community Feedback)

Review of upstream issues revealed:

1. Network Permissions Testing Results - MCP Container Domain Restrictions Validation #159: Final glyph replacement (✅/✗ on stop)

   • Relevance: HIGH - Directly addressed by StopSuccess()/StopError() recommendation
   • Action: Implement in wrapper (not yet upstream)

2. [claude-test] Unable to access Pull Request #146 - the PR appears to be invalid or inaccessible. Please verify the PR number and repository access permissions. #157: Spinner overwrites previous line

   • Relevance: LOW - Doesn't affect gh-aw's usage pattern

3. [copilot] concurrency policy for issue/pull_request events should have issue/pr.number #113: Long messages wrap badly on Windows

   • Relevance: MEDIUM - Could affect Windows users
   • Mitigation: Keep messages concise (already done ✓)

4. [claude-test] Patches flow like streams #143: Windows Taskbar Progress

   • Relevance: LOW - Nice-to-have, not critical

Dependency Analysis

Perfect Alignment ✨

The spinner library's move to golang.org/x/term in v1.23.1 creates perfect alignment with gh-aw:

gh-aw dependencies:
├── golang.org/x/term v0.37.0 (used by pkg/tty)
└── github.com/briandowns/spinner v1.23.2
    └── golang.org/x/term v0.x.x (uses same package!)

Benefits:

• Zero dependency conflicts
• Reduced total dependency count (removed go-isatty)
• Ecosystem convergence (golang.org/x packages are Go standard extensions)
• Both gh-aw and spinner use the same terminal detection mechanism

This is excellent architecture - shared dependencies for shared functionality.

Recommendations

Priority 1: Quick Wins (Implement Soon)

1. ✅ Already excellent: stderr, TTY checking, lifecycle management
2. 🔄 Minor improvement: Switch to WithWriterFile(os.Stderr) in pkg/console/spinner.go:27
3. ✨ UX enhancement: Add StopSuccess() and StopError() methods with ✓/✗ symbols
4. 📋 Maintainability: Extract spinner configuration to constants

Priority 2: Feature Opportunities (Consider)

1. Explore PreUpdate callbacks for automatic progress updates in logs.go
2. Add Toggle() method for dynamic verbose mode control
3. Consider different CharSets for different operation types

Priority 3: Nice-to-Have

1. Document spinner vs. progress bar usage guidelines
2. Show retry attempts in spinner messages
3. Enhance test coverage for SpinnerWrapper edge cases

Next Steps

Immediate Actions: None required! The current implementation is production-ready.

Optional Enhancements:

1. Add success/error completion methods (15 lines of code, high user value)
2. Switch to WithWriterFile for consistency (1 line change)
3. Extract configuration constants (5 lines, better maintainability)

Monitor:

• Watch for v1.24.0 release (no known timeline)
• Community issue Network Permissions Testing Results - MCP Container Domain Restrictions Validation #159 (final glyph) - may be added upstream

Conclusion

The gh-aw project demonstrates exemplary usage of github.com/briandowns/spinner:

✨ Strengths

• ✅ Already on latest version (v1.23.2)
• ✅ Perfect dependency alignment with golang.org/x/term
• ✅ Clean wrapper abstraction prevents library coupling
• ✅ Follows all best practices (stderr, TTY, verbose mode)
• ✅ Consistent usage patterns across 11 instances
• ✅ Battle-tested library (2.3k+ stars, 8+ years active)
• ✅ Zero critical issues

🎯 Minor Improvements Available

• Add visual completion indicators (✓/✗)
• Use WithWriterFile for terminal detection
• Explore PreUpdate callbacks for progress tracking
• Extract configuration constants

📊 Assessment

Overall Grade: A+ (Excellent)

The module is well-chosen, well-utilized, and properly maintained. The recent dependency consolidation (v1.23.1) perfectly aligns with gh-aw's architecture. The suggested improvements are optional enhancements, not fixes for problems.

No action required - continue current usage. Consider the quick wins for incremental UX improvements.

---

Module summary saved to: specs/mods/spinner.md
Repository: https://github.com/briandowns/spinner
Documentation: https://pkg.go.dev/github.com/briandowns/spinner
Last Reviewed: 2025-12-05 by Go Fan 🐹

AI generated by Go Fan

[github-actions[bot]]

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