132 lines
6.2 KiB
Markdown
132 lines
6.2 KiB
Markdown
# 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
|
|
- ✅ **Complete uv project**: Python 3.13 with full dependency management
|
|
- ✅ **Production application**: Fully functional TUI with advanced features and professional interface
|
|
- ✅ **Perfect code quality**: All ruff checks passing with zero issues
|
|
- ✅ **Proper project structure**: Well-organized src/hosts/ package with core and tui modules
|
|
- ✅ **Comprehensive testing**: 97 tests covering all functionality including new features
|
|
- ✅ **Entry point configured**: `hosts` command launches application perfectly
|
|
- ✅ **Configuration system**: Complete settings management with JSON persistence
|
|
- ✅ **Modal interface**: Professional configuration dialogs with keyboard bindings
|
|
- ✅ **Advanced features**: Sorting, filtering, and rich visual interface
|
|
|
|
### Runtime Management
|
|
- ✅ **uv run hosts**: Command executes application instantly
|
|
- ✅ **uv**: Handles all dependency management and virtual environment flawlessly
|
|
- ✅ **Python 3.13**: Modern features working excellently throughout codebase
|
|
- ✅ **Development workflow**: Smooth uv-based development experience
|
|
|
|
## 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 = [
|
|
"textual>=5.0.1",
|
|
"pytest>=8.4.1",
|
|
"ruff>=0.12.5",
|
|
]
|
|
|
|
[project.scripts]
|
|
hosts = "hosts.main:main"
|
|
```
|
|
|
|
### Production Dependencies
|
|
- ✅ **textual**: Rich TUI framework providing excellent reactive UI components, DataTable, and modal system
|
|
- ✅ **pytest**: Comprehensive testing framework with 97 passing tests
|
|
- ✅ **ruff**: Lightning-fast linter and formatter with perfect compliance
|
|
- ✅ **ipaddress**: Built-in Python module for robust IP validation and sorting
|
|
- ✅ **json**: Built-in Python module for configuration persistence
|
|
- ✅ **pathlib**: Built-in Python module for cross-platform path handling
|
|
- ✅ **socket**: Built-in Python module for DNS resolution (planned for Phase 5)
|
|
|
|
## Tool Usage Patterns
|
|
|
|
### Development Workflow
|
|
1. ✅ **uv run hosts**: Execute the application - launches instantly
|
|
2. ✅ **uv run ruff check**: Lint code - all checks passing perfectly
|
|
3. ✅ **uv run ruff format**: Auto-format code - consistent style maintained
|
|
4. ✅ **uv run pytest**: Run test suite - 42 tests passing with 100% success rate
|
|
5. ✅ **uv add**: Add dependencies - seamless dependency management
|
|
|
|
### Code Quality Achieved
|
|
- ✅ **ruff configuration**: Perfect compliance with zero issues across all modules
|
|
- ✅ **Type hints**: Complete type coverage throughout entire codebase including new components
|
|
- ✅ **Docstrings**: Comprehensive documentation for all public APIs and classes
|
|
- ✅ **Test coverage**: Excellent coverage on all core business logic and new features (97 tests)
|
|
- ✅ **Architecture**: Clean separation of concerns with extensible and maintainable structure
|
|
- ✅ **Configuration management**: Robust JSON handling with proper error recovery
|
|
- ✅ **Modal system**: Professional dialog implementation with proper lifecycle management
|
|
|
|
## 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 Implemented
|
|
- ✅ **Unit tests**: 97 comprehensive tests covering all core logic and new features
|
|
- ✅ **Integration tests**: TUI components tested with mocked file system and configuration
|
|
- ✅ **Edge case testing**: Comprehensive coverage of parsing, configuration, and modal edge cases
|
|
- ✅ **Mock external dependencies**: File I/O, system operations, and configuration properly mocked
|
|
- ✅ **Test fixtures**: Realistic hosts file samples and configuration scenarios for thorough testing
|
|
- ✅ **Configuration testing**: Complete coverage of JSON persistence, error handling, and defaults
|
|
- ✅ **Modal testing**: Comprehensive testing of dialog lifecycle and user interactions
|
|
- 🔄 **Snapshot testing**: Planned for Phase 4 TUI visual regression testing
|
|
- 🔄 **Performance testing**: Planned for Phase 3 large file optimization
|