Skip to content

Fully autonomous AI Agents system capable of performing complex penetration testing tasks

18.8 KB
Raw Blame

Terminal Integration Guide for Wizard Screens

This guide covers integration of the terminal package into wizard configuration screens, providing command execution capabilities with real-time UI updates.

Core Architecture

The terminal system consists of three layers:

  • Virtual Terminal (VT): Low-level ANSI parsing and screen management (terminal/vt/)
  • Terminal Interface: High-level command execution with PTY/pipe support (terminal/)
  • Wizard Integration: Screen-specific integration patterns (wizard/models/)

Terminal Modes

PTY Mode (Default on Unix)

  • Full pseudoterminal emulation via creack/pty
  • ANSI escape sequence processing through VT layer
  • Interactive command support (vim, less, etc.)
  • Proper terminal environment variables

Pipe Mode (Windows/NoPty)

  • Standard stdin/stdout/stderr pipes
  • Line-by-line output processing
  • Simpler but limited interactivity
  • Plain text output handling

Configuration Options

Terminal behavior is controlled via functional options:

// Essential options for wizard integration
terminal.NewTerminal(width, height,
    terminal.WithAutoScroll(),     // Auto-scroll to bottom on updates
    terminal.WithAutoPoll(),       // Continuous update polling
    terminal.WithCurrentEnv(),     // Inherit process environment
)

// Advanced options
terminal.WithNoStyled()            // Disable ANSI styling (PTY only)
terminal.WithNoPty()              // Force pipe mode
terminal.WithStyle(lipgloss.Style) // Custom viewport styling

Integration Patterns

Complete Integration Template

type YourFormModel struct {
    *BaseScreen
    terminal terminal.Terminal
    // other screen-specific fields
}

func NewYourFormModel(controller *controllers.StateController, styles *styles.Styles, window *window.Window, args []string) *YourFormModel {
    m := &YourFormModel{}
    m.BaseScreen = NewBaseScreen(controller, styles, window, args, m, nil)
    return m
}

// Required BaseScreenHandler implementation
func (m *YourFormModel) BuildForm() tea.Cmd {
    contentWidth, contentHeight := m.getViewportFormSize()

    // Initialize or reset terminal
    if m.terminal == nil {
        m.terminal = terminal.NewTerminal(
            contentWidth-4,  // Account for border + padding
            contentHeight-1, // Account for border
            terminal.WithAutoScroll(),
            terminal.WithAutoPoll(),
            terminal.WithCurrentEnv(),
        )
    } else {
        m.terminal.Clear()
    }

    // Set initial content
    m.terminal.Append("Terminal initialized...")

    // CRITICAL: Return terminal init for update subscription (idempotent)
    // repeated calls to Init() are safe: only a single waiter will receive
    // the next TerminalUpdateMsg; others will return nil quietly
    return m.terminal.Init()
}

Sizing Calculations

The sizing adjustments account for UI elements:

  • Width -4: Left border (1) + left padding (1) + right padding (1) + right border (1)
  • Height -1: Top/bottom borders, content area needs space for text
  • Use m.getViewportFormSize() from BaseScreen for consistent calculations
  • Handle dynamic resizing in Update() method

Event Flow Architecture

The system uses a single-waiter update notifier for real-time updates:

  1. Update Notifier: Manages single-waiter update notifications (teacmd.go)
  2. Update Messages: TerminalUpdateMsg carries terminal ID
  3. Subscription Model: Commands wait for release() signalling the next update
  4. Auto-polling: Continuous listening when WithAutoPoll() enabled
  5. Single-waiter guarantee: For a given Terminal, at most one pending waiter is active at any time. Multiple Init() calls are safe; only one will receive the next TerminalUpdateMsg after release(), others return nil.

Complete Update Method Implementation

