phg
7872991e0b
- Updated test_dns.py to enhance mock function definitions and improve spacing for better readability. - Modified test_filters.py to streamline assertions and ensure consistent formatting across test cases. - Cleaned up test_import_export.py by organizing imports and ensuring consistent formatting in CSV and JSON tests. - Improved test_main.py by refining mock setups and ensuring consistent error handling in assertions.
2.9 KiB
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.
Commands
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 realsudo, 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.