# gitea-cli

一組 bash 腳本，把自架 Gitea 的常見操作封裝成單一指令；目前實作「建立 repo → init → commit → push」，其他功能（list / clone / rename / release / …）依設計文件擴充中。

## 檔案結構

```
gitea-cli/
├── SKILL.md              # Claude Code skill 定義
├── README.md             # 本檔
├── CLAUDE.md             # 給 Claude 的 repo 內指引
├── config.example.env    # 設定範本（可提交）
├── config.env            # 實際設定（內含 token，.gitignore 排除）
├── .gitignore
├── docs/
│   └── superpowers/specs/  # 擴充設計文件
└── scripts/
    └── publish.sh        # 建 repo + 推送
```

> 以下範例用 `/path/to/gitea-cli` 代表本 skill 實際所在位置（你 clone 到哪裡就是哪裡）；也可以 symlink 到 `~/.claude/skills/gitea-cli` 讓 Claude Code 自動識別。

## 首次設定

1. **產生 Gitea access token**
   登入 Gitea → 使用者設定 → Applications → Generate New Token
   URL： `<你的 Gitea URL>/-/user/settings/applications`
   權限至少勾選：**write:repository**

2. **複製設定檔並填入 token**
   ```bash
   cd /path/to/gitea-cli
   cp config.example.env config.env
   # 用任一編輯器編輯 config.env，填入三個變數
   ```

   `config.env` 範例（請替換為自己的值）：
   ```env
   GITEA_URL=http://your-gitea.example.com:3000
   GITEA_USER=your-username
   GITEA_TOKEN=你剛才產生的_token
   ```

   **多組 Gitea 站／帳號**：另存成 `config.<profile>.env`，執行腳本時帶 `GITEA_PROFILE=<profile>` 切換：
   ```bash
   cp config.example.env config.work.env
   # 編輯 config.work.env

   GITEA_PROFILE=work bash /path/to/gitea-cli/scripts/list.sh
   ```
   未設 `GITEA_PROFILE` 時讀 `config.env`（預設）。`config.*.env` 已被 `.gitignore` 排除。

3. （選用）讓 Claude Code 自動辨識這個 skill（兩擇一）：

   **A. Symlink 本地開發目錄**（適合會持續改腳本的情境）
   ```bash
   ln -s /path/to/gitea-cli ~/.claude/skills/gitea-cli
   ```

   **B. 從自架 Gitea clone 到 skills 目錄**（適合多台機器、每台獨立設定 config.env）
   ```bash
   cd ~/.claude/skills
   # 若已有另一份 gitea-cli 可用，直接：
   bash /path/to/existing/gitea-cli/scripts/clone.sh gitea-cli ~/.claude/skills/gitea-cli
   # 否則用一般 git clone（之後會要求認證）：
   git clone http://your-gitea.example.com:3000/<user>/gitea-cli.git
   # clone 完成後，在 ~/.claude/skills/gitea-cli/ 底下：
   cp config.example.env config.env
   # 編輯 config.env 填入這台機器要用的 GITEA_URL / GITEA_USER / GITEA_TOKEN
   ```

   不管用哪一種，下次開啟 Claude Code session 就會自動載入這個 skill。

## 使用方式

在要推送的專案目錄下執行：

```bash
# 用當前資料夾名當 repo 名，建立 public repo
bash /path/to/gitea-cli/scripts/publish.sh

# 指定 repo 名
bash /path/to/gitea-cli/scripts/publish.sh my-project

# 建立 private repo
bash /path/to/gitea-cli/scripts/publish.sh my-project private
```

| 參數 | 說明 | 預設 |
|------|------|------|
| `$1` | repo 名稱 | 當前目錄名 |
| `$2` | 可見性：`public` / `private` | `public` |

## 所有可用腳本

| 腳本 | 用法 |
|---|---|
| `publish.sh` | `publish.sh [repo] [public\|private] [-m "msg"]` — 建 repo + 推目前目錄 |
| `list.sh` | `list.sh [--private\|--public] [--format table\|tsv\|name]` — 列出自己的 repo |
| `clone.sh` | `clone.sh <repo> [target-dir]` — clone 到本地，origin 保持乾淨 URL |
| `rename.sh` | `rename.sh <old> <new>` — 改名；若 cwd origin 指到舊 repo 自動更新 |
| `visibility.sh` | `visibility.sh <repo> <public\|private>` — 切換可見性 |
| `meta.sh` | `meta.sh <repo> [--desc ...] [--topics a,b,c]` — 設定 description / topics |
| `archive.sh` | `archive.sh <repo> [--unarchive] [-y]` — archive / unarchive |
| `delete.sh` | `delete.sh <repo> [-y]` — 刪除（互動模式需重新輸入 repo 名） |
| `tag.sh` | `tag.sh <tag> [-m "msg"]` — 建 annotated tag 並 push origin |
| `release.sh` | `release.sh <tag> [--name ...] [--notes ...] [--asset PATH]... [--repo NAME]` — 建 release + 上傳 asset |

所有呼叫 API 的腳本共用 `scripts/lib/common.sh`，該 lib 負責 config 載入、API 呼叫、一次性 credential helper 注入、互動確認。

## 腳本執行步驟

1. 讀取 `config.env`，驗證三個必要環境變數都有值
2. 呼叫 Gitea API `POST /api/v1/user/repos` 建立 repo
   - `201` 建立成功
   - `409` repo 已存在，略過
   - `401/403` 授權錯誤，提示檢查 token
3. 若當前目錄沒有 `.git` → `git init -b main`
4. 若還沒有任何 commit → 自動建 initial commit（含空 commit 以支援空目錄）
5. 若有未提交變更 → `git add -A && git commit -m "Update"`
6. 設定 `origin` 為**不含 token** 的乾淨 URL
7. 用一次性 credential helper 帶 token 執行 `git push -u origin <branch>`

## 安全設計

- **`config.env` 內含 token，`.gitignore` 已排除**，不會被提交。
- **token 不寫入 `.git/config`**：`origin` 為乾淨 URL，push 時用 `git -c credential.helper=...` 注入，結束後即消失。
- Credential helper 以變數替換方式產生 shell 片段；命令列參數會短暫出現在 `ps` 中，僅限本機使用者看到（自架 LAN Gitea 場景可接受）。
- `clone.sh` 完成後 origin 也是乾淨 URL，再次 `git pull` / `git push` 要重新帶 credential（跟 `publish.sh` 一致）。

## 常見問題

**Q：推送完之後再跑 `git push`，為什麼失敗？**
A：origin 是乾淨 URL，再次 push 會要求認證。解法二選一：
- 再用本腳本 push（會重新帶 token）
- 自行設定 git credential helper 記住帳密

**Q：Token 失效／過期？**
A：重新到 Gitea 產生 token，覆蓋 `config.env` 裡的 `GITEA_TOKEN`。

**Q：要換成另一個 Gitea 站或使用者？**
A：常駐切換就另存成 `config.<profile>.env`，執行時帶 `GITEA_PROFILE=<profile>`；只是單次替換就直接改 `config.env` 的 `GITEA_URL` / `GITEA_USER`。

**Q：可以用在非 Gitea（例如 Gitea clone 產品）嗎？**
A：本腳本用的是 Gitea API v1，Forgejo 相容，GitHub/GitLab 不相容。