mirror of
https://github.com/shokinn/hosts-go.git
synced 2025-08-23 08:33:02 +00:00
phg
d66ec51ebd
- Created activeContext.md and productContext.md to outline project goals and current focus. - Established progress.md to track project milestones and tasks. - Developed projectbrief.md detailing application overview, requirements, and directory structure. - Documented systemPatterns.md to describe architecture and design patterns used. - Compiled techContext.md to specify technologies and development setup. - Implemented comprehensive unit tests in models_test.go for HostEntry and HostsFile functionalities.
231 lines
5.8 KiB
Markdown
231 lines
5.8 KiB
Markdown
# 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
|
|
```go
|
|
// 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
|
|
```go
|
|
// 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
|
|
```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
|
|
- **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
|
|
```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
|