func (m *YourFormModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    // Helper function to handle terminal delegation
    handleTerminal := func(msg tea.Msg) (tea.Model, tea.Cmd) {
        if m.terminal == nil {
            return m, nil
        }

        updatedModel, cmd := m.terminal.Update(msg)
        if terminalModel := terminal.RestoreModel(updatedModel); terminalModel != nil {
            m.terminal = terminalModel
        }
        return m, cmd
    }

    switch msg := msg.(type) {
    case tea.WindowSizeMsg:
        // Update terminal size first
        contentWidth, contentHeight := m.getViewportFormSize()
        if m.terminal != nil {
            m.terminal.SetSize(contentWidth-4, contentHeight-1)
        }

        // Update viewports (BaseScreen functionality)
        m.updateViewports()
        return m, nil

    case terminal.TerminalUpdateMsg:
        // Terminal content updated - delegate and continue listening
        // Only a single update message will be emitted per content change,
        // even if Init() was invoked multiple times
        return handleTerminal(msg)

    case tea.KeyMsg:
        // Route keys based on terminal state
        if m.terminal != nil && m.terminal.IsRunning() {
            // Command is running - all keys go to terminal
            return handleTerminal(msg)
        }

        // Terminal is idle - handle screen-specific hotkeys first
        switch msg.String() {
        case "enter":
            // Your screen-specific action
            if m.terminal != nil && !m.terminal.IsRunning() {
                m.executeCommands()
                return m, nil
            }
        case "ctrl+r":
            // Reset functionality
            m.handleReset()
            return m, nil
        }

        // Pass remaining keys to terminal for scrolling
        return handleTerminal(msg)

    default:
        // Other messages (like custom commands) - delegate to terminal
        return handleTerminal(msg)
    }
}

Event Processing Order

Process events in this strict order to ensure proper functionality:

  1. Window Resize: Update terminal dimensions before any other processing
  2. Terminal Updates: Handle TerminalUpdateMsg immediately for real-time updates
  3. Key Routing: Route based on IsRunning() state
    • Running commands: All keys forwarded to terminal for interaction
    • Idle terminal: Screen hotkeys first, then terminal scrolling
  4. Other Messages: Delegate to terminal for potential internal handling

Command Execution

Single Command with Error Handling

func (m *YourFormModel) executeCommand() {
    cmd := exec.Command("echo", "hello")

    err := m.terminal.Execute(cmd)
    if err != nil {
        // Display error to user through terminal
        m.terminal.Append(fmt.Sprintf("❌ Command failed: %v", err))
        m.terminal.Append("Please check the command and try again.")
        return
    }

    // Wait for completion if needed
    go func() {
        for m.terminal.IsRunning() {
            time.Sleep(100 * time.Millisecond)
        }
        m.terminal.Append("✅ Command completed successfully")
    }()
}

Sequential Commands with Robust Error Handling

func (m *YourFormModel) executeCommands() {
    if m.terminal.IsRunning() {
        m.terminal.Append("⚠️ Another command is already running")
        return
    }

    commands := []struct {
        cmd     []string
        desc    string
        canFail bool
    }{
        {[]string{"echo", "Starting process..."}, "Initialize", false},
        {[]string{"docker", "--version"}, "Check Docker", true},
        {[]string{"docker-compose", "up", "-d"}, "Start services", false},
    }

    go func() {
        for i, cmdDef := range commands {
            if i > 0 {
                time.Sleep(500 * time.Millisecond)
            }

            m.terminal.Append(fmt.Sprintf("🔄 Step %d: %s", i+1, cmdDef.desc))

            cmd := exec.Command(cmdDef.cmd[0], cmdDef.cmd[1:]...)
            err := m.terminal.Execute(cmd)

            if err != nil {
                m.terminal.Append(fmt.Sprintf("❌ Failed: %v", err))
                if !cmdDef.canFail {
                    m.terminal.Append("💥 Critical error - stopping execution")
                    return
                }
                m.terminal.Append("⚠️ Non-critical error - continuing...")
                continue
            }

            // Wait for command completion
            timeout := time.After(30 * time.Second)
            ticker := time.NewTicker(100 * time.Millisecond)
            completed := false

            for !completed {
                select {
                case <-timeout:
                    m.terminal.Append("⏰ Command timeout - terminating")
                    return
                case <-ticker.C:
                    if !m.terminal.IsRunning() {
                        completed = true
                    }
                }
            }
            ticker.Stop()
        }

        m.terminal.Append("🎉 All commands completed successfully!")
    }()
}

### Interactive Commands
Terminal automatically handles:
- Stdin forwarding in both PTY and pipe modes
- Key-to-input conversion (`key2uv.go`)
- ANSI escape sequence processing (PTY mode)

## Key Input Handling

### PTY Mode
- Full ANSI key sequence support via Ultraviolet conversion
- Vim-style navigation (arrows, page up/down, home/end)
- Control sequences (Ctrl+C, Ctrl+D, etc.)
- Alt+key combinations

### Pipe Mode
- Basic key mapping to stdin bytes
- Enter, space, tab, backspace support
- Control characters (Ctrl+C → \x03)

### Viewport Scrolling
Keys not consumed by running commands are passed to viewport:
- Page Up/Down, Home/End for navigation
- Preserved when terminal is idle

