mirror of
https://github.com/shokinn/hosts-go.git
synced 2025-08-23 08:33:02 +00:00
feat: Initialize hosts-go project with foundational structure and core functionality
- 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.
This commit is contained in:
commit
d66ec51ebd
12 changed files with 1747 additions and 0 deletions
231
memory-bank/techContext.md
Normal file
231
memory-bank/techContext.md
Normal file
|
|
@ -0,0 +1,231 @@
|
|||
# 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue