Initial commit

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

CLAUDE.md

@@ -0,0 +1,109 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 專案性質
+
+這是一個 **Claude Code skill**（根目錄的 `SKILL.md` 就是 skill 定義檔）。本身不是一般應用程式，產物是一組 bash 腳本（`scripts/*.sh`），針對自架 Gitea 做常見操作。`publish.sh` 是最早的腳本，其他腳本是逐步擴充而來。
+
+## 常用指令
+
+在本 repo 裡沒有測試／build／lint；開發流程就是：改 `scripts/*.sh` → `bash -n` 語法檢查 → 在另一個 tmp 目錄實際跑一次看看。所有腳本共用 `scripts/lib/common.sh`。
+
+實際使用腳本時（在任何專案目錄下）：
+
+```bash
+bash /path/to/gitea-cli/scripts/publish.sh [repo] [public|private] [-m "msg"]
+bash /path/to/gitea-cli/scripts/list.sh [--private|--public] [--format table|tsv|name]
+# ... 其他腳本見 SKILL.md / README.md
+```
+
+首次使用前要 `cp config.example.env config.env` 並填入 `GITEA_URL` / `GITEA_USER` / `GITEA_TOKEN`。
+
+## 架構與關鍵不變量
+
+### 安全模型：token 絕不落地
+
+**修改任何腳本時都要守住**：
+
+1. `origin` remote 永遠是**乾淨 URL**，不含 token
+2. Token 只能出現在 `config.env`、呼叫過程的環境變數、以及 `scripts/lib/common.sh` 裡的 `gitea_api` / `git_*_with_token` 函式內
+3. Token 絕不進入 `.git/config`、remote URL、任何 log（stdout/stderr）
+4. `config.env` 被 `.gitignore` 排除
+
+### 共用 lib `scripts/lib/common.sh`
+
+所有 API / push / clone 都走 lib，腳本本身不寫 curl 也不直接操作 credential helper。lib 提供：
+
+- `load_config`：讀 `config.env`，檢查三個變數都非空非預設
+- `gitea_api <METHOD> <path> [json-body]`：單一 API 呼叫入口；回傳後讀 `$HTTP_CODE` 與 `$GITEA_API_RESP_FILE`
+- `git_push_with_token <branch>` / `git_push_tag_with_token <tag>` / `git_clone_with_token <clean-url> <target>`：一次性帶 token 的 git 操作
+- `infer_repo_from_cwd`：從 `git remote get-url origin` 推斷 `owner/repo`
+- `confirm_destructive <prompt>` / `confirm_exact_match <expected>`：破壞性操作互動；`GITEA_YES=1` 或腳本處理的 `-y` 可略過
+- `log_info` / `log_ok` / `log_warn` / `log_err` / `log_done`：統一前綴、**全部寫 stderr**
+
+**什麼不放進 lib**（刻意留在各腳本）：
+- 各腳本自己的 arg 解析（每支不同）
+- JSON body 組字串（放在呼叫處最直觀；複雜的用 jq 在呼叫端組）
+- `publish.sh` 的三種 git 狀態分支（publish 獨有）
+
+### stdout / stderr 分流
+
+- **stderr**：`log_*` 進度訊息、錯誤
+- **stdout**：最終結構化輸出
+  - `publish.sh` / `rename.sh` / `visibility.sh` / `archive.sh` / `meta.sh` → repo web URL
+  - `list.sh` → repo 清單
+  - `clone.sh` → clone 到的絕對路徑
+  - `release.sh` → release URL + 每個 asset URL
+  - `tag.sh` → tag 名
+  - `delete.sh` → 空
+
+使用者可以 `URL=$(publish.sh)` 拿結果。
+
+### 新腳本骨架（照抄）
+
+寫新腳本時以這個為起點：
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/common.sh
+source "${SCRIPT_DIR}/lib/common.sh"
+
+load_config
+# require_cmd jq   # 若會用到
+
+usage() {
+    cat >&2 <<'EOF'
+Usage: <script>.sh ...
+EOF
+    exit 1
+}
+
+# arg parsing
+# ...
+
+log_info "..."
+gitea_api METHOD "/path" "$BODY"
+case "$HTTP_CODE" in
+    2??) log_ok "..." ;;
+    404) log_err "..."; exit 1 ;;
+    *)   log_err "... (HTTP ${HTTP_CODE})"; { cat "$GITEA_API_RESP_FILE"; echo ""; } >&2; exit 1 ;;
+esac
+
+log_done "完成"
+echo "<結構化結果>"  # stdout
+```
+
+### 相容性限制
+
+使用 **Gitea API v1**，Forgejo 相容；GitHub / GitLab **不相容**。要擴充到其他平台要重寫 API 呼叫處。
+
+## 寫入偏好
+
+- 腳本訊息與使用者文件皆為繁體中文（台灣用語）
+- 沿用既有風格：▶ 進行中、✓ 成功、⚠ 警告、❌ 失敗、✅ 完成
+- `SKILL.md` 是給 Claude 讀的 skill metadata + 簡短說明；`README.md` 是給人看的完整文件。修改功能時兩份都要同步
+- 範例路徑用通用形式（`/path/to/gitea-cli`），不要硬編碼個人資訊