> ## Documentation Index
> Fetch the complete documentation index at: https://docs.soundchecklive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools & Utilities

> api-events scripts and local development utilities

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

## Database seeding

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

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
cd api-events
npm run db:migrate
npm run db:migrate:status
npm run db:migrate:reset    # development only
```

***

## OpenAPI and contract gates

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
# Repo root — Postgres, Azurite, Clerk emulator
npm run dev:infra
```

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

***

## Encore dev launcher

```bash theme={null}
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

> [accordion] Seed fails with connection error
>
> Confirm infra is up and `DATABASE_URL` points at `:5433`:
>
> ```bash theme={null}
> npm run dev:infra
> ```

> [accordion] Clerk personas missing
>
> Seed then restart emulator:
>
> ```bash theme={null}
> cd api-events && npm run db:seed:demo-full
> docker compose -p api -f dev/docker-compose.yml restart clerk-emulator
> ```

> [accordion] OpenAPI parity fails
>
> Regenerate and fix drift:
>
> ```bash theme={null}
> cd api-events && npm run openapi:emit
> cd api-events && npm run openapi:parity
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.