feat(deploy): update 前檢查 jsc requires 相依版本

README.md

@@ -24,6 +24,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
 | --- | --- |
 | `tools/detect-clis.sh` | 列出已安裝的 AI CLI 與執行檔路徑（TSV：name / path / version；antigravity 的執行檔為 `agy`、kiro 為 `kiro-cli`） |
 | `tools/deploy.sh` | 對單一 CLI 執行安裝、更新或解除安裝（`deploy.sh [-n] {mode} {cli} {domain}...`，mode 為 install / update / uninstall）；印出每個指令與其結束碼，最後一行 `result` 標 ok 或 fail。`-n` 只印指令不執行。上表五個 CLI 的指令差異全部收在這支腳本裡。install 或 update 全數成功時，收尾轉呼叫 `jsc-hooks` 的 `restart-gate.sh require` 掛上重啟閘門，並印一行 `restart` 標出狀態檔位置；uninstall 不寫。尋找 `restart-gate.sh` 時優先用 `$JSC_HOME/current/jsc-hooks`、本地 clone 與 Kiro skills，最後才掃各 CLI 快取，避免部署收尾綁死單一 CLI 的版號路徑。狀態檔的路徑、格式與判讀全在 `restart-gate.sh`，這支腳本不自己拼——格式只留一個真實來源。站台取自 `GITEA_HOST`，本地 clone 目錄取自 `JSC_LOCAL_PLUGINS`，兩者的預設值見下表 |
+| `tools/check-requires.sh` | `check-requires.sh {cli} {manifest}` 檢查 manifest 的 `jsc.requires` 最低版本。沒有宣告就通過；版本不符或缺相依 plugin 就回 `status=blocked`。`deploy.sh update` 在每個 domain 更新前呼叫它，不符就跳過該 domain 並列出原因 |
 | `tools/write-guides.sh` | 產生這台機器專屬的更新指引 `$JSC_HOME/update-guide.md` 與移除指引 `$JSC_HOME/remove-guide.md`（`write-guides.sh [-n] {install\|update} {domain}...`），一輪部署跑一次。CLI 清單取自 `detect-clis.sh`，每支 CLI 的指令字面直接取自 `deploy.sh -n` 的輸出，所以指引寫的就是實際會跑的指令；kiro 走不走本地複製退路也依實際偵測結果標注 |
 | `tools/list-models.sh` | 讀各 CLI 設定檔列出模型（TSV：cli / model / in-use）；設定檔缺失就不輸出該 CLI 的列，一律 exit 0。設定檔位置只寫在這支腳本裡 |
 | `tools/model-config.sh` | 解析 SDLC 各階段的偏好模型鏈（`get {stage}`、`list`、`resolve {stage}` 印出目前 CLI 可用的第一個模型）；專案 `.jsc/models` 優先於 `$JSC_HOME/models.conf`，格式見 `references/model-tags.md`。鏈只影響建議與偏好順序，不影響閘門放行 |
@@ -48,7 +49,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
 
 ### `deploy`
 
-技能庫批次安裝、更新、解除安裝：偵測 CLI → **先比對各 plugin 的本機與已發佈版本並列表，只要有任一個落後就把「更新」設為推薦選項** → 決策樹選模式 → 每個 CLI 一個 sub agent 呼叫 `tools/deploy.sh` 執行原生 plugin 指令（統一 marketplace `jsc`，token `jsc-{domain}@jsc`）→ install、update 後呼叫 `jsc-hooks:hooks-install`，並把每支 CLI 的 smoke 結果納入部署成敗。domain 名單動態取自 `plugins/meta` 的 marketplace.json，不硬編碼。
+技能庫批次安裝、更新、解除安裝：偵測 CLI → **先比對各 plugin 的本機與已發佈版本並列表，只要有任一個落後就把「更新」設為推薦選項** → 決策樹選模式 → 每個 CLI 一個 sub agent 呼叫 `tools/deploy.sh` 執行原生 plugin 指令（統一 marketplace `jsc`，token `jsc-{domain}@jsc`）→ update 前逐一檢查 `jsc.requires`，版本不符就跳過該 domain 並回報缺哪一版 → install、update 後呼叫 `jsc-hooks:hooks-install`，並把每支 CLI 的 smoke 結果納入部署成敗。domain 名單動態取自 `plugins/meta` 的 marketplace.json，不硬編碼。
 
 ### `doctor`
 

skills/deploy/SKILL.md

