console

package
v0.51.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 1, 2026 License: MIT Imports: 21 Imported by: 0

README

Console Rendering Package

The console package provides utilities for rendering Go structs and data structures to formatted console output, as well as progress bar and spinner components for long-running operations.

Design Philosophy

This package follows Charmbracelet best practices for terminal UI:

  • Adaptive Colors: All styling uses lipgloss.AdaptiveColor for light/dark theme support
  • Rounded Borders: Tables and boxes use rounded corners (╭╮╰╯) for a polished appearance
  • Consistent Padding: All rendered elements include proper spacing (horizontal and vertical)
  • TTY Detection: Automatically adapts output for terminals vs pipes/redirects
  • Visual Hierarchy: Clear separation between sections using borders and spacing
  • Zebra Striping: Tables use alternating row colors for improved readability
Border Usage Guidelines
  • RoundedBorder (primary): Use for tables, boxes, and panels
    • Creates a polished, modern appearance
    • Consistent with Charmbracelet design language
  • NormalBorder (subtle): Use for left-side emphasis on info sections
    • Provides gentle visual guidance without overwhelming
  • ThickBorder (reserved): Available for special cases requiring extra emphasis
    • Use sparingly - rounded borders with bold text usually suffice
Padding Guidelines
  • Table cells: 1 character horizontal padding (left/right)
  • Boxes: 2 character horizontal padding, 0-1 vertical padding
  • Info sections: 2 character left padding for consistent indentation

Spinner Component

The Spinner component provides animated visual feedback during long-running operations with automatic TTY detection and accessibility support.

Features
  • MiniDot animation: Minimal dot spinner (⣾ ⣽ ⣻ ⢿ ⡿ ⣟ ⣯ ⣷)
  • TTY detection: Automatically disabled in pipes/redirects
  • Accessibility support: Respects ACCESSIBLE environment variable
  • Color adaptation: Uses adaptive colors for light/dark themes
  • Idiomatic Bubble Tea: Uses tea.NewProgram() with proper message passing
  • Thread-safe: Safe for concurrent use via Bubble Tea's message handling
Usage
import "github.com/github/gh-aw/pkg/console"

// Create and use a spinner
spinner := console.NewSpinner("Loading...")
spinner.Start()
// Long-running operation
spinner.Stop()

// Stop with a message
spinner := console.NewSpinner("Processing...")
spinner.Start()
// Long-running operation
spinner.StopWithMessage("✓ Done!")

// Update message while running
spinner := console.NewSpinner("Starting...")
spinner.Start()
spinner.UpdateMessage("Still working...")
// Long-running operation
spinner.Stop()
Accessibility

The spinner respects the ACCESSIBLE environment variable. When set to any value, spinner animations are disabled to support screen readers and accessibility tools:

export ACCESSIBLE=1
gh aw compile workflow.md  # Spinners will be disabled
TTY Detection

Spinners only animate in terminal environments. When output is piped or redirected, the spinner is automatically disabled:

gh aw compile workflow.md           # Spinner animates
gh aw compile workflow.md > log.txt # Spinner disabled

ProgressBar Component

The ProgressBar component provides a reusable progress bar with TTY detection and graceful fallback for non-TTY environments.

Features
  • Scaled gradient effect: Smooth color transition from purple to cyan as progress advances
  • TTY detection: Automatically adapts to terminal environment
  • Byte formatting: Converts byte counts to human-readable sizes (KB, MB, GB)
  • Thread-safe updates: Safe for concurrent use with atomic operations
Visual Styling

The progress bar uses bubbles v0.21.0+ gradient capabilities for enhanced visual appeal:

  • Start (0%): #BD93F9 (purple) - vibrant, attention-grabbing
  • End (100%): #8BE9FD (cyan) - cool, completion feeling
  • Empty portion: #6272A4 (muted purple-gray)
  • Gradient scaling: WithScaledGradient ensures gradient scales with filled portion
