mirror of
https://github.com/shokinn/hosts-go.git
synced 2025-08-23 08:33:02 +00:00
87 lines
No EOL
3.2 KiB
Markdown
87 lines
No EOL
3.2 KiB
Markdown
# 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. |