Compare commits
2
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
03463d248b | ||
|
|
c4fc156a8c |
No files matched your search
@@ -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.
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user