# 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.