housecarl/AGENTS.md

# Working on Housecarl

Notes for coding agents (and people) changing this repository. Read this
first, then [docs/design.md](docs/design.md) (how it fits together and
what 0.1 leaves out) and [docs/development.md](docs/development.md)
(layout, tests, releasing).

Housecarl is a firewall manager for Linux: `housecarld` keeps the
machine's nftables ruleset and serves a REST API and a web UI; `hc` is the
CLI; SQLite holds everything. It is the third of a set with Jarl (the BIND
manager, `../jarl`) and Steward (the DHCP server, `../steward`) and copies
their ways: the same auth, socket and web UI helpers, the same release
process, the same look. When in doubt, do it the way Jarl and Steward do.
Go module `housecarl`, `CGO_ENABLED=0`, Linux only for housecarld.

## Ground rules

* **The database is the source of truth.** The ruleset is rendered from
  it; never read nftables' state back as configuration (an importer would
  be the only exception).
* **Every change goes through one engine**: edit a copy of the
  configuration, validate the whole result, render, check with
  `nft -c -f`, apply with `nft -f`, and save the objects, the history
  entry and the audit record together. Never write to the store from a
  handler.
* **Housecarl's own table only.** Write `inet housecarl` and nothing
  else; never flush the whole ruleset (Docker, libvirt and others keep
  theirs).
* **Don't lock the user out.** Changes made over the network are applied
  on probation and rolled back unless confirmed (docs/design.md). An
  empty configuration applies nothing. But never force a rule that keeps
  SSH or the web UI open: the maintainer doesn't want one.
* **Stay within nftables 1.1.3** (Debian 13). The dev machine's newer nft
  accepts things 1.1.3 refuses; the tests with `HOUSECARL_NFT` and the
  e2e test use 1.1.3.
* **Every user-visible change updates `CHANGELOG.md`** under
  `## [Unreleased]`, and the matching `docs/` page in the same change.
  New validation codes get a case in `internal/validate/validate_test.go`
  and a row in `docs/validation.md`.
* **Errors** say what is wrong and how to fix it, naming the object.
* **Schema changes** append a migration; never edit a shipped one.
* `make test` runs `go vet` and a `gofmt -l` check. `goimports` isn't
  installed, so fix imports by hand.

## The logo and wordmark

* The masters are `artwork/logo.svg` (the carved doorway) and
  `artwork/logo-small.svg` (without its carvings, for under about 64 px).
  Each is one evenodd path in a shared viewBox; their color comes from
  CSS (`--logo`, lighter in the dark theme).
* `make logo` (`scripts/logo.py`) copies them into the web UI
  (`assets/logo.js`, and `assets/logo.svg`, the favicon, from the small
  one) and runs `scripts/banner.py`, which rebuilds `artwork/banner.svg`.
  Never edit those outputs by hand.
* The wordmark's letters are paths in `assets/brand.js`, in the angular
  style of Jarl's and Steward's (A, R and L are Jarl's, S and E Steward's).
  `banner.py` reads them from there.

## Testing

```sh
make test      # vet + gofmt check + unit tests
make e2e       # real traffic through a router container (needs Docker)
```

* **Docker** on this machine needs `DOCKER_HOST=unix:///var/run/docker.sock`.
  `docker build` can't reach the network here: images are made with
  `docker run` + `docker commit` (scripts/e2e.sh makes `housecarl-nft`).
  The e2e test prints `RESULT: N passed, 0 failed`; run it after any
  change to `render`, `nft`, `engine`, `server`, `importer` or the CLI.
* **Real nft in unit tests:**
  `HOUSECARL_NFT="docker run --rm -i --cap-add NET_ADMIN housecarl-nft nft"`
  and `HOUSECARL_NFT_IMAGE=housecarl-nft`; without them those tests skip.
  Unprivileged namespaces (`unshare -rn`) are blocked here by AppArmor.
* **The systemd sandbox is only tested by a package test**: `make deb`,
  installed in a `debian:trixie` container running systemd
  (`--privileged --cgroupns=host /sbin/init`).
* **The web UI** has no JS tests. Bundle `assets/app.js` with esbuild to
  catch syntax and import errors, and look at it in headless Chrome
  against the e2e lab (`KEEP=1`, web UI on `10.88.10.1:8070`).

## Web UI rules

As in Jarl and Steward:

* Build DOM only with `h()` from `ui.js`, never `innerHTML`.
* The CSP is `self` only: no inline styles or scripts. Use a class, or set
  `el.style.prop`.
* Colors are the CSS custom properties in `style.css`, with light and dark
  values; reuse them.
* Rebuild housecarld after editing, since the files are embedded.
* Function over polish. Leave pick-list checkboxes unticked by default.

## Git and releases

The maintainer's rules:

* **Commit only when asked. Never push.** The maintainer pushes, to Gitea
  at gitea.adbraun.lol.
* **Branches** are `dev-X.Y.Z`, never named like a tag.
* **A release** is a commit "Release X": it sets `VERSION`, updates the
  README status line, and (for a final release) moves `[Unreleased]` to
  `## [X] - YYYY-MM-DD`. The annotated tag is `vX` with message
  "Housecarl X".

## Shell hygiene

* **Never kill processes by pattern** (`pkill -f`). The pattern matches
  the shell running it. Find the PID with `ps` and kill that.
* **Run long-lived test servers in the background mode of your tool**, not
  with `&` in a shell that exits.
* **Never apply a test ruleset to this machine's own nftables.** Test in a
  network namespace or a container.