Usage
Determinate Mode (known total)

Use when the total size or count is known:

import "github.com/github/gh-aw/pkg/console"

// Create a progress bar for 1GB total
totalBytes := int64(1024 * 1024 * 1024)
bar := console.NewProgressBar(totalBytes)

// Update progress (returns formatted string)
output := bar.Update(currentBytes)
fmt.Fprintf(os.Stderr, "\r%s", output)
Indeterminate Mode (unknown total)

Use when the total size or count is unknown:

import "github.com/github/gh-aw/pkg/console"

// Create an indeterminate progress bar
bar := console.NewIndeterminateProgressBar()

// Update with current progress (shows activity without percentage)
output := bar.Update(currentBytes)
fmt.Fprintf(os.Stderr, "\r%s", output)
Output Examples

Determinate Mode - TTY:

████████████████████░░░░░░░░░░░░░░░░░  50%

(Displays with gradient from purple to cyan)

Determinate Mode - Non-TTY:

50% (512.0MB/1.00GB)

Indeterminate Mode - TTY:

████████████████░░░░░░░░░░░░░░░░░░░░  (pulsing animation)

(Shows pulsing progress indicator)

Indeterminate Mode - Non-TTY:

Processing... (512.0MB)

RenderStruct Function

The RenderStruct function uses reflection to automatically render Go structs based on struct tags.

Struct Tags

Use the console struct tag to control rendering behavior:

Available Tags
  • header:"Column Name" - Sets the display name for the field (used in both structs and tables)
  • title:"Section Title" - Sets the title for nested structs, slices, or maps
  • omitempty - Skips the field if it has a zero value
  • "-" - Always skips the field
Tag Examples
type Overview struct {
    RunID      int64  `console:"header:Run ID"`
    Workflow   string `console:"header:Workflow"`
    Status     string `console:"header:Status"`
    Duration   string `console:"header:Duration,omitempty"`
    Internal   string `console:"-"` // Never displayed
}
Rendering Behavior
Structs

Structs are rendered as key-value pairs with proper alignment:

  Run ID    : 12345
  Workflow  : my-workflow
  Status    : completed
  Duration  : 5m30s
Slices

Slices of structs are automatically rendered as tables using the console table renderer:

type Job struct {
    Name       string `console:"header:Name"`
    Status     string `console:"header:Status"`
    Conclusion string `console:"header:Conclusion,omitempty"`
}

jobs := []Job{
    {Name: "build", Status: "completed", Conclusion: "success"},
    {Name: "test", Status: "in_progress", Conclusion: ""},
}

fmt.Print(console.RenderStruct(jobs))

Renders as:

Name  | Status      | Conclusion
----- | ----------- | ----------
build | completed   | success
test  | in_progress | -
Maps

Maps are rendered as markdown-style headers with key-value pairs:

data := map[string]string{
    "Repository": "github/gh-aw",
    "Author":     "test-user",
}

fmt.Print(console.RenderStruct(data))

Renders as:

  Repository: github/gh-aw
  Author    : test-user
Special Type Handling
time.Time

time.Time fields are automatically formatted as "2006-01-02 15:04:05". Zero time values are considered empty when used with omitempty.

Unexported Fields

The rendering system safely handles unexported struct fields by checking CanInterface() before attempting to access field values.

Usage in Audit Command

The audit command uses the new rendering system for structured output:

// Render overview section
renderOverview(data.Overview)

// Render metrics with custom formatting
renderMetrics(data.Metrics)

// Render jobs as a table
renderJobsTable(data.Jobs)

This provides:

  • Consistent formatting across all audit sections
  • Automatic table generation for slice data
  • Proper handling of optional/empty fields
  • Type-safe reflection-based rendering
Migration Guide

