Enforce per-project cost budgets with a hard-stop guardrail

.env.example

@@ -80,6 +80,35 @@ CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-xxxxxxxxxxxx
 # BACKEND_PORT=8001
 
 
+# ============================================================
+# Optional — security
+# ============================================================
+# Opt-in bearer-token auth for the API. Unset (default) = every
+# endpoint stays open, exactly as before — fine for localhost dev.
+# When set, all /api/* requests must send
+#   Authorization: Bearer <token>
+# Exempt: /api/health, /api/readyz, and CORS preflight. The SSE
+# stream endpoint (/api/sessions/<id>/stream) also accepts
+# ?token=<token>, since the browser EventSource API cannot send
+# an Authorization header. Set this whenever the backend is
+# exposed beyond localhost (e.g. docker-compose.prod.yml).
+#
+# NOTE: ?token= is part of the URL, so uvicorn/nginx/proxy access
+# logs record it verbatim. If the stream endpoint is used behind
+# such a component, redact the token query parameter from access
+# logs (custom uvicorn access-log format, nginx log masking) or
+# restrict log access.
+# API_AUTH_TOKEN=change-me-to-a-long-random-string
+
+# Allowed browser origins for CORS, comma-separated. Defaults to
+# the local frontend (http://localhost:3000, http://127.0.0.1:3000).
+# The frontend normally proxies /api through Next.js (same-origin),
+# so you only need this when a browser calls the backend origin
+# directly. A `*` entry is honored but credentials are then
+# disabled — never both.
+# CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
+
+
 # ============================================================
 # Optional — observability
 # ============================================================
@@ -94,11 +123,36 @@ CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-xxxxxxxxxxxx
 # SENTRY_ENVIRONMENT=local
 
 
+# ============================================================
+# Datastore secrets — REQUIRED by docker-compose.prod.yml
+# ============================================================
+# Prod has NO built-in defaults: docker-compose.prod.yml fails fast
+# (`config`/`up` errors out) if any of these are unset. The backend's
+# DATABASE_URL and AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY are derived
+# from these values, so the app credentials always match the datastores.
+# Replace the placeholders below with strong, unique secrets.
+#
+# Postgres superuser/database (postgres service + backend DATABASE_URL):
+POSTGRES_USER=trainable
+POSTGRES_PASSWORD=change-me-strong-db-password
+POSTGRES_DB=trainable
+#
+# MinIO root credentials (minio service + backend AWS_ACCESS_KEY_ID/SECRET):
+MINIO_ROOT_USER=change-me-minio-user
+MINIO_ROOT_PASSWORD=change-me-strong-minio-password
+#
+# Container image tags for the prebuilt prod images (default: latest):
+# TRAINABLE_BACKEND_TAG=latest
+# TRAINABLE_FRONTEND_TAG=latest
+
+
 # ============================================================
 # Advanced — overridden by docker-compose.prod.yml
 # ============================================================
-# Don't set these unless you're running outside docker-compose.
-# DATABASE_URL=postgresql+asyncpg://trainable:trainable@postgres:5432/trainable
+# docker-compose.prod.yml sets these for the backend container from the
+# datastore secrets above; only set them by hand when running the
+# backend OUTSIDE docker-compose (docker-compose.yml uses fixed dev creds).
+# DATABASE_URL=postgresql+asyncpg://<POSTGRES_USER>:<POSTGRES_PASSWORD>@postgres:5432/<POSTGRES_DB>
 # S3_ENDPOINT=http://minio:9000
-# AWS_ACCESS_KEY_ID=minioadmin
-# AWS_SECRET_ACCESS_KEY=minioadmin
+# AWS_ACCESS_KEY_ID=<same as MINIO_ROOT_USER>
+# AWS_SECRET_ACCESS_KEY=<same as MINIO_ROOT_PASSWORD>

.github/workflows/ci.yml

@@ -23,7 +23,8 @@ jobs:
         with:
           python-version: "3.11"
           cache: pip
-      - run: pip install ruff
+      # Keep in sync with the ruff-pre-commit rev in .pre-commit-config.yaml.
+      - run: pip install "ruff==0.15.22"
       - run: ruff check .
       - run: ruff format --check .
 
@@ -33,13 +34,57 @@ jobs:
     defaults:
       run:
         working-directory: backend
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: trainable_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    env:
+      TEST_DATABASE_URL: postgresql+asyncpg://postgres:postgres@localhost:5432/trainable_test
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
           python-version: "3.11"
           cache: pip
       - run: pip install -r requirements.txt
+      # Coverage is scoped to production code: backend/.coveragerc omits
+      # tests/ so the gate reflects untested application code (with tests
+      # included the total was ~66%; production-only it is ~51%).
+      - run: |
+          pytest tests/ -v --tb=short \
+            --cov=. \
+            --cov-report=xml \
+            --cov-report=term-missing \
+            --cov-fail-under=50
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: backend-coverage
+          path: backend/coverage.xml
+
+  cli-test:
+    name: CLI Tests
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: cli
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - run: pip install pytest .
       - run: pytest tests/ -v --tb=short
 
   backend-security:
