# DevOps Platform API

NestJS + TypeScript backend for the DevOps operations platform. The current local MVP provides the enterprise project skeleton, Prisma data model, configuration validation, integration client boundaries, Gitea webhook handling, Jenkins queue/build synchronization, notification provider boundaries, audit logs, BPMN process definitions, and runnable seed-backed APIs.

## Scope

- Manage projects, deploy runs, BPMN step state, Jenkins/Gitea integration state, notification delivery, audit records, and agent invocations.
- Keep all external credentials server-side.
- Use Prisma as the default data access layer. Native SQL is allowed only inside Repository methods with a documented reason.

## Local Setup

```bash
pnpm install
cp .env.example .env
pnpm prisma:generate
pnpm start:dev
```

The API listens on `http://localhost:4300` by default and runs without a local MySQL database when `USE_DATABASE_READS=false`. In that mode `/projects` and `/deploy-runs` use seed-backed repository data while keeping the same service and controller contracts intended for Prisma-backed reads.

## Useful Commands

```bash
pnpm lint
pnpm test
pnpm build
pnpm check
pnpm prisma:migrate:dev --name init
```

## API

- `GET /health`: dependency configuration and health summary.
- `GET /settings/integration-config`: Jenkins/Gitea/notification/LLM/Database/Redis/Secret Encryption Key configuration status. The response only exposes environment variable names, never secret values.
- `GET /projects`: configured project list.
- `GET /projects/:key`: one project by key.
- `GET /deploy-runs`: latest deploy runs.
- `POST /deploy-runs`: create a deploy run. Missing Jenkins config uses a local dry-run path; configured Jenkins calls `buildWithParameters` and returns `queued/running`.
- `POST /deploy-runs/:id/sync-jenkins`: synchronize Jenkins queue/build/log status and advance success or failure.
- `POST /deploy-runs/:id/cancel`: cancel a deploy run.
- `POST /deploy-runs/:id/retry`: create a retry deploy run.
- `POST /webhooks/gitea`: accept Gitea push webhooks and trigger test deploy runs.
- `GET /process-definitions/release`: BPMN release process definition.
- `GET /audit-logs`: latest sanitized audit records.
- `GET /agent/invocations` and `POST /agent/invocations`: DevOps-scoped agent invocation records and mock results.
- `GET /docs`: Swagger UI.

## Data Access Rules

- Business modules access data through Repository classes, not direct Prisma calls in controllers.
- Prisma owns connection pooling, transactions, migrations, and typed models.
- Deploy run creation, status transition, step transition, and audit writes must use explicit Prisma transactions once DB writes are enabled.
- Idempotency keys are mandatory for webhook callbacks, Jenkins queue/build tracking, and manual deploy retry paths.
- Raw SQL must be parameterized, isolated in a Repository method, covered by tests, and justified in the method comment.

## Secret Rules

- Never commit real `.env`, Jenkins tokens, Gitea tokens, notification webhook URLs, LLM keys, private keys, or cookies.
- Persisted secrets belong in the `secrets` table encrypted with a deployment-provided key or in the deployment secret manager.
- Logs, audit records, integration errors, and LLM prompts must pass through redaction before storage or return.

## Agent Boundary

The Agent module is not a generic chat entrypoint. It can only support DevOps workflows:

- release risk summaries,
- Jenkins failure diagnosis,
- runbook Q&A against whitelisted sources,
- release notes drafts,
- incident review drafts.

Agent calls are read-only. They must not trigger deploys, mutate Jenkins/Gitea, or expose raw secrets. When `LLM_BASE_URL`, `LLM_API_KEY`, and `LLM_MODEL` are configured, the backend proxies DevOps-scoped prompts to `/chat/completions`; otherwise it returns local mock results with the same API shape.