# Active Context: hosts

## Current Work Focus

**Project Initialization Phase**: Setting up the foundational structure for the hosts TUI application. The project is in its earliest stage with basic uv configuration and placeholder code.

## Recent Changes

### Memory Bank Initialization
- Created complete memory bank structure with all core files
- Documented project vision, technical context, and system architecture
- Established clear patterns and design decisions for implementation

### Current Project State
- Basic uv project with Python 3.13 requirement
- Minimal `main.py` with placeholder "Hello from hosts!" message
- ruff configured as the only dependency
- Project structure planned but not yet implemented

## Next Steps

### Immediate Priorities (Phase 1)
1. **Set up proper project structure**:
   - Create `src/hosts/` package directory
   - Move main.py to proper location
   - Add `__init__.py` files

2. **Add core dependencies**:
   - Add textual for TUI framework
   - Add pytest for testing
   - Configure project entry point in pyproject.toml

3. **Implement basic data models**:
   - Create `src/hosts/core/models.py` with HostEntry and HostsFile classes
   - Implement basic validation logic
   - Add type hints and docstrings

4. **Create hosts file parser**:
   - Implement `src/hosts/core/parser.py`
   - Handle comments, active/inactive entries
   - Parse existing `/etc/hosts` format

### Phase 2 Priorities
1. **Basic TUI implementation**:
   - Create main application class
   - Implement two-pane layout
   - Add entry list view

2. **Read-only functionality**:
   - Load and display hosts file
   - Navigate between entries
   - Show entry details

3. **Testing foundation**:
   - Set up pytest configuration
   - Create test fixtures for sample hosts files
   - Implement parser tests

## Active Decisions and Considerations

### Architecture Decisions Made
- **Layered architecture**: TUI → Manager → Core → System layers
- **Command pattern**: For undo/redo functionality
- **Immutable state**: All operations return new state
- **Permission model**: Explicit edit mode with sudo management

### Design Patterns Chosen
- **Observer pattern**: For state change notifications
- **Factory pattern**: For parser creation
- **Command pattern**: For operations with undo capability

### Technical Constraints Acknowledged
- **Python 3.13+**: Using modern Python features
- **Unix-like systems**: Primary target (Linux, macOS)
- **Root access**: Required for `/etc/hosts` modifications
- **File integrity**: Must preserve existing structure

## Important Patterns and Preferences

### Code Organization
- **Separation of concerns**: Clear layer boundaries
- **Type safety**: Comprehensive type hints
- **Documentation**: Docstrings for all public APIs
- **Testing**: TDD approach with high coverage

### User Experience Priorities
- **Safety first**: Read-only by default, explicit edit mode
- **Keyboard-driven**: Efficient navigation without mouse
- **Visual clarity**: Clear active/inactive indicators
- **Error prevention**: Validation before any file writes

### Development Workflow
- **uv for everything**: Package management and execution
- **ruff for quality**: Linting and formatting
- **pytest for testing**: Comprehensive test coverage
- **Incremental development**: Build and test each component

## Learnings and Project Insights

### Key Insights from Planning
1. **Permission management is critical**: The sudo handling needs careful design
2. **File integrity is paramount**: Users trust their hosts file
3. **DNS integration adds complexity**: But provides significant value
4. **TUI responsiveness matters**: No blocking operations in UI thread

### Risk Areas Identified
- **Permission escalation**: Security implications of sudo usage
- **File corruption**: Atomic writes and validation essential
- **Cross-platform compatibility**: Different hosts file locations
- **Large file performance**: Memory usage with many entries

### Success Factors
- **Clear separation of read/write modes**: Reduces accidental changes
- **Comprehensive validation**: Prevents invalid configurations
- **Intuitive keyboard shortcuts**: Faster than manual editing
- **Visual feedback**: Users always know current state

## Current Development Environment

### Tools Ready
- **uv**: Package manager configured
- **ruff**: Code quality tool available
- **Python 3.13**: Runtime environment set

### Next Tool Additions Needed
- **textual**: TUI framework (primary dependency)
- **pytest**: Testing framework
- **textual.testing**: TUI testing utilities

### Project Structure Status
- **Current**: Flat structure with main.py
- **Target**: Proper package structure in src/hosts/
- **Migration needed**: Move and reorganize files

This active context represents the current state as we begin actual implementation of the hosts TUI application.