phg/hosts
0
0
Fork 0
Code Issues 3 Pull requests Projects Releases Packages Wiki Activity Actions
hosts/memory-bank/projectbrief.md

6 KiB
Raw Blame History

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