# gitea-cli 擴充設計

**日期**：2026-04-21
**狀態**：待實作

## 背景

`gitea-cli` 目前只有一支 `scripts/publish.sh`，負責在自架 Gitea 建立 repo 並把目前工作目錄推上去。本 spec 定義將它擴充為完整的 Gitea 操作工具集。

## 目標

- 新增三大類功能：**repo 管理**、**取用既有 repo**、**推送進階（release / tag / 自訂 commit 訊息）**
- 抽出共用 lib（`scripts/lib/common.sh`），新舊腳本都使用
- **完全不破壞** 現有 `publish.sh` 的外部行為：既有呼叫方式仍然有效
- 維持既有安全不變量：token 絕不寫進 `.git/config` / remote URL / log

## 非目標（刻意 YAGNI）

以下情境**不**在本次範圍，留待真正需要時再加：

- 批次 clone 所有 repo（`clone.sh --all`）
- Fork / mirror / webhook / collaborator 管理
- 多站台切換 config（`GITEA_PROFILE` 等）
- 互動式 UI / 問答精靈（Claude 會代問，腳本維持純 CLI）
- GitHub / GitLab 相容

## 架構

### 組織方式：多支獨立腳本 + 共用 lib

選擇理由：腳本風格延續既有、每支單一職責、最不破壞現況；相對於單一子命令 CLI，shell subcommand 分派需要自己寫會讓單檔肥大。

### 檔案結構

```
gitea-cli/
├── SKILL.md
├── README.md
├── CLAUDE.md
├── config.example.env
├── config.env              (gitignored)
├── .gitignore
├── docs/superpowers/specs/ (本 spec 所在)
└── scripts/
    ├── lib/
    │   └── common.sh       (所有腳本 source 此檔)
    ├── publish.sh          (重構後 source lib；外部行為不變 + 新增 -m)
    ├── list.sh
    ├── clone.sh
    ├── rename.sh
    ├── visibility.sh
    ├── archive.sh
    ├── delete.sh
    ├── meta.sh
    ├── release.sh
    └── tag.sh
```

### `scripts/lib/common.sh` 介面

**必須放進來**（跨腳本重複且短小）：

| Function | 職責 |
|---|---|
| `load_config` | 找 `config.env` → `source` → 檢查 `GITEA_URL` / `GITEA_USER` / `GITEA_TOKEN` 非空且非預設值；失敗時統一錯誤訊息 |
| `gitea_api <METHOD> <path> [json-body]` | 封裝 curl；回傳 HTTP 狀態碼、把 body 寫入 `$GITEA_API_RESP_FILE`；呼叫端自行判斷狀態碼。所有新腳本**只透過這支呼叫 API**，不自己寫 curl |
| `git_push_with_token <branch>` | 封裝一次性 `credential.helper` 推送 |
| `git_clone_with_token <clean-url> <target-dir>` | 同上，用於 clone；clone 完自動把 origin 重設為乾淨 URL |
| `infer_repo_from_cwd` | 從 `git remote get-url origin` 推斷 repo 名；解析不到回非零 |
| `confirm_destructive <prompt>` | 互動 y/N；若 `--yes` flag 或 `GITEA_YES=1` 則直接通過 |
| `confirm_exact_match <expected>` | 要求使用者完整輸入指定字串才通過（給 `delete.sh` 用）；同樣支援 `--yes` 略過 |
| `log_info` / `log_warn` / `log_err` | 統一輸出前綴（`▶ / ⚠ / ❌ / ✅ / ✓`），**全部寫到 stderr** |

**刻意不放**（留在各腳本）：

- 各腳本的 arg 解析（幾行而已，抽共用反而難讀）
- 各 API endpoint 的 JSON body 組字串（放在呼叫處比較直觀）
- `publish.sh` 的三種 git 狀態分支判斷（是 publish 獨有）

### 不變量（review 時必守）

1. **Token 絕不落地**：token 僅允許出現在 `config.env`、環境變數、`gitea_api` / `git_*_with_token` 函式內部；不得寫進 `.git/config`、remote URL、log、`stderr`、`stdout`
2. **origin URL 永遠乾淨**：`publish.sh` 和 `clone.sh` 結束後 origin 都是不含 token 的 URL
3. **`publish.sh` 外部行為**：`publish.sh [repo] [public|private]` 原有參數位置與預設值完全不變；`-m "msg"` 是**新增**選項，不影響舊呼叫方式
4. **`set -euo pipefail` + `trap` 清臨時檔**：每支腳本都要
5. **stdout 只有結構化結果；stderr 放進度訊息**

