# Repository guide

`hosts` is a Python 3.13+ Textual application for inspecting and editing the
system `/etc/hosts` file on macOS and Linux. Treat the implementation and tests
as the source of truth; user-facing documentation describes only behavior that
is reachable in the current application.

## Context pointers

- Read [CONTEXT.md](CONTEXT.md) when changing entry semantics, parsing, DNS
  behavior, or user-facing terminology.
- Read [ADR 0001](docs/adr/0001-privileged-mode-gates-writes.md) before changing
  privileged mode, sudo handling, system-file writes, or backups.
- Read [ADR 0002](docs/adr/0002-normalize-hosts-serialization.md) before changing
  parsing, serialization, comment placement, or formatting preservation.

## Commands

```bash
uv sync
uv run hosts
uv run pytest
uv run pytest tests/test_parser.py
uv run ruff check .
uv run ruff format --check .
uv run ruff format .
```

Use `uv run pytest <path>` for the narrowest relevant test during development.
Before handing off a change, run the full test suite, Ruff lint, and Ruff format
check.

## Code boundaries

- `src/hosts/core/` owns entries, parsing and serialization, configuration,
  DNS resolution, filters, import/export, undo/redo commands, and privileged
  file operations.
- `src/hosts/tui/` owns the Textual application, handlers, modals, widgets,
  keybindings, and styles.
- `tests/` mirrors both layers. Keep system interactions behind mocks or
  temporary files.

Keep domain and system logic out of Textual widgets. Route privileged writes
through `HostsManager`; UI actions should coordinate services and render their
results.

## Safety contracts

- Tests must never read from or write to the real `/etc/hosts`, invoke real
  `sudo`, or depend on live DNS. Inject temporary paths and mock subprocess and
  resolver boundaries.
- The application starts in read-only mode. Mutating actions require privileged
  mode and a backup must exist before writes are enabled.
- Default entries are protected from mutation and remain first when entries are
  sorted.
- Serialization is semantic and normalized, not byte-preserving. Update ADR
  0002 and the README if that contract changes.
- A core service is not a supported product feature until users can reach it
  through the TUI.

## Documentation discipline

Keep `README.md` aligned with reachable behavior. Keep `CONTEXT.md` a glossary,
not an architecture guide or progress log. Record an ADR only for a consequential,
surprising trade-off that would be expensive to reverse. Track planned work in
Forgejo issues rather than evergreen repository documents.

## Agent skills

### Issue tracker

Issues are tracked in Forgejo using `fgj` against `git.s1q.dev/phg/hosts`. See `docs/agents/issue-tracker.md`.

### Triage labels

The repository uses the five default triage labels. See `docs/agents/triage-labels.md`.

### Domain docs

Domain documentation uses a single-context layout. See `docs/agents/domain.md`.