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 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

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
Model Tests:
- HostEntry creation, validation, and serialization
- Container for multiple entries
- IPv4/IPv6 validation
- Hostname validation
Configuration Tests:
- Load/save config in JSON or TOML
- Default values handling
- Error handling on corrupt configs
TUI Tests:
- Model initialization
- State transitions (selection, sorting, toggling)
- Modal dialog lifecycle
- Keyboard input mapping
Manager Tests:
- Permission handling (sudo)
- Edit mode transitions
- File backup and atomic saves
- Entry manipulation
DNS Tests:
- Hostname resolution
- IP comparison
- Handling unreachable hosts
Integration Tests:
- Complete TUI workflows
- File modifications with rollback

5.8 KiB Raw Blame History Unescape Escape