Add AGENTS.md with Cursor Cloud development instructions

Co-authored-by: Nick Misasi <nick13misasi@gmail.com>
2026-08-30 17:06:34 +08:00 · 2026-02-25 16:59:09 +00:00
parent 116313e0f6
commit 95d40265c4
1 changed files with 57 additions and 21 deletions
@@ -1,32 +1,68 @@
+# Mattermost Development
+
+Mattermost is an open-source collaboration/messaging platform with a Go backend (`server/`) and React/TypeScript frontend (`webapp/`).
+
 ## Cursor Cloud specific instructions

-This is the Mattermost monorepo. The webapp lives under `webapp/`.
+### Services overview

-### Environment
+| Service | Description | Port |
+|---------|-------------|------|
+| Mattermost Server (Go) | Backend API + serves webapp | 8065 |
+| PostgreSQL | Primary database | 5432 |
+| Inbucket | Fake email server for testing | 9001 (web), 10025 (SMTP) |
+| Redis | Cache/session store | 6379 |

- Node.js v24+ and npm v11+ are required (managed via nvm).
- Source nvm before running any node/npm commands: `export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"`
- Go toolchain is at `/usr/local/go/bin` — add to PATH when needed.
+### Starting Docker services

-### webapp dependencies
+Docker must be started manually in Cloud Agent VMs since `systemd` is not running:

- `cd /workspace/webapp && npm install` installs all workspace dependencies.
- The `postinstall` script automatically builds shared workspaces (`platform/types`, `platform/client`, `platform/components`, `platform/shared`).
+```bash
+sudo dockerd &>/tmp/dockerd.log &
+sleep 3
+sudo chmod 666 /var/run/docker.sock
+```
+
+Then start the required services:
+
+```bash
+cd server && ENABLED_DOCKER_SERVICES="postgres inbucket redis" make start-docker
+```
+
+### Running the server
+
+```bash
+cd server && make run-server
+```
+
+The server runs on port 8065. To verify: `curl -s http://localhost:8065/api/v4/system/ping`
+
+The server's `run-server` target handles `setup-go-work`, `start-docker`, and building the client symlink automatically. If you need to start things separately, ensure `go.work` is set up (`make setup-go-work`) and the `client` symlink exists (`ln -nfs ../webapp/channels/dist client`).
+
+### Building the webapp
+
+```bash
+cd webapp && npm install && make dist
+```
+
+For development with hot-reloading: `cd webapp && make run` (or `make dev` for webpack-dev-server).
+
+### Lint / Style checks
+
+- **Webapp**: `cd webapp && npm run check` (runs ESLint + Stylelint across all workspaces)
+- **Server**: `cd server && go vet ./...`

 ### Running tests

-#### Go server tests
- Run from `/workspace/server` with `PATH=/usr/local/go/bin:$PATH`.
- Example (small package): `go test ./public/model/... -count=1 -short -timeout 120s`
- The `-short` flag skips long-running integration tests that need a database.
+- **Webapp unit tests**: `cd webapp && npm run test --workspace platform/client` (or any specific workspace)
+- **Server unit tests**: `cd server && go test ./public/model/... -count=1 -short -timeout 120s`
+- Full server tests need database and are slow: `cd server && make test-server`

-#### Webapp tests
- To run tests for a specific workspace, use `npm run test --workspace <name>` from `webapp/`.
-  - Example: `npm run test --workspace platform/client`
- Do **not** use `npx jest --testPathPatterns="platform/client"` from the root — it picks up both compiled `lib/` tests and uncompiled `src/` TypeScript tests without the correct transform config, causing failures.
- The `platform/client` workspace has 4 test suites / 27 tests (websocket, client4, helpers, errors).
+### Gotchas

-### Linting
-
- `npm run check` from `webapp/` runs ESLint across all workspaces.
- Per-workspace: `npm run check --workspace <name>`.
+- The Go version must match `server/.go-version` (currently 1.24.13). The system Go at `/usr/bin/go` may be outdated; use `/usr/local/go/bin/go`.
+- Node.js must match `.nvmrc` (currently 24.11). Use nvm: `nvm use` from the repo root.
+- The webapp uses npm workspaces (not pnpm/yarn). Always use `npm install` from `webapp/`.
+- `make run` in `server/` starts both server and webapp in development mode. The server runs in the background by default (`RUN_SERVER_IN_BACKGROUND=true` in `config.mk`).
+- When running Jest tests, use `npm run test --workspace <name>` rather than calling `npx jest` directly, because the root-level Jest config differs from workspace-level configs (Jest 30 renamed `--testPathPattern` to `--testPathPatterns`).
+- First-time `go run` or `go test` in the server will download many dependencies and can take 60+ seconds.