jiantw83andClaude Sonnet 5
1030f9d403
依 todo.md 執行的規範治理專案：新增 spec-preflight 等 14 個共用規範（含 conventional-commit/pull-request/git-push/issue-read/todo-list/ask-user/ subagent/no-scratch-files/skill-invocation/script-path/action-scaffold/ node-src-layout/plugin-cli/model），擴充 spec-git-safety 與 spec-gitea（token 優先序、機密遮蔽、Wiki 頁名轉義規則）；新增可執行 skill `models`（模型能力 查詢與標籤）與 `todo`（依指定模型產生/附加 todo.md）；新增 plugin.meta.json 單一事實來源與 gen-plugin-files.mjs 樣板產生器，統一四個 repo 的 manifest／ README／AGENTS.md 並移除寫死的本機使用者路徑；新增 shared/scripts/lib 的 log／機密遮蔽三語言參考實作。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
75 lines
4.8 KiB
Markdown
75 lines
4.8 KiB
Markdown
---
|
||
name: spec-git-push
|
||
description: JSC plugins 共用「git push 憑證選擇規範」：push 分支前依序嘗試認證管理器（既有 git credential helper）→ token（環境變數組帶 token 遠端 URL，全程遮蔽、用完即棄不落地）→ 詢問使用者三段式，前者失敗才退到下一個；與 `/jsc-shared:spec-gitea`「token 解析優先序」（API 呼叫用、多來源逐一驗證取優）不同，本規範專講 `git push` 本身的憑證選擇順序。當其他 skill 內文引用 spec-git-push 或 /jsc-shared:spec-git-push、或執行任何會 `git push` 的 JSC skill 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||
---
|
||
|
||
# spec-git-push — 共用 git push 憑證選擇規範
|
||
|
||
機密保護的總則（不 echo、遮蔽、不落地）沿用 `/jsc-shared:spec-gitea`「Token 機密保護」章節；本規範只補 `git push` 情境特有的三段式憑證選擇順序，不重複該章節已涵蓋的內容。
|
||
|
||
## 與 spec-gitea「token 解析優先序」的差異
|
||
|
||
兩者都在講「憑證怎麼決定」，但用途與判定方式不同，**不可互相取代**：
|
||
|
||
| | `/jsc-shared:spec-gitea`「token 解析優先序」 | 本規範（`spec-git-push`） |
|
||
| --- | --- | --- |
|
||
| 用途 | Gitea REST API 呼叫（GET／POST 等） | `git push` 本身取得推送權限 |
|
||
| 選擇單位 | 多個「token 來源」 | 多種「推送方式」（不只 token） |
|
||
| 判定方式 | 每個候選以輕量 API 請求**實際驗證**（HTTP 200 才採用），失敗就換下一個候選 | 直接嘗試該推送方式，**push 本身失敗**才換下一個 |
|
||
| 候選順序 | 專用變數 → `$GITEA_TOKEN` → tea 設定檔 → `~/.git-credentials` | 認證管理器 → token → 詢問使用者 |
|
||
| 最終手段 | 全部候選驗證失敗 → 回報錯誤並停止 | 前兩段都失敗 → **詢問使用者**如何 push，不猜測其他憑證 |
|
||
|
||
同一個 skill 可以先用 spec-gitea 的順序決定 API 呼叫要用哪個 token，再於 push 時套用本規範的三段式；兩套順序彼此獨立，不共用判定結果。
|
||
|
||
## 三段式流程
|
||
|
||
push 前先確認目前分支是否有領先遠端的 commit；**無 commit 可推就跳過整段，不需要嘗試任何憑證**：
|
||
|
||
```bash
|
||
source_branch="$(git rev-parse --abbrev-ref HEAD)"
|
||
git rev-parse --verify "origin/${source_branch}" 2>/dev/null # 遠端無此分支視為全部要推
|
||
git log --oneline "origin/${source_branch}..${source_branch}" 2>/dev/null # 領先遠端的 commit
|
||
```
|
||
|
||
確認有 commit 需要 push 後，依序嘗試以下三段，**前者失敗才退到下一個**，任一段成功即停止：
|
||
|
||
| 順序 | 方式 | 適用條件 |
|
||
| --- | --- | --- |
|
||
| 1 | 認證管理器（優先） | git 既有的 credential helper 可用（如 Windows 的 `manager-core`） |
|
||
| 2 | token push | 環境變數已提供 token（如 `GITEA_TOKEN`） |
|
||
| 3 | 詢問使用者 | 前兩段都失敗 |
|
||
|
||
### 1. 認證管理器
|
||
|
||
不預先判斷有沒有 credential helper，直接嘗試，讓 git 自己走既有認證流程：
|
||
|
||
```bash
|
||
git push -u origin "$(git rev-parse --abbrev-ref HEAD)"
|
||
```
|
||
|
||
### 2. token push
|
||
|
||
失敗才進入此段。從環境變數讀 token，組帶 token 的遠端 URL 推送：
|
||
|
||
```bash
|
||
# GITEA_TOKEN 來自環境變數；host/owner/repo 解析自 origin
|
||
git push "https://oauth2:${GITEA_TOKEN}@<host>/<owner>/<repo>.git" \
|
||
"$(git rev-parse --abbrev-ref HEAD)"
|
||
```
|
||
|
||
- token 一律用變數帶入組出遠端 URL，**指令與輸出全程不可印出含 token 的字串**。
|
||
- token 用完即棄：**不寫進 `git remote set-url`／`.git/config`、不落地**——這個帶 token 的 URL 只用於這一次 push，用完即丟，不留存、不設回 remote。
|
||
- 若 push 之外的流程（例如 clone）曾把帶 token 的 URL 設進 remote，還原成乾淨 URL 屬於 clone／remote 憑證管理範疇，做法見 `/jsc-shared:spec-gitea`「Token 機密保護」章節，不在本規範重複。
|
||
|
||
### 3. 詢問使用者
|
||
|
||
兩段都失敗才進入此步：列出兩段各自的失敗原因（**先遮蔽 token**），請使用者指示要如何推送，**不可自行猜測**其他憑證或來源；排程情境（無人可即時回應）改為寫入 log 並結束，等使用者事後處理。
|
||
|
||
## 全程遮蔽 token
|
||
|
||
三段流程中任何會印出指令、URL、錯誤訊息，或寫進 log 的地方，一律套用 `/jsc-shared:spec-gitea`「機密遮蔽實作」章節的規則過濾後才輸出，不得只遮蔽字面 token 值。
|
||
|
||
## 適用情境
|
||
|
||
供任何會執行 `git push` 的 JSC skill 引用，例如 `/jsc-code:review-resolve` push 當前分支的階段、`/jsc-code:target` push `develop` 的階段。**clone 時組裝帶 token 的 URL 與 `remote set-url origin` 還原乾淨 URL**（例如 `/jsc-code:sync` 建立資料夾並 clone 的階段）屬於 clone／remote 憑證管理，已由 `/jsc-shared:spec-gitea`「Token 機密保護」章節涵蓋，不屬本規範範疇。
|