Tools & Utilities

Utilities for api-events development, seeding, and contract gates.

Database seeding

Populate Postgres with test data from api-events/scripts/seed/.

cd api-events
export DATABASE_URL='postgresql://postgres:postgres@localhost:5433/soundcheck?schema=public'

npm run db:seed:baseline     # roles, positions, plans
npm run db:seed:demo-full      # rich persona-driven local dataset (recommended)

After demo-full, restart the Clerk emulator:

docker compose -p api -f dev/docker-compose.yml restart clerk-emulator

Manifest: api-events/scripts/seed/manifest/local-personas.json. Details: api-events/scripts/seed/README.md. Blake Admin is Admin on Seed Demo Band and Owner of leftover Blake Workspace; one-click sign-in lands on Blake Workspace.

Migrations

cd api-events
npm run db:migrate
npm run db:migrate:status
npm run db:migrate:reset    # development only

OpenAPI and contract gates

cd api-events
npm run openapi:emit                    # generate OpenAPI snapshot
npm run openapi:assert-path-templates   # emitted templates must match Encore extract ({userId} not {id})
npm run openapi:parity                  # contract parity gate
npm run openapi:generate-schemas        # write openapiSchemas.generated.ts from a spec, leaving out hand-written names not on driftedSchemaDuplicates.json
npm run openapi:annotate-routes -- --merge-from <go-era-spec.json>  # restore required + missing statuses onto sibling openapiRoute() calls
npm run openapi:generate-baseline       # freeze the Go-era operation checklist used by coverage tests
npm run checks                          # full local quality gate

Emitted OpenAPI syncs to docs/openapi/soundcheck.json for web/mobile client codegen. Path templates use Encore param names. Query/body/response shapes come from sibling openapiRoute() annotations on api.raw handlers. Named $ref schemas come from sibling openapiSchema() registrations. The extractor keeps the first registration of a name it reads, so a copy in src/systems/shared/openapiSchemas.generated.ts can shadow the hand-written schema. openapi:assert-path-templates fails when a name is registered in both places, unless it is on api-events/scripts/openapi/driftedSchemaDuplicates.json. That list holds the copies that still differ from their hand-written schema. Do not add names to it. A listed name that is no longer duplicated also fails, so the list shrinks as copies are deleted. After editing a hand-written schema, delete its generated block if it has one and re-emit. Annotation coverage compares emit to the frozen Go-era checklist in api-events/scripts/openapi/testdata/openapi.baseline-ops.json, not the spec this branch writes. Schema-catalog equality also uses that in-memory emit (only $ref’d openapiSchema() names survive); leftover keys in the committed snapshot must not mask unused registrations. On PRs, api-events-deploy.yml openapi-parity emits and asserts Encore path templates (and catalog keys when the committed snapshot changed). On api-events/ pushes to dev/qa/main, docs-ci sync-openapi-spec emits first, then asserts Encore path templates and catalog keys, and refuses to auto-commit if either drifts. When a PR edits the committed snapshot, Docs CI also requires that file’s catalog keys to match emit so docs-only leftover schemas cannot land.

E2E runner

cd api-events
npm run test:e2e              # full regression against :4000
npm run test:e2e:standalone   # when Encore already running

PowerShell entrypoint: api-events/scripts/run-encore-e2e.ps1

Shared infra launcher

# Repo root — Postgres, Azurite, Clerk emulator
npm run dev:infra

Implementation: scripts/dev-infra.mjs → dev/docker-compose.yml

Encore dev launcher

cd api-events
npm run dev:emulator    # Encore with local Clerk + stub providers
npm run dev             # plain encore run (needs env set manually)

Implementation: api-events/scripts/dev-emulator.mjs

Troubleshooting

Seed fails with connection error

Confirm infra is up and DATABASE_URL points at :5433:

npm run dev:infra

Clerk personas missing

Seed then restart emulator:

cd api-events && npm run db:seed:demo-full
docker compose -p api -f dev/docker-compose.yml restart clerk-emulator

OpenAPI parity fails

Regenerate and fix drift:

cd api-events && npm run openapi:emit
cd api-events && npm run openapi:parity

Overview

Backend

Backend integrations

API reference

Frontend

Mobile

Infrastructure

CI/CD

Development

Guides

Reference

Database seeding

Migrations

OpenAPI and contract gates

E2E runner

Shared infra launcher

Encore dev launcher

Troubleshooting

​Database seeding

​Migrations

​OpenAPI and contract gates

​E2E runner

​Shared infra launcher

​Encore dev launcher

​Troubleshooting

Database seeding

Migrations

OpenAPI and contract gates

E2E runner

Shared infra launcher

Encore dev launcher

Troubleshooting