golib/shell/README.md

Shell Package

Interactive command-line shell framework for Go with thread-safe command registration, auto-completion, terminal state management, and signal handling.

---

Table of Contents

• Overview
• Key Features
• Installation
• Architecture
• Quick Start
• Performance
• Use Cases
• Subpackages
  • command - Command Definition
  • tty - Terminal State Management
• Best Practices
• Testing
• Contributing
• Future Enhancements
• License

---

Overview

This library provides production-ready shell functionality for building interactive CLI applications in Go. It emphasizes thread-safe command management, intelligent terminal handling, and rich user interaction through auto-completion and command history.

Design Philosophy

1. Thread-First: Lock-free operations using atomic.MapTyped and atomic.Value
2. Terminal-Safe: Automatic state preservation and restoration via TTYSaver
3. User-Friendly: Built-in auto-completion, suggestions, and command history
4. Signal-Aware: Graceful shutdown on SIGINT, SIGTERM, SIGQUIT, SIGHUP
5. Modular: Independent subpackages (command, tty) that compose seamlessly

---

Key Features

• Thread-Safe Command Registry: Atomic operations with atomic.MapTyped for lock-free concurrent access
• Interactive Prompt: Rich REPL with autocomplete, suggestions, and history via go-prompt
• Terminal Management: Automatic state save/restore preventing terminal corruption
• Signal Handling: Graceful shutdown with terminal restoration on Ctrl+C and termination signals
• Command Namespacing: Organize commands with prefixes (e.g., sys:, user:, db:)
• Command Walking: Iterate and inspect registered commands
• Zero Dependencies: Only stdlib and well-maintained libraries (go-prompt, golang.org/x/term)

---

Installation

go get github.com/nabbar/golib/shell

---

Architecture

Package Structure

The package is organized into three main components:

shell/
├── command/              # Command definition and creation
│   ├── interface.go     # Command interface
│   └── model.go         # Command implementation
├── tty/                 # Terminal state management
│   ├── interface.go     # TTYSaver interface
│   ├── model.go         # Terminal state implementation
│   └── Signal handling  # SIGINT, SIGTERM, etc.
├── interface.go         # Shell interface and constructor
├── model.go             # Shell implementation
└── goprompt.go          # Interactive prompt with go-prompt

Component Overview

┌──────────────────────────────────────────────────────┐
│                    Shell Interface                   │
│  Add(), Run(), Get(), Desc(), Walk(), RunPrompt()    │
└────────────┬─────────────┬───────────────────────────┘
             │             │
   ┌─────────▼────┐  ┌────▼──────┐
   │   command    │  │    tty    │
   │              │  │           │
   │ Definition   │  │ Terminal  │
   │ Interface    │  │ State Mgmt│
   └──────────────┘  └───────────┘

Component	Purpose	Memory	Thread-Safe
Shell	Command registry & execution	O(n) commands	✅ Atomic operations
command	Command definition interface	O(1) per cmd	✅ Immutable
tty	Terminal state save/restore	O(1)	✅ Atomic + Mutex

Execution Flow

Non-Interactive Mode:

User → Shell.Run(args) → Command Registry → Command.Run() → Output

Interactive Mode:

User Input → go-prompt → Executor → Shell.Run() → Command → Output
     ↓           ↓
TTYSaver → Signal Handler → Graceful Shutdown

---

Performance

Memory Efficiency

The Shell maintains constant memory per command with minimal overhead:

• Command Registry: O(n) where n = number of commands
• Each Command: ~48 bytes (name, description, function pointer)
• TTYSaver: ~24 bytes (file descriptor, state pointer, flags)
• Example: 100 commands ≈ 5KB total memory

Thread Safety

All operations are thread-safe through:

• Atomic Map: atomic.MapTyped for lock-free command registry
• Atomic Value: atomic.Value for TTYSaver reference
• Signal Channels: Buffered channels for signal handling
• Concurrent Safe: Multiple goroutines can register and execute commands simultaneously

Operation Benchmarks

Operation	Throughput	Memory	Notes
Add Command	~10M ops/s	O(1)	Atomic store
Get Command	~50M ops/s	O(1)	Atomic load
Run Command	~1M ops/s	O(1)	Function call overhead
Walk Registry	~500K/s	O(n)	Iterate all commands
TTY Restore	~100µs	O(1)	System call
Signal Handler Setup	~50µs	O(1)	Goroutine + channel

Measured on AMD64, Go 1.21

Concurrent Performance

The shell handles concurrent operations efficiently:

Concurrent Add:    10 goroutines → 0s (zero contention)
Concurrent Get:    100 goroutines → 0s (lock-free reads)
Concurrent Walk:   100 goroutines → 100µs (snapshot iteration)

