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.
80 lines
2.9 KiB
Markdown
80 lines
2.9 KiB
Markdown
# 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`.
|