jhalitaksoy/mancala
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ec833b4ec5
mancala/AGENTS.md

7.8 KiB
Raw Blame History

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, the login theme 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), game-clock (5 minutes per player, ending games on time) and web-redesign (the web app's look: themes, board, pages).

Running locally

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 (with "types": ["styled-jsx", "react", "react-dom"]). 1 type error (react-dom/client) is known
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.
  • Colours come from CSS variables of the theme class on <html> (styles/app.css); the web app's themes (theme/themes.ts) are passed to core's ThemeManager, which the mobile app uses with its own default themes.
  • Styles that need container queries (@container, cqw), such as the board's, are plain .css files imported by the component; styled-jsx 5.0 does not handle them. BoardView fills its container and stands upright below 600 px.
  • When a script drives the app in Chrome, wait for the header (.hdr) and a few seconds after the first load before navigating; navigating during the guest login leaves an invalid token. Open the lobby with the "New Game" button, not by URL, or the matchmaking message goes out before the WebSocket is open.
  • 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.
  • The login theme (apps/keycloak/themes/mancala) is only CSS on top of keycloak.v2. Keycloak in start mode caches themes and keeps gzipped resources in data/tmp/kc-gzip-cache across restarts; see apps/keycloak/README.md for reloading it in a running container.

Mobile

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