Race Detection: Zero data races detected with go test -race

---

Use Cases

This library is designed for scenarios requiring interactive command-line interfaces:

Administration Tools

• System administration shells with namespaced commands (sys:, net:, disk:)
• Database management CLI with query, backup, restore commands
• Kubernetes/Docker management tools with resource commands

Developer Tools

• Build automation CLI with compile, test, deploy commands
• Git-like version control interfaces
• Project scaffolding and code generation tools

Interactive Applications

• Live monitoring dashboards with interactive commands
• Configuration managers with command-line interfaces
• Testing and debugging consoles

Embedded CLIs

• Microservice admin interfaces
• IoT device configuration shells
• Embedded database consoles (Redis, SQLite-like)

CI/CD Pipelines

• Deployment orchestration with manual approval steps
• Build artifact management
• Release automation with interactive confirmation

---

Quick Start

Simple Command Execution

Execute commands without interactive mode:

package main

import (
    "fmt"
    "io"
    "os"
    
    "github.com/nabbar/golib/shell"
    "github.com/nabbar/golib/shell/command"
)

func main() {
    // Create shell without TTYSaver (non-interactive)
    sh := shell.New(nil)
    
    // Register commands
    sh.Add("", command.New("hello", "Say hello", func(out, err io.Writer, args []string) {
        fmt.Fprintln(out, "Hello, World!")
    }))
    
    sh.Add("", command.New("echo", "Echo arguments", func(out, err io.Writer, args []string) {
        fmt.Fprintln(out, strings.Join(args, " "))
    }))
    
    // Execute command
    sh.Run(os.Stdout, os.Stderr, []string{"hello"})
}

Interactive Shell with Auto-completion

Create an interactive REPL with command history and autocomplete:

package main

import (
    "fmt"
    "io"
    "os"
    
    "github.com/nabbar/golib/shell"
    "github.com/nabbar/golib/shell/command"
    "github.com/nabbar/golib/shell/tty"
)

func main() {
    // Create TTYSaver with signal handling
    ttySaver, err := tty.New(nil, true) // Enable signal handling
    if err != nil {
        panic(err)
    }
    
    // Create shell with TTYSaver
    sh := shell.New(ttySaver)
    
    // Register commands
    sh.Add("", 
        command.New("help", "Show help", helpFunc),
        command.New("version", "Show version", versionFunc),
    )
    
    sh.Add("sys:", 
        command.New("info", "System information", sysInfoFunc),
        command.New("status", "System status", sysStatusFunc),
    )
    
    // Start interactive prompt (blocks until user exits)
    sh.RunPrompt(os.Stdout, os.Stderr)
}

Namespaced Commands

Organize commands into logical groups:

package main

import (
    "github.com/nabbar/golib/shell"
    "github.com/nabbar/golib/shell/command"
)

func main() {
    sh := shell.New(nil)
    
    // System commands (sys:*)
    sh.Add("sys:",
        command.New("info", "System info", sysInfo),
        command.New("restart", "Restart system", sysRestart),
        command.New("shutdown", "Shutdown system", sysShutdown),
    )
    
    // User management (user:*)
    sh.Add("user:",
        command.New("list", "List users", userList),
        command.New("add", "Add user", userAdd),
        command.New("delete", "Delete user", userDelete),
    )
    
    // Database operations (db:*)
    sh.Add("db:",
        command.New("connect", "Connect to DB", dbConnect),
        command.New("query", "Run query", dbQuery),
        command.New("backup", "Backup database", dbBackup),
    )
    
    // Commands accessible as: sys:info, user:add, db:query, etc.
    sh.Run(os.Stdout, os.Stderr, []string{"sys:info"})
}

Walking and Inspecting Commands

Iterate through registered commands:

package main

import (
    "fmt"
    
    "github.com/nabbar/golib/shell"
    "github.com/nabbar/golib/shell/command"
)

func main() {
    sh := shell.New(nil)
    sh.Add("", cmd1, cmd2)
    sh.Add("sys:", cmd3, cmd4)
    
    // List all commands
    count := 0
    sh.Walk(func(name string, cmd command.Command) bool {
        fmt.Printf("%-20s %s\n", name, cmd.Describe())
        count++
        return true // Continue walking
    })
    
    fmt.Printf("\nTotal: %d commands\n", count)
}

---

Subpackages

command Subpackage

Command definition interface for creating executable commands.

Features

• Simple function-based command definition
• Name, description, and execution function
• Nil-safe: Commands with nil functions are handled gracefully
• Immutable: Commands are created once and don't change

