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 │ │ └── 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.