## Lifecycle Management

### Terminal Creation and Cleanup
```go
// Terminal lifecycle follows screen lifecycle
func (m *YourFormModel) BuildForm() tea.Cmd {
    // Create terminal once per screen instance
    if m.terminal == nil {
        m.terminal = terminal.NewTerminal(...)
    } else {
        // Reset content when re-entering screen
        m.terminal.Clear()
    }
    return m.terminal.Init()
}

// No manual cleanup needed - handled by finalizers
// Terminal will be cleaned up when screen model is garbage collected

Screen Navigation Considerations

  • Terminal Persistence: Terminal remains active during screen navigation
  • Content Reset: Use Clear() when re-entering screens to avoid content buildup
  • Resource Cleanup: Automatic via finalizers when screen model is destroyed
  • State Preservation: Terminal state (size, options) persists across BuildForm() calls

State Checking and Debugging

// Essential state checks
if m.terminal == nil {
    // Terminal not initialized - call BuildForm()
}

if m.terminal.IsRunning() {
    // Command is executing - avoid new commands
    // Show spinner or disable UI elements
}

// Debugging helpers
terminalID := m.terminal.ID()           // Unique identifier for logging
width, height := m.terminal.GetSize()  // Current dimensions
view := m.terminal.View()               // Current rendered content

// For debugging terminal content
if DEBUG {
    log.Printf("Terminal %s: %dx%d, running=%t",
        terminalID, width, height, m.terminal.IsRunning())
}

Resource Management Details

Resources managed via Go finalizers (terminal.go:131-142):

  • PTY file descriptors: Automatically closed when terminal is garbage collected
  • Process termination: Running processes killed during cleanup
  • Notifier shutdown: Wait channel closed and state reset
  • Mutex-protected cleanup: Thread-safe resource cleanup
  • No manual Close(): Resources cleaned automatically, no explicit cleanup needed

Virtual Terminal Capabilities

The VT layer provides advanced features:

  • Screen Buffer: Main and alternate screen support
  • Scrollback: Configurable history buffer
  • ANSI Processing: Full VT100/xterm compatibility
  • Color Support: 256-color palette + true color
  • Cursor Modes: Various cursor styles and visibility
  • Character Sets: GL/GR charset switching

Testing Strategies

Key test patterns from terminal_test.go:

  • Command Output: Verify content appears in View()
  • Interactive Input: Simulate key sequences via Update()
  • Resource Cleanup: Manual finalizer calls for verification
  • Concurrent Access: Execute refuses a second command while one runs
  • Error Handling: Invalid commands and process failures

Concurrency and Threading

Thread Safety

// Terminal methods are thread-safe for these operations:
m.terminal.Append("message")       // Safe from any goroutine
m.terminal.IsRunning()            // Safe to check from any goroutine
m.terminal.ID()                   // Safe to call from any goroutine

// UI operations must be on main thread:
m.terminal.Update(msg)            // Only from main BubbleTea thread
m.terminal.View()                 // Only from main rendering thread
m.terminal.SetSize(w, h)          // Only from main thread

Command Execution Patterns

// CORRECT: Run commands in separate goroutine
go func() {
    m.terminal.Append("Starting long operation...")
    cmd := exec.Command("long-running-command")
    err := m.terminal.Execute(cmd)
    // Error handling...
}()

// INCORRECT: Blocking main thread
cmd := exec.Command("long-running-command")
m.terminal.Execute(cmd) // Will block UI updates

AutoPoll vs Manual Updates

  • WithAutoPoll(): Continuous listening, higher CPU but immediate updates; still single-waiter per terminal ensures no message storm. Updates are triggered internally via release() when content changes.
  • Manual polling: Call terminal.Init() only when needed, lower resource usage
  • Use AutoPoll: For active terminal screens with frequent updates
  • Skip AutoPoll: For background or rarely updated terminals

Troubleshooting Guide

Terminal Not Updating

Problem: Terminal content doesn't appear or update

Solutions:

  1. Ensure terminal.Init() is returned from BuildForm()
  2. Check TerminalUpdateMsg handling in Update() method — it should return next wait command to continue listening
  3. Verify handleTerminal() function calls RestoreModel()
  4. Add debug logging to track message flow
case terminal.TerminalUpdateMsg:
    log.Printf("Received terminal update: %s", msg.ID)
    return handleTerminal(msg)

Commands Not Executing

Problem: Execute() returns nil but nothing happens

Solutions:

  1. Check if previous command is still running: m.terminal.IsRunning()
  2. Verify command path and arguments
  3. Check terminal initialization
  4. Add error logging and terminal output
if m.terminal.IsRunning() {
    m.terminal.Append("⚠️ Previous command still running")
    return
}

UI Freezing During Commands

Problem: Interface becomes unresponsive

Solutions:

  1. Always run Execute() in goroutines for long commands
  2. Use WithAutoPoll() for real-time updates
  3. Implement proper key routing in Update()

Resource Leaks

Problem: Memory or file descriptor leaks

Solutions:

  1. Avoid creating multiple terminals unnecessarily
  2. Let finalizers handle cleanup (don't try manual cleanup)
  3. Check for goroutine leaks in command execution

Size and Layout Issues

Problem: Terminal appears cut off or incorrectly sized

Solutions:

  1. Use proper sizing calculations (width-4, height-1)
  2. Handle tea.WindowSizeMsg correctly
  3. Call m.updateViewports() after size changes

Best Practices

Initialization Checklist

  • ✅ Return terminal.Init() from BuildForm() (idempotent, single-waiter)
  • ✅ Use WithAutoPoll() for active terminals
  • ✅ Set appropriate dimensions with border adjustments
  • ✅ Initialize once per screen, clear content on re-entry

Event Processing Checklist

  • ✅ Handle TerminalUpdateMsg first in Update() and return next wait command
  • ✅ Properly restore terminal models after updates
  • ✅ Route keys based on IsRunning() state
  • ✅ Update terminal size on window resize

Command Management Checklist

  • ✅ Run long operations in goroutines
  • ✅ Check IsRunning() before new commands
  • ✅ Use Append() for progress and error messages
  • ✅ Implement timeouts for long-running commands
  • ✅ Handle both critical and non-critical errors

Performance Optimization

  • VT Layer: Automatically caches rendered lines for efficiency
  • Notifier: Single-waiter, release-based notifications to prevent message storms and deadlocks
  • Resource Cleanup: Deferred via finalizers to avoid blocking
  • AutoPoll Usage: Enable only for active terminals requiring real-time updates

Integration Examples

Progress Display (apply_changes.go)

Shows terminal integration in configuration screen with:

  • Dynamic content based on configuration state
  • Command execution with progress feedback
  • Proper event routing and error handling

Test Scenarios (terminal_test.go)

Demonstrates various usage patterns:

  • Simple command output verification
  • Interactive input simulation
  • Concurrent command execution prevention
  • Resource lifecycle management

Platform Considerations

Unix Systems

  • PTY mode provides full terminal emulation
  • ANSI sequences processed through VT layer
  • Interactive commands work naturally

Windows

  • Pipe mode used automatically
  • Limited interactivity compared to PTY
  • Plain text output processing

Environment Variables

  • TERM=xterm-256color set automatically in PTY mode
  • Current process environment inherited with WithCurrentEnv()
  • Custom environment via exec.Cmd.Env

Quick Reference

Essential Methods

// Creation and lifecycle
terminal.NewTerminal(width, height, options...)
m.terminal.Init()                    // Subscribe to updates
m.terminal.Clear()                   // Reset content

// Command execution
m.terminal.Execute(cmd)              // Run command
m.terminal.IsRunning()               // Check execution status
m.terminal.Append(text)              // Add content

// UI integration
m.terminal.Update(msg)               // Handle messages
m.terminal.View()                    // Render content
m.terminal.SetSize(width, height)    // Update dimensions

Common Error Patterns to Avoid

  • ❌ Creating multiple terminals per screen
  • ❌ Running Execute() on main thread for long commands
  • ❌ Forgetting to return terminal.Init() from BuildForm()
  • ❌ Not handling TerminalUpdateMsg in Update()
  • ❌ Calling UI methods from background goroutines
  • ❌ Manual resource cleanup (use finalizers instead)

Integration Checklist for New Screens

  1. ✅ Add terminal terminal.Terminal to model struct
  2. ✅ Initialize in BuildForm() with proper sizing
  3. ✅ Return terminal.Init() from BuildForm()
  4. ✅ Handle TerminalUpdateMsg first in Update()
  5. ✅ Implement proper key routing based on IsRunning()
  6. ✅ Handle window resize events
  7. ✅ Run commands in goroutines with error handling
  8. ✅ Add progress feedback via Append()

This comprehensive architecture provides robust terminal integration with wizard screens while maintaining proper resource management, real-time UI updates, and cross-platform compatibility.