# Active Context: hosts-go

## Current Work Focus

**Status**: Foundation Complete - Ready for Phase 1 (Core Functionality)
**Priority**: Implementing hosts file parser with format preservation

## Recent Changes

### Foundation Implementation (COMPLETED)
- ✅ **Go module setup**: Created `go.mod` with all required dependencies
- ✅ **Project structure**: Complete directory layout (`cmd/`, `internal/`, `tests/`)
- ✅ **Core data models**: Full `HostEntry` and `HostsFile` structs with validation
- ✅ **Comprehensive testing**: 44 test cases covering all model functionality
- ✅ **Demo application**: Working proof-of-concept showing foundation capabilities
- ✅ **TDD implementation**: Successfully proven test-driven development approach

### Validation System Complete
- ✅ **IP validation**: IPv4/IPv6 support using Go's net.ParseIP
- ✅ **Hostname validation**: RFC-compliant with label-by-label checking
- ✅ **Edge case handling**: Hyphen restrictions, length limits, format validation
- ✅ **Error messaging**: Clear, specific error messages for all validation failures

## Next Steps

### Immediate (Phase 1 - Current Priority)
1. **Hosts File Parser Implementation**
   - Write comprehensive parser tests for various hosts file formats
   - Implement `internal/core/parser.go` for reading `/etc/hosts`
   - Handle comment preservation and formatting retention
   - Support active/inactive entry detection (commented lines)

2. **File Operations**
   - Add file reading with proper error handling
   - Implement round-trip parsing (read → parse → modify → write)
   - Test with real hosts file formats and edge cases

3. **Integration Testing**
   - Test parser with actual `/etc/hosts` file variations
   - Verify format preservation during round-trip operations
   - Handle malformed entries gracefully

### Medium-term (Following sessions)
1. **Core business logic**
   - Implement hosts file parsing with comment preservation
   - Add validation for IP addresses and hostnames
   - Create entry manipulation functions (add, edit, delete, toggle)

2. **Basic TUI foundation**
   - Create main Bubble Tea model structure
   - Implement two-pane layout (list + detail)
   - Add basic navigation and selection

3. **Permission handling**
   - Implement view-mode by default
   - Add edit-mode transition with sudo handling
   - Test permission scenarios

## Active Decisions and Considerations

### Architecture Decisions Made
- **Layered architecture**: TUI → Business Logic → System Interface
- **Repository pattern**: Abstract file operations for testability
- **Command pattern**: Encapsulate edit operations for undo support
- **Test-driven development**: Write tests before implementation

### Key Design Patterns
- **MVU (Model-View-Update)**: Following Bubble Tea conventions
- **Separation of concerns**: Clear boundaries between UI, business logic, and system operations
- **Graceful degradation**: Handle permission issues without crashing

### Technology Choices Confirmed
- **Go 1.21+**: Modern Go features and performance
- **Bubble Tea**: Mature, well-documented TUI framework
- **Testify**: Enhanced testing capabilities beyond stdlib
- **golangci-lint**: Code quality and consistency

## Important Patterns and Preferences

### Code Organization
- Use `internal/` package for application-specific code
- Group related functionality in packages (`tui/`, `core/`, `utils/`)
- Keep main.go minimal - delegate to internal packages

### Testing Strategy
- Write tests before implementation (TDD)
- Mock external dependencies (file system, network)
- Use table-driven tests for multiple scenarios
- Test both success and error cases

### Error Handling
- Return errors explicitly, don't panic
- Provide clear error messages with context
- Implement graceful fallbacks where possible
- Log errors appropriately for debugging

### UI/UX Principles
- **Safety first**: Default to read-only mode
- **Clear feedback**: Show operation status and results
- **Keyboard-driven**: Efficient navigation without mouse dependency
- **Responsive**: Sub-16ms update cycles for smooth interaction

## Learnings and Project Insights

### Development Environment
- **macOS focus**: Primary development and testing platform
- **Cross-platform awareness**: Consider Linux compatibility from start
- **Terminal compatibility**: Test with multiple terminal applications

### User Experience Priorities
1. **Safety**: Cannot accidentally corrupt hosts file
2. **Speed**: Faster than manual editing for common tasks
3. **Clarity**: Always know what mode you're in and what operations are available
4. **Confidence**: Validate changes before applying them

### Technical Priorities
1. **Reliability**: Atomic file operations with backup/restore
2. **Performance**: Handle large hosts files efficiently
3. **Maintainability**: Clear code structure for future enhancements
4. **Testability**: Comprehensive test coverage for confidence in changes

## Dependencies and Constraints

### External Dependencies
- **Bubble Tea ecosystem**: Core framework and components
- **System permissions**: sudo access for editing hosts file
- **File system**: Atomic write operations and backup capability

### Development Constraints
- **No breaking changes**: Must preserve existing hosts file format
- **Backward compatibility**: Work with various hosts file styles
- **Minimal dependencies**: Keep external dependencies focused and essential

## Communication Preferences

### Documentation Style
- **Concrete examples**: Show actual code snippets and command examples
- **Clear structure**: Use consistent heading hierarchy and formatting
- **Actionable items**: Specific next steps rather than vague suggestions

### Progress Tracking
- **Incremental development**: Small, testable changes
- **Regular updates**: Update memory bank after significant milestones
- **Clear status**: Always know what's working, what's not, and what's next