To migrate existing rendering code to use the new system:

  1. Add struct tags to your data types:

    type MyData struct {
    Field1 string `console:"header:Field 1"`
    Field2 int    `console:"header:Field 2,omitempty"`
}

  2. Use RenderStruct for simple structs:

    fmt.Print(console.RenderStruct(myData))

  3. Use custom rendering for special formatting needs:

    func renderMyData(data MyData) {
    fmt.Printf("  %-15s %s\n", "Field 1:", formatCustom(data.Field1))
    // ... custom formatting logic
}

  4. Use console.RenderTable for tables with custom formatting:

    config := console.TableConfig{
    Headers: []string{"Name", "Value"},
    Rows: [][]string{
        {truncateString(item.Name, 40), formatNumber(item.Value)},
    },
}
fmt.Print(console.RenderTable(config))

Documentation

Overview

Package console provides terminal UI components including spinners for long-running operations.

Spinner Component

The spinner provides visual feedback during long-running operations with a minimal dot animation (⣾ ⣽ ⣻ ⢿ ⡿ ⣟ ⣯ ⣷). It automatically adapts to the environment:

  • TTY Detection: Spinners only animate in terminal environments (disabled in pipes/redirects)
  • Accessibility: Respects ACCESSIBLE environment variable to disable animations
  • Color Adaptation: Uses lipgloss adaptive colors for light/dark terminal themes

Implementation

This spinner uses idiomatic Bubble Tea patterns with tea.NewProgram() for proper message handling and rendering pipeline integration. It includes thread-safe lifecycle management:

  • Thread-safe start/stop tracking with mutex protection
  • Safe to call Stop/StopWithMessage before Start (no-op or message-only)
  • Prevents multiple concurrent Start calls
  • No deadlock when stopping before goroutine initializes
  • Leverages Bubble Tea's message passing for updates

Usage Example 

spinner := console.NewSpinner("Loading...")
spinner.Start()
// Long-running operation
spinner.Stop()

Accessibility

Spinners respect the ACCESSIBLE environment variable. When ACCESSIBLE is set to any value, spinner animations are disabled to support screen readers and accessibility tools. 

export ACCESSIBLE=1
gh aw compile workflow.md  # Spinners will be disabled

Index

Constants

This section is empty.

Variables

View Source 
var BannerStyle = lipgloss.NewStyle().
	Bold(true).
	Foreground(styles.ColorPurple)

BannerStyle defines the style for the ASCII banner Uses GitHub's purple color theme

Functions

func ClearLine 

func ClearLine()

ClearLine clears the current line in the terminal if stderr is a TTY Uses ANSI escape codes: \r moves cursor to start, \033[K clears to end of line

func ClearScreen 

func ClearScreen()

ClearScreen clears the terminal screen if stderr is a TTY Uses ANSI escape codes for cross-platform compatibility

func ConfirmAction 

func ConfirmAction(title, affirmative, negative string) (bool, error)

ConfirmAction shows an interactive confirmation dialog using Bubble Tea (huh) Returns true if the user confirms, false if they cancel or an error occurs

func FormatBanner 

func FormatBanner() string

FormatBanner returns the ASCII logo formatted with purple GitHub color theme. It applies the purple color styling when running in a terminal (TTY).

func FormatCommandMessage 

func FormatCommandMessage(command string) string

FormatCommandMessage formats a command execution message

func FormatError 

func FormatError(err CompilerError) string

FormatError formats a CompilerError with Rust-like rendering

func FormatErrorMessage 

func FormatErrorMessage(message string) string

FormatErrorMessage formats a simple error message (for stderr output)

func FormatErrorWithSuggestions 

func FormatErrorWithSuggestions(message string, suggestions []string) string

FormatErrorWithSuggestions formats an error message with actionable suggestions

func FormatFileSize 

func FormatFileSize(size int64) string

FormatFileSize formats file sizes in a human-readable way (e.g., "1.2 KB", "3.4 MB")

func FormatInfoMessage 

func FormatInfoMessage(message string) string

FormatInfoMessage formats an informational message

func FormatListItem 

func FormatListItem(item string) string

FormatListItem formats an item in a list

func FormatNumber 

func FormatNumber(n int) string

FormatNumber formats large numbers in a human-readable way (e.g., "1k", "1.2k", "1.12M")

func FormatProgressMessage 

func FormatProgressMessage(message string) string

FormatProgressMessage formats a progress/activity message

func FormatPromptMessage 

func FormatPromptMessage(message string) string

FormatPromptMessage formats a user prompt message

func FormatSectionHeader 

func FormatSectionHeader(header string) string

FormatSectionHeader formats a section header with proper styling

func FormatSuccessMessage 

func FormatSuccessMessage(message string) string

FormatSuccessMessage formats a success message with styling

func FormatVerboseMessage 

func FormatVerboseMessage(message string) string

FormatVerboseMessage formats verbose debugging output

func FormatWarningMessage 

func FormatWarningMessage(message string) string

FormatWarningMessage formats a warning message

func IsAccessibleMode 

func IsAccessibleMode() bool

IsAccessibleMode detects if accessibility mode should be enabled based on environment variables. Accessibility mode is enabled when: - ACCESSIBLE environment variable is set to any value - TERM environment variable is set to "dumb" - NO_COLOR environment variable is set to any value

This function should be used by UI components to determine whether to: - Disable animations and spinners - Simplify interactive elements - Use plain text instead of fancy formatting

func LogVerbose 

func LogVerbose(verbose bool, message string)

LogVerbose outputs a verbose message to stderr only when verbose mode is enabled. This is a convenience helper to avoid repetitive if-verbose checks throughout the codebase.

func PrintBanner 

func PrintBanner()

PrintBanner prints the ASCII logo to stderr with purple GitHub color theme. This is used by the --banner flag to display the logo at the start of command execution.

func PromptSecretInput added in v0.42.14 

func PromptSecretInput(title, description string) (string, error)

PromptSecretInput shows an interactive password input prompt with masking The input is masked for security and includes validation Returns the entered secret value or an error

func RenderComposedSections 

func RenderComposedSections(sections []string)

RenderComposedSections composes and outputs a slice of sections to stderr

func RenderErrorBox 

func RenderErrorBox(title string) []string

RenderErrorBox renders an error/warning message with a rounded border box

func RenderInfoSection 

func RenderInfoSection(content string) []string

RenderInfoSection renders an info section with left border emphasis

func RenderStruct 

func RenderStruct(v any) string

RenderStruct renders a Go struct to console output using reflection and struct tags. It supports: - Rendering structs as markdown-style headers with key-value pairs - Rendering slices as tables using the console table renderer - Rendering maps as markdown headers

Struct tags: - `console:"title:My Title"` - Sets the title for a section - `console:"header:Column Name"` - Sets the column header name for table columns - `console:"omitempty"` - Skips zero values - `console:"-"` - Skips the field entirely

func RenderTable 

func RenderTable(config TableConfig) string

RenderTable renders a formatted table using lipgloss/table package

func RenderTitleBox 

func RenderTitleBox(title string, width int) []string

RenderTitleBox renders a title with a double border box in TTY mode

func ShowInteractiveList 

func ShowInteractiveList(title string, items []ListItem) (string, error)

ShowInteractiveList displays an interactive list with arrow key navigation Returns the selected item's value, or an error if cancelled or failed

func ShowWelcomeBanner added in v0.45.5 

func ShowWelcomeBanner(description string)

ShowWelcomeBanner clears the screen and displays the welcome banner for interactive commands. Use this at the start of interactive commands (add, trial, init) for a consistent experience.

func ToRelativePath 

func ToRelativePath(path string) string

ToRelativePath converts an absolute path to a relative path from the current working directory If the relative path contains "..", returns the absolute path instead for clarity

Types

type CompilerError 

type CompilerError struct {
	Position ErrorPosition
	Type     string // "error", "warning", "info"
	Message  string
	Context  []string // Source code lines for context
	Hint     string   // Optional hint for fixing the error
}

CompilerError represents a structured compiler error with position information

type ErrorPosition 

type ErrorPosition struct {
	File   string
	Line   int
	Column int
}

ErrorPosition represents a position in a source file

type FormField added in v0.42.14 

type FormField struct {
	Type        string // "input", "password", "confirm", "select"
	Title       string
	Description string
	Placeholder string
	Value       any                // Pointer to the value to store the result
	Options     []SelectOption     // For select fields
	Validate    func(string) error // For input/password fields
}

FormField represents a generic form field configuration

type ListItem 

type ListItem struct {
	// contains filtered or unexported fields
}

ListItem represents an item in an interactive list

func NewListItem 

func NewListItem(title, description, value string) ListItem

NewListItem creates a new list item with title, description, and value

func (ListItem) Description 

func (i ListItem) Description() string

Description returns the item's description

func (ListItem) FilterValue 

func (i ListItem) FilterValue() string

FilterValue returns the value used for filtering

func (ListItem) Title 

func (i ListItem) Title() string

Title returns the item's title

type ProgressBar 

type ProgressBar struct {
	// contains filtered or unexported fields
}

ProgressBar provides a reusable progress bar component with TTY detection and graceful fallback to text-based progress for non-TTY environments.

Modes:

  • Determinate: When total size is known (shows percentage and progress)
  • Indeterminate: When total size is unknown (shows activity indicator)

Visual Features:

  • Scaled gradient effect from purple (#BD93F9) to cyan (#8BE9FD)
  • Smooth color transitions using bubbles v0.21.0+ gradient capabilities
  • Gradient scales with filled portion for enhanced visual feedback
  • Works well in both light and dark terminal themes

The gradient provides visual appeal without affecting functionality:

  • TTY mode: Visual progress bar with smooth gradient transitions
  • Non-TTY mode: Text-based percentage with human-readable byte sizes

func NewProgressBar 

func NewProgressBar(total int64) *ProgressBar

NewProgressBar creates a new progress bar with the specified total size (determinate mode) The progress bar automatically adapts to TTY/non-TTY environments

func (*ProgressBar) Update 

func (p *ProgressBar) Update(current int64) string

Update updates the current progress and returns a formatted string In determinate mode:

  • TTY: Returns a visual progress bar with gradient and percentage
  • Non-TTY: Returns text percentage with human-readable sizes

In indeterminate mode:

  • TTY: Returns a pulsing progress indicator
  • Non-TTY: Returns processing indicator with current value

type SelectOption added in v0.42.14 

type SelectOption struct {
	Label string
	Value string
}

SelectOption represents a selectable option with a label and value

type SpinnerWrapper 

type SpinnerWrapper struct {
	// contains filtered or unexported fields
}

SpinnerWrapper wraps the spinner functionality with TTY detection and Bubble Tea program

func NewSpinner 

func NewSpinner(message string) *SpinnerWrapper

NewSpinner creates a new spinner with the given message using MiniDot style. Automatically disabled when not running in a TTY or when ACCESSIBLE env var is set.

func (*SpinnerWrapper) Start 

func (s *SpinnerWrapper) Start()

func (*SpinnerWrapper) Stop 

func (s *SpinnerWrapper) Stop()

func (*SpinnerWrapper) StopWithMessage 

func (s *SpinnerWrapper) StopWithMessage(msg string)

func (*SpinnerWrapper) UpdateMessage 

func (s *SpinnerWrapper) UpdateMessage(message string)

type TableConfig 

type TableConfig struct {
	Headers   []string
	Rows      [][]string
	Title     string
	ShowTotal bool
	TotalRow  []string
}

TableConfig represents configuration for table rendering

type TreeNode 

type TreeNode struct {
	Value    string
	Children []TreeNode
}

TreeNode represents a node in a hierarchical tree structure

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.