mancala/AGENTS.md

# AGENTS.md

Guidance for coding agents working in this repository. Keep it current: when you learn something that would have
saved time, add it here.

## Project

Online Mancala (the Turkish *Mangala* rules) with a web app, an Android/iOS app and a Node backend.

| Path | What |
|---|---|
| `packages/mancala.js` | Game engine; rules are plug-ins in `src/common/game_rules` |
| `packages/core` | Code shared by the apps: models, WebSocket client (`RTMTWS`), channel names, history helpers, themes, `PitAnimator`, translations (en, tr) |
| `apps/backend` | Express + `ws`: matchmaking, games, auth, saved games, HTTP API |
| `apps/frontend` | React web app, built with Parcel |
| `apps/mobile` | React Native app |
| `apps/keycloak` | Keycloak image with the realm and a Java extension for guest login |
| `apps/postgres` | Init script creating the `keycloak` and `mancala` databases |
| `apps/compose.yaml` | Postgres, Valkey, Keycloak, backend, frontend |
| `config/nginx.conf` | The production server's nginx config (Certbot managed) |
| `docs/specs/<feature>` | Specs: `requirements.md`, `design.md`, `tasks.md` |
| `TODO.md` | Open work, known bugs and deployment steps; read it before starting |

Specs that exist: `keycloak-auth` (login, guests, tokens), `game-history` (saved games, live games, replay) and
`game-clock` (5 minutes per player, ending games on time).

## Running locally

```sh
yarn build:packages                       # repo root; builds mancala.js and core
cd apps && docker compose up -d --build postgres valkey keycloak   # needs apps/.env, see README.md
cd apps/backend && yarn dev               # http://localhost:5005
cd apps/frontend && yarn dev              # http://localhost:1234 (must be 1234, Keycloak only allows that)
```

Postgres is on `localhost:5433` (5432 is often taken), Valkey on `6379`, Keycloak on `8080`
(admin console `/admin`). The backend's and frontend's defaults point at these. The mobile app points at production
unless `useLocalServer` is set in `apps/mobile/src/const/config.ts`.

## Checks

| What | Command | Notes |
|---|---|---|
| Engine | `cd packages/mancala.js && npx jest` | |
| Core | `cd packages/core && npx jest` | |
| Backend | `cd apps/backend && npx tsc --noEmit -p . && npx jest` | Needs Docker: Postgres and Valkey run in testcontainers |
| Keycloak extension | `cd apps/keycloak/extension && mvn test` | Needs Docker; starts Keycloak with the real realm file |
| Web app | `cd apps/frontend && yarn build` | There is no `tsconfig.json`, so nothing type-checks it; use a temporary one when needed. 3 type errors are known and older than recent work |
| Mobile | `cd apps/mobile && npx tsc --noEmit -p .` and `npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output /tmp/x.bundle` | 11 type errors are known and older than recent work |

There is no automated end-to-end suite. Changes to the game flow were checked by driving Chrome with
`playwright-core` (installed outside the repo, `executablePath: /usr/bin/google-chrome`) against the local stack.

## How we work

- The user writes in Turkish; code, comments, commit messages and specs are in English.
- Larger features start with a spec in `docs/specs/<feature>/` (requirements with acceptance criteria, design with
  decisions and reasons, tasks as a checklist). Implement the tasks in order, one commit each, and tick them. Small
  fixes need no spec. When resuming a feature, read its spec and `tasks.md` first.
- Work on feature branches; commit messages follow `type(scope): summary` with a short body.
- Never add AI attribution (Co-Authored-By lines, "Generated with …") to commits or PRs.
- Do not commit files the user changed but did not ask to commit; stage only your own changes (hunks if needed).
- New dependencies get exact versions.

## Things that are easy to get wrong

**Packages and builds**
- The apps use `packages/core` and `packages/mancala.js` through `link:` dependencies, i.e. their built `dist`.
  After changing a package, run `yarn build` in it (or `yarn dev` to rebuild on change), or the apps use stale code.
  Running dev servers do not notice a rebuilt package: restart the backend, and restart Parcel after deleting
  `apps/frontend/.parcel-cache`.
- Backend and frontend Docker images are built from the repo root: `docker build -f apps/backend/Dockerfile .`.
- The mobile app uses `RTMTWS` from core (its own `src/rtmt` copy is unused), so changing the core WebSocket client
  changes mobile too. Metro needs `watchFolders` and `nodeModulesPaths` (already in `metro.config.js`).

**Backend**
- User ids: Keycloak users are `kc:<sub>`; legacy mobile users are their `userKey`, which is a secret. Anything
  saved or listed publicly goes through `publicUserId()`; clients get `toClientGame()`, never spectator ids.
- Live games: memory is the source of truth, Valkey is a write-through copy restored on startup; the backend
  assumes a single instance. Finished games are written to Postgres once, with retry when it is down.
- Postgres or Valkey being down must not stop games; reads fall back, writes are retried.
- The game clock is stored as each player's time at the start of the turn plus `turnStartedAt`; compute the time
  left with `getClockTimes`, never store a ticking value. `GAME_CLOCK_MS=40000` makes games short for manual tests.
- `RTMT.listenOnClientConnectionChange` adds a listener (several are allowed).
- Jest 27 lacks Node's web globals that testcontainers needs; `tests/support/NodeEnvironment.js` copies them in.
- A Valkey client pointed at a dead port keeps Jest alive for `disconnectTimeout`; tests pass a short one.

**Web app**
- styled-jsx only scopes JSX written directly in a component's render; elements built in helper functions or
  `map` callbacks need `.parent :global(.child)` rules.
- Pages are full-height flex columns: a block with `overflow: hidden` needs `flex-shrink: 0` or it gets squeezed.
- Board components size themselves from the `--board-unit` CSS variable; `BoardView` takes an optional `width`.
- The WebSocket client emits `open` after authentication; anything the server must know about a connection
  (spectating a game, live game previews) is sent on `open`, because the server forgets it when a user goes offline.

**Keycloak**
- The realm file is imported only when the realm does not exist; changes to it must also be made in a running
  Keycloak (or recreate the database).
- Listing some `requiredActions` in the realm file replaces Keycloak's whole default list, so the file contains all
  of them.
- The guest authenticator uses an internal Keycloak SPI: keep the version in `extension/pom.xml` and `Dockerfile` in
  sync and run `mvn test` when upgrading.
- Keycloak sets `Secure` cookies; browsers send them to `http://localhost`, simple HTTP clients do not.

**Mobile**
- `apps/mobile/release_android.sh` contains signing passwords (see `TODO.md`); do not copy them anywhere.