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`
2. **Check**: `make check` — the tests and the linter, which run in Docker, and
the format check: all passing, zero issues
## Before every commit
Never run `go test`, `golangci-lint` or `gofmt` directly; use the `make`
targets.
1. Run `make fmt`.
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
- All exported types, functions, methods, and vars must have doc comments
- All packages must have a package doc comment
- JSON tags use camelCase (not snake_case)
- No magic numbers — use named constants
- No inline error handling (`if err := ...; err != nil`) — use plain assignment
- Blank line before every `return` statement
- Blank line separating embedded fields from regular fields in structs
- Blank imports must have a justification comment
- Never commit to `main` or `next` directly. Every change is a pull request from
a feature branch into `next`.
- Only the owner merges `next` into `main`.
- A pull request that closes an issue has the title `Description (closes #N)`.
- One logical change per commit.
- Commit messages are in the imperative mood and short.
## Git Workflow
## Code style
- **Never commit directly to main** — all changes go on feature branches
- Merge to main only when ready and passing all checks
- PR titles: `Description (closes #N)` when closing an issue
- One logical change per commit
- Commit messages: imperative mood, concise
- Follow `CONVENTIONS.md`.
- Every package has a package doc comment. Test files need none.
- Every exported type, function and variable has a doc comment. Test files need
none.
- 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
- Dependency injection via Uber fx — all components are fx providers
- `internal/` for all application packages — one package per concern
- Handlers return `http.HandlerFunc` using the closure pattern
- Request/response structs defined inside handler closures
- Models embed `models.Base` for database access to relation methods
- Database migrations in `internal/db/schema/` — embedded via `go:embed`
- SQLite by default (pure Go driver: modernc.org/sqlite)
- The server uses `go.uber.org/fx` for dependency injection.
`cmd/neoircd/main.go` lists its `fx` providers, such as `db.New` and
`handlers.New`.
- Application packages live under `internal/`, one package per concern.
- `pkg/irc` holds the IRC command names and numeric reply codes.
- The `web` package embeds the built web client.
- 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
- Table-driven tests preferred
- Use `testing.T` helpers, not assertion libraries
- Test files live next to the code they test
- `_test.go` suffix, same package for white-box testing
- Prefer table-driven tests.
- Use `testing.T` helpers, not assertion libraries.
- A test file lives next to the code it tests and ends in `_test.go`.
- 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
- Required libraries are listed in CONVENTIONS.md §1
- No new dependencies without justification
- Pure Go preferred (no CGO)
- The required libraries are listed in `CONVENTIONS.md` §1.
- No new dependency without a reason given in the pull request.
- 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.
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
other host they send it only over HTTPS, which a reverse proxy provides.
server on `localhost` over plain HTTP too; Python's `requests` does not. To a
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
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
channel has members, then `RPL_ENDOFNAMES` (`366`). `RPL_NAMREPLY` has `params`
`["=", channel]` and a `body` with one string: the members' hostmasks in nick
order, separated by spaces, each with `@` before a channel operator and `+`
before a voiced member:
`["=", channel]` and a `body` with one string. That string holds the members'
hostmasks in nick order, separated by spaces. A `@` before a hostmask marks a
channel operator, and a `+` marks a voiced member:
```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/precommit` and `script/projectname`, which have none.
- `script/bootstrap`: installs `make`, `git`, Go, Node and `yarn`, and prettier
through `yarn`. Docker must already be installed.
- `script/bootstrap`: installs `make`, `git`, Go, Node and `yarn`, and
`prettier` through `yarn`. Docker must already be installed.
- `script/setup`: makes a fresh clone ready: runs `script/bootstrap`, then
`script/install-precommit`.
- `script/test`: builds the `Dockerfile`'s `test` stage, which runs the tests
with `-race`.
- `script/lint`: builds the `Dockerfile`'s `lint` stage, which runs
golangci-lint.
- `script/fmt`: formats the Go code with `gofmt` and the Markdown with prettier.
`golangci-lint`.
- `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/check`: runs `script/test`, `script/lint` and `script/fmt-check`.
- `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
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`
builds the `lint` stage, which runs golangci-lint with the shared
`.golangci.yml`. `make fmt-check` runs `gofmt` and prettier on the host. Tests
builds the `lint` stage, which runs `golangci-lint` with the shared
`.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
gets an in-memory one of its own from `internal/dbtest`, which holds a second
connection open to keep it.
@@ -2019,9 +2020,9 @@ connection open to keep it.
The `Dockerfile` has five stages:
1. `web-builder`: installs the web client's Node dependencies and bundles
`web/src/app.jsx` with esbuild into `web/dist/`.
2. `lint`: runs golangci-lint, with placeholder files in `web/dist/` so that it
does not wait for the web build.
`web/src/app.jsx` with `esbuild` into `web/dist/`.
2. `lint`: runs `golangci-lint`, with placeholder files in `web/dist/` so that
it does not wait for the web build.
3. `test`: runs the tests, with the same placeholders.
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