hosts/memory-bank/techContext.md

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

[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