---
name: spec-gitea
description: 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 內容：

   ```bash
   [ -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：

  ```bash
  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`）。