@@ -21,7 +21,7 @@ description: Batch install, update, or uninstall the whole jsc skill set on ever
 4. Get the domain list (**never hardcode it**; this skill follows automatically when domains are added or removed): read `plugins[].name` from the unified marketplace via
    `jsc-gitea/tools/gitea.sh api GET /repos/plugins/meta/raw/.claude-plugin/marketplace.json`.
    The marketplace is unified as `jsc`; the install token is `jsc-{domain}@jsc`. Each `plugins[].name` already carries the `jsc-` prefix (e.g. `jsc-ask`) — pass it to `tools/deploy.sh` as-is, prefixed or not; the script normalizes it. Done when the domain list comes from that response and holds at least one name.
-5. Run `tools/deploy.sh {mode} {cli} {domain}...` once per detected CLI, passing the whole domain list in one call so the marketplace command runs only once. This step **MUST run as a sub agent** (one sub agent per CLI). The script prints `cmd` and `exit` lines for every command, then one `result` line; `-n` prints the commands without running them. Antigravity cannot install from a Gitea URL, so the script clones each domain into the local plugin directory (`JSC_LOCAL_PLUGINS`, default `$JSC_HOME/plugins`) and installs from that path — keep that clone, because update pulls the same one. That default deliberately avoids a development checkout: when the directory holds uncommitted changes or unpushed commits, the script prints a `skip` line, leaves the tree untouched, and installs the on-disk content. Done when every detected CLI has reported an exit status for every command it ran.
+5. Run `tools/deploy.sh {mode} {cli} {domain}...` once per detected CLI, passing the whole domain list in one call so the marketplace command runs only once. This step **MUST run as a sub agent** (one sub agent per CLI). The script prints `cmd` and `exit` lines for every command, one `requires` line before each domain update, and one `result` line at the end; `-n` prints the commands without running them. On update, `tools/check-requires.sh {cli} {manifest}` checks each domain's `jsc.requires` before that domain is updated. A missing or too-old required jsc plugin prints a `skip` line and leaves that domain untouched. Antigravity cannot install from a Gitea URL, so the script clones each domain into the local plugin directory (`JSC_LOCAL_PLUGINS`, default `$JSC_HOME/plugins`) and installs from that path — keep that clone, because update pulls the same one. That default deliberately avoids a development checkout: when the directory holds uncommitted changes or unpushed commits, the script prints a `skip` line, leaves the tree untouched, and installs the on-disk content. Done when every detected CLI has reported an exit status for every command it ran, and every skipped domain has a dependency reason or local-tree reason.
 6. After install or update, call `jsc-hooks:hooks-install` to rewire the hooks. The hook installer must refresh `$JSC_HOME/current/jsc-hooks` and must run `tools/wire-cli.sh smoke {cli}` for every detected CLI. Treat any `No such file` in those smoke results as a failed update and report it; do not let the deploy finish as successful when a rewritten hook path cannot execute. Done when hooks-install reports purge, wiring, smoke and scan results for each detected CLI, and every smoke result is either `status=ok` or explicitly reported as the update failure.
 7. After install or update, run `tools/write-guides.sh {mode} {domain}...` **once for the whole machine**, after every CLI in step 5 has finished. It rewrites `$JSC_HOME/update-guide.md` and `$JSC_HOME/remove-guide.md` from the live detection result, so the later update and removal runs have the real commands for this machine. Skip it for `uninstall`: the guides describe an installed skill set. Done when the script printed a `wrote` line for both files.
 8. Report the result and any failure reason for every CLI × mode, plus every `skip` line and every CLI that could not be version-checked in step 2. Done when every detected CLI appears in the report with its `result` status.

