2 Commits
Author SHA1 Message Date
clawbot 03463d248b Rewrite README.md sentence by sentence
check / check (push) Canceled after 0s
README.md is rewritten from scratch against the rules on issue 190 and
checked statement by statement against the code on next. It leads with
what the program is and how to use it, puts every endpoint, command,
numeric reply, mode and setting in reference sections, and ends with
development and testing. Where the old text disagreed with the code,
the code decides; the PR body lists each case. The hashcash examples
are real 20-bit stamps. REPO_POLICIES.md and CONVENTIONS.md are copies
of shared documents and are untouched.

Model: fable-5-1 (writing, rework)
2026-11-03 06:02:30 +00:00
clawbot c4fc156a8c Rewrite AGENTS.md sentence by sentence
check / check (push) Canceled after 0s
Rewrite the agent rules from scratch, with one idea per sentence and
every file name and command in backticks. Drop the rule that models
embed `models.Base`, which no package has. Say that the linter keeps
tests in external test packages, and that an `export_test.go` file
gives them access to unexported code. Limit the rules on doc comments
and blank imports to files outside the tests. State magic numbers as
a preference, and correct the blank-line rule for `return`. State the
branch workflow: pull requests target `next` and only the owner
merges `next` into `main`. Record the three snake_case JSON tags the
HTTP API keeps.

Part of #190.

Model: fable-5-1 (writing, rework); opus-5-5 (rework)
2026-11-03 06:59:36 +01:00
2 changed files with 71 additions and 52 deletions

No files matched your search

