# ============================================================================
# 用途：Gitea/GitHub Docker container action「Calculate Next Version」的
#       metadata 定義檔。宣告此 action 的名稱、輸入（is_beta）、輸出（value）
#       與執行方式（runner 於執行時就地以 Dockerfile 建置映像並以 entrypoint.sh 啟動）。
#       由 workflow 以 `uses:` 引用本 repo 時，runner 讀取此檔決定如何執行。
# 更新時間：2026/07/16 11:18:57
# ============================================================================

# action 的顯示名稱：出現在 workflow log 與 marketplace/action 清單中，
# 供使用者辨識此步驟在做什麼
name: 'Calculate Next Version'

# action 的一句話用途說明：從 git tag 取得最新版號，依 is_beta 分流計算
# 下一個正式版（X.Y.Z）或 beta 版（X.Y.Z-beta.N）版號，各號碼滿 9 進位，
# 結果輸出為 value；與 entrypoint.sh 啟動訊息、README 的描述一致
description: '從 git tag 取得最新版號，依 is_beta 計算下一個正式版或 beta 版號（各號碼滿 9 進位）並輸出為 value。'

# action 作者，僅供標示用途，不影響執行
author: 'Jeffery'

# 輸入參數區：workflow 以 `with:` 傳入的值，
# runner 會轉成 INPUT_<大寫參數名> 環境變數注入容器
inputs:
  # is_beta：是否產生 beta 版號；runner 會以 INPUT_IS_BETA 環境變數
  # 傳入容器，由主程式 src/index.js 讀取後決定版號計算分流
  is_beta:
    # 參數說明：true 時產生 X.Y.Z-beta.N 格式的 beta 版號，
    # false（預設）時產生下一個正式版 X.Y.Z
    description: '是否為 beta 版（true 時產生 X.Y.Z-beta.N 版號）'
    # 非必填：未提供時使用下方 default 值
    required: false
    # 預設為 'false'（正式版分流）；YAML 需以字串表示，
    # action 輸入一律為字串，布林判斷由主程式自行解析
    default: 'false'

  # sha：要檢查的 commit SHA，建議由 workflow 傳入 ${{ gitea.sha }}；
  # runner 會以 INPUT_SHA 環境變數傳入容器，該 commit 已有版號 tag 時
  # 直接輸出該版號（忽略 is_beta）、不再計算下一版
  sha:
    # 參數說明：未提供時主程式自動改用 runner 內建的 GITHUB_SHA；
    # 兩者皆空才略過已標記檢查、直接走一般計算流程
    description: '要檢查的 commit SHA（建議傳入 ${{ gitea.sha }}）；該 commit 已有版號 tag 時直接輸出該版號。未提供時自動改用 GITHUB_SHA'
    # 非必填：省略時依上述順序自動回退
    required: false
    # 預設空字串，表示交由主程式依 INPUT_SHA → GITHUB_SHA 順序解析
    default: ''

# 輸出參數區：供 workflow 後續步驟以 steps.<id>.outputs.value 取用
outputs:
  # value：計算出的下一版號；由主程式（src/index.js）將
  # 「value=<版號>」寫入 GITHUB_OUTPUT 檔案而產生，
  # container action 不需在此宣告 value 的來源（無 composite 的 value: 欄位）
  value:
    description: '計算出的下一版號'

# 執行方式定義區：宣告此 action 為 Docker container action 及其啟動方式
runs:
  # 使用 docker 執行模式：runner 會以容器方式執行此 action
  using: docker
  # image 指向 repo 內的 Dockerfile：表示 runner 於「執行時」就地建置映像
  # （非預建映像），每次執行都可能觸發 docker build（有 layer 快取時較快）
  image: dockerfile
  # 覆寫容器進入點為 /action/entrypoint.sh：
  # 該腳本輸出啟動訊息後以 exec 交棒給 node 主程式 /action/src/index.js；
  # 與 Dockerfile 的 ENTRYPOINT ["/action/entrypoint.sh"] 一致（此處為明確重申）
  entrypoint: /action/entrypoint.sh