initial commit

memory-bank/activeContext.md

@@ -0,0 +1,135 @@
+# 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.