Fully autonomous AI Agents system capable of performing complex penetration testing tasks
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:
- Update Notifier: Manages single-waiter update notifications (
teacmd.go) - Update Messages:
TerminalUpdateMsgcarries terminal ID - Subscription Model: Commands wait for
release()signalling the next update - Auto-polling: Continuous listening when
WithAutoPoll()enabled - Single-waiter guarantee: For a given
Terminal, at most one pending waiter is active at any time. MultipleInit()calls are safe; only one will receive the nextTerminalUpdateMsgafterrelease(), 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:
- Window Resize: Update terminal dimensions before any other processing
- Terminal Updates: Handle
TerminalUpdateMsgimmediately for real-time updates - Key Routing: Route based on
IsRunning()state- Running commands: All keys forwarded to terminal for interaction
- Idle terminal: Screen hotkeys first, then terminal scrolling
- 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:
Executerefuses 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:
- Ensure
terminal.Init()is returned fromBuildForm() - Check
TerminalUpdateMsghandling inUpdate()method — it should return next wait command to continue listening - Verify
handleTerminal()function callsRestoreModel() - 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:
- Check if previous command is still running:
m.terminal.IsRunning() - Verify command path and arguments
- Check terminal initialization
- 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:
- Always run
Execute()in goroutines for long commands - Use
WithAutoPoll()for real-time updates - Implement proper key routing in
Update()
Resource Leaks
Problem: Memory or file descriptor leaks
Solutions:
- Avoid creating multiple terminals unnecessarily
- Let finalizers handle cleanup (don't try manual cleanup)
- Check for goroutine leaks in command execution
Size and Layout Issues
Problem: Terminal appears cut off or incorrectly sized
Solutions:
- Use proper sizing calculations (width-4, height-1)
- Handle
tea.WindowSizeMsgcorrectly - Call
m.updateViewports()after size changes
Best Practices
Initialization Checklist
- ✅ Return
terminal.Init()fromBuildForm()(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
TerminalUpdateMsgfirst inUpdate()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-256colorset 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()fromBuildForm() - ❌ Not handling
TerminalUpdateMsginUpdate() - ❌ Calling UI methods from background goroutines
- ❌ Manual resource cleanup (use finalizers instead)
Integration Checklist for New Screens
- ✅ Add
terminal terminal.Terminalto model struct - ✅ Initialize in
BuildForm()with proper sizing - ✅ Return
terminal.Init()fromBuildForm() - ✅ Handle
TerminalUpdateMsgfirst inUpdate() - ✅ Implement proper key routing based on
IsRunning() - ✅ Handle window resize events
- ✅ Run commands in goroutines with error handling
- ✅ 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.