Flight-Ops/AGENTS.md

Flight Simulator — Workflow Rules

Change process (mandatory)

1. Small, incremental changes — work is done one change at a time, in smaller parts; each part must be tested thoroughly with unit and e2e tests covering it before moving on.
2. Feature branch + PR — every change lands on a feature branch off master (no direct pushes to master). The branch carries the commits below; open a pull request to master.
3. Changelog entry — every such change is listed in CHANGELOG.md with date, time and version (format: ## v<version> — YYYY-MM-DD HH:MM, then bullet points of what changed).
4. Version bump — the version is updated in package.json.
5. CI must pass — the PR's pipeline (build → unit tests → e2e, .gitea/workflows/ci.yml) must be green before merging. CI never deploys to production; its e2e runs against an isolated stack inside dind.
6. Tag + manual deploy after merge — once merged, tag the version on master (e.g. v0.13.0). Production (https://flight.dev.kkhost.pl) is updated manually afterwards: docker compose up -d --build on the host.

E2E tests (mandatory)

1. Docker compose instance is the app under test — e2e always runs against a docker-compose build, never a local next dev on :3000 (dev builds don't render for non-loopback clients, and a second instance splits state). Locally that means the Traefik-routed instance at https://flight.dev.kkhost.pl; in CI it is an isolated stack inside dind (docker-compose.ci.yml) — CI never deploys to or modifies production.
2. Update before testing (local) — deploy current code first: docker compose up -d --build, then run the suite with plain npx playwright test. The config's webServer block is off by default; set E2E_DEPLOY_CMD to have Playwright itself run a deploy command and wait for readiness.
3. Remote browsers — local runs drive browsers through the shared Playwright server at 192.168.1.4:3000 (Docker image tag must match this repo's @playwright/test version, pinned in devDependencies). Set PW_REMOTE_BROWSER=0 to run local chromium instead — CI does, because the remote server cannot reach a stack inside dind.
4. CI env vars (playwright.config.ts, all optional; defaults preserve the local flow) — E2E_BASE_URL (app under test), E2E_DEPLOY_CMD (webServer deploy command), PW_REMOTE_BROWSER=0 (local browsers); e2e/state.spec.ts reads E2E_COMPOSE_ARGS for its mid-run container restart.

API

1. Live base URL — https://flight.dev.kkhost.pl (the docker-compose build behind Traefik).
2. Machine-readable spec — OpenAPI 3.x at https://flight.dev.kkhost.pl/api/openapi; current app version at /api/version.
3. Spec lives in code — generated from lib/openapi.ts, served by app/api/openapi/route.ts; must be updated whenever an endpoint changes.

Other

1. For longer terminal tasks you should use pty_* tools.