## 腳本詳細設計

### 既有腳本（微調）

#### `publish.sh`

**用法**：`publish.sh [repo] [public|private] [-m "msg"]`

- 新增 `-m "msg"`：若指定，取代預設 commit 訊息（原本是 `Initial commit` / `Update`）
- 重構：`load_config` / `gitea_api` / `git_push_with_token` / `log_*` 改用 lib
- 三種 git 狀態分支保留在腳本內
- **stdout**：最後只印 repo web URL（方便 `URL=$(publish.sh)`）
- **stderr**：進度訊息

### 新腳本（方向 1：repo 管理）

#### `rename.sh`

**用法**：`rename.sh <old-name> <new-name>`

- `PATCH /repos/{GITEA_USER}/{old}` body `{"name": "<new>"}`
- 若 cwd 的 `git remote get-url origin` 指向舊 repo，順手 `git remote set-url origin <new-clean-url>`
- **stdout**：新 repo web URL
- 不需二次確認（重命名非破壞性）

#### `visibility.sh`

**用法**：`visibility.sh <repo> <public|private>`

- `PATCH /repos/{GITEA_USER}/{repo}` body `{"private": true|false}`
- 不需二次確認

#### `archive.sh`

**用法**：`archive.sh <repo> [--unarchive] [--yes|-y]`

- `PATCH /repos/{GITEA_USER}/{repo}` body `{"archived": true}`（`--unarchive` 則 `false`）
- 互動模式預設需 y/N 確認；`--yes` / `-y` / `GITEA_YES=1` 略過

#### `delete.sh`

**用法**：`delete.sh <repo> [--yes|-y]`

- `DELETE /repos/{GITEA_USER}/{repo}`
- 互動模式：用 `confirm_exact_match <repo>` 要求使用者**重新輸入完整 repo 名稱**才動（最高保險）
- `--yes` / `-y` / `GITEA_YES=1` 略過

#### `meta.sh`

**用法**：`meta.sh <repo> [--desc "..."] [--topics "a,b,c"]`

- `--desc`：`PATCH /repos/{owner}/{repo}` body `{"description": "..."}`
- `--topics`：`PUT /repos/{owner}/{repo}/topics` body `{"topics": ["a","b","c"]}`（覆蓋式，非增量）
- 兩者可同時給；都不給時印用法並非零退出

### 新腳本（方向 2：取用既有 repo）

#### `list.sh`

**用法**：`list.sh [--private|--public] [--format table|tsv|name]`

- `GET /user/repos`（自動翻頁，每頁 50）
- `--private` / `--public`：過濾可見性，預設顯示全部
- `--format`：
  - `table`（預設）：對齊欄位 `NAME  VISIBILITY  DESCRIPTION`
  - `tsv`：`name\tvisibility\tdescription`，給管線 / Claude 用
  - `name`：每行一個 repo 名，給 `xargs` 用
- **stdout**：清單內容
- **stderr**：進度（抓到幾頁、共幾個）

#### `clone.sh`

**用法**：`clone.sh <repo> [target-dir]`

- 預設 clone 到 `./<repo>`，可指定 target
- 目標目錄已存在且非空 → 失敗（不覆蓋）
- 用 `git_clone_with_token` 做 clone，完成後把 origin 重設為乾淨 URL
- **stdout**：clone 到的絕對路徑

### 新腳本（方向 3：推送進階）

#### `release.sh`

**用法**：`release.sh <tag> [--name "..."] [--notes "..."] [--target <branch>] [--draft] [--prerelease] [--asset <path>]...`

- 從 cwd 的 origin 推斷 repo；推不到強制要 `--repo <name>`
- **兩段 API**：
  1. `POST /repos/{owner}/{repo}/releases` body 組合參數 → 取回 `id`
  2. 對每個 `--asset` 做 `POST /repos/{owner}/{repo}/releases/{id}/assets?name=<basename>`（`multipart/form-data`）
