Initial commit

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/superpowers/specs/2026-04-21-gitea-cli-expansion-design.md

@@ -0,0 +1,259 @@
+# 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. 整套驗收（上節「測試策略」）