hosts/AGENTS.md

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 when changing entry semantics, parsing, DNS behavior, or user-facing terminology.
• Read ADR 0001 before changing privileged mode, sudo handling, system-file writes, or backups.
• Read ADR 0002 before changing parsing, serialization, comment placement, or formatting preservation.
• Read the TUI design guide before changing layouts, components, interaction states, user-visible copy, or terminal-size behavior.

Commands

mise install
mise run sync
mise run app
mise run test
mise run test -- tests/test_parser.py
mise run lint
mise run format-check
mise run typecheck
mise run check
mise run format

Use mise run test -- <path> for the narrowest relevant test during development. Before handing off a change, run mise run 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.