Initial commit

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

README.md

@@ -0,0 +1,120 @@
+# 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
+   ```
+
+3. （選用）讓 Claude Code 自動辨識這個 skill：
+   ```bash
+   ln -s /path/to/gitea-cli ~/.claude/skills/gitea-cli
+   ```
+
+## 使用方式
+
+在要推送的專案目錄下執行：
+
+```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.env` 的 `GITEA_URL` / `GITEA_USER`。
+
+**Q：可以用在非 Gitea（例如 Gitea clone 產品）嗎？**
+A：本腳本用的是 Gitea API v1，Forgejo 相容，GitHub/GitLab 不相容。