python-react-ci.yml

name: Reusable Python+React CI

# Reusable CI workflow for homelabforge Python+React repos.
# Consumers wrap this via a thin .github/workflows/ci.yml that calls:
#
#   jobs:
#     ci:
#       uses: homelabforge/shared-workflows/.github/workflows/python-react-ci.yml@v1.0.0
#       with:
#         enable-translations: true   # mygarage only
#         enable-bootstrap-token: true # vulnforge only
#         security-tripwire-script: .github/scripts/security-tripwire.sh
#
# Inputs default to the homelab-standard values. Bun version comes from
# the consumer repo's .bun-version file (single source of truth).

on:
  workflow_call:
    inputs:
      python-version:
        type: string
        default: "3.14"
      bun-version-file:
        type: string
        default: ".bun-version"
      bun-version:
        # Escape hatch — leave empty to use bun-version-file.
        type: string
        default: ""
      enable-e2e:
        type: boolean
        default: true
      enable-translations:
        type: boolean
        default: false
      enable-bootstrap-token:
        type: boolean
        default: false
      enable-api-freshness-check:
        type: boolean
        default: true
      enable-pg-migrations:
        # Run the consumer's docker-compose.test.yml stack and execute
        # pytest against its PostgreSQL sidecar. Off by default — only
        # mygarage ships a compose stack today (added in v2.27.0-rc2).
        # See pg-migrations-* inputs below for paths/service.
        type: boolean
        default: false
      pg-migrations-compose-file:
        type: string
        default: "docker-compose.test.yml"
      pg-migrations-service:
        type: string
        default: "mygarage-test"
      pg-migrations-pytest-path:
        type: string
        default: "tests/migrations/"
      runner-os:
        type: string
        default: ubuntu-latest
      security-tripwire-script:
        type: string
        default: ""

permissions:
  contents: read

