diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 0a18d87..2cdeae5 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-cli", - "version": "0.2.1", + "version": "0.2.2", "description": "CLI 偵測、模型能力標籤、子代理派工與技能庫批次部署", "skills": "./skills", "author": { @@ -13,5 +13,11 @@ "cli", "skills", "cross-tool" - ] + ], + "jsc": { + "requires": { + "jsc-gitea": ">=0.1.7", + "jsc-hooks": ">=0.2.8" + } + } } diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 2558af5..b975952 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,12 @@ { "name": "jsc-cli", - "version": "0.2.1", + "version": "0.2.2", "description": "CLI 偵測、模型能力標籤、子代理派工與技能庫批次部署", - "skills": "./skills" + "skills": "./skills", + "jsc": { + "requires": { + "jsc-gitea": ">=0.1.7", + "jsc-hooks": ">=0.2.8" + } + } } diff --git a/README.md b/README.md index f5063df..1f834a7 100644 --- a/README.md +++ b/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` diff --git a/plugin.json b/plugin.json index 11d3fe0..1c9b741 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,12 @@ { "name": "jsc-cli", - "version": "0.2.1", + "version": "0.2.2", "description": "CLI 偵測、模型能力標籤、子代理派工與技能庫批次部署", - "skills": "./skills/" + "skills": "./skills/", + "jsc": { + "requires": { + "jsc-gitea": ">=0.1.7", + "jsc-hooks": ">=0.2.8" + } + } } diff --git a/skills/deploy/SKILL.md b/skills/deploy/SKILL.md index 71d05d9..b145f84 100644 --- a/skills/deploy/SKILL.md +++ b/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. diff --git a/tools/check-requires.sh b/tools/check-requires.sh new file mode 100755 index 0000000..262ef4e --- /dev/null +++ b/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 diff --git a/tools/deploy.sh b/tools/deploy.sh index c0d050a..c7d6c02 100755 --- a/tools/deploy.sh +++ b/tools/deploy.sh @@ -11,6 +11,7 @@ # skip{domain}{原因} 本地 clone 是開發中的樹，略過 git pull # note{cli}{原因} 非逐指令的說明（例：kiro 整批改走複製退路的理由） # restart{路徑} 這次寫下的重啟狀態檔 +# requires{domain}{檢查結果} update 前的 jsc.requires 檢查 # result{cli}{mode}{domain 清單}{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