hosts-go/memory-bank/projectbrief.md

# Project Brief: hosts

## Foundation of the Project

The **hosts** project is a Go-based terminal application designed to manage the system `/etc/hosts` file with a modern, interactive Text User Interface (TUI). The goal is to simplify the manipulation, organization, and updating of hostname entries directly from the terminal without manually editing text files.

The application will use the [**Bubble Tea**](https://github.com/charmbracelet/bubbletea) framework to provide a clean, responsive TUI experience, with a focus on clarity, speed, and ease of use.

## High-Level Overview

The application provides a **two-pane TUI**:

- **Left pane:** List of all hostname entries, with columns:
  - Active (✓ when enabled)
  - IP address
  - Canonical hostname
- **Right pane:** Detailed view of the selected entry, with the option to edit the entry.
  - Active status
  - IP Address
  - Hostname
    - Since an entry can have multiple hostnames, every hostname after the first is treated as an alias and displayed here.
  - Comment

The user can:
- Activate/deactivate entries
- Reorder entries manually
- Sort by different attributes
- Maintain inline comments
- Use DNS-based resolution for hostnames
- Quickly update IP addresses

Key Bindings:
- `ctrl`+`e`: Change to edit mode
- `e`: Edit the currently selected hostname entry
- `space`: Entry activation toggle
- `shift`+`up`/`down`: Move the selected entry up or down
- `i` Sort by IP addresses
- `n` Sort by (the first) hostname
- `ctrl`+`s`: Save
- `c` To open the tool configuration
- `?` or `h`: Display help about all Key Bindings

The program will operate in **view-only mode** by default and require explicit entry into **edit mode**, at which point it will request elevated (sudo) permissions until editing is disabled.

The project uses:
- **Go** as the development language
- **Bubble Tea** for TUI rendering and interaction
- **Bubbles** Common Bubble Tea components such as text inputs, viewports, spinners and so on
- **Lip Gloss** for styling
- **bubblezone** Easy mouse event tracking for Bubble Tea components
- **Go modules** for dependency management
- **golangci-lint** for linting
- **Test-driven development** with **Go’s built-in testing** and **testify** for assertions

## Core Requirements & Goals

- Display `/etc/hosts` entries in a two-pane Bubble Tea interface
- Activate or deactivate specific hostname entries
- Reorder hostname entries manually
- Sort entries by IP or hostname
- Add and edit comments for entries
- Support CNAME-like DNS name storage with automatic IP resolution
- Compare resolved IP addresses and allow the user to choose
- Validate all changes before writing to `/etc/hosts`
- Require edit mode for changes, with sudo access requested when entering edit mode
- Preserve `/etc/hosts` formatting and comments when saving changes

## Example One-Line Summary

**“A Go + Bubble Tea TUI app for managing `/etc/hosts` with sorting, DNS resolution, and quick activation/deactivation.”**

## Directory Structure

```
hosts/
├── go.mod                # Go module definition
├── go.sum
├── README.md
├── cmd/
│   └── hosts/
│       └── main.go       # Entry point (go run ./cmd/hosts)
├── internal/
│   ├── tui/              # UI components (Bubble Tea models)
│   │   ├── model.go      # Main Bubble Tea model
│   │   ├── view.go       # Rendering logic
│   │   ├── update.go     # State updates
│   │   ├── config_modal.go # Configuration modal dialog
│   │   └── styles.go     # Lip Gloss styles
│   ├── core/             # Business logic
│   │   ├── parser.go     # /etc/hosts parsing & writing
│   │   ├── models.go     # Data models (Entry, Comment, etc.)
│   │   ├── config.go     # Configuration management
│   │   ├── dns.go        # DNS resolution & comparison
│   │   └── manager.go    # Edit mode operations
│   └── utils/            # Shared helpers
└── tests/
├── parser_test.go
├── models_test.go
├── config_test.go
├── tui_test.go
├── manager_test.go
├── dns_test.go
└── integration_test.go
```

## Testing Strategy (TDD)

### Approach

- **Write tests before implementation** for all features
- Use **Go’s `testing` package** for core tests
- Use **testify** for assertions and mocks
- Mock `/etc/hosts` file I/O and DNS lookups to avoid system dependencies
- Include integration tests for Bubble Tea models (test `Update` and `View` functions)
- Aim for **full coverage** in core logic (`parser`, `dns`, `manager`)

### Planned Test Coverage

1. **Parser Tests**:
   - Parse `/etc/hosts` with comments and disabled entries
   - Preserve formatting when writing back
   - Handle empty and comment-only files
   - Validate round-trip parsing

2. **Model Tests**:
   - `HostEntry` creation, validation, and serialization
   - Container for multiple entries
   - IPv4/IPv6 validation
   - Hostname validation

3. **Configuration Tests**:
   - Load/save config in JSON or TOML
   - Default values handling
   - Error handling on corrupt configs

4. **TUI Tests**:
   - Model initialization
   - State transitions (selection, sorting, toggling)
   - Modal dialog lifecycle
   - Keyboard input mapping

5. **Manager Tests**:
   - Permission handling (sudo)
   - Edit mode transitions
   - File backup and atomic saves
   - Entry manipulation

6. **DNS Tests**:
   - Hostname resolution
   - IP comparison
   - Handling unreachable hosts

7. **Integration Tests**:
   - Complete TUI workflows
   - File modifications with rollback

## Important Documentation

- [Bubble Tea](https://pkg.go.dev/github.com/charmbracelet/bubbletea)
- [Bubbles](https://github.com/charmbracelet/bubbles)
- [Lip Gloss](https://github.com/charmbracelet/lipgloss)
- [bubblezone](https://pkg.go.dev/github.com/lrstanley/bubblezone)