# C6 — workflow-commands compatibility test.
#
# Verifies the runner honours the modern file-based workflow-command interface:
#   * $GITHUB_OUTPUT  (single-line + multi-line value via heredoc delimiter)
#   * $GITHUB_PATH    (added directory becomes callable in a LATER step)
#   * $GITHUB_ENV     (var set in one step is visible in the NEXT step)
#   * $GITHUB_STEP_SUMMARY
#   * ::warning:: / ::error:: / ::notice:: workflow commands
#
# Annotation assertion policy (important):
#   A job CANNOT observe its own RENDERED annotations in the UI. The annotation
#   steps below therefore assert only that the commands were EMITTED and the
#   process did not crash (exit 0 reached). Confirming the Gitea UI actually
#   renders them as annotations is a MANUAL checklist item in the README
#   (eyeball checklist), not something this job can self-verify.
#
# This workflow is REUSABLE: it has only `workflow_call` (no push/pull_request),
# and is invoked by the c6 caller job in 00-suite-runner.yml.

name: "06 Workflow Commands"

on:
  workflow_call:

permissions:
  contents: read

jobs:
  workflow-commands:
    runs-on: ubuntu-24.04
    steps:
      # ------------------------------------------------------------------
      # Bootstrap: check out the repo so lib/assert.sh is on disk, then
      # source it. assert_* log [PASS]/[FAIL] to stderr and return 0/1.
      # We do NOT set `set -e` globally: assert.sh leaves flow control to
      # the caller, so each step explicitly checks $? after asserting.
      # ------------------------------------------------------------------
      - name: Checkout
        uses: actions/checkout@v4

      - name: Source assert library
        id: source-lib
        shell: bash
        run: |
          # shellcheck source=lib/assert.sh
          source ./lib/assert.sh
          # Smoke-check that sourcing actually loaded the functions.
          assert_eq "${BASH_SOURCE[1]:-sourced}" "sourced" "assert.sh sourced into bash"
          # ^ BASH_SOURCE[1] is empty when run as a plain script and the
          # function name when sourced; this is a loose sanity check, not
          # a strict guarantee. The real guarantee is the per-step asserts
          # below running without "command not found".

      # ------------------------------------------------------------------
      # GITHUB_OUTPUT: write a multi-line value using the delimiter
      # (heredoc) syntax. The NEXT step consumes it via steps.<id>.outputs.
      # ------------------------------------------------------------------
      - name: Write GITHUB_OUTPUT (multi-line value)
        id: output-writer
        shell: bash
        run: |
          source ./lib/assert.sh
          # Single-line value.
          echo "simple=hello" >> "$GITHUB_OUTPUT"
          # Multi-line value via delimiter (the modern replacement for
          # the deprecated ::set-output heredoc hack).
          {
            echo "myval<<DELIMITER_EOF"
            echo "line1"
            echo "line2"
            echo "DELIMITER_EOF"
          } >> "$GITHUB_OUTPUT"
          # Sanity: the file actually received the block.
          assert_contains "$(cat "$GITHUB_OUTPUT")" "DELIMITER_EOF" "GITHUB_OUTPUT delimiter block written"

      - name: Assert GITHUB_OUTPUT consumed via step output
        id: output-check
        shell: bash
        run: |
          source ./lib/assert.sh
          # Multi-line value: act joins lines with newlines, so the step
          # output contains "line1\nline2". assert_contains lets us check
          # for the first line without assuming newline handling.
          assert_contains "${{ steps.output-writer.outputs.myval }}" "line1" "GITHUB_OUTPUT multi-line value consumed"
          assert_eq "${{ steps.output-writer.outputs.simple }}" "hello" "GITHUB_OUTPUT single-line value consumed"

      # ------------------------------------------------------------------
      # GITHUB_PATH: create a bin/ dir with an executable helper, append
      # the dir to $GITHUB_PATH, then call the helper BY NAME from the
      # NEXT step. If the runner honoured $GITHUB_PATH, the call resolves.
      # ------------------------------------------------------------------
      - name: Append dir to GITHUB_PATH
        id: path-writer
        shell: bash
        run: |
          source ./lib/assert.sh
          mkdir -p ./bin
          cat > ./bin/myhelper <<'EOF'
          #!/usr/bin/env bash
          echo "helper-output"
          EOF
          chmod +x ./bin/myhelper
          assert_exists "./bin/myhelper" "helper script created before GITHUB_PATH append"
          echo "$PWD/bin" >> "$GITHUB_PATH"
          assert_contains "$(cat "$GITHUB_PATH")" "/bin" "GITHUB_PATH received the dir entry"

      - name: Assert GITHUB_PATH dir is callable from next step
        id: path-check
        shell: bash
        run: |
          source ./lib/assert.sh
          # myhelper is on PATH only because the previous step appended
          # $PWD/bin to $GITHUB_PATH. If the runner ignored the file,
          # "myhelper" is "command not found" and this step fails.
          assert_eq "$(myhelper)" "helper-output" "GITHUB_PATH added dir is callable in later step"

      # ------------------------------------------------------------------
      # GITHUB_ENV: set a var in one step, read it in the NEXT step.
      # ------------------------------------------------------------------
      - name: Write GITHUB_ENV
        id: env-writer
        shell: bash
        run: |
          source ./lib/assert.sh
          echo "MY_ENV_VAR=envvalue" >> "$GITHUB_ENV"
          assert_contains "$(cat "$GITHUB_ENV")" "MY_ENV_VAR=envvalue" "GITHUB_ENV file received the var entry"

      - name: Assert GITHUB_ENV propagated to next step
        id: env-check
        shell: bash
        run: |
          source ./lib/assert.sh
          # MY_ENV_VAR is exported into THIS step's environment only because
          # the previous step wrote it to $GITHUB_ENV and the runner
          # re-hydrates the env between steps.
          assert_eq "${MY_ENV_VAR:-}" "envvalue" "GITHUB_ENV propagated to next step"

      # ------------------------------------------------------------------
      # Annotations + step summary (EMIT-ONLY assertion).
      #
      # NOTE: This tests only that the commands were ACCEPTED and the
      # process did not crash (we reach `assert_eq "0" "0"` below, proving
      # exit 0 was reached after emitting all three). Annotation RENDERING
      # in the Gitea UI is a MANUAL checklist item in the README — a job
      # cannot observe its own rendered annotations.
      # ------------------------------------------------------------------
      - name: Emit annotations and write step summary
        id: annotations
        shell: bash
        run: |
          source ./lib/assert.sh
          # Emit the three annotation workflow commands. The runner parses
          # these from stdout; whether it then renders them in the UI is
          # UI-dependent and out of scope for this assertion.
          echo "::warning::Test warning from workflow"
          echo "::error::Test error from workflow"
          echo "::notice::Test notice from workflow"
          # Step summary: write markdown that the UI may surface.
          echo "## Step summary test" >> "$GITHUB_STEP_SUMMARY"
          # The fact that we reach this line at all proves the emit did
          # not abort the step. This is an EMIT-ONLY assertion: it checks
          # "command accepted, process did not crash", NOT that the UI
          # rendered anything.
          assert_eq "0" "0" "annotations emitted without error"
          assert_exists "$GITHUB_STEP_SUMMARY" "step summary file exists after write"