# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a Go TUI application for managing `/etc/hosts` files using the Bubble Tea framework. The app provides a two-pane interface (list view + detail view) for viewing, editing, and managing host entries with features like activation/deactivation, sorting, and DNS resolution.

## Architecture

The codebase follows a clean architecture pattern with separation of concerns:

- `cmd/hosts/main.go` - Entry point that parses `/etc/hosts` and launches the TUI
- `internal/core/` - Core business logic and data models
  - `models.go` - Data structures for HostEntry and HostsFile with validation
  - `parser.go` - Hosts file parsing, formatting, and writing with intelligent formatting detection
- `internal/tui/` - Bubble Tea TUI components
  - `model.go` - Main Bubble Tea model with pane navigation and mode management
  - `view.go` - Rendering logic for the two-pane interface
  - `update.go` - Message handling and state updates
- `tests/` - Test files following TDD approach

## Key Technical Patterns

### Data Models
- `HostEntry` represents individual host entries with IP, hostname, aliases, comments, and active status
- `HostsFile` contains collections of entries with methods for searching, adding, and removing
- All models include validation methods and proper error handling

### TUI Architecture
- Uses Bubble Tea's Model-View-Update pattern
- Two-pane layout with list and detail views
- Mode switching between ViewMode and EditMode
- Pane focus management (listPane/detailPane)

### File Operations
- Intelligent formatting detection preserves original hosts file style
- Atomic file operations with backup creation
- Proper validation before writing changes

## Development Commands

### Build and Run
```bash
go run cmd/hosts/main.go
go build -o hosts cmd/hosts/main.go
```

### Testing
```bash
go test ./...                    # Run all tests
go test ./tests/                 # Run tests in tests directory
go test -v ./internal/core/      # Run core package tests with verbose output
go test -cover ./...             # Run tests with coverage
```

### Dependencies
Key dependencies are managed via `go.mod`:
- Bubble Tea framework for TUI
- Bubbles for common components
- Lip Gloss for styling
- testify for test assertions

## Important Implementation Details

### Hosts File Parsing
The parser in `internal/core/parser.go` handles:
- Active and inactive (commented) entries
- Inline comments preservation
- Intelligent formatting detection (tabs vs spaces)
- IPv4/IPv6 address validation
- RFC-compliant hostname validation

### TUI Navigation
- Tab/Shift+Tab for pane switching
- Arrow keys for list navigation
- Space for toggling entry activation
- 'q' to quit application

### Error Handling
- Comprehensive validation at model level
- Parse warnings collection during file parsing
- Graceful error recovery in TUI operations

## Memory Bank Integration

This project uses Cline's Memory Bank system located in `memory-bank/` directory. The project brief and context files provide additional architectural context and development history. Always consult these files when making significant changes to understand the project's evolution and design decisions.