Files
2026-11-01 15:52:46 -05:00

78 lines
5.1 KiB
Markdown

# Agent guidelines
Rules for anyone, human or AI, changing this repo. Read [ARCHITECTURE.md](ARCHITECTURE.md) first.
## Environment
- `nix develop` (or direnv with `.envrc`) gives Go, gopls, staticcheck, delve, bazelisk and btrfs-progs. Use it rather than system tools.
- Go code lives in `slackerbot/`, and that's where `go` commands run. Nix files and docs live at the repo root.
## Versioning
Versions look like `YYYY.MM.DD-<commit-sha>`. `flake.nix` builds the string from the commit date and short rev (with `-dirty` for uncommitted trees) and passes it to the binary with `-X main.version`. Don't hardcode a version anywhere. `slackerbot -version` prints it, and a plain `go build` reports `dev`. Bazel builds the same string in `tools/workspace_status.sh` and stamps it only with `--config=release`.
## Checks before you finish
Run from `slackerbot/`, and all must pass:
```
gofmt -l . # must print nothing
go vet ./...
go test ./...
```
If you changed `flake.nix`, `nix/`, `go.mod` or `go.sum`, also run from the repo root:
```
nix build .#slackerbot
nix build .#agent
nix flake check --no-build
```
- Flakes only see files tracked by git. `git add` new files before a nix build.
- After changing Go dependencies, run `go mod tidy`, then set `vendorHash` in `flake.nix` to the `got:` hash the next `nix build .#slackerbot` prints.
- Bazel sits alongside Nix and reads the same `go.mod`. When you add, remove or move a Go file, package or import, run `bazel run //:gazelle` from the repo root and commit the updated `BUILD.bazel` files. After changing Go dependencies, run `bazel mod tidy` as well. `bazel test //...` must pass. Gazelle keeps hand-added attributes such as `data`, `pure` and `x_defs`.
- The Nix build skips tests (`doCheck = false`), because they open local ports and read `../config.example.toml`. `go test` is the real test run.
- Tests need no root, btrfs or Slack. The manager and bot tests start a real master and slave over TLS on `127.0.0.1` using fake nodes (`internal/testutil`). Code that shells out to `btrfs`, `systemd-run` or D-Bus (`local`, parts of `storage`) has no automated tests, so test it by hand on a btrfs host.
## Package rules
- Each package does one job (see the table in ARCHITECTURE.md). Put new code where its job is, and don't create a package for a single function.
- Imports go downward only: `model`, `units`, `storage` and `util` import nothing internal, and `bot` and `main` sit at the top. Never introduce a cycle. If two packages need a type, it belongs in `model` (or `node` for node wire types).
- `manager`, its cluster link and migration stay in one package on purpose.
- `commands` only parses text. It must never call Slack or the manager.
- The bot talks to nodes only through `manager`, never `local` directly.
- Shared test fakes go in `internal/testutil`. Tests that need a running cluster use `testutil/clustertest`.
## Code style
- **Few comments. Code should document itself.** Only add a comment when the code really is unclear, such as a non-obvious reason, a protocol quirk or a race. Don't add comments that repeat the code, section banners or doc comments on obvious functions.
- Follow the existing style: short functions, early returns, errors wrapped with `%w`, and user-facing text written plainly.
- Key struct literals for types from other packages (`model.Size{MemoryMB: 1024, CPUs: 1}`), or `go vet` will complain.
- Keep a function's arguments, results and locals from using a package's name (`node`, `state`, …).
- Text that Slack users see lives in `bot` and goes in plain sentences. Keep it consistent with USERGUIDE.md.
## Behaviour you must not break
- The `state.json` format: existing owners, sessions and permissions must still load. JSON field names are effectively a public format. The same goes for `in-flight-<channel>.json`: turns written by the previous build are resumed by the next one.
- The cluster wire protocol: frame types and call names in `manager/cluster.go`. A master and slaves may run different versions for a while.
- Machine names (`u-<id>`, `c-<id>`), unit names (`slackerbot-<machine>.service`), and paths (`/var/lib/slackerbot`, the agent env file at `/var/lib/slackerbot/agent.env`, which must match `nix/container.nix`).
- Anything that decides whether a message is a command or goes to the agent: `commands.ErrNotCommand`. Ordinary sentences must still reach the agent.
## Docs
Update the matching doc in the same change:
- Slack commands, replies or permissions → USERGUIDE.md
- Packages, data flow, protocol, placement → ARCHITECTURE.md
- Config, Nix module options, setup steps → INSTALLATION.md and `config.example.toml`
- Workflow or rules → this file
Designs that aren't built yet live in `plan/`. When you build one, move what it describes into the docs above and delete the plan file.
## Git
- Before you start changing anything, ask the human whether to work in a git worktree (`git worktree add`). Wait for an answer, and don't create a worktree or edit files until you have one.
- Don't commit, push or rewrite history unless asked.
- Never commit build output (`result`, the `slackerbot` binary, `.direnv/`).