diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..2affec9 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,87 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +This is a Python TUI (Terminal User Interface) application for managing `/etc/hosts` files. The application provides a two-pane interface built with Textual, allowing users to view, edit, activate/deactivate, and reorder hostname entries in their system's hosts file with proper sudo permission handling. + +## Development Commands + +### Package Management (uv) +- `uv sync` - Update project environment and install dependencies +- `uv add ` - Add new dependency to project +- `uv run ` - Run commands in the project environment + +### Running the Application +- `uv run hosts` - Launch the TUI application (main entry point) +- `uv run python -m hosts.main` - Alternative way to run the application + +### Testing +- `uv run pytest` - Run all tests +- `uv run pytest tests/test_.py` - Run specific test module +- `uv run pytest -k ` - Run tests matching pattern + +### Code Quality +- `uv run ruff check` - Run linter checks +- `uv run ruff check --fix` - Auto-fix linting issues +- `uv run ruff format` - Format code + +## Architecture + +### Core Structure +The application follows a modular architecture with clear separation of concerns: + +``` +src/hosts/ +├── core/ # Core business logic +│ ├── config.py # Configuration management +│ ├── manager.py # HostsManager with sudo permission handling +│ ├── models.py # Data models (HostEntry, HostsFile) +│ └── parser.py # Hosts file parsing/serialization +├── tui/ # Textual UI components +│ ├── app.py # Main application class (HostsManagerApp) +│ └── ... # Various handlers and modals +└── main.py # Entry point +``` + +### Key Components + +**HostsManager** (`src/hosts/core/manager.py:106`): Central component that handles all edit operations with proper sudo permission management. Key features: +- Permission management through PermissionManager class +- Edit mode with backup creation and restoration +- Safe file operations with validation +- Entry manipulation (toggle, move, update) + +**HostsParser** (`src/hosts/core/parser.py`): Handles reading/writing hosts files and maintains original formatting. + +**HostsManagerApp** (`src/hosts/tui/app.py:26`): Main Textual application providing the two-pane interface with reactive state management. + +### Permission Model +The application operates in two modes: +- **Read-only mode** (default): Safe browsing of hosts file entries +- **Edit mode**: Requires sudo permissions for modifications, includes automatic backup creation + +### Memory Bank Integration +This project uses Cline's Memory Bank system (see `.clinerules`) for maintaining project context across sessions. Key files are in `memory-bank/` directory. + +## Development Guidelines + +### Testing Approach +- Tests are located in `tests/` directory +- Uses pytest framework +- Test individual modules with `uv run pytest tests/test_.py` + +### Code Style +- Uses ruff for both linting and formatting +- Configuration is embedded in `pyproject.toml` +- Run `uv run ruff check --fix && uv run ruff format` before committing + +### Dependencies +- **Textual**: TUI framework for the interface +- **pytest**: Testing framework +- **ruff**: Linting and code formatting +- Managed via uv with dependencies declared in `pyproject.toml` + +### File Permissions +When working on permission-related code, be aware that the application needs to handle sudo operations safely. The PermissionManager class in `src/hosts/core/manager.py:17` manages this complexity. \ No newline at end of file