Jason Woltje
4cc43bece6
All checks were successful
ci/woodpecker/push/api Pipeline was successful
Add SpeechConfig with typed configuration and startup validation for STT (Whisper/Speaches), TTS default (Kokoro), TTS premium (Chatterbox), and TTS fallback (Piper/OpenedAI). Includes registerAs factory for NestJS ConfigModule integration, .env.example documentation, and 51 unit tests covering all validation paths. Refs #401
26 lines
2.2 KiB
Markdown
26 lines
2.2 KiB
Markdown
# api — Agent Context
|
|
|
|
> Part of the apps layer.
|
|
|
|
## Patterns
|
|
|
|
- **Config validation pattern**: Config files use exported validation functions + typed getter functions (not class-validator). See `auth.config.ts`, `federation.config.ts`, `speech/speech.config.ts`. Pattern: export `isXEnabled()`, `validateXConfig()`, and `getXConfig()` functions.
|
|
- **Config registerAs**: `speech.config.ts` also exports a `registerAs("speech", ...)` factory for NestJS ConfigModule namespaced injection. Use `ConfigModule.forFeature(speechConfig)` in module imports and access via `this.config.get<string>('speech.stt.baseUrl')`.
|
|
- **Conditional config validation**: When a service has an enabled flag (e.g., `STT_ENABLED`), URL/connection vars are only required when enabled. Validation throws with a helpful message suggesting how to disable.
|
|
- **Boolean env parsing**: Use `value === "true" || value === "1"` pattern. No default-true -- all services default to disabled when env var is unset.
|
|
|
|
## Gotchas
|
|
|
|
- **Prisma client must be generated** before `tsc --noEmit` will pass. Run `pnpm prisma:generate` first. Pre-existing type errors from Prisma are expected in worktrees without generated client.
|
|
- **Pre-commit hooks**: lint-staged runs on staged files. If other packages' files are staged, their lint must pass too. Only stage files you intend to commit.
|
|
- **vitest runs all test files**: Even when targeting a specific test file, vitest loads all spec files. Many will fail if Prisma client isn't generated -- this is expected. Check only your target file's pass/fail status.
|
|
|
|
## Key Files
|
|
|
|
| File | Purpose |
|
|
| ------------------------------------- | ---------------------------------------------------------------------- |
|
|
| `src/speech/speech.config.ts` | Speech services env var validation and typed config (STT, TTS, limits) |
|
|
| `src/speech/speech.config.spec.ts` | Unit tests for speech config validation (51 tests) |
|
|
| `src/auth/auth.config.ts` | Auth/OIDC config validation (reference pattern) |
|
|
| `src/federation/federation.config.ts` | Federation config validation (reference pattern) |
|