feat(shared): 新增14個共用spec、models/todo工具與樣板產生器,收斂跨repo重複規範
依 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>
This commit is contained in:
@@ -0,0 +1,74 @@
|
||||
---
|
||||
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 機密保護」章節涵蓋,不屬本規範範疇。
|
||||
Reference in New Issue
Block a user