tools/check-requires.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env sh
+# check-requires.sh — Check jsc.requires before updating one plugin.
+set -u
+
+usage() {
+  echo "用法：check-requires.sh {claude|codex|copilot|antigravity|kiro} {manifest}" >&2
+  exit 2
+}
+
+[ "$#" -eq 2 ] || usage
+CLI=$1
+MANIFEST=$2
+
+case "$CLI" in
+  claude|codex|copilot|antigravity|kiro) ;;
+  *) usage ;;
+esac
+
+[ -f "$MANIFEST" ] || {
+  printf 'status=blocked reason=找不到 manifest：%s\n' "$MANIFEST"
+  exit 1
+}
+
+JSC_HOME_DIR="${JSC_HOME:-$HOME/.jsc}"
+LOCAL_DIR="${JSC_LOCAL_PLUGINS:-$JSC_HOME_DIR/plugins}"
+KIRO_SKILLS="${JSC_KIRO_SKILLS:-$HOME/.kiro/skills}"
+
+python3 - "$CLI" "$MANIFEST" "$LOCAL_DIR" "$KIRO_SKILLS" <<'PY'
+import glob
+import json
+import os
+import re
+import sys
+
+cli, manifest, local_dir, kiro_skills = sys.argv[1:5]
+
+try:
+    with open(manifest, encoding="utf-8") as fh:
+        data = json.load(fh)
+except Exception as exc:
+    print(f"status=blocked reason=manifest 不是有效 JSON：{manifest}：{exc}")
+    sys.exit(1)
+
+requires = ((data.get("jsc") or {}).get("requires") or {})
+if not requires:
+    print("status=ok reason=沒有宣告相依版本")
+    sys.exit(0)
+
+def version_tuple(value):
+    value = str(value or "").strip()
+    parts = value.split(".")
+    out = []
+    for part in parts[:3]:
+        match = re.match(r"^(\d+)", part)
+        out.append(int(match.group(1)) if match else 0)
+    while len(out) < 3:
+        out.append(0)
+    return tuple(out)
+
+def current_version(plugin):
+    domain = plugin[4:] if plugin.startswith("jsc-") else plugin
+    candidates = []
+    patterns = []
+    if cli == "claude":
+        registry = os.path.expanduser("~/.claude/plugins/installed_plugins.json")
+        try:
+            with open(registry, encoding="utf-8") as fh:
+                entries = (json.load(fh).get("plugins") or {}).get(f"jsc-{domain}@jsc") or []
+            for entry in entries:
+                path = os.path.join(entry.get("installPath") or "", "plugin.json")
+                with open(path, encoding="utf-8") as fh:
+                    version = json.load(fh).get("version", "")
+                if version:
+                    return version, path
+        except Exception:
+            pass
+        patterns.append(os.path.expanduser(f"~/.claude/plugins/cache/jsc/jsc-{domain}/*/plugin.json"))
+    elif cli == "codex":
+        patterns.append(os.path.expanduser(f"~/.codex/plugins/cache/jsc/jsc-{domain}/*/plugin.json"))
+    elif cli == "copilot":
+        patterns.append(os.path.expanduser(f"~/.copilot/installed-plugins/jsc/jsc-{domain}/plugin.json"))
+    elif cli == "antigravity":
+        patterns.append(os.path.join(local_dir, domain, "plugin.json"))
+        patterns.append(os.path.expanduser(f"~/.antigravity/plugins/jsc-{domain}/plugin.json"))
+    elif cli == "kiro":
+        patterns.append(os.path.join(kiro_skills, f"jsc-{domain}", "plugin.json"))
+
+    for pattern in patterns:
+        for path in glob.glob(pattern):
+            try:
+                with open(path, encoding="utf-8") as fh:
+                    version = json.load(fh).get("version", "")
+            except Exception:
+                continue
+            if version:
+                candidates.append((version_tuple(version), version, path))
+    if not candidates:
+        return "", ""
+    candidates.sort()
+    return candidates[-1][1], candidates[-1][2]
+
+failures = []
+for plugin, constraint in sorted(requires.items()):
+    required = str(constraint).strip()
+    minimum = required[2:].strip() if required.startswith(">=") else required
+    current, path = current_version(plugin)
+    if not current:
+        failures.append(f"{plugin} 需要 {required}，目前未安裝")
+        continue
+    if version_tuple(current) < version_tuple(minimum):
+        failures.append(f"{plugin} 需要 {required}，目前 {current}（{path}）")
+
+if failures:
+    print("status=blocked reason=" + "；".join(failures))
+    sys.exit(1)
+
+print("status=ok reason=相依版本符合：" + ", ".join(f"{k} {v}" for k, v in sorted(requires.items())))
+sys.exit(0)
+PY

tools/deploy.sh

@@ -11,6 +11,7 @@
 #   skip<TAB>{domain}<TAB>{原因}                       本地 clone 是開發中的樹，略過 git pull
 #   note<TAB>{cli}<TAB>{原因}                          非逐指令的說明（例：kiro 整批改走複製退路的理由）
 #   restart<TAB>{路徑}                                 這次寫下的重啟狀態檔
