# =============================================================================
# CI Workflow（Gitea Actions）
# 用途：在 Pull Request 開啟或更新時觸發的持續整合流程，依序執行三個 job：
#   1. BUILD  - 發佈 Gitea Release（beta 版本號取自 run_number），並輸出 is_beta。
#   2. TEST   - 依 BUILD 輸出的 is_beta 決定是否執行；checkout 原始碼，執行本
#               composite action（setup-codex），再用 codex exec 產生「自我介紹」
#               文字，透過 heredoc 寫入 job output。
#   3. RESULT - 顯示 TEST job 輸出的 message，用於驗證整條流程串接成功。
#   另外，CI 僅在 base 分支為 master 或 develop 的 Pull Request 觸發。
# 更新日期：2026/07/03 17:43:30
# =============================================================================

# workflow 名稱，會顯示在 Gitea Actions 的執行清單中。
name: CI
# 觸發條件設定區塊。
on:
  # 監聽 Pull Request 事件。
  pull_request:
    # 限制只有當 PR 的目標（base）分支為 master 或 develop 時才觸發此 CI。
    branches:
    # 納入的目標分支：master。
    - master
    # 納入的目標分支：develop。
    - develop
    # 僅在 PR「開啟」(opened) 或「有新 commit 推送 / 更新」(synchronize) 時觸發，
    # 避免 closed / reopened 等其他事件也啟動整條 CI。
    types: [opened, synchronize]
# 定義本 workflow 的所有 job。
jobs:
  # ---- Job 1：BUILD（發佈 Release）----
  build:
    # job 顯示名稱（前綴數字用於在 UI 中排序閱讀）。
    name: 1. BUILD
    # 指定執行環境（runner label），使用 ubuntu runner。
    runs-on: ubuntu
    # 此 job 專屬的環境變數。
    env:
      # 版本號規則：固定 0.0.0-beta. 前綴 + Gitea 的執行流水號 run_number，
      # 讓每次 CI 產生遞增且唯一的 beta 版本字串。
      VERSION: "0.0.0-beta.${{ gitea.run_number }}"
    # 定義此 job 對外輸出，供後續 job（test）取用其判斷結果。
    outputs:
      # 【需人工確認】將環境變數 IS_BETA 暴露為 job 層級的 is_beta 輸出；但本 job 的
      # env 只定義了 VERSION、並未定義 IS_BETA，因此 env.IS_BETA 會取到空字串，
      # 配合 test 的 if ... == 'true' 判斷，將導致 test job 永遠被略過。
      # 此行內容維持原樣不修改，請人工確認是否應補上 IS_BETA 的設定。
      is_beta: ${{ env.IS_BETA }}
    # 此 job 的執行步驟。
    steps:
    # 步驟：發佈 Release。
    - name: Publishing Release
      # 使用第三方 action 建立 Gitea Release；版本號由 repo variable 控制，
      # 便於集中管理 action 版本、避免硬編碼。
      uses: akkuman/gitea-release-action@${{ vars.ACTION_GITEA_RELEASE_VERSION }}
      # 傳入該 action 的參數。
      with:
        # Release 顯示名稱：「儲存庫名稱 v版本號」。
        name: "${{ gitea.event.repository.name }} v${{ env.VERSION }}"
        # Release 對應的 tag 名稱，前綴 v + 版本號。
        tag_name: "v${{ env.VERSION }}"
        # tag 指向的 commit，使用本次觸發事件的 commit SHA。
        target_commitish: ${{ gitea.sha }}
        # 是否標記為「預發佈」(prerelease)：當 PR 目標分支 base_ref 為 develop 時為 true，
        # 代表流向 develop 的變更視為預發佈版本。
        prerelease: ${{ gitea.base_ref == 'develop' }}
  # ---- Job 2：TEST（執行 setup-codex 並產生自我介紹）----
  test:
    # job 顯示名稱。
    name: 2. TEST
    # 指定 ubuntu runner。
    runs-on: ubuntu
    # 相依關係：需等 build job 成功後才執行。
    needs: [build]
    # 執行條件：僅當 build job 的 is_beta 輸出等於字串 'true' 時才執行本 test job；
    # 否則整個 test job 會被略過。
    if: ${{ needs.build.outputs.is_beta == 'true' }}
    # 定義此 job 對外輸出，供後續 job（result）取用。
    outputs:
      # 將名為 execute 的步驟輸出的 message，暴露為 job 層級的 message 輸出。
      message: ${{ steps.execute.outputs.message }}
    # 此 job 的執行步驟。
    steps:
    # 步驟：取出原始碼。
    - name: Source Code Checkout
      # 使用官方 checkout action 將 repo 內容拉到 runner；版本由 repo variable 控制。
      uses: actions/checkout@${{ vars.ACTION_CHECKOUT_VERSION }}
    # 步驟：執行本 repo 的 composite action（setup-codex）。
    - name: Run Setup Codex
      # 指定步驟 id，方便後續引用其輸出。
      id: setup-codex
      # 「./」代表使用當前 repo 根目錄的 action（即本專案自身這個 composite action）。
      uses: ./
      # 傳入該 action 的參數。
      with:
        # 從 secrets 帶入 CODEX_OAUTH 授權憑證，供 codex 登入 / 認證使用（機密不外顯）。
        oauth: ${{ secrets.CODEX_OAUTH }}
    # 步驟：實際呼叫 codex 產生自我介紹並寫入 job output。
    - name: Execute Codex
      # 指定步驟 id 為 execute，對應上方 outputs.message 的來源。
      id: execute
      # 明確指定以 bash 執行下方 run 腳本。
      shell: bash
      # 多行 shell 腳本（run: | 表示保留換行的區塊字面值）。
      run: |
        # 執行 codex exec 送出提示「請你進行自我介紹」，取得回覆文字存入 MESSAGE 變數；
        # 2>/dev/null 將 stderr 丟棄，避免非結果訊息污染輸出內容。
        MESSAGE=$(codex exec "請你進行自我介紹" 2>/dev/null)
        # 用大括號將多個 echo 群組化，統一把整段輸出一次重導向到 $GITHUB_OUTPUT。
        {
          # 宣告輸出鍵 message 並使用 heredoc 分隔符 CODEX_EOF，以支援「多行值」的寫法。
          echo "message<<CODEX_EOF"
          # 寫入實際的多行自我介紹內容。
          echo "$MESSAGE"
          # heredoc 結束分隔符，標示 message 值到此為止。
          echo "CODEX_EOF"
        # 將上述群組化輸出「附加」(>>) 到 $GITHUB_OUTPUT 檔，登記為此步驟的 output。
        } >> "$GITHUB_OUTPUT"
  # ---- Job 3：RESULT（顯示 TEST 的 message）----
  result:
    # job 顯示名稱。
    name: 3. RESULT
    # 指定 ubuntu runner。
    runs-on: ubuntu
    # 相依關係：需等 build 與 test 兩個 job 都完成後才執行。
    needs: [build,test]
    # 此 job 專屬的環境變數。
    env:
      # 從 test job 的輸出取得 message，供下方步驟印出。
      MESSAGE: ${{ needs.test.outputs.message }}
    # 此 job 的執行步驟。
    steps:
    # 步驟：印出訊息。
    - name: Show Message
      # 將環境變數 MESSAGE 的內容輸出到 log，用於確認整條流程串接與 codex 回覆結果。
      run: echo "$MESSAGE"