@@ -58,6 +103,86 @@ jobs:
       - run: bandit -r . -x ./tests --severity-level medium -f json -o bandit-report.json || true
       - run: bandit -r . -x ./tests --severity-level high
 
+  backend-vuln-scan:
+    name: Backend Dependency Vulnerability Scan (advisory)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: backend
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          # Match backend/Dockerfile (python:3.13-slim) so the audited
+          # dependency resolution mirrors what actually ships.
+          python-version: "3.13"
+          cache: pip
+      - run: pip install -r requirements.txt pip-audit
+      # Advisory only: known advisories (e.g. transitive starlette/mcp/
+      # python-multipart CVEs) already exist in the dependency tree today,
+      # and shouldn't block CI. Flip this to blocking (drop
+      # continue-on-error) once those are triaged and cleared.
+      - name: pip-audit
+        run: pip-audit
+        continue-on-error: true
+
+  frontend-vuln-scan:
+    name: Frontend Dependency Vulnerability Scan (advisory)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+      - run: npm ci
+      # Advisory only: known advisories (next/glob/prismjs/postcss/js-yaml)
+      # already exist in the dependency tree today, and shouldn't block CI.
+      # Flip this to blocking (drop continue-on-error) once those are
+      # triaged and cleared.
+      - name: npm audit
+        run: npm audit
+        continue-on-error: true
+
+  image-scan:
+    name: Container Image Vulnerability Scan (advisory)
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - image: trainable-backend
+            context: ./backend
+          - image: trainable-frontend
+            context: ./frontend
+            target: runner
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - name: Build ${{ matrix.image }} image (local only, not pushed)
+        uses: docker/build-push-action@v5
+        with:
+          context: ${{ matrix.context }}
+          target: ${{ matrix.target || '' }}
+          push: false
+          load: true
+          tags: ${{ matrix.image }}:ci-scan
+      # Advisory only: base-image and OS-package advisories aren't triaged
+      # yet and shouldn't block CI. Flip to blocking (drop
+      # continue-on-error, or set exit-code back to 1 without the wrapper)
+      # once they are.
+      - name: Trivy scan
+        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
+        continue-on-error: true
+        with:
+          image-ref: ${{ matrix.image }}:ci-scan
+          format: table
+          severity: "CRITICAL,HIGH"
+          exit-code: "1"
+
   frontend-lint:
     name: Frontend Lint & Typecheck
     runs-on: ubuntu-latest
@@ -75,6 +200,7 @@ jobs:
       - run: npx next lint
       - run: npx tsc --noEmit
       - run: npx prettier --check 'src/**/*.{ts,tsx,css}'
+      - run: npm test
 
   frontend-build:
     name: Frontend Build

.pre-commit-config.yaml

@@ -0,0 +1,32 @@
+# Pre-commit hooks for Trainable. See CONTRIBUTING.md.
+# Install: pip install pre-commit && pre-commit install
+# Run manually: pre-commit run --all-files
+# Generated / vendored artifacts: not hand-edited, so keep the hooks off them.
+exclude: |
+  (?x)^(
+    package-lock\.json|
+    frontend/package-lock\.json|
+    frontend/tsconfig\.tsbuildinfo|
+    .*\.excalidraw|
+    sample-data/.*
+  )$
+
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Keep in sync with the pinned ruff version in .github/workflows/ci.yml.
+    rev: v0.15.22
+    hooks:
+      # Lint (with autofix) the backend Python code using backend/pyproject.toml.
+      - id: ruff
+        args: [--fix]
+        files: ^backend/
+      # Format the backend Python code.
+      - id: ruff-format
+        files: ^backend/
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: detect-private-key

CONTRIBUTING.md

@@ -38,7 +38,7 @@ This automatically runs ruff (lint + format), trailing whitespace fixes, and pri
 
 ### Python (backend)
 
-- Formatter/linter: [Ruff](https://docs.astral.sh/ruff/) (configured in `pyproject.toml`)
+- Formatter/linter: [Ruff](https://docs.astral.sh/ruff/) (configured in `backend/pyproject.toml`)
 - Run manually: `cd backend && ruff check . && ruff format .`
 - Type hints are expected on all function signatures
 - Use `logger` (not `print`) for all logging
@@ -77,6 +77,6 @@ All tests must pass before submitting a PR.
 
 ## Reporting Issues
 
-- Use [GitHub Issues](https://github.com/lucastononro/trainable-monorepo/issues)
+- Use [GitHub Issues](https://github.com/lucastononro/trainable/issues)
 - Include steps to reproduce, expected vs actual behavior, and environment details
 - For security vulnerabilities, please email the maintainer directly instead of opening a public issue