# hosts - /etc/hosts Manager

A modern Python TUI (Text User Interface) application for managing your system's `/etc/hosts` file with ease and safety.

## Overview

The `hosts` application provides a powerful, user-friendly terminal interface for viewing, editing, and managing your `/etc/hosts` file. It eliminates the need for manual text editing while providing advanced features like DNS resolution, entry validation, and comprehensive backup capabilities.

## Features

### 🔍 **Read-Only Mode (Default)**
- **Two-pane interface**: List view with detailed entry information
- **Smart parsing**: Handles all real-world hosts file formats
- **Sorting capabilities**: Sort by IP address or hostname
- **Filtering options**: Hide/show system default entries
- **Search functionality**: Find entries by hostname, IP, or comment
- **Configuration management**: Persistent settings with modal interface
- **Live reload**: Automatically refresh when hosts file changes

### ✏️ **Edit Mode (Permission-Protected)**
- **Safe editing**: Automatic backups before any modifications
- **Entry management**: Add, delete, and modify host entries
- **Activation control**: Toggle entries active/inactive
- **Reordering**: Move entries up/down with keyboard shortcuts
- **Undo/Redo system**: Full operation history with Ctrl+Z/Ctrl+Y
- **Atomic operations**: Safe file writing with rollback capability
- **Permission management**: Secure sudo handling for system file access

### 🛡️ **Safety & Reliability**
- **Automatic backups**: Timestamped backups before modifications
- **Change detection**: Track modifications with save confirmation
- **Input validation**: Comprehensive IP and hostname validation
- **Error handling**: Graceful error recovery with user feedback
- **File integrity**: Preserve comments and formatting

## Installation

