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](https://github.com/charmbracelet/bubbletea)**: Core TUI framework
  - Event-driven architecture
  - Model-View-Update pattern
  - Cross-platform terminal support
- **[Bubbles](https://github.com/charmbracelet/bubbles)**: Pre-built components
  - Text inputs, viewports, spinners
  - List components, progress bars
  - Standardized interaction patterns
- **[Lip Gloss](https://github.com/charmbracelet/lipgloss)**: Styling and layout
  - CSS-like styling for terminal
  - Colors, borders, padding, margins
  - Responsive layout capabilities
- **[bubblezone](https://github.com/lrstanley/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
```bash
# Go installation (1.21+)
go version

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

### Project Initialization
```bash
# 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
```bash
# 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
```go
// 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
```go
// 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
```bash
# 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
```bash
# Run linter
golangci-lint run

# Format code
go fmt ./...

# Vet code
go vet ./...

# Check dependencies
go mod tidy
go mod verify
```

### Development Workflow
```bash
# 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
```bash
# Build with debug symbols
go build -gcflags="all=-N -l" ./cmd/hosts

# Run with debug logging
DEBUG=1 ./hosts
```

### Profiling
```bash
# 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