86 lines
3.7 KiB
Markdown
86 lines
3.7 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:
|
|
- 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
|
|
│ │ └── views.py
|
|
│ ├── core/ # Business logic
|
|
│ │ ├── init.py
|
|
│ │ ├── parser.py # /etc/hosts parsing & writing
|
|
│ │ ├── models.py # Data models (Entry, Comment, etc.)
|
|
│ │ ├── dns.py # DNS resolution & comparison
|
|
│ │ └── manager.py # Core operations (activate, sort, reorder)
|
|
│ └── utils.py
|
|
└── tests/
|
|
├── init.py
|
|
├── test_parser.py
|
|
├── test_manager.py
|
|
├── test_dns.py
|
|
└── test_tui.py
|
|
|
|
## 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).
|
|
|
|
### Example Tests to Start With (MVP)
|
|
|
|
1. **Parsing Tests**:
|
|
- Parse simple `/etc/hosts` with comments and disabled entries.
|
|
- Ensure writing back preserves file integrity.
|
|
2. **Activation/Deactivation Tests**:
|
|
- Toggle entries and validate updated state.
|
|
3. **TUI Rendering Tests**:
|
|
- Ensure initial layout shows entries correctly.
|