120 lines
5.3 KiB
Markdown
120 lines
5.3 KiB
Markdown
# Project Brief: hosts
|
|
|
|
## Foundation of the Project
|
|
|
|
The **hosts** project is a Python-based terminal application designed to manage the system `/etc/hosts` file with a modern, user-friendly Text User Interface (TUI). The goal is to simplify the manipulation, organization, and updating of hostname entries directly from the terminal without manual text editing.
|
|
|
|
## High-Level Overview
|
|
|
|
The application provides a two-pane TUI:
|
|
|
|
- **Left pane:** List of all hostname entries. With columns:
|
|
- - Active (add a ✓, when active)
|
|
- IP address
|
|
- Canonical hostname
|
|
- **Right pane:** Detailed view of the selected entry.
|
|
- Since a hostname entry can have multiple host names, every hostname after the 1st is considered as alias and should be displayed in the detail view
|
|
The user can easily activate/deactivate entries, reorder them, sort by different attributes, and maintain comments. It also supports CNAME-like functionality by allowing DNS-based IP resolution and quick IP updates.
|
|
|
|
The project uses:
|
|
|
|
- **Python** for development
|
|
- **Textual** as the TUI framework
|
|
- **uv** for Python runtime management and execution
|
|
- **ruff** for linting and formatting, ensuring clean and consistent code
|
|
|
|
## Core Requirements & Goals
|
|
|
|
- Display all `/etc/hosts` entries in a two-pane TUI.
|
|
- Activate or deactivate specific hostname entries.
|
|
- Reorder hostname entries manually.
|
|
- Sort entries by target or destination.
|
|
- Add and edit comments for entries.
|
|
- Support CNAME-style DNS name storage and automatic IP address resolution.
|
|
- Compare resolved IP addresses and let the user choose which one to keep.
|
|
- Validate all changes before writing to `/etc/hosts`.
|
|
- Provide an intuitive, efficient terminal experience for managing hosts without manually editing text.
|
|
- The user must enable edit mode, before only viewing of `/etc/hosts` is allowed. When edit mode is enabled ask for sudo permissions, keep the permissions until the edit mode is exited.
|
|
|
|
## Example One-Line Summary
|
|
|
|
**“Building a Python-based TUI app for managing `/etc/hosts` entries with sorting, DNS resolution, and quick activation/deactivation using uv and ruff.”**
|
|
|
|
## Directory structure
|
|
|
|
hosts/
|
|
├── pyproject.toml # Project file, uv managed
|
|
├── README.md
|
|
├── src/
|
|
│ └── hosts/
|
|
│ ├── __init__.py
|
|
│ ├── main.py # Entry point (uv run hosts)
|
|
│ ├── tui/ # UI components (Textual)
|
|
│ │ ├── __init__.py
|
|
│ │ └── config_modal.py # Configuration modal dialog
|
|
│ ├── core/ # Business logic
|
|
│ │ ├── __init__.py
|
|
│ │ ├── parser.py # /etc/hosts parsing & writing
|
|
│ │ ├── models.py # Data models (Entry, Comment, etc.)
|
|
│ │ ├── config.py # Configuration management
|
|
│ │ ├── dns.py # DNS resolution & comparison (planned)
|
|
│ │ └── manager.py # Core operations (planned for edit mode)
|
|
│ └── utils.py # Shared utilities (planned)
|
|
└── tests/
|
|
├── __init__.py
|
|
├── test_parser.py # Parser tests
|
|
├── test_models.py # Data model tests
|
|
├── test_config.py # Configuration tests
|
|
├── test_config_modal.py # Modal dialog tests
|
|
├── test_main.py # Main application tests
|
|
├── test_manager.py # Core operations tests (planned)
|
|
├── test_dns.py # DNS resolution tests (planned)
|
|
└── test_tui.py # Additional TUI tests (planned)
|
|
|
|
## Testing Strategy (TDD)
|
|
|
|
### Approach
|
|
|
|
- Write unit tests **before** implementing each feature.
|
|
- Use **pytest** as the testing framework.
|
|
- Ensure full coverage for critical modules (`parser`, `dns`, `manager`).
|
|
- Mock `/etc/hosts` file I/O and DNS lookups to avoid system dependencies.
|
|
- Include integration tests for the Textual TUI (using `textual.testing` or snapshot testing).
|
|
|
|
### Implemented Tests (97 tests total)
|
|
|
|
1. **Parsing Tests** (15 tests):
|
|
- Parse simple `/etc/hosts` with comments and disabled entries
|
|
- Ensure writing back preserves file integrity
|
|
- Handle edge cases like empty files, comments-only files
|
|
- Validate round-trip parsing accuracy
|
|
|
|
2. **Data Model Tests** (27 tests):
|
|
- HostEntry creation, validation, and serialization
|
|
- HostsFile container operations and state management
|
|
- IP address validation for IPv4 and IPv6
|
|
- Hostname validation and edge cases
|
|
|
|
3. **Configuration Tests** (22 tests):
|
|
- JSON persistence and error handling
|
|
- Default settings management
|
|
- Configuration loading and saving
|
|
- Default entry detection and filtering
|
|
|
|
4. **Modal Dialog Tests** (15 tests):
|
|
- Configuration modal lifecycle
|
|
- User interaction handling
|
|
- Keyboard binding validation
|
|
- State management during configuration changes
|
|
|
|
5. **Main Application Tests** (18 tests):
|
|
- Application initialization and startup
|
|
- File loading and error handling
|
|
- User interface state management
|
|
- Sorting and navigation functionality
|
|
|
|
### Future Test Areas (Planned)
|
|
- **Edit Mode Tests**: Permission management and file modification
|
|
- **DNS Resolution Tests**: Hostname resolution and IP comparison
|
|
- **Performance Tests**: Large file handling and optimization
|
|
- **Integration Tests**: End-to-end workflow testing
|