deploy.yml

name: Build & Deploy

on:
  workflow_dispatch:
    inputs:
      environment:
        description: Target environment
        required: true
        default: dev
        type: choice
        options:
          - dev
          - qa
          - prod

env:
  NODE_VERSION: '22'
  MBT_VERSION: '1.2.31'

jobs:
  validate-mtaext-substitution:
    # [#455 / finish-credstore-migration] Verify no envsubst placeholders
    # remain in any mtaext. After the credstore migration, the three
    # deploy-time secrets (CONTENT_API_KEY, GITHUB_DISPATCH_TOKEN,
    # APPROUTER_URL) no longer live here — the grep-guard catches
    # regressions if anyone tries to reintroduce a ${…} placeholder for
    # a fourth key without also wiring the corresponding envsubst step
    # in the deploy job.
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Verify no unresolved placeholders in any mtaext
        run: |
          set -euo pipefail
          for env in dev qa prod; do
            # The character class also catches hyphenated leftovers (e.g.
            # ${content-api-key}) so a half-finished rename surfaces here too.
            if grep -nE '\$\{[A-Za-z_-]+\}' "deploy/${env}.mtaext"; then
              echo "::error::deploy/${env}.mtaext still contains \${…} placeholders — see docs/superpowers/specs/2026-07-04-finish-credstore-migration-design.md for the removal rationale."
              exit 1
            fi
          done
          echo "All three mtaext files are placeholder-free."

  deploy:
    runs-on: ubuntu-latest
    needs: validate-mtaext-substitution
    timeout-minutes: 30
    permissions:
      contents: write
      packages: read
      pull-requests: write   # gh pr comment from 'Comment HDI tripwire on PR' step (#257 follow-up)
    outputs:
      environment: ${{ steps.env.outputs.target }}

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          fetch-tags: true

      - name: Determine environment
        id: env
        run: echo "target=${{ inputs.environment }}" >> "$GITHUB_OUTPUT"

      - name: Set version
        id: version
        run: |
          set -euo pipefail
          # Exclude env-suffixed tags created by the "Create GitHub Release" step
          # (format: v<version>-dev, v<version>-qa, v<version>-prod). Without
          # these excludes, a previous deploy tag on HEAD would be consumed by
          # --match 'v*' and compound garbage like "v1.0.0-prod-1-gabcdef" into
          # the next version string.
          RAW=$(git describe --tags --match 'v*' --exclude '*-dev' --exclude '*-qa' --exclude '*-prod' --always)
          # Normalize to valid MTA semver: strip a leading 'v<digit>', else
          # fall back to 0.0.0-g<raw> (no v* tag reachable). See
          # docs/superpowers/specs/2026-07-25-mta-versioning-design.md §1.
          if [[ "$RAW" =~ ^v[0-9] ]]; then
            VERSION="${RAW#v}"
          else
            VERSION="0.0.0-g${RAW}"
          fi
          SHORT_SHA=$(git rev-parse --short HEAD)
          # Strict allowlist gate — reject any value with shell metacharacters
          # before it can reach GITHUB_OUTPUT or downstream interpolation.
          if [[ ! "$VERSION" =~ ^[0-9A-Za-z._+-]+$ ]]; then
            echo "::error::Computed VERSION contains disallowed characters: $VERSION"
            exit 1
          fi
          if [[ ! "$SHORT_SHA" =~ ^[0-9A-Za-z._+-]+$ ]]; then
            echo "::error::Computed SHORT_SHA contains disallowed characters: $SHORT_SHA"
            exit 1
          fi
          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
          echo "gitSha=$SHORT_SHA" >> "$GITHUB_OUTPUT"
          echo "Computed MTA version: $VERSION (sha $SHORT_SHA)"
          sed -i "s/^version: .*/version: $VERSION/" mta.yaml

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: npm

      # Cache node_modules across runs. setup-node@v4's `cache: npm` above caches
      # the ~/.npm tarball download cache, but still runs `npm install` (~30-90s
      # including native-binding compile for better-sqlite3, hdb, etc.). This
      # cache skips the install entirely on a hit.
      #
      # Three lockfiles drive the cache key — root, hugo-apps, and display-app —
      # because mta.yaml's before-all runs `npm install` against all three.
      # admin-shell / analytics-explorer / approuter are NOT installed in this
      # workflow (they're in .deploy/mta.yaml's approuter module, used by other
      # build paths — out of scope here).
      #
      # Key includes runner.os + Node version so a runner image swap or Node
      # bump auto-invalidates (native bindings would otherwise be ABI-mismatched).
      # restore-keys fallback catches the case where one lockfile changed and
      # we want most of the cache anyway.
      - name: Cache node_modules
        uses: actions/cache@v4
        with:
          path: |
            node_modules
            hugo-apps/node_modules
            app/display-app/node_modules
          key: node-modules-${{ runner.os }}-node${{ env.NODE_VERSION }}-${{ hashFiles('package-lock.json', 'hugo-apps/package-lock.json', 'app/display-app/package-lock.json') }}
          restore-keys: |
            node-modules-${{ runner.os }}-node${{ env.NODE_VERSION }}-

      - name: Install MTA Build Tool
        run: npm install -g mbt@${{ env.MBT_VERSION }}

      # Cache .tutorial-cache/ across runs so fetch-tutorials does not re-pull
      # ~1400 tutorials from GitHub on every CI run. Without this, mbt's 10-min
      # per-command timeout fires during the QA-channel fetch (the second of
      # two fetches in the build sequence). Mirrors rebuild-content.yml's
      # caching pattern.
      # Cache key is keyed to the fetcher implementation (scripts/fetch-tutorials.ts
      # + scripts/parsers/), NOT to deploy.yml. Workflow file edits don't change
      # what's IN the cache; the fetcher does. Keying on deploy.yml meant every
      # CI tweak today (PR #481-#495 chain) busted the cache and forced ~4 min
      # cold metadata prefetches. The restore-keys cascade still catches drift
      # via the broad 'tutorial-cache-deploy-' prefix.
      - name: Restore tutorial cache
        uses: actions/cache@v4
        with:
          path: .tutorial-cache
          key: tutorial-cache-deploy-${{ hashFiles('scripts/fetch-tutorials.ts', 'scripts/parsers/**') }}-${{ github.run_id }}
          restore-keys: |
            tutorial-cache-deploy-${{ hashFiles('scripts/fetch-tutorials.ts', 'scripts/parsers/**') }}-
            tutorial-cache-deploy-
            tutorial-cache-

      # The QA-channel fetch (npm run fetch-tutorials -- --channel qa) writes
      # to .tutorial-cache-qa/ — a SEPARATE directory from .tutorial-cache/.
      # Both must be warm or mbt's 10-minute before-all timeout fires during
      # the QA fetch (cf run 27882676435: prod cache hit ✓, QA cold-fetch ✗).
      # Mirrors rebuild-content-qa.yml's cache step.
      - name: Restore QA tutorial cache
        uses: actions/cache@v4
        with:
          path: .tutorial-cache-qa
          key: tutorial-cache-qa-deploy-${{ hashFiles('scripts/fetch-tutorials.ts', 'scripts/parsers/**') }}-${{ github.run_id }}
          restore-keys: |
            tutorial-cache-qa-deploy-${{ hashFiles('scripts/fetch-tutorials.ts', 'scripts/parsers/**') }}-
            tutorial-cache-qa-deploy-
            tutorial-cache-qa-

      - name: Set CAP_BASE_URL for build
        id: cap-url
        run: |
          case "${{ steps.env.outputs.target }}" in
            dev)  echo "url=${{ secrets.CAP_SRV_URL_DEV }}" >> "$GITHUB_OUTPUT" ;;
            qa)   echo "url=${{ secrets.CAP_SRV_URL_QA }}" >> "$GITHUB_OUTPUT" ;;
            prod) echo "url=${{ secrets.CAP_SRV_URL_PROD }}" >> "$GITHUB_OUTPUT" ;;
          esac

      # Prefetch tutorials OUTSIDE the mbt before-all phase. mbt enforces a
      # 10-minute timeout for the entire before-all sequence; cold-cache CI
      # runs do TWO ~6-min full fetches (prod + QA) which blow past 10 min.
      # Doing the fetches as separate workflow steps removes them from mbt's
      # cap, AND populates the actions/cache@v4 directories for any future
      # mbt invocation in the same job (mbt's own fetch step then hits a
      # warm cache and finishes in seconds).
      #
      # Both fetches run sequentially since they share the GitHub API rate
      # limit budget; in parallel they'd compete for tokens. Each is gated
      # by `if: failure()` is NOT used — we WANT a hard failure if discovery
      # breaks (otherwise mbt would re-fetch anyway and surface the same
      # error inside the 10-min cap).
      - name: Prefetch prod tutorials (warms .tutorial-cache)
        run: npm install && npm run fetch-tutorials -- --target hugo
        env:
          GITHUB_TOKEN: ${{ secrets.TUTORIALS_GITHUB_TOKEN || github.token }}
          NODE_AUTH_TOKEN: ${{ secrets.PACKAGES_READ_TOKEN || secrets.GITHUB_TOKEN }}
          CAP_BASE_URL: ${{ steps.cap-url.outputs.url }}

      - name: Prefetch QA tutorials (warms .tutorial-cache-qa)
        run: npm run fetch-tutorials -- --target hugo --channel qa
        env:
          GITHUB_TOKEN: ${{ secrets.TUTORIALS_GITHUB_TOKEN || github.token }}
          CAP_BASE_URL: ${{ steps.cap-url.outputs.url }}

      # [#797] Hugo safeHTML XSS-guard. Sweeps hugo/layouts/**/*.{html,xml,xsl}
      # for unmarked `| safeHTML` / `| safeHTMLAttr` / `printf "<...%s"` usages
      # and fails CI if any occurrence lacks a `<!-- security-reviewed: <reason> -->`
      # marker within 3 lines above (guard: scripts/check-hugo-safe-html.cjs).
      # Also transitively invoked via `npm run prebuild` inside `npm run
      # build:all`, but wired here explicitly so the failure attribution
      # is clear and the guard runs even if the pre-Hugo step order changes.
      - name: Check Hugo security annotations
        run: npm run check:security-annotations

      # Run the postbuild static guards before mbt build. These were defined
      # as `postbuild:apps` (lifecycle hook on root `npm run build:apps`), but
      # CI never invokes root `build:apps` — `mbt build` walks straight to
      # `npm --prefix hugo-apps run build` per mta.yaml's before-all, which
      # only fires hugo-apps' own (empty) postbuild. The eight guards were
      # therefore never gating CI deploys — they only ran for contributors
      # who happened to invoke `npm run build:all` locally before pushing.
      # Confirmed via issue #706 investigation.
      #
      # Running them here, BEFORE mbt build, fail-fasts in seconds instead
      # of after the ~10 min MTA build. The guards are read-only static
      # checks (regex sweeps over source); they need npm install (done in
      # the prefetch step above) but no extra credentials.
      - name: Run postbuild guards (icons, build collisions, srv-qa, slug lookups, …)
        run: npm run postbuild:apps

      # Cache the Hugo binary download (~25MB tarball) across runs. mta.yaml's
      # before-all curls hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz from
      # GitHub on every run; that takes 5-10s warm, longer on a slow runner.
      # The cache key is keyed off mta.yaml's hash so a Hugo version bump in
      # mta.yaml line 32 automatically invalidates the cache (no manual sync
      # required between the two files).
      #
      # mta.yaml's before-all now has a `[ -x /tmp/hugo ] || (curl ... && tar ...)`
      # guard, so a cache hit short-circuits the download entirely. Local
      # `mbt build` invocations fall through to the curl path (and re-extract
      # to /tmp/hugo) since no cache restores them — small recurring cost on
      # the dev side, big CI win.
      - name: Cache Hugo binary
        uses: actions/cache@v4
        with:
          path: /tmp/hugo
          key: hugo-binary-${{ hashFiles('mta.yaml') }}-linux-amd64
          restore-keys: |
            hugo-binary-

      - name: Write srv/version.json
        env:
          VERSION: ${{ steps.version.outputs.version }}
          GITSHA: ${{ steps.version.outputs.gitSha }}
        run: |
          set -euo pipefail
          jq -n --arg v "$VERSION" --arg s "$GITSHA" --arg t "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
            '{version:$v, gitSha:$s, builtAt:$t}' > srv/version.json
          echo "Wrote srv/version.json:"; cat srv/version.json

      - name: Build MTA archive
        run: mbt build -e deploy/${{ steps.env.outputs.target }}.mtaext
        env:
          GITHUB_TOKEN: ${{ secrets.TUTORIALS_GITHUB_TOKEN || github.token }}
          # Required by scripts/parsers/cap.ts during fetch-tutorials Phase 4
          # (mission/group catalog fetch from the deployed srv). Without it,
          # the build defaults to http://localhost:4004 and fails with
          # "TypeError: fetch failed" since no local CAP runs in CI. The
          # build is target-aware so qa fetches its own QA-channel catalog.
          CAP_BASE_URL: ${{ steps.cap-url.outputs.url }}
          # APPROUTER_URL for asset-hash-retention (Task 5): allows mta.yaml's
          # before-all retention step to fetch the currently-deployed approuter's
          # _retained-assets.json and carry hashed bundles forward. Maps per-env
          # secrets: prod→APPROUTER_URL_PROD, qa→APPROUTER_URL_QA, else→APPROUTER_URL_DEV.
          APPROUTER_URL: ${{ steps.env.outputs.target == 'prod' && secrets.APPROUTER_URL_PROD || (steps.env.outputs.target == 'qa' && secrets.APPROUTER_URL_QA || secrets.APPROUTER_URL_DEV) }}

      - name: Upload MTAR artifact
        uses: actions/upload-artifact@v4
        with:
          name: mtar-${{ steps.env.outputs.target }}-${{ github.run_number }}
          path: mta_archives/*.mtar
          retention-days: 30

      - name: Set CF space
        id: cf
        run: |
          case "${{ steps.env.outputs.target }}" in
            dev)  echo "space=${{ secrets.CF_SPACE_DEV }}" >> "$GITHUB_OUTPUT" ;;
            qa)   echo "space=${{ secrets.CF_SPACE_QA }}" >> "$GITHUB_OUTPUT" ;;
            prod) echo "space=${{ secrets.CF_SPACE_PROD }}" >> "$GITHUB_OUTPUT" ;;
          esac

      - name: Install CF CLI
        run: |
          curl -L "https://packages.cloudfoundry.org/stable?release=linux64-binary&version=v8&source=github" | tar xz
          sudo mv cf8 /usr/local/bin/cf

      - name: Install CF MTA plugin
        run: cf install-plugin multiapps -f

      - name: CF Login preflight (diagnose missing/malformed secrets)
        # Prints structural info (lengths, presence, scheme of the api endpoint)
        # for each CF_* secret WITHOUT echoing any value. GH Actions masks the
        # full secret string, but bypassing the mask is easy with substrings or
        # encodings, so this step deliberately uses only mask-safe operations:
        #   - "${#VAR}" (length only)
        #   - "[ -z ... ]" (empty boolean)
        #   - "[ -n ... ]" (present boolean)
        #   - scheme prefix of URL secrets via "${URL%%://*}" (only emits 'https' / 'http' / '')
        #
        # Step output makes it obvious which secret is empty or mis-shaped, so
        # you can fix it in repo settings without trial-and-error rerunning
        # the workflow.
        env:
          CF_API_ENDPOINT: ${{ secrets.CF_API_ENDPOINT }}
          CF_USERNAME: ${{ secrets.CF_USERNAME }}
          CF_PASSWORD: ${{ secrets.CF_PASSWORD }}
          CF_ORG: ${{ secrets.CF_ORG }}
        run: |
          set +e   # don't abort on the conditional emits
          echo "::group::CF_* secret structural check (no values printed)"

          # 1. presence + length
          for name in CF_API_ENDPOINT CF_USERNAME CF_PASSWORD CF_ORG; do
            val="${!name}"
            if [ -z "$val" ]; then
              echo "::warning::$name is EMPTY (length 0) — secret missing or unset"
            else
              echo "$name: present, length=${#val}"
            fi
          done

          # 2. api endpoint URL scheme check (must be https://, not http:// or
          #    a bare host). cf login -a expects a full URL.
          if [ -n "$CF_API_ENDPOINT" ]; then
            scheme="${CF_API_ENDPOINT%%://*}"
            if [ "$scheme" = "$CF_API_ENDPOINT" ]; then
              echo "::warning::CF_API_ENDPOINT has NO scheme (no '://' separator) — cf login expects 'https://api.cf.<region>.hana.ondemand.com'"
            elif [ "$scheme" != "https" ]; then
              echo "::warning::CF_API_ENDPOINT scheme is '$scheme', expected 'https'"
            else
              echo "CF_API_ENDPOINT scheme: https (OK)"
            fi
          fi

          # 3. trailing whitespace / newlines (a common copy-paste failure mode)
          for name in CF_API_ENDPOINT CF_USERNAME CF_ORG; do
            val="${!name}"
            if [ -n "$val" ]; then
              trimmed="$(printf '%s' "$val" | tr -d '[:space:]')"
              if [ "$val" != "$trimmed" ]; then
                echo "::warning::$name has trailing/leading whitespace — re-set the secret with no surrounding whitespace"
              fi
            fi
          done
          # (CF_PASSWORD intentionally NOT checked for whitespace — passwords
          # legitimately may contain spaces. If a password has accidental
          # whitespace, the error will surface as 'Credentials were rejected'
          # which is unmistakable.)

          # 4. CF_USERNAME shape: should look like an email (contains '@')
          if [ -n "$CF_USERNAME" ] && [ "${CF_USERNAME#*@}" = "$CF_USERNAME" ]; then
            echo "::notice::CF_USERNAME does not contain '@' — usually CF auth uses email addresses, but S-user IDs without '@' are valid in some BTP setups"
          fi

          echo "::endgroup::"

      - name: CF Login
        run: |
          cf login \
            -a "${{ secrets.CF_API_ENDPOINT }}" \
            -u "${{ secrets.CF_USERNAME }}" \
            -p "${{ secrets.CF_PASSWORD }}" \
            -o "${{ secrets.CF_ORG }}" \
            -s "${{ steps.cf.outputs.space }}"

      # Note: 'npm ci --ignore-scripts' previously ran here to install hdb
      # for check-hana-rowcounts.cjs. After PR #492 the prefetch step at the
      # top of this job runs 'npm install' which already installs hdb (and
      # everything else); node_modules persists across steps in a single-job
      # workflow. The redundant 'npm ci' added ~30-60s per run. If we ever
      # split into multi-job (research item #1), each job needs its own
      # node_modules — reintroduce here or use actions/cache for node_modules.
      - name: HDI pre-deploy row-count snapshot
        # Captures all COM_SAP_DEVELOPERS_IMS_* row counts BEFORE the deploy.
        # Uploaded as artifact so the post-deploy step can diff against it.
        # See docs/developers/operations/hdi-deploy-checklist.md for context.
        run: |
          mkdir -p .hana-snapshots
          node scripts/check-hana-rowcounts.cjs --snapshot .hana-snapshots/pre-deploy.json

      - name: Upload pre-deploy snapshot artifact
        uses: actions/upload-artifact@v4
        with:
          name: hana-snapshot-${{ steps.env.outputs.target }}-${{ github.run_number }}
          path: .hana-snapshots/pre-deploy.json
          retention-days: 90

      - name: Verify no unresolved placeholders (target env)
        # [finish-credstore-migration] After stripping the three deploy-time
        # secrets from the mtaext files, cf deploy consumes them verbatim.
        # This guard mirrors validate-mtaext-substitution but scoped to the
        # target env for a clearer error in the deploy job's logs if someone
        # reintroduces a ${…} placeholder.
        run: |
          set -euo pipefail
          IN=deploy/${{ steps.env.outputs.target }}.mtaext
          if grep -nE '\$\{[A-Za-z_-]+\}' "$IN"; then
            echo "::error::$IN contains \${…} placeholders — see docs/superpowers/specs/2026-07-04-finish-credstore-migration-design.md before adding new deploy-time envsubst plumbing."
            exit 1
          fi

      - name: Deploy MTA
        env:
          VERSION: ${{ steps.version.outputs.version }}
        run: |
          # --version-rule ALL: the version comes from `git describe`, so any
          # deploy from a commit AHEAD of the last release tag produces a
          # semver *prerelease* (e.g. 1.0.0-4-g7fbca2aa). Semver ranks a
          # prerelease BELOW its base release (1.0.0-4-… < 1.0.0), and the MTA
          # deployer's default version-rule (HIGHER) then rejects it as a
          # downgrade once a clean tagged version has ever been deployed. The
          # safety in this scheme is the embedded git SHA (full traceability),
          # not monotonic semver ordering, so we allow all versions. Applies to
          # every environment — prod deploys from ahead-of-tag HEAD hit the
          # identical block otherwise; prod keeps its blue-green safety below.
          STRATEGY_FLAGS="--version-rule ALL"
          if [ "${{ steps.env.outputs.target }}" = "prod" ]; then
            STRATEGY_FLAGS="$STRATEGY_FLAGS --strategy blue-green --skip-testing-phase"
          fi

          cf deploy "mta_archives/tutorials-ims_${VERSION}.mtar" \
            -e deploy/${{ steps.env.outputs.target }}.mtaext \
            $STRATEGY_FLAGS \
            -f

      - name: Record deployed version in DEPLOYED.md
        if: success()
        env:
          VERSION: ${{ steps.version.outputs.version }}
          GITSHA: ${{ steps.version.outputs.gitSha }}
        run: |
          set -euo pipefail
          ENV="${{ steps.env.outputs.target }}"
          VER="$VERSION"
          SHA="$GITSHA"
          TS="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
          RUN="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
          ROW="| $ENV | \`$VER\` | \`$SHA\` | $TS | [run]($RUN) |"
          # Replace the single row whose first cell is this environment.
          # Anchored on '| <env> |' at line start so we touch exactly one row.
          sed -i -E "s%^\| ${ENV} \|.*\$%${ROW}%" DEPLOYED.md
          echo "Updated DEPLOYED.md row for $ENV:"
          grep -E "^\| ${ENV} \|" DEPLOYED.md
          git config user.name  "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git fetch origin main
          git checkout main
          git stash push -- DEPLOYED.md || true
          git pull --ff-only origin main
          git stash pop || true
          git add DEPLOYED.md
          if git diff --cached --quiet; then
            echo "No DEPLOYED.md change to commit."
          else
            git commit -m "chore(deploy): $ENV now at $VER ($SHA) [skip ci]"
            git push origin main || echo "::warning::Could not push DEPLOYED.md update to main (branch protection or concurrent push); deploy itself succeeded."
          fi

      - name: Abort blue-green on failure
        if: failure() && steps.env.outputs.target == 'prod'
        run: |
          # During the tutorials-poc → tutorials-ims rename cutover window the
          # old `tutorials-poc` MTA registration may still co-exist briefly —
          # grep either name so blue-green abort works regardless of which
          # registration the failed operation belongs to. Remove the `-poc`
          # branch once `cf purge-mta tutorials-poc` is done.
          OP_ID=$(cf mta-ops | grep -E "tutorials-(ims|poc)" | grep -i "error\|abort" | head -1 | awk '{print $1}')
          if [ -n "$OP_ID" ]; then
            echo "Aborting failed blue-green operation: $OP_ID"
            cf deploy -i "$OP_ID" -a abort || true
          fi

      - name: Capture deployer log post-deploy
        # cf logs --recent is a ring buffer; capture immediately so the
        # scrape step (and any future forensic work) has a stable copy.
        # See docs/developers/operations/hdi-deploy-checklist.md.
        if: always()
        run: |
          mkdir -p .hana-snapshots
          cf logs tutorials-db-deployer --recent > .hana-snapshots/db-deployer-post.log 2>&1 || true

      - name: Upload deployer log artifact
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: db-deployer-log-${{ steps.env.outputs.target }}-${{ github.run_number }}
          path: .hana-snapshots/db-deployer-post.log
          retention-days: 90
          if-no-files-found: warn

      - name: Scrape deployer log for danger patterns
        id: hdi-scrape
        # Catches Rolled back / TABLE_REPLACE / DROP TABLE / non-empty
        # 'Files to undeploy' — the patterns that triggered the
        # 2026-06-05 data-loss incident (issue #257). Exits 2 on critical
        # findings; we report them as a warning so we don't block the
        # deploy on a legitimate planned rollback or schema migration,
        # but the failures are visible in the workflow summary AND
        # surface as a comment on the merge PR via the 'Comment HDI
        # tripwire' step below.
        if: success()
        continue-on-error: true
        run: |
          mkdir -p .hana-snapshots
          if node scripts/scrape-deployer-log.cjs --file .hana-snapshots/db-deployer-post.log --json > .hana-snapshots/scrape-result.json; then
            echo "::notice title=HDI scrape::Deployer log clean — no danger patterns"
            echo "tripwire=false" >> "$GITHUB_OUTPUT"
          else
            echo "::warning title=HDI scrape::Deployer log shows critical patterns — review"
            echo "tripwire=true" >> "$GITHUB_OUTPUT"
            echo "" >> "$GITHUB_STEP_SUMMARY"
            echo "### ⚠️ HDI deployer log scrape found critical patterns" >> "$GITHUB_STEP_SUMMARY"
            echo "" >> "$GITHUB_STEP_SUMMARY"
            echo "Review the deployer log artifact for this run. Patterns like \`Rolled back\`, \`TABLE_REPLACE\`, or \`DROP TABLE\` triggered the 2026-06-05 data-loss incident." >> "$GITHUB_STEP_SUMMARY"
            echo "Run \`npm run hana:scrape-deployer-log -- --file <log>\` locally for full output." >> "$GITHUB_STEP_SUMMARY"
          fi

      - name: HDI post-deploy row-count diff
        id: hdi-diff
        # Compares post-deploy table row counts against the pre-deploy
        # snapshot from earlier in this job. Exits 2 if any table dropped
        # >5% of its rows; reports as a warning rather than blocking the
        # deploy (some deploys legitimately delete data, e.g. cleanup
        # migrations). Failures are visible in the workflow summary AND
        # surface as a comment on the merge PR via the 'Comment HDI
        # tripwire' step below.
        if: success()
        continue-on-error: true
        run: |
          mkdir -p .hana-snapshots
          if node scripts/check-hana-rowcounts.cjs --diff .hana-snapshots/pre-deploy.json --json > .hana-snapshots/diff-result.json; then
            echo "::notice title=HDI rowcount diff::All tables within threshold"
            echo "tripwire=false" >> "$GITHUB_OUTPUT"
          else
            echo "::warning title=HDI rowcount diff::Table row counts dropped beyond threshold"
            echo "tripwire=true" >> "$GITHUB_OUTPUT"
            echo "" >> "$GITHUB_STEP_SUMMARY"
            echo "### ⚠️ HDI row-count diff fired tripwire" >> "$GITHUB_STEP_SUMMARY"
            echo "" >> "$GITHUB_STEP_SUMMARY"
            echo "Some tables lost >5% of their rows during this deploy. If unexpected, review the deployer log artifact (\`db-deployer-log-${{ steps.env.outputs.target }}-${{ github.run_number }}\`) and the pre-deploy snapshot artifact (\`hana-snapshot-${{ steps.env.outputs.target }}-${{ github.run_number }}\`)." >> "$GITHUB_STEP_SUMMARY"
            echo "" >> "$GITHUB_STEP_SUMMARY"
            echo "If this is a known cleanup migration, no action needed. Otherwise, see [the recovery cookbook](../blob/main/docs/developers/operations/hdi-deploy-checklist.md)." >> "$GITHUB_STEP_SUMMARY"
          fi

      - name: HDI post-deploy orphan-view audit
        id: hdi-orphan-views
        # Compares gen/db/src/gen/*.hdbview against HANA SYS.VIEWS to find
        # views still in HANA that no longer have a corresponding build
        # artifact. Orphans rot silently — they only break a deploy when
        # the underlying column changes (see PR #519, 2026-06-21 where a
        # forgotten @analytics.exposed left ANALYTICSSERVICE_TUTORIALREPOSITORIES
        # in HANA, then PR #517's column drop made it undeployable). Exits
        # 1 on orphans found; we report as a warning rather than fail the
        # deploy because (a) a freshly-removed annotation that hasn't yet
        # gotten its undeploy.json entry is not strictly broken until the
        # next column change, and (b) the orphan list itself is the
        # actionable signal — reviewers can add the path to undeploy.json
        # in a follow-up.
        if: success()
        continue-on-error: true
        run: |
          mkdir -p .hana-snapshots
          if node scripts/check-orphan-views.cjs \
               --service-instance=tutorials-hana \
               --json > .hana-snapshots/orphan-views.json; then
            echo "::notice title=HDI orphan-view audit::No orphans — gen/ and HANA in sync"
            echo "tripwire=false" >> "$GITHUB_OUTPUT"
          else
            echo "::warning title=HDI orphan-view audit::Orphan view(s) found in HANA"
            echo "tripwire=true" >> "$GITHUB_OUTPUT"
            echo "" >> "$GITHUB_STEP_SUMMARY"
            echo "### ⚠️ HDI orphan-view audit fired tripwire" >> "$GITHUB_STEP_SUMMARY"
            echo "" >> "$GITHUB_STEP_SUMMARY"
            echo "Views exist in HANA that are no longer in \`gen/db/src/gen/\`. Most likely cause: an \`@analytics.exposed\` (or similar) annotation was removed from a CDS entity, leaving the previously-generated view stranded in HANA." >> "$GITHUB_STEP_SUMMARY"
            echo "" >> "$GITHUB_STEP_SUMMARY"
            echo "**Orphans found:**" >> "$GITHUB_STEP_SUMMARY"
            jq -r '.orphans[]?' .hana-snapshots/orphan-views.json | sed 's/^/- /' >> "$GITHUB_STEP_SUMMARY" || true
            echo "" >> "$GITHUB_STEP_SUMMARY"
            echo "**Fix:** add the corresponding \`src/gen/<Service>.<Entity>.hdbview\` path to \`db/undeploy.json\` and redeploy. The orphan view will be dropped on next deploy. Reference: PR #519." >> "$GITHUB_STEP_SUMMARY"
          fi

      - name: Upload orphan-view audit artifact
        if: success() || failure()
        uses: actions/upload-artifact@v4
        with:
          name: orphan-views-${{ steps.env.outputs.target }}-${{ github.run_number }}
          path: .hana-snapshots/orphan-views.json
          retention-days: 30
          if-no-files-found: ignore

      - name: Comment HDI tripwire on PR
        # If either HDI guard fired (scrape OR diff), surface it as a
        # comment on the PR that introduced the merged commit. Reviewers
        # see the comment in their PR notification stream even if they
        # never look at the workflow summary.
        #
        # Uses gh CLI (already installed for `gh release create` below)
        # to look up the PR by merge commit SHA. Fails closed: if no PR
        # is found (e.g., direct push to main, force push), the step
        # is a no-op rather than a hard error.
        #
        # Filed as #257 prevention follow-up.
        if: |
          always() &&
          (steps.hdi-scrape.outputs.tripwire == 'true' || steps.hdi-diff.outputs.tripwire == 'true' || steps.hdi-orphan-views.outputs.tripwire == 'true')
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          # Look up the PR that contained this commit. gh pr list returns
          # JSON; jq extracts the PR number. Empty result = no PR -> no-op.
          PR_NUMBER=$(gh pr list --search "${{ github.sha }}" --state merged --json number --jq '.[0].number // empty')
          if [ -z "$PR_NUMBER" ]; then
            echo "::notice title=HDI tripwire::No PR found for commit ${{ github.sha }} — skipping comment"
            exit 0
          fi
          echo "::notice title=HDI tripwire::Posting comment to PR #$PR_NUMBER"

          # Build the comment body. Compose findings into one Markdown blob.
          {
            echo "## ⚠️ HDI deploy tripwire fired (${{ steps.env.outputs.target }})"
            echo ""
            echo "The post-deploy HDI guards detected one or more critical patterns during the v${{ steps.version.outputs.version }} deploy of this PR. **Review before further deploys.**"
            echo ""
            echo "**Workflow run:** [${{ github.workflow }} #${{ github.run_number }}](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})"
            echo ""
            if [ "${{ steps.hdi-scrape.outputs.tripwire }}" = "true" ]; then
              echo "### Deployer log scrape — CRITICAL pattern(s) detected"
              echo ""
              echo "Patterns matched: \`Rolled back\` / \`TABLE_REPLACE\` / \`DROP TABLE\` / non-empty \`Files to undeploy\`. These are the patterns that triggered the [2026-06-05 data-loss incident](${{ github.server_url }}/${{ github.repository }}/issues/257)."
              echo ""
              echo "**Findings:**"
              echo ""
              echo '```json'
              jq '.findings // []' .hana-snapshots/scrape-result.json 2>/dev/null || echo '(no JSON output captured)'
              echo '```'
              echo ""
            fi
            if [ "${{ steps.hdi-diff.outputs.tripwire }}" = "true" ]; then
              echo "### Row-count diff — table(s) lost rows beyond 5% threshold"
              echo ""
              echo "**Failures:**"
              echo ""
              echo '```json'
              jq '.failures // []' .hana-snapshots/diff-result.json 2>/dev/null || echo '(no JSON output captured)'
              echo '```'
              echo ""
            fi
            if [ "${{ steps.hdi-orphan-views.outputs.tripwire }}" = "true" ]; then
              echo "### Orphan-view audit — view(s) in HANA but not in build artifacts"
              echo ""
              echo "These views were generated by a prior build (likely via \`@analytics.exposed\` or similar) but the annotation has since been removed. They survive in HANA and become deploy-blocking the next time their underlying columns change — exactly the failure mode from PR #519 (2026-06-21)."
              echo ""
              echo "**Orphans:**"
              echo ""
              echo '```json'
              jq '.orphans // []' .hana-snapshots/orphan-views.json 2>/dev/null || echo '(no JSON output captured)'
              echo '```'
              echo ""
              echo "**Fix:** add the corresponding \`src/gen/<Service>.<Entity>.hdbview\` path(s) to \`db/undeploy.json\` and redeploy. After one successful pass the entry becomes a no-op. See \`hdi_orphan_views_from_removed_annotations.md\` memory."
              echo ""
            fi
            echo "### Next steps"
            echo ""
            echo "- If this is a known cleanup migration, document it in the PR description and dismiss this comment."
            echo "- Otherwise, follow the [HDI deploy checklist recovery cookbook](${{ github.server_url }}/${{ github.repository }}/blob/main/docs/developers/operations/hdi-deploy-checklist.md)."
            echo "- Review artifacts: \`db-deployer-log-${{ steps.env.outputs.target }}-${{ github.run_number }}\`, \`hana-snapshot-${{ steps.env.outputs.target }}-${{ github.run_number }}\`."
            echo ""
            echo "---"
            echo "<sub>Auto-generated by \`deploy.yml\` HDI tripwire (#258 / #259 prevention scripts; this step shipped via #257 follow-up).</sub>"
          } > .hana-snapshots/pr-comment.md

          gh pr comment "$PR_NUMBER" --body-file .hana-snapshots/pr-comment.md
          echo "Posted comment to PR #$PR_NUMBER"

      - name: Post-deploy credstore smoke — /content/publish/begin
        # #1018 — proves the freshly-deployed tutorials-srv can actually
        # RESOLVE its credstore-fronted secrets. The rebuild-content
        # workflow was our previous canary for this; on 2026-07-06 it took
        # ~an hour after cf deploy to fire and reveal that CONTENT_API_KEY
        # was silently missing from credstore (envsubst fallback stripped
        # by PR #980, credstore write during 2026-06-23 mTLS/JWE transition
        # had never landed). This step shifts detection to seconds after
        # deploy.
        #
        # Expected outcomes:
        #   400 — server accepted the Bearer, rejected the empty payload.
        #         Credstore is resolvable; guard passes.
        #   401 — Bearer missing / malformed (shouldn't happen given we
        #         send one). Fails.
        #   403 — Bearer present but doesn't match server's resolved value.
        #         Means CI's CONTENT_API_KEY GH secret has drifted from
        #         what the credstore holds. Fails.
        #   503 — server's resolveSecret('CONTENT_API_KEY') returned null.
        #         This is exactly the 2026-07-06 failure. Fails.
        #   any other — network / cold start / DNS. Fails, retry the
        #         deploy or investigate. Retries once after 30 s before
        #         failing to absorb slow cold starts (fresh MTA-deployed
        #         apps take ~15-45 s to answer traffic).
        #
        # QA is not smoked here — QA has its own CONTENT_API_KEY_QA and
        # the rebuild-content-qa workflow is the canary for that surface.
        env:
          CONTENT_API_KEY: ${{ secrets.CONTENT_API_KEY }}
        run: |
          set -euo pipefail
          case "${{ steps.env.outputs.target }}" in
            dev)  SRV_URL="${{ vars.SRV_URL_DEV }}" ;;
            qa)   echo "::notice::skipping publish-endpoint smoke on QA (uses CONTENT_API_KEY_QA — separate canary via rebuild-content-qa.yml)"; exit 0 ;;
            prod) SRV_URL="${{ vars.SRV_URL_PROD }}" ;;
            *)    echo "::error::unknown target ${{ steps.env.outputs.target }}"; exit 1 ;;
          esac
          if [ -z "$SRV_URL" ]; then
            echo "::error::SRV_URL not set for target ${{ steps.env.outputs.target }} — cannot smoke publish endpoint"
            exit 1
          fi
          if [ -z "${CONTENT_API_KEY:-}" ]; then
            echo "::error::CONTENT_API_KEY GH secret is empty — smoke would false-positive as 403"
            exit 1
          fi

          probe() {
            curl -sS -o /tmp/publish-begin.body -w '%{http_code}' \
              --max-time 20 \
              -X POST \
              -H "Authorization: Bearer $CONTENT_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{}' \
              "$SRV_URL/content/publish/begin" || echo "000"
          }

          STATUS=$(probe)
          echo "First probe: HTTP $STATUS"
          if [ "$STATUS" = "000" ] || [ "$STATUS" = "502" ] || [ "$STATUS" = "504" ]; then
            echo "Cold-start retry in 30 s…"
            sleep 30
            STATUS=$(probe)
            echo "Second probe: HTTP $STATUS"
          fi

          BODY=$(head -c 500 /tmp/publish-begin.body 2>/dev/null || true)

          case "$STATUS" in
            400)
              echo "::notice title=Credstore smoke::PASS — publish endpoint accepted the bearer and rejected empty payload (400 as expected)"
              ;;
            401|403)
              echo "::error title=Credstore smoke::FAIL — CI CONTENT_API_KEY does not match server's resolved value (HTTP $STATUS). CI GH secret has drifted from credstore. Rotate at /admin-ui/#secrets and update the GH secret to match."
              echo "Response body (first 500 chars): $BODY"
              exit 1
              ;;
            503)
              echo "::error title=Credstore smoke::FAIL — server returned 503 'Content API not configured'. resolveSecret('CONTENT_API_KEY') returned null → credstore has no value for this alias. Set it via /admin-ui/#secrets on ${SRV_URL}. This is the 2026-07-06 (#1018) failure mode."
              echo "Response body (first 500 chars): $BODY"
              exit 1
              ;;
            *)
              echo "::error title=Credstore smoke::FAIL — unexpected HTTP $STATUS from $SRV_URL/content/publish/begin"
              echo "Response body (first 500 chars): $BODY"
              exit 1
              ;;
          esac

      - name: Create GitHub Release
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          TAG="v${{ steps.version.outputs.version }}-${{ steps.env.outputs.target }}"
          MTAR_FILE="mta_archives/tutorials-ims_${{ steps.version.outputs.version }}.mtar"

          gh release create "$TAG" "$MTAR_FILE" \
            --title "v${{ steps.version.outputs.version }} (${{ steps.env.outputs.target }})" \
            --notes "Deployed to **${{ steps.env.outputs.target }}** from commit ${{ github.sha }}" \
            --target "${{ github.sha }}"

      - name: Summary
        run: |
          echo "### Build & Deploy Complete" >> "$GITHUB_STEP_SUMMARY"
          echo "" >> "$GITHUB_STEP_SUMMARY"
          echo "- **Version:** ${{ steps.version.outputs.version }}" >> "$GITHUB_STEP_SUMMARY"
          echo "- **Environment:** ${{ steps.env.outputs.target }}" >> "$GITHUB_STEP_SUMMARY"
          echo "- **Space:** ${{ steps.cf.outputs.space }}" >> "$GITHUB_STEP_SUMMARY"
          echo "- **Release:** v${{ steps.version.outputs.version }}-${{ steps.env.outputs.target }}" >> "$GITHUB_STEP_SUMMARY"

  smoke-test:
    needs: deploy
    runs-on: ubuntu-latest
    timeout-minutes: 5
    permissions:
      contents: read
      packages: read
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: npm

      - name: Install dependencies
        run: npm ci
        env:
          NODE_AUTH_TOKEN: ${{ secrets.PACKAGES_READ_TOKEN || secrets.GITHUB_TOKEN }}

      - name: Wait for app stabilization
        run: sleep 30

      - name: Resolve environment URLs
        id: urls
        run: |
          case "${{ needs.deploy.outputs.environment }}" in
            dev)  echo "base_url=${{ vars.APPROUTER_URL_DEV }}" >> "$GITHUB_OUTPUT"
                  echo "srv_url=${{ vars.SRV_URL_DEV }}" >> "$GITHUB_OUTPUT" ;;
            qa)   echo "base_url=${{ vars.APPROUTER_URL_QA }}" >> "$GITHUB_OUTPUT"
                  echo "srv_url=${{ vars.SRV_URL_QA }}" >> "$GITHUB_OUTPUT" ;;
            prod) echo "base_url=${{ vars.APPROUTER_URL_PROD }}" >> "$GITHUB_OUTPUT"
                  echo "srv_url=${{ vars.SRV_URL_PROD }}" >> "$GITHUB_OUTPUT" ;;
          esac

      - name: Run smoke tests
        run: npm run test:smoke
        env:
          SMOKE_BASE_URL: ${{ steps.urls.outputs.base_url }}
          SMOKE_SRV_URL: ${{ steps.urls.outputs.srv_url }}
          SMOKE_TECH_USER: ${{ secrets.SMOKE_TECH_USER }}
          SMOKE_TECH_PASSWORD: ${{ secrets.SMOKE_TECH_PASSWORD }}
          # QA channel smoke vars: qa-routes.test.ts self-skips when absent.
          # Wired here so QA suite runs alongside prod smoke in the same vitest
          # invocation. Repo-level vars/secrets must be set as part of QA bootstrap.
          SMOKE_QA_BASE_URL: ${{ vars.APPROUTER_URL_QA }}
          SMOKE_QA_SRV_URL: ${{ vars.SRV_URL_QA }}
          SMOKE_QA_TOKEN: ${{ secrets.SMOKE_QA_TOKEN }}

      - name: Guard — HANA content assets resolve on deployed approuter (advisory, #1678)
        # Defense-in-depth mirror of deploy-mta.cjs Step 4.5. CI prod deploys with
        # --skip-testing-phase (blue-green auto-swaps, no pause), so there is no
        # pre-swap window here — instead we probe the LIVE (now-green) approuter
        # POST-deploy: fetch a sample of HANA-served tutorial + concept pages and
        # confirm their css AND hashed-js assets resolve on that same approuter.
        # This catches the 2026-08-12 CSS-404 incident class (a fingerprint deploy
        # dropping a hash that already-published HANA content still references) if
        # asset-retention (PR #1677) ever regresses. Non-gating by design (mirrors
        # the e2e job): continue-on-error means a MISSING is a visible ⚠️ in the
        # summary but never rolls back the deploy. The guard's own inconclusive
        # guard fail-opens on a gated/unreachable channel, so it won't false-red.
        if: always()
        continue-on-error: true
        run: |
          echo "### HANA content asset guard (#1678)" >> "$GITHUB_STEP_SUMMARY"
          BASE="${{ steps.urls.outputs.base_url }}"
          if [ -z "$BASE" ]; then
            echo "- ⏭️ skipped: no approuter URL resolved for ${{ needs.deploy.outputs.environment }}" >> "$GITHUB_STEP_SUMMARY"
            exit 0
          fi
          if node scripts/check-approuter-assets.cjs --served-base "$BASE"; then
            echo "- ✅ sampled tutorial/concept pages' css+js assets all resolve on $BASE" >> "$GITHUB_STEP_SUMMARY"
          else
            echo "- ⚠️ some HANA-served assets do NOT resolve on $BASE — see step log (non-blocking; check PR #1677 retention)" >> "$GITHUB_STEP_SUMMARY"
          fi

      - name: Smoke test summary
        if: always()
        run: |
          echo "### Smoke Test Results" >> "$GITHUB_STEP_SUMMARY"
          echo "" >> "$GITHUB_STEP_SUMMARY"
          echo "- **Target:** ${{ needs.deploy.outputs.environment }}" >> "$GITHUB_STEP_SUMMARY"
          echo "- **URL:** ${{ steps.urls.outputs.base_url }}" >> "$GITHUB_STEP_SUMMARY"

  e2e:
    # Playwright admin-UI smoke tier (#1338). Non-gating: a failure is visible
    # in the workflow summary but does NOT roll back the deploy or block a11y.
    # Runs after smoke-test so the environment has stabilised.
    needs: [deploy, smoke-test]
    if: always() && needs.deploy.result == 'success'
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read
      packages: read
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: npm

      - name: Install dependencies
        run: npm ci
        env:
          NODE_AUTH_TOKEN: ${{ secrets.PACKAGES_READ_TOKEN || secrets.GITHUB_TOKEN }}

      - name: Install Chromium for playwright-core
        # playwright-core ships without browsers; install the same headless shell
        # the a11y-scan job uses. `--with-deps` installs OS-level libs (libnss etc.)
        # needed by the headless shell on ubuntu-latest.
        run: npx playwright install --with-deps chromium

      - name: Resolve environment URLs
        id: urls
        run: |
          case "${{ needs.deploy.outputs.environment }}" in
            dev)  echo "base_url=${{ vars.APPROUTER_URL_DEV }}" >> "$GITHUB_OUTPUT"
                  echo "srv_url=${{ vars.SRV_URL_DEV }}" >> "$GITHUB_OUTPUT" ;;
            qa)   echo "base_url=${{ vars.APPROUTER_URL_QA }}" >> "$GITHUB_OUTPUT"
                  echo "srv_url=${{ vars.SRV_URL_QA }}" >> "$GITHUB_OUTPUT" ;;
            prod) echo "base_url=${{ vars.APPROUTER_URL_PROD }}" >> "$GITHUB_OUTPUT"
                  echo "srv_url=${{ vars.SRV_URL_PROD }}" >> "$GITHUB_OUTPUT" ;;
          esac

      - name: Run e2e tests
        continue-on-error: true
        run: npm run test:e2e
        env:
          PLAYWRIGHT_BASE_URL: ${{ steps.urls.outputs.base_url }}
          SMOKE_BASE_URL: ${{ steps.urls.outputs.base_url }}
          SMOKE_SRV_URL: ${{ steps.urls.outputs.srv_url }}
          SMOKE_TECH_USER: ${{ secrets.SMOKE_TECH_USER }}
          SMOKE_TECH_PASSWORD: ${{ secrets.SMOKE_TECH_PASSWORD }}
          CI: 'true'

      - name: Upload Playwright artefacts on failure
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: e2e-artefacts-${{ needs.deploy.outputs.environment }}
          path: |
            test-results/
            playwright-report/
          retention-days: 7
          if-no-files-found: ignore

      - name: e2e summary
        if: always()
        run: |
          {
            echo "### e2e Results"
            echo ""
            echo "- **Target:** ${{ needs.deploy.outputs.environment }}"
            echo "- **URL:** ${{ steps.urls.outputs.base_url }}"
          } >> "$GITHUB_STEP_SUMMARY"

  a11y-scan:
    needs: [deploy, smoke-test]
    if: always() && needs.deploy.result == 'success'
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
      packages: read
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: npm

      - name: Install dependencies
        run: npm ci
        env:
          NODE_AUTH_TOKEN: ${{ secrets.PACKAGES_READ_TOKEN || secrets.GITHUB_TOKEN }}

      - name: Install Chromium for Playwright
        run: npx playwright install --with-deps chromium

      - name: Resolve environment URLs
        id: urls
        run: |
          case "${{ needs.deploy.outputs.environment }}" in
            dev)  echo "base_url=${{ vars.APPROUTER_URL_DEV }}" >> "$GITHUB_OUTPUT" ;;
            qa)   echo "base_url=${{ vars.APPROUTER_URL_QA }}" >> "$GITHUB_OUTPUT" ;;
            prod) echo "base_url=${{ vars.APPROUTER_URL_PROD }}" >> "$GITHUB_OUTPUT" ;;
          esac

      - name: Run axe-core scan (warn-only)
        run: npm run test:a11y
        env:
          SMOKE_BASE_URL: ${{ steps.urls.outputs.base_url }}

      - name: Build Lighthouse URL list
        id: lhci-urls
        run: |
          URL_FLAGS=$(node --input-type=module -e "
            import { resolveUrls } from './test/a11y/urls.js';
            console.log(resolveUrls(process.env.BASE).map(u => '--collect.url=' + u.url).join(' '));
          ")
          echo "flags=$URL_FLAGS" >> "$GITHUB_OUTPUT"
        env:
          BASE: ${{ steps.urls.outputs.base_url }}

      - name: Run Lighthouse CI (warn-only)
        run: npx lhci autorun --config=test/a11y/lighthouserc.json ${{ steps.lhci-urls.outputs.flags }}
        continue-on-error: true

      - name: Write combined summary
        if: always()
        run: node test/a11y/summary.js >> "$GITHUB_STEP_SUMMARY"

      - name: Upload scan artifacts
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: a11y-scan-${{ needs.deploy.outputs.environment }}-${{ github.run_number }}
          path: |
            test/a11y/axe-results.md
            .lighthouseci/
          retention-days: 30
          if-no-files-found: warn