1 Commits
Author SHA1 Message Date
clawbot 27586c249b 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 05:20:38 +00:00
2 changed files with 52 additions and 71 deletions

No files matched your search

+38 -56
View File
@@ -1,73 +1,55 @@
# Rules for coding agents
# AGENTS.md — Rules for AI Agents
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.
## Before Every Commit
## Before every commit
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
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.
Never run `go test`, `golangci-lint` or `gofmt` directly; use the `make`
targets.
Never run `go test`, `golangci-lint` or `gofmt` directly. Use the `make` targets
instead, such as `make test` and `make lint`.
No commit lands on main with lint errors, test failures, or formatting issues.
## Branches and pull requests
## Code Style
- 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.
- 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
## Code style
## Git Workflow
- 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.
- **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
## Architecture
- 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`.
- 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)
## 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.
- 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
## Dependencies
- 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.
- Required libraries are listed in CONVENTIONS.md §1
- No new dependencies without justification
- Pure Go preferred (no CGO)
+14 -15
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 a
remote 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 any
other 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. 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:
`["=", 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:
```json
{
@@ -1970,16 +1970,15 @@ 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`.
@@ -2011,8 +2010,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.
@@ -2020,9 +2019,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