---
name: serverpod-change
description: >-
  Guides Serverpod backend changes: protocol models (.spy.yaml), endpoints, code
  generation, and database migrations. Use whenever adding or changing a Serverpod
  endpoint, a .spy.yaml/protocol model, a wire type shared with the client, or a
  database schema/migration in durak_server.
---

# Serverpod Change

Backend changes that touch the protocol, endpoints, or schema. Server-authority
rules and patterns are in `.cursor/rules/server-patterns.mdc`.

## Use the Serverpod MCP first

Before guessing API shapes, consult the **Serverpod MCP** (`serverpod_mcp`) for
endpoints, `.spy.yaml`, codegen, ORM, migrations, auth, and streaming. Prefer it
over training-data assumptions.

## Protocol & endpoints

1. Define/modify the model in a `*.spy.yaml` under `durak_server/lib/src/<domain>/`.
2. Wire types are defined **once** here — never re-declare them on the client.
3. Add/modify the endpoint in the same domain folder. Keep authority server-side:
   authorize every protected call (deny by default); validate all client input.

## Regenerate (never hand-edit generated code)

After any `.spy.yaml` or endpoint change:

```bash
cd durak_server && serverpod generate
```

This regenerates `durak_server/lib/src/generated/` and the `durak_client`
package. Generated files are the single source — edit the `.spy.yaml`, not the
output.

## Migrations (forward-only)

When a model change alters the schema:

```bash
cd durak_server && serverpod create-migration        # generate migration
cd durak_server && dart bin/main.dart --apply-migrations   # apply locally
```

- Review the generated migration before applying; migrations are forward-only
  and reproducible across environments.
- Multi-step writes that must be consistent run in a single transaction.
- Confirm exact CLI flags via the Serverpod MCP if unsure.

## Verify

Regenerate, then run `dart analyze --fatal-infos` and the relevant tests per
`.cursor/rules/verify-commands.md`. Functional-core logic needs unit tests.

## Commit

Conventional Commit with an imperative subject and concise what-&-why body, e.g.
`feat(economy): add coin-transaction ledger model and migration`.