initial commit

memory-bank/projectbrief.md

@@ -0,0 +1,83 @@
+# 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.
+- **Right pane:** Detailed view of the selected entry.
+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.