- Tag 處理：Gitea release API 的 `tag_name` 若不存在會自動建（指到 `target_commitish`，預設 HEAD）。不強制先 `tag.sh`
- **錯誤處理**：
  - 第 1 步失敗 → 直接結束
  - 第 2 步某個 asset 失敗 → 繼續其他 asset，最後非零退出並列出失敗的
- **stdout**：第一行 release web URL，其餘每行一個 asset 下載 URL

#### `tag.sh`

**用法**：`tag.sh <tag> [-m "msg"]`

- 本地 `git tag -a <tag> -m "<msg>"`（預設 msg = `"Tag <tag>"`）
- `git_push_with_token` 推這個 tag（`git push origin <tag>`）
- **定位**：只打 tag 不發 release 的情境；與 `release.sh` 獨立

### Repo 名稱解析原則（跨腳本）

所有需要 repo 名的腳本，若參數省略，呼叫 `infer_repo_from_cwd` 嘗試從 `git remote get-url origin` 推斷。推斷不到就要求使用者帶參數。這樣在 repo 裡直接跑 `rename.sh newname`、`release.sh v1.0.0` 都能用。

## 錯誤處理與輸出格式

### 退出碼

- `0` 成功
- 非零 失敗（不細分子類；錯誤訊息本身會講清楚原因）

### stdout / stderr 分流

- **stderr**：所有 `▶ / ✓ / ⚠ / ❌ / ✅` 進度訊息與錯誤
- **stdout**：僅最終結構化輸出
  - `publish.sh` / `rename.sh` → repo web URL
  - `list.sh` → repo 清單
  - `clone.sh` → 絕對路徑
  - `release.sh` → release URL + 每個 asset URL
  - 其他 → 空

**既有 `publish.sh` 變更**：原本進度訊息是 stdout，會改到 stderr。在終端機看起來一樣（兩者都會顯示），但若有人 pipe 其 stdout 會只看到最後的 URL。這是刻意設計，不視為 regression。

## 測試策略

無自動化測試。驗收方式：

1. 既有 `publish.sh` 使用情境（三種 git 狀態、public/private、已存在 repo）全部手動跑過，確認行為不變
2. 每支新腳本在測試用的 Gitea repo 上跑 happy path 一次
3. 破壞性操作（`delete.sh` / `archive.sh`）特別驗證：
   - 不帶 `-y` 時會提示
   - `delete.sh` 輸入錯 repo 名會被拒
   - 帶 `-y` 時直接執行
4. Token 不落地驗收：跑完 `publish.sh` 後 `grep -r "$GITEA_TOKEN" .git/` 應為空

## 文件同步

### `SKILL.md`

- `description:` 擴寫以涵蓋所有擴充後的觸發情境（push / clone / list / rename / release / archive / delete / tag…）
- 正文改以「常見情境 → 對應腳本」方式列全部腳本，保留 `config.env` 一次性設定段落

### `README.md`

- 新增「腳本總覽」表格：每支腳本一行用法與一句說明
- 每支新腳本 1-2 段詳細說明 + 範例
- 「安全設計」段落補上「clone 完 origin 也是乾淨 URL」

### `CLAUDE.md`

- 補充「擴展為多腳本」的架構敘述
- 不變量改寫為**所有 push / clone 腳本**都必須守 token 不落地
- 新增「`scripts/lib/common.sh` 的用途與邊界」段落
- 新增「新腳本的檔案骨架」小範本（source lib → parse args → 呼叫 lib → 印結果），讓未來加新腳本的人照抄

### `config.example.env`

不變，仍是三個變數。

## 實作順序建議

1. `scripts/lib/common.sh`（所有後續腳本的底）
2. 重構 `publish.sh` 改用 lib，新增 `-m`；手動驗證外部行為不變
3. `list.sh` / `clone.sh`（方向 2：最常用）
4. `rename.sh` / `visibility.sh` / `meta.sh`（方向 1：非破壞）
5. `archive.sh` / `delete.sh`（方向 1：破壞性，需測確認機制）
6. `tag.sh` / `release.sh`（方向 3）
7. 更新 `SKILL.md` / `README.md` / `CLAUDE.md`
8. 整套驗收（上節「測試策略」）