initial commit

memory-bank/techContext.md

@@ -0,0 +1,110 @@
+# Technical Context: hosts
+
+## Technologies Used
+
+### Core Technologies
+- **Python 3.13+**: Modern Python with latest features and performance improvements
+- **Textual**: Rich TUI framework for building terminal applications with modern UI components
+- **uv**: Fast Python package manager and runtime for dependency management and execution
+
+### Development Tools
+- **ruff**: Lightning-fast Python linter and formatter for code quality
+- **pytest**: Testing framework for comprehensive test coverage
+- **textual.testing**: Built-in testing utilities for TUI components
+
+## Development Setup
+
+### Project Structure
+```
+hosts/
+├── pyproject.toml          # uv-managed project configuration
+├── README.md
+├── main.py                 # Current entry point (temporary)
+├── src/hosts/              # Main package (planned)
+│   ├── __init__.py
+│   ├── main.py            # Application entry point
+│   ├── tui/               # UI components
+│   ├── core/              # Business logic
+│   └── utils.py
+└── tests/                 # Test suite
+```
+
+### Current State
+- Basic uv project initialized with Python 3.13
+- Minimal main.py with placeholder implementation
+- ruff configured as dependency for code quality
+- Project structure planned but not yet implemented
+
+### Runtime Management
+- **uv run hosts**: Planned command to execute the application
+- **uv**: Handles all dependency management and virtual environment
+- **Python 3.13**: Required minimum version for modern features
+
+## Technical Constraints
+
+### System Integration
+- **Root access required**: Must handle `/etc/hosts` file modifications
+- **Sudo permission management**: Request permissions only in edit mode
+- **File integrity**: Must preserve existing hosts file structure and comments
+- **Cross-platform compatibility**: Focus on Unix-like systems (Linux, macOS)
+
+### Performance Requirements
+- **Fast startup**: TUI should load quickly even with large hosts files
+- **Responsive UI**: No blocking operations in the main UI thread
+- **Memory efficient**: Handle large hosts files without excessive memory usage
+
+### Security Considerations
+- **Privilege escalation**: Only request sudo when entering edit mode
+- **Input validation**: Validate all IP addresses and hostnames before writing
+- **Backup strategy**: Consider creating backups before modifications
+- **Permission dropping**: Release sudo permissions when exiting edit mode
+
+## Dependencies
+
+### Current Dependencies
+```toml
+[project]
+requires-python = ">=3.13"
+dependencies = [
+    "ruff>=0.12.5",
+]
+```
+
+### Planned Dependencies
+- **textual**: TUI framework (to be added)
+- **pytest**: Testing framework (to be added)
+- **ipaddress**: Built-in Python module for IP validation
+- **socket**: Built-in Python module for DNS resolution
+
+## Tool Usage Patterns
+
+### Development Workflow
+1. **uv run**: Execute the application during development
+2. **ruff check**: Lint code for style and potential issues
+3. **ruff format**: Auto-format code to maintain consistency
+4. **pytest**: Run test suite for validation
+5. **uv add**: Add new dependencies as needed
+
+### Code Quality
+- **ruff configuration**: Enforce consistent Python style
+- **Type hints**: Use modern Python typing for better code clarity
+- **Docstrings**: Document all public APIs and complex logic
+- **Test coverage**: Aim for high coverage on core business logic
+
+## Architecture Decisions
+
+### Separation of Concerns
+- **TUI layer**: Handle user interface and input/output
+- **Core layer**: Business logic for hosts file management
+- **Utils layer**: Shared utilities and helper functions
+
+### Error Handling
+- **Graceful degradation**: Handle missing permissions or file access issues
+- **User feedback**: Clear error messages in the TUI
+- **Recovery mechanisms**: Allow users to retry failed operations
+
+### Testing Strategy
+- **Unit tests**: Test core logic in isolation
+- **Integration tests**: Test TUI components with mocked file system
+- **Snapshot testing**: Verify TUI rendering consistency
+- **Mock external dependencies**: DNS resolution and file I/O