# maestro — development policy

Maestro is the NestJS BFF between the Angular frontend and the gRPC services
(pi-factory, in-factory) / platform-api. These rules come from code review and
apply to every change; the same rules live in pi-factory and in-factory.

## Layering
- Controllers are thin: decorators, body validation, one call into a service,
  response shape. Orchestration (multi-step calls, rollbacks, platform-api or
  gRPC round-trips) lives in a `*.service.ts`. Example:
  `platform-api/pipeline-tables.service.ts`.
- One platform-api route per operation. If the platform already dispatches by
  pipeline type (batch vs CDC), do not branch on the type here — call the
  route that dispatches (e.g. `DELETE /pipeline/{id}/jobs` for table removal,
  never `DELETE /jobs/{id}` from maestro).

## Types
- No `any` / `as any`. gRPC calls take the protospack request type exactly
  (`AddCdcTableRequest`, `MarkTableDeletedRequest`, ...); DTOs and interfaces
  are explicit classes/interfaces. Use `Record<string, T>` or `unknown` (with
  narrowing) when a shape is genuinely open — never `any`.
- Protospack payloads are built in one mapper per entity (e.g.
  `inputs/cdc-table.mapper.ts`), so a field that mirrors another
  (`CdcTable.name` == `table_name`) is derived in exactly one place.

## Pipeline type
- Decide CDC vs batch with `src/utils/cdc.ts` (`isCdcPlugin`, `isCdcJob`,
  `isCdcPipeline`), never with inline `plugin.endsWith('_cdc')`, `!!x`, or
  the absence of some other data (e.g. "no run history ⇒ editable").
- The platform-api stamps `job.input.connector === 'cdc'` on CDC jobs; that
  is the authoritative discriminator once a pipeline exists.

## Dependencies
- `@dadosfera/protospack-v2` is consumed from CodeArtifact, pinned to an exact
  version (`npm i @dadosfera/protospack-v2@<version> --save-exact`). A `file:`
  / tarball reference is for local development only and must never be
  committed. Note: `^3.40.0-beta.N` resolves to the stable `3.40.0` —
  prereleases must be pinned exactly.

## Commits and releases
- Deploys are cut by semantic-release with the eslint preset: the commit
  title MUST start with `FIX:` (patch), `UPDATE:` or `FEAT:` (minor). A
  lowercase `feat(scope): ...` merges without producing a version, so the
  code never reaches stg/prd.
- Pushing to `beta` deploys stg; `main` deploys prd.

## Tests
- Every service method with a rollback path has a spec covering the
  happy path, the platform failure (rollback fires) and a rollback failure
  (does not mask the original error). Run `npx jest <path>` for a folder,
  `npx tsc --noEmit -p tsconfig.json` for types.
- Several gRPC client configs read `process.env` at import time, so the full
  suite needs the service URLs set (any `0.0.0.0:<port>` value works):
  `DUC_URL=0.0.0.0:50051 INFACTORY_URL=0.0.0.0:50052 PIFACTORY_URL=0.0.0.0:50053 npx jest`.
  A `Cannot read properties of undefined (reading 'startsWith')` at import is
  this, not a broken test.