+#   requires<TAB>{domain}<TAB>{檢查結果}                update 前的 jsc.requires 檢查
 #   result<TAB>{cli}<TAB>{mode}<TAB>{domain 清單}<TAB>{ok|fail}
 # 結束碼：全部指令成功 0；任一指令失敗 1；參數錯誤 2。skip、note 不算失敗，但呼叫端要據實回報。
 # marketplace 指令一輪只跑一次：install 與 update 先跑，uninstall 最後跑。
@@ -36,6 +37,8 @@
 #   JSC_DEPLOY_DRYRUN   設為 1 等同 -n
 set -u
 
+HERE=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+
 # Gitea 站台一律讀 GITEA_HOST（技能準則指定的變數），未設定才用正本站台。
 HOST="${GITEA_HOST:-https://gitea.jsc.idv.tw}"
 case "$HOST" in http://*|https://*) ;; *) HOST="https://$HOST" ;; esac
@@ -89,6 +92,25 @@ restart_gate_sh() {
   return 1
 }
 
+check_requires() { # $1=domain；0=可更新，1=略過這個 domain
+  [ "$MODE" = update ] || return 0
+  sync_local "$1"
+  manifest="$LOCAL_DIR/$1/plugin.json"
+  out=$(sh "$HERE/check-requires.sh" "$CLI" "$manifest" 2>&1)
+  code=$?
+  printf 'requires\t%s\t%s\n' "$1" "$out"
+  if [ "$code" -eq 0 ]; then
+    return 0
+  fi
+  if [ "$code" -eq 1 ]; then
+    printf 'skip\t%s\t%s\n' "$1" "相依版本不符，未更新：$out"
+    return 1
+  fi
+  FAILED=1
+  printf 'skip\t%s\t%s\n' "$1" "相依版本檢查失敗，未更新：$out"
+  return 1
+}
+
 # 掛上部署後的重啟閘門。狀態檔的路徑、格式與判讀全在 jsc-hooks 的 restart-gate.sh，
 # 這裡只轉呼叫它的 require 子命令，比照 jsc-sdlc 轉呼叫 sdlc-gate.sh wp-lock 的慣例。
 # 兩邊各拼一份格式就會對不上：2026-08-27 這裡曾自己寫四欄 TSV，而 hooks 那端讀的是
@@ -175,7 +197,7 @@ marketplace_cli() { # $1=執行檔
       ;;
     update)
       run "$1" plugin marketplace update jsc
-      for d in $DOMAINS; do run "$1" plugin update "jsc-$d@jsc"; done
+      for d in $DOMAINS; do check_requires "$d" && run "$1" plugin update "jsc-$d@jsc"; done
       ;;
     uninstall)
       for d in $DOMAINS; do run "$1" plugin uninstall "jsc-$d@jsc"; done
@@ -199,7 +221,7 @@ deploy_codex() {
       ;;
     update)
       run "$bin" plugin marketplace upgrade jsc
-      for d in $DOMAINS; do run "$bin" plugin add "jsc-$d@jsc"; done
+      for d in $DOMAINS; do check_requires "$d" && run "$bin" plugin add "jsc-$d@jsc"; done
       ;;
     uninstall)
       for d in $DOMAINS; do run "$bin" plugin remove "jsc-$d@jsc"; done
@@ -217,6 +239,7 @@ deploy_antigravity() {
         run "$bin" plugin install "$LOCAL_DIR/$d"
         ;;
       update)
+        check_requires "$d" || continue
         sync_local "$d"
         run "$bin" plugin uninstall "jsc-$d"
         run "$bin" plugin install "$LOCAL_DIR/$d"
@@ -278,6 +301,7 @@ deploy_kiro() {
           run_soft "$bin" plugin install "jsc-$d@jsc" || kiro_copy "$d"
           ;;
         update)
+          check_requires "$d" || continue
           run_soft "$bin" plugin update "jsc-$d@jsc" || kiro_copy "$d"
           ;;
         uninstall)
@@ -291,7 +315,8 @@ deploy_kiro() {
   printf 'note\tkiro\t%s\n' "此版本 kiro-cli 沒有 plugin 子指令，改走本地複製（git pull 或 clone 後，複製 skills、tools、references、templates、hooks 與 plugin.json）"
   for d in $DOMAINS; do
     case "$MODE" in
-      install|update) kiro_copy "$d" ;;
+      install) kiro_copy "$d" ;;
+      update) check_requires "$d" && kiro_copy "$d" ;;
       uninstall) run rm -rf "$KIRO_SKILLS/jsc-$d" ;;
     esac
   done