API Example

import "github.com/nabbar/golib/shell/command"

// Create command
cmd := command.New("hello", "Say hello", func(out, err io.Writer, args []string) {
    fmt.Fprintln(out, "Hello!")
})

// Access properties
name := cmd.Name()        // "hello"
desc := cmd.Describe()    // "Say hello"

// Execute
cmd.Run(os.Stdout, os.Stderr, []string{"arg1", "arg2"})

Command Interface

type Command interface {
    Name() string                                      // Command name
    Describe() string                                  // Command description
    Run(out io.Writer, err io.Writer, args []string)  // Execute command
}

Use Cases

• Simple single-purpose commands
• Complex multi-step operations
• Commands that interact with external systems
• Utility functions exposed as commands

Test Coverage: 84.9% (48 specs)

See GoDoc for complete API.

---

tty Subpackage

Terminal state management for safe interactive mode operation.

Features

• Terminal state capture via golang.org/x/term
• Automatic restoration on exit or error
• Signal handling (SIGINT, SIGTERM, SIGQUIT, SIGHUP)
• Fallback ANSI escape sequences for emergency reset
• Thread-safe with atomic operations

API Example

import "github.com/nabbar/golib/shell/tty"

// Create TTYSaver with signal handling enabled
ttySaver, err := tty.New(nil, true)
if err != nil {
    // Not a terminal (piped input, etc.)
    return
}

// Terminal state is automatically captured
// Use in shell
sh := shell.New(ttySaver)
defer tty.Restore(ttySaver)

// Or handle signals manually
go func() {
    _ = ttySaver.Signal() // Blocks until signal received
}()

TTYSaver Interface

type TTYSaver interface {
    IsTerminal() bool    // Check if connected to terminal
    Restore() error      // Restore saved terminal state
    Signal() error       // Block until signal, then restore
}

Signal Handling

Supported signals (Unix/Linux):

• SIGINT (Ctrl+C): Interactive interrupt
• SIGTERM: Graceful shutdown from systemd/docker
• SIGQUIT (Ctrl+\): Quit with terminal restoration
• SIGHUP: Terminal hangup

Fallback Mechanism

If primary restoration fails, fallback ANSI sequences are used:

