developer-experience.yml

name: Developer Experience

on:
  push:
    branches: ["main"]
    paths:
      - ".dockerignore"
      - ".env.example"
      - ".env.minimal"
      - ".github/workflows/developer-experience.yml"
      - ".github/workflows/docker-publish.yml"
      - "Dockerfile"
      - "README.md"
      - "compose.yaml"
      - "compose.dev.yaml"
      - "compose.prod.yaml"
      - "compose.smoke.yaml"
      - "docs/**"
      - "entrypoint.sh"
      - "mkdocs.yml"
      - "mcp-bridge/**"
      - "pyproject.toml"
      - "scripts/write_compose_env.py"
      - "setup.sh"
      - "src/**"
      - "systemd/**"
      - "tests/test_deployment_contract.py"
      - "uv.lock"
  pull_request:
    branches: ["main"]
    paths:
      - ".dockerignore"
      - ".env.example"
      - ".env.minimal"
      - ".github/workflows/developer-experience.yml"
      - ".github/workflows/docker-publish.yml"
      - "Dockerfile"
      - "README.md"
      - "compose.yaml"
      - "compose.dev.yaml"
      - "compose.prod.yaml"
      - "compose.smoke.yaml"
      - "docs/**"
      - "entrypoint.sh"
      - "mkdocs.yml"
      - "mcp-bridge/**"
      - "pyproject.toml"
      - "scripts/write_compose_env.py"
      - "setup.sh"
      - "src/**"
      - "systemd/**"
      - "tests/test_deployment_contract.py"
      - "uv.lock"

permissions:
  contents: read

concurrency:
  group: developer-experience-${{ github.ref }}
  cancel-in-progress: true

jobs:
  documentation:
    name: Build documentation
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v5
        with:
          enable-cache: true
          cache-dependency-glob: "uv.lock"

      - name: Set up Python
        run: uv python install 3.13

      - name: Install documentation dependencies
        run: uv sync --locked --only-group docs

      - name: Build documentation in strict mode
        run: uv run --no-sync mkdocs build --strict

  deployment-contract:
    name: Validate deployment contract
    runs-on: ubuntu-latest
    env:
      ENV_FILE: .env.minimal
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v5
        with:
          enable-cache: true
          cache-dependency-glob: "uv.lock"

      - name: Set up Python
        run: uv python install 3.13

      - name: Install project dependencies
        run: uv sync --locked

      - name: Build the production image
        run: docker build --tag blacki:contract-test .

      - name: Run deployment contract tests
        run: uv run pytest tests/test_deployment_contract.py

      - name: Validate shell syntax
        run: bash -n setup.sh entrypoint.sh

      - name: Validate Docker Compose
        run: |
          docker compose --env-file .env.minimal \
            -f compose.yaml -f compose.prod.yaml config --quiet
          docker compose --env-file .env.minimal \
            -f compose.yaml -f compose.dev.yaml config --quiet

      - name: Smoke test production startup
        env:
          ENV_FILE: .env.minimal
          IMAGE: blacki:contract-test
          SMOKE_PROJECT: blacki-contract-smoke
        run: |
          cleanup() {
            docker compose --project-name "$SMOKE_PROJECT" \
              -f compose.smoke.yaml down --remove-orphans >/dev/null 2>&1 || true
          }
          trap cleanup EXIT

          docker compose --project-name "$SMOKE_PROJECT" \
            --env-file "$ENV_FILE" -f compose.smoke.yaml up -d
          CONTAINER_ID=$(
            docker compose --project-name "$SMOKE_PROJECT" \
              -f compose.smoke.yaml ps --all -q agent
          )
          if [ -z "$CONTAINER_ID" ]; then
            echo "Production smoke test did not create the agent container."
            docker compose --project-name "$SMOKE_PROJECT" \
              -f compose.smoke.yaml logs --no-color
            exit 1
          fi

          for attempt in $(seq 1 15); do
            if docker exec "$CONTAINER_ID" python -c \
              'import urllib.request; urllib.request.urlopen("http://127.0.0.1:8080/ready", timeout=3).read()' \
              >/dev/null 2>&1; then
              echo "Production image readiness check passed."
              exit 0
            fi

            RUNNING=$(
              docker inspect --format '{{.State.Running}}' \
                "$CONTAINER_ID" 2>/dev/null || true
            )
            if [ "$RUNNING" != "true" ]; then
              echo "Production image exited before becoming ready."
              docker compose --project-name "$SMOKE_PROJECT" \
                -f compose.smoke.yaml logs --no-color
              exit 1
            fi

            echo "Readiness attempt $attempt/15 failed; retrying in 2s..."
            sleep 2
          done

          echo "Production image did not become ready."
          docker compose --project-name "$SMOKE_PROJECT" \
            -f compose.smoke.yaml logs --no-color
          exit 1

      - name: Validate production OTLP exporters
        run: |
          docker run --rm --entrypoint python \
            --env OTEL_EXPORTER_OTLP_ENDPOINT=http://collector.example:4318 \
            --env OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
            blacki:contract-test -c \
            "from blacki.utils.observability import validate_observability_environment; validate_observability_environment()"