hosts-go/memory-bank/techContext.md

Technical Context: hosts-go

Technologies Used

Core Language & Runtime

• Go 1.21+: Primary development language
• Go Modules: Dependency management (go.mod, go.sum)

TUI Framework Stack

• Bubble Tea: Core TUI framework
  • Event-driven architecture
  • Model-View-Update pattern
  • Cross-platform terminal support
• Bubbles: Pre-built components
  • Text inputs, viewports, spinners
  • List components, progress bars
  • Standardized interaction patterns
• Lip Gloss: Styling and layout
  • CSS-like styling for terminal
  • Colors, borders, padding, margins
  • Responsive layout capabilities
• bubblezone: Mouse event handling
  • Click detection for TUI components
  • Mouse wheel support
  • Touch-friendly interactions

Development Tools

• golangci-lint: Static analysis and linting
• Go testing: Built-in testing framework
• testify: Enhanced assertions and mocks
• Go race detector: Concurrency testing
• Go build: Cross-platform compilation

Development Setup

Prerequisites

# Go installation (1.21+)
go version

# Development tools
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

Project Initialization

# Initialize Go module
go mod init hosts-go

# Add core dependencies
go get github.com/charmbracelet/bubbletea@latest
go get github.com/charmbracelet/bubbles@latest
go get github.com/charmbracelet/lipgloss@latest
go get github.com/lrstanley/bubblezone@latest

# Testing dependencies
go get github.com/stretchr/testify@latest

Build & Run

# Development run
go run ./cmd/hosts

# Build binary
go build -o hosts ./cmd/hosts

# Cross-platform builds
GOOS=linux GOARCH=amd64 go build -o hosts-linux ./cmd/hosts
GOOS=windows GOARCH=amd64 go build -o hosts.exe ./cmd/hosts
GOOS=darwin GOARCH=amd64 go build -o hosts-darwin ./cmd/hosts

Technical Constraints

System Requirements

• Unix-like systems: macOS, Linux (primary targets)
• Terminal support: 256+ colors, UTF-8 encoding
• File permissions: /etc/hosts read access (view mode)
• Elevated permissions: sudo access (edit mode)

Performance Constraints

• Memory: Minimal footprint for terminal application
• Startup time: < 100ms launch time
• File size: Support hosts files up to 10MB
• Responsiveness: < 16ms UI update cycles

Security Constraints

• Privilege escalation: Only when explicitly requested
• File validation: Prevent hosts file corruption
• Input sanitization: Validate all hostname/IP inputs
• Backup strategy: Atomic updates with rollback capability

Dependencies

Runtime Dependencies

// Core TUI framework
github.com/charmbracelet/bubbletea v0.25.0
github.com/charmbracelet/bubbles v0.17.1
github.com/charmbracelet/lipgloss v0.9.1
github.com/lrstanley/bubblezone v0.0.0-20231228141418-c04f8a77c893

// Standard library usage
net          // DNS resolution, IP validation
os           // File operations, environment
os/exec      // Sudo command execution
path/filepath // Path manipulation
strings      // Text processing
regex        // Pattern matching

Development Dependencies

// Testing framework
github.com/stretchr/testify v1.8.4

// Optional: Enhanced development
github.com/golangci/golangci-lint // Linting
github.com/air-verse/air         // Live reload (dev only)

Tool Usage Patterns

Testing Workflow

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run specific test package
go test ./internal/core

# Run tests with race detection
go test -race ./...

# Benchmark tests
go test -bench=. ./...

Linting & Quality

# Run linter
golangci-lint run

# Format code
go fmt ./...

# Vet code
go vet ./...

# Check dependencies
go mod tidy
go mod verify

Development Workflow

# Live reload during development
air

# Build and test
go build ./... && go test ./...

# Install locally
go install ./cmd/hosts

Platform-Specific Considerations

macOS

• Hosts file location: /etc/hosts
• Permission model: sudo required for editing
• Terminal compatibility: Terminal.app, iTerm2

Linux

• Hosts file location: /etc/hosts
• Permission model: sudo/root required for editing
• Terminal compatibility: GNOME Terminal, Konsole, xterm

Windows (Future)

• Hosts file location: C:\Windows\System32\drivers\etc\hosts
• Permission model: Administrator elevation required
• Terminal compatibility: Windows Terminal, Command Prompt

Performance Optimizations

Memory Management

• Lazy loading: Only load visible entries in large files
• String interning: Reuse common hostname strings
• Garbage collection: Minimize allocations in render loop

UI Responsiveness

• Background processing: DNS resolution in goroutines
• Debounced updates: Batch rapid state changes
• Efficient rendering: Only update changed UI components

File Operations

• Streaming parser: Handle large files without full memory load
• Atomic writes: Prevent corruption during updates
• Change detection: Only write when modifications exist

Debugging & Profiling

Debug Build

# Build with debug symbols
go build -gcflags="all=-N -l" ./cmd/hosts

# Run with debug logging
DEBUG=1 ./hosts

Profiling

# CPU profiling
go test -cpuprofile=cpu.prof -bench=.

# Memory profiling  
go test -memprofile=mem.prof -bench=.

# Analyze profiles
go tool pprof cpu.prof

Common Debug Patterns

• TUI debugging: Log to file instead of stdout
• State inspection: JSON marshal model state
• Event tracing: Log all Bubble Tea messages