### Prerequisites
- Python 3.13 or higher
- [uv](https://docs.astral.sh/uv/) package manager

### Run with uv
```bash
uvx git+https://git.s1q.dev/phg/hosts.git
```

### Setup alias
```bash
# Install uv if not already installed
echo "alias hosts=\"uvx git+https://git.s1q.dev/phg/hosts.git\"" >> ~/.zshrc
```

## Usage

### Basic Usage
```bash
# Launch the application
uvx git+https://git.s1q.dev/phg/hosts.git

# Or if you've setup the alias
hosts
```

### Interface Overview

![User Interface](./images/user_interface.png)

### Keyboard Shortcuts

#### Navigation
- `↑/↓`: Navigate entries
- `Home/End`: Go to first/last entry
- `Page Up/Down`: Navigate by page

#### View Operations
- `Ctrl+e`: Toggle between Read-only and Edit mode
- `Ctrl+r`: Reload hosts file
- `i`: Sort by IP address
- `h`: Sort by hostname
- `c`: Open configuration modal
- `q` or `Ctrl+C`: Quit application

#### Edit Mode (requires sudo)
- `e`: Toggle Entry edit mode
- `Space`: Toggle entry active/inactive
- `Shift+↑/↓`: Move entry up/down
- `n`: Add new entry
- `d`: Delete selected entry
- `r`: Update the current select DNS based Entry
- `Shift+r`: Update all DNS based Entries
- `Ctrl+z`: Undo last operation
- `Ctrl+y`: Redo operation
- `Ctrl+s`: Save changes

## Configuration

The application stores its configuration in `~/.config/hosts-manager/config.json`:

```json
{
  "show_default_entries": true,
  "default_sort_column": "ip",
  "default_sort_reverse": false,
  "backup_directory": "~/.config/hosts-manager/backups"
}
```

### Configuration Options
- **show_default_entries**: Show/hide system default entries (localhost, etc.)
- **default_sort_column**: Default sorting column ("ip" or "hostname")
- **default_sort_reverse**: Default sort direction
- **backup_directory**: Location for automatic backups

## Architecture

The application follows a clean, layered architecture:

```
src/hosts/
├── main.py              # Application entry point
├── core/                # Business logic layer
│   ├── models.py        # Data models (HostEntry, HostsFile)
│   ├── parser.py        # File parsing and writing
│   ├── manager.py       # Edit operations and permissions
│   ├── config.py        # Configuration management
│   ├── dns.py           # DNS resolution (planned)
│   ├── commands.py      # Command pattern for undo/redo
│   ├── filters.py       # Entry filtering and search
│   └── import_export.py # Data import/export utilities
└── tui/                 # User interface layer
    ├── app.py           # Main TUI application
    ├── styles.py        # Visual styling
    ├── keybindings.py   # Keyboard shortcuts
    └── *.py             # Modal dialogs and components
```

### Key Components

- **HostEntry**: Immutable data class representing a single hosts entry
- **HostsFile**: Container managing collections of entries with operations
- **HostsParser**: File I/O operations with atomic writing and backup
- **HostsManager**: Edit mode operations with permission management
- **HostsManagerApp**: Main TUI application with Textual framework

## Development

### Setup Development Environment
```bash
# Clone and enter directory
git clone https://github.com/yourusername/hosts.git
cd hosts

# Install development dependencies
uv sync

# Run tests
uv run pytest

# Run linting
uv run ruff check
uv run ruff format
```

### Testing

The project maintains comprehensive test coverage with 150+ tests:

```bash
# Run all tests
uv run pytest

# Run specific test modules
uv run pytest tests/test_models.py
uv run pytest tests/test_parser.py

# Run with coverage
uv run pytest --cov=src/hosts
```

### Test Coverage
- **Models**: Data validation and serialization (27 tests)
- **Parser**: File operations and parsing (15 tests)  
- **Manager**: Edit operations and permissions (38 tests)
- **Configuration**: Settings persistence (22 tests)
- **TUI Components**: User interface (28 tests)
- **Commands**: Undo/redo system (43 tests)
- **Integration**: End-to-end workflows (additional tests)

### Code Quality

The project uses `ruff` for linting and formatting:

```bash
# Check code quality
uv run ruff check

# Format code
uv run ruff format

# Fix auto-fixable issues
uv run ruff check --fix
```

## Security Considerations

- **Sudo handling**: Secure elevation only when entering edit mode
- **File validation**: Comprehensive input validation and sanitization
- **Atomic operations**: Safe file writing to prevent corruption
- **Backup system**: Automatic backups before any modifications
- **Permission boundaries**: Clear separation between read and edit operations

## Troubleshooting

### Common Issues

**Permission denied when entering edit mode:**
```bash
# Ensure you can run sudo
sudo -v

# Check file permissions
ls -la /etc/hosts
```

**Configuration not saving:**
```bash
# Ensure config directory exists
mkdir -p ~/.config/hosts-manager

# Check directory permissions
ls -la ~/.config/
```

**Application won't start:**
```bash
# Check Python version
python3 --version

# Verify uv installation
uv --version

# Install dependencies
uv sync
```

## Contributing

We welcome contributions! Please see our development setup above.

### Contribution Guidelines

1. **Fork the repository** and create a feature branch
2. **Write tests** for new functionality
3. **Ensure all tests pass** with `uv run pytest`
4. **Follow code style** with `uv run ruff check`
5. **Submit a pull request** with clear description

### Future Enhancements

- **DNS Resolution**: Automatic hostname-to-IP resolution
- **Import/Export**: Support for different file formats
- **Advanced Filtering**: Complex search and filter capabilities
- **Performance Optimization**: Large file handling improvements

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Support

- **Issues**: Report bugs and feature requests on GitHub Issues
- **Documentation**: See the [project wiki](https://github.com/yourusername/hosts/wiki)
- **Discussions**: Join community discussions on GitHub Discussions

---

**Note**: This application modifies system files. Always ensure you have proper backups and understand the implications of hosts file changes. The application includes safety features, but system administration knowledge is recommended.