hosts/memory-bank/projectbrief.md

# 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 (149 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. **TUI Application Tests** (28 tests):
   - Main application initialization and startup
   - File loading and error handling
   - User interface state management
   - Sorting and navigation functionality
   - Modal dialog lifecycle and interactions
   - Keyboard binding validation

5. **Manager Module Tests** (38 tests):
   - Permission management and sudo handling
   - Edit mode operations and state transitions
   - File backup and atomic operations
   - Entry manipulation and validation

6. **Save Confirmation Tests** (13 tests):
   - Modal dialog lifecycle and user interactions
   - Change detection and validation
   - Save/discard/cancel functionality
   - Integration with edit workflow

7. **Configuration Modal Tests** (6 tests):
   - Modal configuration interface
   - Settings persistence and validation
   - User interaction handling

### Current Test Coverage Status
- **Total Tests**: 149 comprehensive tests
- **Pass Rate**: 100% (all tests passing)
- **Coverage Areas**: Core models, file parsing, configuration, TUI components, edit operations, modal dialogs
- **Code Quality**: 20 minor linting issues (unused imports/variables) requiring cleanup

### Future Test Areas (Planned)
- **Advanced Edit Tests**: Add/delete entries, bulk operations
- **DNS Resolution Tests**: Hostname resolution and IP comparison
- **Performance Tests**: Large file handling and optimization
- **Search Functionality Tests**: Entry searching and filtering