name: Deploy Docs (dev)

# Builds apps/docs (Docusaurus - the canonical docs/ tree plus the generated TypeDoc API
# reference) and publishes it to the DEV Cloudflare Pages project (bloom-docs), beside
# deploy-web-dev.yml's dashboard and deploy-admin-dev.yml's admin console. It runs only after
# CI (all stages: security, test, build - including the docs-build gate in ci-test.yml)
# succeeds on main, so a red pipeline never deploys.
#
# Unlike the web/admin/storybook deploys, this workflow must NOT no-op while Cloudflare is
# unconfigured (M45-5): the live docs URL is linked from the README and docs/index.md, so a
# silently-skipped deploy would leave it stale (or dead) under a green pipeline. Missing
# credentials fail the preflight step below, and a missing Pages project fails the wrangler
# publish - both loud. OPERATOR STEP (one-time, needs the Cloudflare key): create the project
# before the first run - `wrangler pages project create bloom-docs --production-branch=main`.

on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]
    branches: [main]
  workflow_dispatch:

concurrency:
  group: deploy-docs-dev
  cancel-in-progress: true

jobs:
  deploy:
    # Auto runs only when CI succeeded (all stages passed on main); manual runs always proceed.
    # No Cloudflare guard here - an unconfigured account must fail the run, never skip it.
    if: >-
      ${{ github.event_name == 'workflow_dispatch' ||
          github.event.workflow_run.conclusion == 'success' }}
    runs-on: bloom-arc
    steps:
      - uses: actions/checkout@v4
        with:
          ref: main

      # Fail loud, never silently skip (M45-5). Secrets are invisible to `if:`, so the check
      # goes through env vars, mirroring deploy-storybook.yml's HAS_CF - but failing instead
      # of skipping.
      - name: Preflight - require the Cloudflare configuration
        env:
          HAS_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN != '' }}
          HAS_ACCOUNT: ${{ vars.CLOUDFLARE_ACCOUNT_ID != '' }}
        run: |
          set -euo pipefail
          ok=true
          if [ "$HAS_TOKEN" != "true" ]; then
            echo "::error::CLOUDFLARE_API_TOKEN secret is not set - the docs deploy must not silently skip"
            ok=false
          fi
          if [ "$HAS_ACCOUNT" != "true" ]; then
            echo "::error::CLOUDFLARE_ACCOUNT_ID variable is not set - the docs deploy must not silently skip"
            ok=false
          fi
          [ "$ok" = "true" ] || exit 1

      - uses: pnpm/action-setup@v4
        with:
          version: 10.6.3

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
          cache-dependency-path: pnpm-lock.yaml

      # Workspace-root install (single lockfile, #481); build + publish stay in apps/docs.
      # The build also generates the TypeDoc reference from packages/api-client + packages/ui
      # sources (M45-4), which the root install provides.
      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Build
        working-directory: apps/docs
        run: pnpm run build

      - name: Publish to Cloudflare Pages (dev)
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
          workingDirectory: apps/docs
          packageManager: pnpm
          command: >-
            pages deploy build
            --project-name=${{ vars.CLOUDFLARE_DOCS_PAGES_PROJECT || 'bloom-docs' }}
            --branch=main