jobs:
  test-backend:
    name: Backend Tests
    runs-on: ${{ inputs.runner-os }}
    timeout-minutes: 25

    steps:
      - name: Checkout code
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Set up Python
        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
        with:
          python-version: ${{ inputs.python-version }}

      - name: Install uv
        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8
        with:
          enable-cache: true
          cache-dependency-glob: 'backend/uv.lock'

      - name: Install dependencies
        run: |
          cd backend
          uv sync --frozen --all-extras

      - name: Run ruff linter
        run: cd backend && uv run ruff check .

      - name: Run ruff formatter check
        run: cd backend && uv run ruff format --check .

      - name: Run pyright type checking
        run: cd backend && PYTHONPATH=. uv run pyright

      - name: Security tripwire
        if: inputs.security-tripwire-script != ''
        run: bash "${{ inputs.security-tripwire-script }}"

      - name: Run pytest
        run: |
          cd backend
          timeout 25m uv run pytest tests/ -v --tb=short

  test-frontend:
    name: Frontend Tests
    runs-on: ${{ inputs.runner-os }}

    steps:
      - name: Checkout code
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Set up Bun (from version-file)
        if: inputs.bun-version == ''
        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
        with:
          bun-version-file: ${{ inputs.bun-version-file }}

      - name: Set up Bun (from explicit override)
        if: inputs.bun-version != ''
        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
        with:
          bun-version: ${{ inputs.bun-version }}

      - name: Install dependencies
        run: |
          cd frontend
          if [ "${{ github.actor }}" = "dependabot[bot]" ]; then bun install; else bun install --frozen-lockfile; fi

      - name: Run TypeScript type checking
        run: cd frontend && bun run type-check

      - name: Run linter
        run: cd frontend && bun run lint

      - name: Validate translation keys
        if: inputs.enable-translations
        run: cd frontend && bun run validate:translations

      - name: Run tests
        run: cd frontend && bun run test:run

  test-e2e:
    name: E2E Tests
    if: inputs.enable-e2e
    runs-on: ${{ inputs.runner-os }}
    timeout-minutes: 20
    needs: [test-backend, test-frontend]

    steps:
      - name: Checkout code
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Set up Python
        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
        with:
          python-version: ${{ inputs.python-version }}

      - name: Install uv
        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8
        with:
          enable-cache: true
          cache-dependency-glob: 'backend/uv.lock'

      - name: Install backend dependencies
        run: cd backend && uv sync --frozen --all-extras

      - name: Set up Bun (from version-file)
        if: inputs.bun-version == ''
        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
        with:
          bun-version-file: ${{ inputs.bun-version-file }}

      - name: Set up Bun (from explicit override)
        if: inputs.bun-version != ''
        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
        with:
          bun-version: ${{ inputs.bun-version }}

      - name: Install frontend dependencies
        run: |
          cd frontend
          if [ "${{ github.actor }}" = "dependabot[bot]" ]; then bun install; else bun install --frozen-lockfile; fi

      - name: Install Playwright browsers
        run: cd frontend && bunx playwright install chromium --with-deps

      - name: Run E2E tests
        run: cd frontend && bun run e2e
        env:
          CI: true
          VULNFORGE_BOOTSTRAP_TOKEN: ${{ inputs.enable-bootstrap-token && 'e2e-ci-test-token' || '' }}

      - name: Upload Playwright report
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        if: ${{ !cancelled() }}
        with:
          name: playwright-report
          path: frontend/playwright-report/
          retention-days: 14

      - name: Upload test results
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        if: ${{ !cancelled() }}
        with:
          name: playwright-results
          path: frontend/test-results/
          retention-days: 7

  api-types-freshness:
    name: API Types Freshness
    if: inputs.enable-api-freshness-check
    runs-on: ${{ inputs.runner-os }}
    needs: [test-backend]

    steps:
      - name: Checkout code
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Set up Python
        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
        with:
          python-version: ${{ inputs.python-version }}

      - name: Install uv
        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8
        with:
          enable-cache: true
          cache-dependency-glob: 'backend/uv.lock'

      - name: Install backend dependencies
        run: cd backend && uv sync --frozen --all-extras

      - name: Set up Bun (from version-file)
        if: inputs.bun-version == ''
        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
        with:
          bun-version-file: ${{ inputs.bun-version-file }}

      - name: Set up Bun (from explicit override)
        if: inputs.bun-version != ''
        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
        with:
          bun-version: ${{ inputs.bun-version }}

      - name: Install frontend dependencies
        run: |
          cd frontend
          if [ "${{ github.actor }}" = "dependabot[bot]" ]; then bun install; else bun install --frozen-lockfile; fi

      - name: Check API types freshness
        run: cd frontend && bun run check:api-freshness

  pg-migrations:
    # Why this job exists:
    #   The repo's existing test-backend job runs pytest against
    #   SQLite. Migration 054 in mygarage v2.27.0-rc1 shipped with two
    #   PG-only bugs (DATETIME column type, ADD CONSTRAINT IF NOT
    #   EXISTS) that all CI passes ignored — `Base.metadata.create_all`
    #   was always run before the migrations, so by the time the
    #   migration's literal SQL ran the columns/constraints already
    #   existed and the idempotency guards short-circuited. The
    #   migration's actual SQL never executed against PG in any test.
    #
    #   Consumers can opt in to a PG matrix via a docker-compose stack
    #   that pairs a postgres:16-alpine sidecar with a test image and
    #   a pre-migration SQL baseline. Migration tests load the
    #   baseline into a clean PG schema and exercise the new
    #   migration's SQL for real.
    name: PostgreSQL Migration Tests
    if: inputs.enable-pg-migrations
    runs-on: ${{ inputs.runner-os }}
    timeout-minutes: 15
    needs: [test-backend]

    steps:
      - name: Checkout code
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0

      - name: Build test image (cached via gha)
        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
        with:
          context: ./backend
          file: ./backend/Dockerfile.test
          tags: ${{ inputs.pg-migrations-service }}:local
          load: true
          cache-from: type=gha,scope=pg-migrations
          cache-to: type=gha,scope=pg-migrations,mode=max

      - name: Bring up PostgreSQL sidecar
        env:
          MYGARAGE_TEST_UID: "1001"
          MYGARAGE_TEST_GID: "1001"
        run: |
          docker compose -f "${{ inputs.pg-migrations-compose-file }}" \
            -p ${{ inputs.pg-migrations-service }} up -d postgres-test

      - name: Wait for postgres healthy
        run: |
          for _ in $(seq 1 30); do
            health=$(docker compose -f "${{ inputs.pg-migrations-compose-file }}" \
              -p ${{ inputs.pg-migrations-service }} ps postgres-test \
              --format '{{.Health}}' || true)
            if [ "$health" = "healthy" ]; then
              echo "postgres-test healthy"
              exit 0
            fi
            sleep 2
          done
          echo "postgres-test did not become healthy in 60s" >&2
          docker compose -f "${{ inputs.pg-migrations-compose-file }}" \
            -p ${{ inputs.pg-migrations-service }} logs postgres-test
          exit 1

      - name: Run pytest against PG sidecar
        env:
          MYGARAGE_TEST_UID: "1001"
          MYGARAGE_TEST_GID: "1001"
        run: |
          docker compose -f "${{ inputs.pg-migrations-compose-file }}" \
            -p ${{ inputs.pg-migrations-service }} run --rm \
            ${{ inputs.pg-migrations-service }} \
            pytest ${{ inputs.pg-migrations-pytest-path }} -v --tb=short

      - name: Tear down stack
        if: always()
        run: |
          docker compose -f "${{ inputs.pg-migrations-compose-file }}" \
            -p ${{ inputs.pg-migrations-service }} down -v || true

  docker-build-test:
    name: Docker Build Test
    runs-on: ${{ inputs.runner-os }}
    env:
      BUILDKIT_PROGRESS: plain

    steps:
      - name: Checkout code
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0

      - name: Read bun version
        id: bun
        run: echo "version=$(cat ${{ inputs.bun-version-file }})" >> "$GITHUB_OUTPUT"

      - name: Build Docker image
        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
        with:
          context: .
          push: false
          tags: ci-check:test
          build-args: |
            BUN_VERSION=${{ steps.bun.outputs.version }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
          provenance: false