+56 -38
View File
@@ -1,55 +1,73 @@
# AGENTS.md — Rules for AI Agents # Rules for coding agents
## Before Every Commit This file holds the rules for coding agents working in this repository.
`CONVENTIONS.md` defines the architecture. `REPO_POLICIES.md` defines the
repository standards. Both are copies of shared documents. Do not edit them
here.
1. **Format**: `make fmt` ## Before every commit
2. **Check**: `make check` — the tests and the linter, which run in Docker, and
the format check: all passing, zero issues
Never run `go test`, `golangci-lint` or `gofmt` directly; use the `make` 1. Run `make fmt`.
targets. 2. Run `make check`. It runs the tests and the linter in Docker, then the format
check. All three must pass with no findings.
No commit lands on main with lint errors, test failures, or formatting issues. Never run `go test`, `golangci-lint` or `gofmt` directly. Use the `make` targets
instead, such as `make test` and `make lint`.
## Code Style ## Branches and pull requests
- Follow CONVENTIONS.md exactly — it defines the architecture - Never commit to `main` or `next` directly. Every change is a pull request from
- All exported types, functions, methods, and vars must have doc comments a feature branch into `next`.
- All packages must have a package doc comment - Only the owner merges `next` into `main`.
- JSON tags use camelCase (not snake_case) - A pull request that closes an issue has the title `Description (closes #N)`.
- No magic numbers — use named constants - One logical change per commit.
- No inline error handling (`if err := ...; err != nil`) — use plain assignment - Commit messages are in the imperative mood and short.
- Blank line before every `return` statement
- Blank line separating embedded fields from regular fields in structs
- Blank imports must have a justification comment
## Git Workflow ## Code style
- **Never commit directly to main** — all changes go on feature branches - Follow `CONVENTIONS.md`.
- Merge to main only when ready and passing all checks - Every package has a package doc comment. Test files need none.
- PR titles: `Description (closes #N)` when closing an issue - Every exported type, function and variable has a doc comment. Test files need
- One logical change per commit none.
- Commit messages: imperative mood, concise - JSON tags are camelCase. The HTTP API's `last_id`, `pow_token` and
`hashcash_bits` stay as they are, each with a `//nolint:tagliatelle` comment.
- Prefer named constants to magic numbers. The `mnd` linter checks for them
outside test files.
- No inline error handling such as `if err := f(); err != nil`. Assign the error
on its own line, then test it.
- A `return` that follows another statement in its block has a blank line before
it.
- A blank line between the embedded fields of a struct and its other fields.
- Every blank import has a comment saying why it is there. Test files need none.
## Architecture ## Architecture
- Dependency injection via Uber fx — all components are fx providers - The server uses `go.uber.org/fx` for dependency injection.
- `internal/` for all application packages — one package per concern `cmd/neoircd/main.go` lists its `fx` providers, such as `db.New` and
- Handlers return `http.HandlerFunc` using the closure pattern `handlers.New`.
- Request/response structs defined inside handler closures - Application packages live under `internal/`, one package per concern.
- Models embed `models.Base` for database access to relation methods - `pkg/irc` holds the IRC command names and numeric reply codes.
- Database migrations in `internal/db/schema/` — embedded via `go:embed` - The `web` package embeds the built web client.
- SQLite by default (pure Go driver: modernc.org/sqlite) - Each exported `Handle…` method of `Handlers` returns an `http.HandlerFunc`.
- A request struct is defined inside the method that decodes it.
- The server uses the database only through the methods of `db.Database`.
- The database migrations live in `internal/db/schema/` and are embedded with
`go:embed`.
- The database is SQLite, through the pure Go driver `modernc.org/sqlite`.
## Testing ## Testing
- Table-driven tests preferred - Prefer table-driven tests.
- Use `testing.T` helpers, not assertion libraries - Use `testing.T` helpers, not assertion libraries.
- Test files live next to the code they test - A test file lives next to the code it tests and ends in `_test.go`.
- `_test.go` suffix, same package for white-box testing - The linter requires each test file to be in the package's external test
package, such as `handlers_test`. It allows `export_test.go` and files ending
in `_internal_test.go` in the package itself.
- An `export_test.go` file gives the external tests access to the package's
unexported code.
## Dependencies ## Dependencies
- Required libraries are listed in CONVENTIONS.md §1 - The required libraries are listed in `CONVENTIONS.md` §1.
- No new dependencies without justification - No new dependency without a reason given in the pull request.
- Pure Go preferred (no CGO) - Prefer dependencies written in pure Go, which build without cgo.
+15 -14
View File
@@ -186,8 +186,8 @@ of the response does not repeat it. A browser sends the cookie by itself. Any
other client must save it and send it back, as `curl -c` and `curl -b` do. other client must save it and send it back, as `curl -c` and `curl -b` do.
The cookie is `Secure`. Chrome, Firefox, `curl` and `neoirc-cli` send it to a The cookie is `Secure`. Chrome, Firefox, `curl` and `neoirc-cli` send it to a
server on `localhost` over plain HTTP too; Python's `requests` does not. To any server on `localhost` over plain HTTP too; Python's `requests` does not. To a
other host they send it only over HTTPS, which a reverse proxy provides. remote host they send it only over HTTPS, which a reverse proxy provides.
`QUIT`, `POST /api/v1/logout`, `KILL` and the idle cleanup invalidate the `QUIT`, `POST /api/v1/logout`, `KILL` and the idle cleanup invalidate the
cookie. After that, every request with it gets `401`. cookie. After that, every request with it gets `401`.
@@ -984,9 +984,9 @@ HTTP response: `{"status": "ok"}`.
The server adds a missing `#`. The reply is `RPL_NAMREPLY` (`353`), when the The server adds a missing `#`. The reply is `RPL_NAMREPLY` (`353`), when the
channel has members, then `RPL_ENDOFNAMES` (`366`). `RPL_NAMREPLY` has `params` channel has members, then `RPL_ENDOFNAMES` (`366`). `RPL_NAMREPLY` has `params`
`["=", channel]` and a `body` with one string: the members' hostmasks in nick `["=", channel]` and a `body` with one string. That string holds the members'
order, separated by spaces, each with `@` before a channel operator and `+` hostmasks in nick order, separated by spaces. A `@` before a hostmask marks a
before a voiced member: channel operator, and a `+` marks a voiced member:
```json ```json
{ {
@@ -1970,15 +1970,16 @@ standard. Each script has a `make` target of the same name, except
`script/install-precommit`, which is `make hooks`, and `script/cibuild`, `script/install-precommit`, which is `make hooks`, and `script/cibuild`,
`script/precommit` and `script/projectname`, which have none. `script/precommit` and `script/projectname`, which have none.
- `script/bootstrap`: installs `make`, `git`, Go, Node and `yarn`, and prettier - `script/bootstrap`: installs `make`, `git`, Go, Node and `yarn`, and
through `yarn`. Docker must already be installed. `prettier` through `yarn`. Docker must already be installed.
- `script/setup`: makes a fresh clone ready: runs `script/bootstrap`, then - `script/setup`: makes a fresh clone ready: runs `script/bootstrap`, then
`script/install-precommit`. `script/install-precommit`.
- `script/test`: builds the `Dockerfile`'s `test` stage, which runs the tests - `script/test`: builds the `Dockerfile`'s `test` stage, which runs the tests
with `-race`. with `-race`.
- `script/lint`: builds the `Dockerfile`'s `lint` stage, which runs - `script/lint`: builds the `Dockerfile`'s `lint` stage, which runs
golangci-lint. `golangci-lint`.
- `script/fmt`: formats the Go code with `gofmt` and the Markdown with prettier. - `script/fmt`: formats the Go code with `gofmt` and the Markdown with
`prettier`.
- `script/fmt-check`: the same, read-only; fails if anything would change. - `script/fmt-check`: the same, read-only; fails if anything would change.
- `script/check`: runs `script/test`, `script/lint` and `script/fmt-check`. - `script/check`: runs `script/test`, `script/lint` and `script/fmt-check`.
- `script/docker`: builds the image, tagged `neoirc`. - `script/docker`: builds the image, tagged `neoirc`.
@@ -2010,8 +2011,8 @@ standard. Each script has a `make` target of the same name, except
The tests and the linter run inside Docker, as stages of the `Dockerfile`, so The tests and the linter run inside Docker, as stages of the `Dockerfile`, so
every developer and the CI run the same toolchain. `make test` builds the `test` every developer and the CI run the same toolchain. `make test` builds the `test`
stage: `go test -race` over every package, with a 90-second limit. `make lint` stage: `go test -race` over every package, with a 90-second limit. `make lint`
builds the `lint` stage, which runs golangci-lint with the shared builds the `lint` stage, which runs `golangci-lint` with the shared
`.golangci.yml`. `make fmt-check` runs `gofmt` and prettier on the host. Tests `.golangci.yml`. `make fmt-check` runs `gofmt` and `prettier` on the host. Tests
live next to the code, most in `_test` packages. A test that needs a database live next to the code, most in `_test` packages. A test that needs a database
gets an in-memory one of its own from `internal/dbtest`, which holds a second gets an in-memory one of its own from `internal/dbtest`, which holds a second
connection open to keep it. connection open to keep it.
@@ -2019,9 +2020,9 @@ connection open to keep it.
The `Dockerfile` has five stages: The `Dockerfile` has five stages:
1. `web-builder`: installs the web client's Node dependencies and bundles 1. `web-builder`: installs the web client's Node dependencies and bundles
`web/src/app.jsx` with esbuild into `web/dist/`. `web/src/app.jsx` with `esbuild` into `web/dist/`.
2. `lint`: runs golangci-lint, with placeholder files in `web/dist/` so that it 2. `lint`: runs `golangci-lint`, with placeholder files in `web/dist/` so that
does not wait for the web build. it does not wait for the web build.
3. `test`: runs the tests, with the same placeholders. 3. `test`: runs the tests, with the same placeholders.
4. `builder`: runs only after `lint` and `test` have passed. It compiles 4. `builder`: runs only after `lint` and `test` have passed. It compiles
`neoircd` with the real web client, and compiles `neoirc-cli` to check that `neoircd` with the real web client, and compiles `neoirc-cli` to check that