\x1b[?25h   - Show cursor (DECTCEM)
\x1b[0m     - Reset text attributes (SGR)

Architecture

┌────────────────────────────────────────┐
│         TTYSaver Creation              │
│  tty.New(io.Reader, signalEnabled)     │
└──────────────┬─────────────────────────┘
               │
        ┌──────▼──────┐
        │ Save State  │
        │ (term.GetState)
        └──────┬──────┘
               │
    ┌──────────▼───────────┐
    │                      │
┌───▼────┐           ┌─────▼──────┐
│Restore │           │  Signal    │
│        │           │  Handler   │
│Primary │           │  Goroutine │
│term.   │           │            │
│Restore │           │ SIGINT     │
│        │           │ SIGTERM    │
└───┬────┘           │ SIGQUIT    │
    │                │ SIGHUP     │
    │ Fail           └─────┬──────┘
    │                      │
┌───▼──────┐               │
│ Fallback │               │
│ ANSI     │◄──────────────┘
│ Sequences│
└──────────┘

Use Cases

• Interactive shells with go-prompt
• CLI applications that modify terminal settings
• Applications needing graceful signal handling
• Terminal-based UIs

Test Coverage: 44.7% (116/126 specs, 10 skipped for non-terminal env)

See GoDoc for complete API.

---

Testing

Test Suite: 284 specs across all subpackages using Ginkgo v2 and Gomega

# Run all tests
go test ./...

# With coverage
go test -cover ./...

# With race detection (recommended)
CGO_ENABLED=1 go test -race ./...

# Specific subpackage
go test ./command
go test ./tty

Coverage Summary

Package	Specs	Coverage	Status
shell	120	45.5%	✅ All pass
shell/command	48	84.9%	✅ All pass
shell/tty	116/126	44.7%	✅ 10 skipped (terminal-dependent)
Total	284	~60%	✅ Zero race conditions

Quality Assurance

• ✅ Zero data races (verified with -race)
• ✅ Thread-safe concurrent operations
• ✅ Atomic operations validated
• ✅ Signal handling tested

See TESTING.md for detailed testing documentation.

---

Best Practices

Use TTYSaver for Interactive Mode

// ✅ Good: TTYSaver for interactive
func interactive() {
    ttySaver, err := tty.New(nil, true)
    if err != nil {
        log.Fatal(err)
    }
    
    sh := shell.New(ttySaver)
    // ... register commands ...
    sh.RunPrompt(os.Stdout, os.Stderr)
}

// ✅ Good: nil for non-interactive
func nonInteractive() {
    sh := shell.New(nil)
    // ... register commands ...
    sh.Run(os.Stdout, os.Stderr, args)
}

// ❌ Bad: RunPrompt without TTYSaver
func bad() {
    sh := shell.New(nil)
    sh.RunPrompt(os.Stdout, os.Stderr) // No terminal restoration!
}

Always Handle Errors

// ✅ Good
func createShell() (*shell.Shell, error) {
    ttySaver, err := tty.New(nil, true)
    if err != nil {
        return nil, fmt.Errorf("terminal init: %w", err)
    }
    return shell.New(ttySaver), nil
}

// ❌ Bad: Silent failures
func createShellBad() *shell.Shell {
    ttySaver, _ := tty.New(nil, true) // Ignoring error
    return shell.New(ttySaver)
}

Use Command Namespaces

// ✅ Good: Clear organization
sh.Add("system:", cmdInfo, cmdStatus, cmdRestart)
sh.Add("user:", cmdList, cmdAdd, cmdDelete)
sh.Add("log:", cmdView, cmdClear, cmdRotate)

// ❌ Bad: Flat structure
sh.Add("", cmdSystemInfo, cmdSystemStatus, cmdSystemRestart,
           cmdUserList, cmdUserAdd, cmdUserDelete,
           cmdLogView, cmdLogClear, cmdLogRotate) // Confusing!

Safe Command Implementation

// ✅ Good: Validate inputs
func processCmd(out, err io.Writer, args []string) {
    if len(args) < 1 {
        fmt.Fprintln(err, "Usage: process <file>")
        return
    }
    
    file := args[0]
    if !fileExists(file) {
        fmt.Fprintf(err, "Error: file %s not found\n", file)
        return
    }
    
    // ... process file ...
}

// ❌ Bad: No validation
func processCmdBad(out, err io.Writer, args []string) {
    file := args[0] // Panic if no args!
    // ... process ...
}

Proper Resource Cleanup

// ✅ Good: Deferred cleanup
func main() {
    ttySaver, err := tty.New(nil, true)
    if err != nil {
        log.Fatal(err)
    }
    defer tty.Restore(ttySaver) // Always restore
    
    sh := shell.New(ttySaver)
    // ... use shell ...
}

---

Contributing

Contributions are welcome! Please follow these guidelines:

Code Contributions

• Do not use AI to generate package implementation code
• AI may assist with tests, documentation, and bug fixing
• All contributions must pass CGO_ENABLED=1 go test -race ./...
• Maintain or improve test coverage (target: 70%+)
• Follow existing code style and patterns

Documentation

• Update README.md for new features
• Add examples for common use cases
• Keep TESTING.md synchronized with test changes
• Write clear GoDoc comments

Testing

• Write tests for all new features
• Test edge cases and error conditions
• Verify thread safety with race detector
• Add comments explaining complex scenarios

Pull Requests

• Provide clear description of changes
• Reference related issues
• Include test results
• Update documentation

See CONTRIBUTING.md for detailed guidelines.

---

Future Enhancements

Potential improvements for future versions:

Interactive Features

• Custom key bindings and shortcuts
• Multi-line input support
• Syntax highlighting for commands
• Command history persistence to file
• Tab completion for command arguments
• Context-aware suggestions

Shell Features

• Command aliases and shortcuts
• Environment variables support
• Command piping (cmd1 | cmd2)
• Background job management
• Shell scripting language
• Configuration file support (YAML/TOML)

Terminal Enhancements

• Color output support with themes
• Progress bars and spinners
• Table formatting utilities
• ASCII art and banners
• Terminal size detection and responsive layouts

Platform Support

• Windows console API native support
• PowerShell integration
• SSH remote shell support
• WebSocket-based remote shells

Performance

• Command caching and preloading
• Lazy command registration
• Optimized autocomplete algorithms

Developer Experience

• Code generation for command boilerplate
• Command middleware/interceptors
• Pluggable architecture
• Command validation framework

Suggestions and contributions are welcome via GitHub issues.

---

AI Transparency Notice

In accordance with Article 50.4 of the EU AI Act, AI assistance has been used for testing, documentation, and bug fixing under human supervision.

---

License

MIT License - See LICENSE file for details.

---

Resources

• Issues: GitHub Issues
• Documentation: GoDoc
• Testing Guide: TESTING.md
• Contributing: CONTRIBUTING.md
• go-prompt: github.com/c-bata/go-prompt
• Terminal Docs: golang.org/x/term