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 ✅ IMPLEMENTED

// Core TUI framework (ready for Phase 2)
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 (actively used in Phase 1)
net          // ✅ IP validation (net.ParseIP for IPv4/IPv6)
os           // ✅ File operations, backup system
os/exec      // 🔄 Future sudo command execution (Phase 3)
path/filepath // ✅ Backup path management
strings      // ✅ Extensive text processing in parser
regexp       // ✅ Whitespace parsing and validation
time         // ✅ Backup timestamps
bufio        // ✅ File line-by-line reading
fmt          // ✅ String formatting and error messages

Development Dependencies ✅ IMPLEMENTED

// Testing framework (extensively used)
github.com/stretchr/testify v1.8.4 // ✅ 54 tests using assert/require

// Development tools (configured and ready)
github.com/golangci/golangci-lint // ✅ Code quality and linting
go test                          // ✅ Built-in testing with coverage
go fmt                           // ✅ Code formatting
go vet                           // ✅ Static analysis

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 ✅ IMPLEMENTED

• Efficient parsing: String processing with minimal allocations (✅ Implemented in parser)
• Slice reuse: HostsFile.Entries slice grows as needed without excessive copying (✅ Implemented)
• String handling: Direct string manipulation without unnecessary copies (✅ Implemented)

File Operations ✅ IMPLEMENTED

• Atomic writes: Prevent corruption during updates (✅ WriteHostsFile with temp files)
• Backup system: Safe operations with rollback capability (✅ BackupHostsFile)
• Change detection: Only write when modifications exist (✅ Planned for TUI integration)

Future UI Optimizations (PLANNED)

• Background processing: DNS resolution in goroutines (Phase 4)
• Debounced updates: Batch rapid state changes (Phase 2)
• Efficient rendering: Only update changed UI components (Phase 2)
• Lazy loading: Only load visible entries in large files (Phase 2)

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