turniere-backend/AGENTS.md

# turniere-backend Agent Notes

This repository should be operated through `invoke` tasks by default.

For routine development, verification, Docker, and E2E work, agents should use
`inv ...` rather than ad-hoc shell commands unless there is a strong reason not to.

## Default Workflow

Use `tasks.py` and run commands through `inv ...` instead of ad-hoc shell commands for routine work.

## Local Setup

Assume Ruby is already installed at the version from `.ruby-version`.

For local development, the preferred path is:

- `inv setup`
- `inv start-local`

`inv setup` installs the Bundler version pinned in `Gemfile.lock`, configures Bundler for local development (`development test`, without `production`), and runs `bundle install`.

`inv start-local` runs the normal local bootstrap flow:

- `inv setup`
- `inv db-migrate`
- optional local user bootstrap via `--bootstrap-user`
- Rails server start on `0.0.0.0:3000`

Useful local commands:

- `inv setup`
- `inv db-reset --env=test`
- `inv db-migrate`
- `inv server`
- `inv start-local`
- `inv start-local --bootstrap-user`
- `inv start-test-local`
- `inv bootstrap-dev-user`
- `inv bootstrap-e2e-user`

Examples:

- `inv db-migrate`
- `inv test`
- `inv test-shard --node-index=1 --node-total=8`
- `inv lint`
- `inv verify-http`
- `inv blackbox-production`
- `inv scenario-main-usecase`
- `inv docker-build-all`
- `inv docker-test-shard --node-index=3 --node-total=8`
- `inv docker-test-http-e2e`

## Concurrent Local Testing

If other agents or local runs may already be using shared test resources, do not
reuse `db/test.sqlite3` or fixed ports for ad-hoc verification.

Prefer isolated per-run resources instead:

- use a unique temporary sqlite database via `DATABASE_URL=sqlite3:/tmp/...`
- choose open ports automatically or derive unique ports per run
- keep normal repo tasks as default, but use isolated overrides when avoiding collisions is important

Practical expectation:

- for targeted/spec-specific verification where `inv` does not provide isolation knobs, it is acceptable to run the underlying command with isolated env vars
- if isolated local verification becomes recurring, add or extend an `inv` task for it

For local E2E-style startup with a usable login, prefer:

- `inv start-local --bootstrap-user`
- `inv start-test-local`

`inv start-test-local` is preferred for cross-repo or Playwright-style local E2E runs.
It recreates `db/test.sqlite3` on every run, re-migrates, bootstraps the default E2E
users, and starts Rails in `test` mode on `0.0.0.0:3000`.

Default local bootstrap credentials:

- email: `e2e@example.com`
- password: `password123`
- username: `e2e-user`

The GitLab CI pipeline is expected to use these tasks as well.
In CI, blackbox E2E should prefer the documented GitLab service-to-service model with `FF_NETWORK_PER_BUILD: "true"` when the production image needs to talk to a Postgres sidecar.
The normal Rails spec suite is sharded through `inv test-shard ...` and should stay aligned with the CI matrix configuration.

Useful GitLab push-option variables for saving CI minutes on public repos:

- skip all spec jobs: `git push -o ci.variable="SKIP_ALL_SPECS=1"`
- skip only normal Rails specs: `git push -o ci.variable="SKIP_RAILS_SPEC=1"`
- skip only blackbox E2E: `git push -o ci.variable="SKIP_E2E_SPEC=1"`

Do not use these by default. Only use them when the change truly does not affect the skipped area.

This is not just a convenience preference. The task layer is the operational
contract for this repo and should stay aligned across local use, CI, and
cross-repo consumers.

## Why

The point of the task layer is:

- one stable entrypoint for local development
- one stable entrypoint for CI
- one stable entrypoint for frontend and cross-repo test setup
- fewer undocumented command variants

If a workflow matters often enough that a human or CI needs to remember it, it
should usually become an `invoke` task.

## Maintenance Rule

When new functionality or recurring maintenance work is added, extend `tasks.py`
so the new workflow stays easy to discover and easy to run.

Do not leave important multi-step flows only in:

- CI YAML
- MR descriptions
- shell history
- team memory

Instead, add or update an `inv` task and then have CI or docs call that task.

If a new backend capability introduces a meaningful setup, verification, fixture,
or scenario workflow, add or extend a task for it as part of the same change.

## Local-Only Helper Code

If helper code exists only for local development, local profiling, or test/E2E support,
prefer placing it in a path that the production Docker image does not copy.

Current production image copies:

- `app`
- `bin`
- `config`
- `db`
- `public`
- `script`
- `config.ru`
- `Rakefile`

It does not copy `lib`, `spec`, `e2e`, or `tasks.py`.

Practical rule:

- production runtime code belongs in copied paths such as `app/`
- local-only helpers should prefer `lib/`, `spec/`, `e2e/`, or task-layer code when feasible
- if production must ignore a local-only feature, cover that with blackbox E2E against the production image

## HTTP E2E

The backend HTTP E2E flow is intended to be reusable outside this repo, especially by frontend tests that need realistic backend state.

That means:

- scenario creation should stay HTTP-driven
- reusable scenario setup should be exposed through `inv` tasks and `script/e2e_scenarios.rb`
- new commonly needed backend states should be added to the scenario/task layer, not recreated ad hoc in each consuming test suite
- the released production image should be exercised through the blackbox task layer, not only Rails-internal test entrypoints

## Practical Expectation

If you touch test, verification, boot, Docker, or scenario setup workflows,
check whether `tasks.py` also needs to change.