phg
780d9c12fe
- Lock Python and uv versions with mise - Add unified sync, app, test, lint, format, and typecheck tasks - Update development documentation and strengthen type handling
82 lines
2.9 KiB
Markdown
82 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
|
|
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`.
|