phg/hosts-go
0
0
Fork 0
mirror of https://github.com/shokinn/hosts-go.git synced 2025-08-23 08:33:02 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
hosts-go/CLAUDE.md

3.2 KiB
Raw Blame History

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

go run cmd/hosts/main.go
go build -o hosts cmd/hosts/main.go

Testing

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.