272 lines
12 KiB
Bash
Executable File
272 lines
12 KiB
Bash
Executable File
#!/usr/bin/env sh
|
||
# version-guard.sh — 技能使用前的版本前置檢查（PreToolUse，matcher: Skill）。
|
||
#
|
||
# 本機版本落後遠端發佈版本時擋下該次技能呼叫，並提示更新指令。
|
||
#
|
||
# 輸入：stdin JSON（Claude 格式）或環境變數，兩者都收。
|
||
# 工具名 JSC_TOOL_NAME、TOOL_NAME、stdin 的 tool_name
|
||
# 技能名 JSC_SKILL、SKILL、stdin 的 skill
|
||
# 兩邊都拿不到就安靜降級 exit 0。
|
||
#
|
||
# 判準與取值：
|
||
# - 比對對象是「遠端發佈版本」與「本機**實際載入**的版本」。
|
||
# 實際載入版本只認 installed_plugins.json 的 installPath 底下那份 plugin.json，
|
||
# 不看註冊在 installed_plugins.json 的版本欄位——那兩者可能不同，註冊值比較新時
|
||
# 會放過真正被載入的舊版。讀不到那份檔案就當查不到，安靜放行。
|
||
# - 只擋落後。本機版本等於或超前遠端一律放行：開發技能組時本機本來就會
|
||
# 超前預設分支，擋下去會讓維護者自己動不了。
|
||
# - **只有「本機落後遠端」會擋**。查不到資料一律放行（exit 0）：本機版本、
|
||
# Gitea 站台、遠端版本全部來自 Claude 的 plugin 檔案與 Gitea API，沒裝
|
||
# Claude 或離線的機器一筆都讀不到。那種情況擋下去，等於在沒有任何版本
|
||
# 證據時停掉每一次技能呼叫，護欄變成故障點。
|
||
#
|
||
# 豁免（這些技能永遠放行）：
|
||
# jsc-cli:deploy 更新整組技能的入口，擋了就沒有任何方法更新，會死鎖
|
||
# jsc-hooks:hooks-install 更新後要重新接線，擋了會讓更新做一半卡住
|
||
# jsc-cli:models SDLC 閘門依賴它產生 model-tags.tsv
|
||
# jsc-meta:* 開發技能組本身的工具，擋了就修不了技能組
|
||
# jsc-ask:ask deploy 問「install/update/uninstall」一定會呼叫它；
|
||
# 它本身落後版本被擋下，訊息又指回 /jsc-cli:deploy，
|
||
# deploy 卡在問不出模式那一步，跟直接擋 deploy 是同一種死鎖
|
||
# jsc-gitea:wiki jsc-ask:ask 問完一定寫回 wiki 才算完成，理由同上一條，
|
||
# 擋在這一步一樣是 deploy 做不完
|
||
#
|
||
# 逃生門：JSC_VERSION_GUARD=off 完全略過檢查（離線工作時用）。
|
||
#
|
||
# 快取：$JSC_HOME/version-cache/{CLI 代號}/{domain}，單行「{版本} {epoch}」，
|
||
# 預設 600 秒內不重查（JSC_VERSION_TTL 可調）。hook 與 report 在同一支 CLI 內共用。
|
||
# 舊路徑 $JSC_HOME/version-cache/{domain} 會在第一次讀取時複製到當前 CLI 的新路徑。
|
||
#
|
||
# 另有一個非 hook 的子指令：
|
||
# version-guard.sh report 把每個已安裝 jsc-* plugin 的版本比對印成 TSV，每行
|
||
# 「{domain}<TAB>{本機}<TAB>{遠端}<TAB>{落後|最新|超前|查詢失敗}」，
|
||
# 最後一行「behind<TAB>{落後個數}」。供 jsc-cli:deploy 判斷要不要
|
||
# 把「更新」設成推薦選項。report 只讀不擋，永遠 exit 0。
|
||
# 本機沒有 Claude 的 plugin 註冊檔時改印「noregistry<TAB>{路徑}」
|
||
# 再接 behind 0：那代表這台機器無法做版本檢查，跟「全部最新」是兩件事。
|
||
HERE=$(dirname "$0"); . "$HERE/lib.sh"
|
||
|
||
REG="$HOME/.claude/plugins/installed_plugins.json"
|
||
MK="$HOME/.claude/plugins/known_marketplaces.json"
|
||
|
||
# 從檔案取 JSON 字串欄位。與 lib.sh 的 json_str 同一種 naive 解析，只是來源是檔案：
|
||
# 先把換行換成空白、再以逗號斷行，這樣每行最多一個欄位，取值不會被貪婪比對吃掉。
|
||
file_json_str() { # $1=檔案 $2=欄位名
|
||
[ -f "$1" ] || return 0
|
||
tr '\n' ' ' < "$1" | tr ',' '\n' \
|
||
| sed -n "s/.*\"$2\"[[:space:]]*:[[:space:]]*\"\([^\"]*\)\".*/\1/p" | head -n1
|
||
}
|
||
|
||
# 本機實際載入版本：先取該 plugin 的 installPath，再讀那個目錄下的 plugin.json。
|
||
# 只認 installPath 底下那份檔案。註冊在 installed_plugins.json 的 version 欄位不當備援：
|
||
# 註冊值可能比實際載入的版本新，拿它來比對會放過真正被載入的舊版，護欄形同虛設。
|
||
# 讀不到那份檔案就當「查不到本機載入版本」，由呼叫端安靜放行。
|
||
local_version() { # $1=domain
|
||
[ -f "$REG" ] && [ -r "$REG" ] || return 0
|
||
_seg=$(tr -d '\n' < "$REG" \
|
||
| sed -n "s/.*\"jsc-$1@jsc\"[[:space:]]*:[[:space:]]*\[\([^]]*\)\].*/\1/p")
|
||
[ -n "$_seg" ] || return 0
|
||
_path=$(printf '%s' "$_seg" | tr ',' '\n' \
|
||
| sed -n 's/.*"installPath"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)
|
||
[ -n "$_path" ] || return 0
|
||
file_json_str "$_path/plugin.json" version
|
||
}
|
||
|
||
# 遠端站台與 owner：從已註冊的 jsc marketplace 來源推導，其次 GITEA_HOST。
|
||
# 印出「{host} {owner}」；推導不出來時 host 為空字串。
|
||
remote_host_owner() {
|
||
_url=""
|
||
if [ -f "$MK" ]; then
|
||
_url=$(tr -d '\n' < "$MK" | sed -n 's/.*"jsc"[[:space:]]*:[[:space:]]*{//p' \
|
||
| tr ',' '\n' \
|
||
| sed -n 's/.*"url"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)
|
||
fi
|
||
_h=$(printf '%s' "$_url" | sed -n 's#^\(https\{0,1\}://[^/]*\)/.*#\1#p')
|
||
_o=$(printf '%s' "$_url" | sed -n 's#^https\{0,1\}://[^/]*/\([^/]*\)/.*#\1#p')
|
||
if [ -z "$_h" ] || [ -z "$_o" ]; then
|
||
_h="${GITEA_HOST:-}"; _o="${JSC_GITEA_OWNER:-plugins}"
|
||
fi
|
||
printf '%s %s' "$_h" "$_o"
|
||
}
|
||
|
||
# 遠端發佈版本：一律經由 jsc-gitea 的 gitea.sh（技能準則），它會帶 GITEA_TOKEN，
|
||
# 並在缺 token 或 401／403 時退回 tea 的登入金鑰，私有存取庫才讀得到。
|
||
# 不指定 ref：Gitea 的 raw 端點預設就取該存取庫的預設分支，比在這裡寫死分支名準。
|
||
# 查不到就回傳空字串，由呼叫端放行。
|
||
remote_version() { # $1=domain $2=host $3=owner
|
||
_gsh=$(jsc_gitea_sh) || return 0
|
||
_v=""
|
||
for _try in 1 2; do # 暫時性網路失敗不該誤判成版本問題，失敗重試一次
|
||
_body=$(GITEA_HOST="$2" sh "$_gsh" api GET "/repos/$3/$1/raw/plugin.json" 2>/dev/null) \
|
||
&& _v=$(printf '%s' "$_body" | tr '\n' ' ' | tr ',' '\n' \
|
||
| sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)
|
||
[ -n "$_v" ] && break
|
||
sleep 1
|
||
done
|
||
printf '%s' "$_v"
|
||
}
|
||
|
||
TTL="${JSC_VERSION_TTL:-600}"
|
||
cache_root="$JSC_HOME/version-cache"
|
||
|
||
cache_cli() {
|
||
_cli=$(cli_name | sed 's/[^A-Za-z0-9._-]/_/g')
|
||
[ -n "$_cli" ] || _cli=unknown
|
||
printf '%s' "$_cli"
|
||
}
|
||
|
||
cache_file() { # $1=domain
|
||
printf '%s/%s/%s' "$cache_root" "$(cache_cli)" "$1"
|
||
}
|
||
|
||
legacy_cache_file() { # $1=domain
|
||
printf '%s/%s' "$cache_root" "$1"
|
||
}
|
||
|
||
# 帶快取的遠端版本查詢。hook 與 report 共用同一份快取與同一個 TTL：
|
||
# report 每個 domain 各打一次網路（還帶重試），/jsc-cli:deploy 一跑就是全部 domain，
|
||
# 不共用快取等於每次部署都付一輪網路成本。同主機的不同 CLI 不共用快取，避免其中一支
|
||
# 讀到另一支留下的檢查紀錄。
|
||
cached_remote_version() { # $1=domain $2=host $3=owner
|
||
_cache=$(cache_file "$1")
|
||
_legacy=$(legacy_cache_file "$1")
|
||
if [ ! -f "$_cache" ] && [ -f "$_legacy" ]; then
|
||
mkdir -p "${_cache%/*}" 2>/dev/null || true
|
||
cat "$_legacy" > "$_cache" 2>/dev/null || true
|
||
fi
|
||
_now=$(now_epoch)
|
||
if [ -f "$_cache" ]; then
|
||
_cv=$(cut -d' ' -f1 "$_cache" 2>/dev/null)
|
||
_ca=$(cut -d' ' -f2 "$_cache" 2>/dev/null)
|
||
if [ -n "$_cv" ] && [ -n "$_ca" ] && [ $((_now - _ca)) -lt "$TTL" ]; then
|
||
printf '%s' "$_cv"; return 0
|
||
fi
|
||
fi
|
||
_rv=$(remote_version "$1" "$2" "$3")
|
||
if [ -n "$_rv" ]; then
|
||
mkdir -p "${_cache%/*}" 2>/dev/null || true
|
||
printf '%s %s\n' "$_rv" "$_now" > "$_cache" 2>/dev/null || true
|
||
fi
|
||
printf '%s' "$_rv"
|
||
}
|
||
|
||
# 語意化比較：印出 -1（$1 落後）、0（相等）、1（$1 超前）
|
||
ver_cmp() { # $1=版本 A $2=版本 B
|
||
awk -v a="$1" -v b="$2" '
|
||
BEGIN {
|
||
n = split(a, x, "."); m = split(b, y, ".")
|
||
for (i = 1; i <= 3; i++) {
|
||
xi = (i <= n ? x[i] + 0 : 0); yi = (i <= m ? y[i] + 0 : 0)
|
||
if (xi < yi) { print -1; exit }
|
||
if (xi > yi) { print 1; exit }
|
||
}
|
||
print 0
|
||
}'
|
||
}
|
||
|
||
# ── report：一次比對所有已安裝的 jsc plugin（非 hook 模式，不讀 stdin）
|
||
if [ "${1:-}" = "report" ]; then
|
||
# 註冊檔不存在或讀不到就明講。這裡不能只印 behind 0：呼叫端會把它讀成「都是最新」，
|
||
# 於是把「這台機器無法做版本檢查」誤報成「不用更新」。
|
||
# 舊版用 `tr -d '\n' < "$REG" 2>/dev/null`，那個 2>/dev/null 只蓋住 tr 的 stderr，
|
||
# 蓋不住 shell 開檔失敗的訊息，所以沒裝 Claude 的機器會先漏一行 cannot open。
|
||
if [ ! -f "$REG" ] || [ ! -r "$REG" ]; then
|
||
printf 'noregistry\t%s\n' "$REG"
|
||
printf 'behind\t0\n'
|
||
exit 0
|
||
fi
|
||
ho=$(remote_host_owner)
|
||
r_host=$(printf '%s' "$ho" | cut -d' ' -f1)
|
||
r_owner=$(printf '%s' "$ho" | cut -d' ' -f2)
|
||
behind=0
|
||
domains=$(tr -d '\n' < "$REG" | tr ',' '\n' \
|
||
| sed -n 's/.*"jsc-\([a-z0-9][a-z0-9-]*\)@[^"]*"[[:space:]]*:.*/\1/p' | sort -u)
|
||
for d in $domains; do
|
||
lv=$(local_version "$d")
|
||
rv=""
|
||
[ -n "$r_host" ] && rv=$(cached_remote_version "$d" "$r_host" "$r_owner")
|
||
if [ -z "$rv" ]; then
|
||
st="查詢失敗"
|
||
else
|
||
case "$(ver_cmp "$lv" "$rv")" in
|
||
-1) st="落後"; behind=$((behind + 1)) ;;
|
||
1) st="超前" ;;
|
||
*) st="最新" ;;
|
||
esac
|
||
fi
|
||
printf '%s\t%s\t%s\t%s\n' "$d" "${lv:-?}" "${rv:-?}" "$st"
|
||
done
|
||
printf 'behind\t%s\n' "$behind"
|
||
exit 0
|
||
fi
|
||
|
||
read_stdin
|
||
|
||
[ "${JSC_VERSION_GUARD:-}" = "off" ] && exit 0
|
||
|
||
# 輸入相容：stdin JSON（Claude 格式）與環境變數（其他四支 CLI 接線時設定）都要收。
|
||
# 只讀 stdin 的話，用環境變數餵資料的 CLI 一律拿到空值，檢查會整支靜靜放行。
|
||
# 兩者都缺才是真的沒資料，那時照舊安靜降級 exit 0。
|
||
tool="${JSC_TOOL_NAME:-${TOOL_NAME:-$(json_str tool_name)}}"
|
||
[ -z "$tool" ] || [ "$tool" = "Skill" ] || exit 0
|
||
|
||
skill="${JSC_SKILL:-${SKILL:-$(json_str skill)}}"
|
||
[ -n "$skill" ] || exit 0
|
||
|
||
# 只管本技能組（jsc-{domain}:{name}）
|
||
case "$skill" in
|
||
jsc-*:*) ;;
|
||
*) exit 0 ;;
|
||
esac
|
||
|
||
domain=${skill#jsc-}
|
||
domain=${domain%%:*}
|
||
[ -n "$domain" ] || exit 0
|
||
|
||
# 豁免清單
|
||
case "$skill" in
|
||
jsc-cli:deploy|jsc-hooks:hooks-install|jsc-cli:models|jsc-meta:*|jsc-ask:ask|jsc-gitea:wiki) exit 0 ;;
|
||
esac
|
||
|
||
# 更新指令依實際 CLI 給。印別的 CLI 的指令等於沒給指令，使用者照著打只會失敗。
|
||
update_cmd() { # $1=domain
|
||
case "$(cli_name)" in
|
||
claude)
|
||
printf 'claude plugin marketplace update jsc && claude plugin update jsc-%s@jsc' "$1" ;;
|
||
codex)
|
||
printf 'codex plugin marketplace upgrade jsc' ;;
|
||
copilot)
|
||
printf 'copilot plugin marketplace update jsc && copilot plugin update jsc-%s@jsc' "$1" ;;
|
||
antigravity)
|
||
printf 'git -C ~/plugins/%s pull && agy plugin uninstall jsc-%s && agy plugin install ~/plugins/%s' "$1" "$1" "$1" ;;
|
||
kiro)
|
||
printf 'kiro-cli plugin marketplace update jsc && kiro-cli plugin update jsc-%s@jsc' "$1" ;;
|
||
*)
|
||
printf '用你的 CLI 的 plugin 更新指令更新 jsc-%s@jsc' "$1" ;;
|
||
esac
|
||
}
|
||
|
||
deny() { # $1=訊息
|
||
printf '[jsc][版本檢查][ERR]：%s\n' "$1" >&2
|
||
printf '更新指令：%s\n' "$(update_cmd "$domain")" >&2
|
||
printf '更新整組：/jsc-cli:deploy ｜ 確定要略過檢查：JSC_VERSION_GUARD=off\n' >&2
|
||
exit 2
|
||
}
|
||
|
||
# 讀不到本機實際載入版本就放行：沒有版本證據時擋下等於停掉每一次技能呼叫
|
||
local_ver=$(local_version "$domain")
|
||
[ -n "$local_ver" ] || exit 0
|
||
|
||
ho=$(remote_host_owner)
|
||
host=$(printf '%s' "$ho" | cut -d' ' -f1)
|
||
owner=$(printf '%s' "$ho" | cut -d' ' -f2)
|
||
[ -n "$host" ] || exit 0
|
||
|
||
# 遠端版本（走 hook 與 report 共用的快取與 TTL）
|
||
remote_ver=$(cached_remote_version "$domain" "$host" "$owner")
|
||
[ -n "$remote_ver" ] || exit 0
|
||
|
||
# 只擋「本機 < 遠端」這一種情況
|
||
[ "$(ver_cmp "$local_ver" "$remote_ver")" = "-1" ] || exit 0
|
||
deny "jsc-$domain 本機版本 $local_ver 落後遠端發佈版本 $remote_ver，本次技能呼叫已擋下"
|