shared/skills/spec-gitea/SKILL.md

name, description

name	description
spec-gitea	JSC plugins 共用「Gitea 工具規範」：tea 或 Gitea REST API + GITEA_TOKEN 的工具選擇與可用性檢查、token 機密保護（不 echo、遮蔽、不落地）、不依賴 jq、API 呼叫慣例（分頁完整讀取、UTF-8 JSON body、實際換行）、gitea 主機決定順序。當其他 skill 內文引用 spec-gitea 或 /jsc-shared:spec-gitea、或執行任何需存取 Gitea 的 JSC skill 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。

spec-gitea — 共用 Gitea 工具規範

所有 JSC skills 存取 Gitea（議題、留言、PR、repo 清單）時，一律遵守以下規範。

工具選擇（tea 或 api）

使用者已明確選定工具（--tool 或對話中已選）時跳過詢問，只做該工具的可用性驗證。否則：

1. 檢查 tea 是否存在：command -v tea；存在則執行 tea login list 記錄可用 login 與 host（失敗記錄原因，不中止）。

2. 檢查 GITEA_TOKEN 是否已設定，只輸出「已設定／未設定」，不得輸出 token 內容：

   [ -n "${GITEA_TOKEN}" ] && echo "GITEA_TOKEN 已設定" || echo "GITEA_TOKEN 未設定"
   

3. 以表格呈現檢查結果後詢問使用者要用哪一種：

   選項	可選條件	後續使用方式
   tea	tea 可執行且目標 host 有對應 login	命令一律帶 --login <name> --repo <owner>/<repo>
   api	GITEA_TOKEN 已設定	Gitea REST API + curl，標頭 Authorization: token $GITEA_TOKEN

4. 兩種方式都不可用 → 回報缺少 tea login 或 GITEA_TOKEN 並停止；不要請使用者把 token 貼進對話。

5. 多筆來源分屬不同 host：選 tea 須確認每個 host 都有對應 login；選 api 須同一個 token 可存取全部，否則回報權限不足並停止。

Token 機密保護（極重要）

• token 一律從環境變數讀取（$GITEA_TOKEN），絕不寫死在 skill、commit、PR、議題、log 或任何輸出。

• 不可 echo 含 token 的指令或 URL；顯示給使用者的指令／錯誤訊息一律遮蔽 token（以 *** 取代）；檢查時只輸出「已設定／未設定」。

• 帶 token 的 URL（clone／push）用變數帶入、不可印出；token 用完即棄，不寫進 git remote 設定、不落地。clone 完成後把 origin 還原成不含 token 的乾淨 URL：

  git -C "${dest}" remote set-url origin "https://<host>/<owner>/<repo>.git"
  

• 流程若可能使對話內文殘留 token（push／API 呼叫），完成後提醒使用者清除對話（Claude Code：/clear），並先確認輸出與 log 無明文 token。

不依賴 jq（環境未必安裝）

• 解析 JSON 用 tea 的結構化輸出（--output csv／--fields），或把原始 JSON 直接交給助理／subagent 解析，不要 pipe 到 jq。

API 呼叫慣例

• API base：https://<host>/api/v1（repo 層：https://<host>/api/v1/repos/<owner>/<repo>）。
• 標頭：Authorization: token $GITEA_TOKEN。
• 分頁必須完整讀取：持續累加 page 直到回傳筆數 < limit（或回空陣列）為止，不可只取第一頁。
• 寫入（議題描述／留言／PR body）以 UTF-8 JSON 檔帶入（如 --data @body.json）；換行必須是實際換行，不可讓內容顯示字面 \n（編碼細節見 /jsc-shared:spec-output）。
• API 失敗（401／403／網路錯誤）→ 回報錯誤（遮蔽 token）並停止；401／403 多半是 token 失效或權限不足。
• 版本相依端點（project／column／dependency 等）先以 GET 探測（404／501 視為不支援），不得對未確認存在的端點做寫入。

gitea 主機決定順序

依序決定（取第一個成功者）：

1. 參數 --host <主機>。
2. 環境變數 $GITEA_HOST（若有）。
3. 目前工作目錄是 git repo 且 git remote get-url origin 指向某 gitea 主機 → 取該 host。
4. 以上皆無 → 詢問使用者，不臆測。

主機僅取 host 部分（如 gitea.jsc.idv.tw）。