diff --git a/RELEASE-CHECKLIST.md b/RELEASE-CHECKLIST.md new file mode 100644 index 0000000..1c5b1c4 --- /dev/null +++ b/RELEASE-CHECKLIST.md @@ -0,0 +1,61 @@ +# RELEASE-CHECKLIST — 出貨清單（沒有 GitHub Actions，每個 target 分開推，照順序不漏） + +> 為什麼要這份：沒有 CI，deploy 是「一個個分開」的動作（git / CF workers / npm CLI）。 +> 漏任一步就會「有些新有些舊」——壓測踩過兩次： +> - 第一次：CLI 改了但 npm 沒發 → 用戶 npm 裝到舊 CLI。 +> - 第二次（階段 6）：cypher 改了但**沒推 main** → `acr init` 從 origin/main codeload 抓到**舊 worker** → 薄殼打不存在的 API（seed 404）。 +> +> 核心鐵則：**self-hosted `acr init` 從 `origin/main` 抓 worker 源。所以「git push main」必須在「部署」之前。** +> 順序錯了 = deploy 出去的 prod 是新的，但 self-hosted 用戶裝到的是舊的。 + +--- + +## 正確順序（照做不會忘） + +### 0. 改完 code，先驗證 +- [ ] 三端 typecheck 綠：`cd cli && npx tsc --noEmit`、`cd cypher-executor && npx tsc --noEmit`、`cd mcp && npx tsc --noEmit` +- [ ] 動到的 .sh：`bash -n scripts/<檔>.sh` + +### 1. ⬆️ 先 git commit + push（**必須在 deploy 之前**） +- [ ] `git add -A`（確認 `.env` / secret 沒被加：`git diff --cached --name-only | grep -iE '\.env|secret|token'` 應空） +- [ ] `git commit -m "..."` +- [ ] `git push origin main` +- 理由：self-hosted 從 `origin/main` codeload 抓 worker。沒先 push → 用戶抓到舊碼。 + +### 2. ✅ 跑出貨前檢查（會擋住「git 沒同步」） +- [ ] `bash scripts/check-release.sh` → 必須全綠（含「0. Git 同步」段）。 + - 紅燈「領先 origin/main N commit 未 push」= 回步驟 1。 + - 此腳本 git 未同步會 `exit 1`，是 deploy 的前置閘。 + +### 3. 🚀 deploy（worker + CLI npm） +- [ ] Node ≥ 20（本機若預設舊版：`export PATH="$HOME/.nvm/versions/node/v22.21.0/bin:$PATH"`） +- [ ] `bash scripts/local-deploy.sh --all`（或不帶 `--all` 只 deploy diff） + - 此腳本**會先自動跑步驟 2 的 git 閘**；未過直接拒絕 deploy（要強推設 `SKIP_GIT_CHECK=true`，自負風險）。 + - worker 走 `wrangler deploy`；CLI 走 `npm publish`（版本未 bump 會自動 patch +1 + 寫 CHANGELOG）。 + - npm publish 需 `npm login` 或 `.env` 的 `NPM_API_TOKEN`（authToken）。 + +### 4. 🔁 deploy 後線上驗證（確認新碼真的上去了） +- [ ] `curl https://cypher.arcrun.dev/health` → 200 +- [ ] 改了 cypher 路由時，**實際打那條新路由**確認存在（例：`curl -X POST https://cypher.arcrun.dev/init/seed`、`curl https://cypher.arcrun.dev/recipes` 應非空）。 + ← 這步就是階段 6 的教訓：別只看「部署成功」，要打新端點確認。 +- [ ] 改了 CLI：`npm view arcrun version` == `cli/package.json` version。 +- [ ] landing 有改：確認 arcrun.dev 更新。 + +### 5. 📣 通知 / 收尾 +- [ ] 若是回應壓測：到壓測報告加「開發者回覆」+ 請壓測者重跑。 + +--- + +## 一眼對照表：每個 target 怎麼推、誰依賴它 + +| Target | 推法 | 誰依賴「它在 origin/main」 | +|---|---|---| +| **git origin/main** | `git push origin main` | **self-hosted `acr init` codeload 抓這裡的 worker 源** → 必須最先 | +| CF workers（26 個含 mcp） | `local-deploy.sh`（wrangler deploy） | 平台 prod；self-hosted 自己 deploy | +| CLI（npm `arcrun`） | `local-deploy.sh` 第 6 段 / `cd cli && npm publish` | 用戶 `npm i -g arcrun` | +| landing（arcrun.dev） | `cd landing && wrangler pages deploy` | 訪客 | + +## 常見漏失（自我檢查） +- ❌ 「我 deploy 了 prod cypher 但忘了 push main」→ self-hosted 用戶 init 抓舊碼。**先 push 再 deploy。** +- ❌ 「改了 CLI 但版本沒 bump」→ npm publish 跳過（同版）。`local-deploy.sh` 會自動 bump，但手動 publish 時要記得。 +- ❌ 「改了 cypher 路由只看到『部署成功』就收工」→ 要實際 curl 新路由確認（步驟 4）。 diff --git a/scripts/check-release.sh b/scripts/check-release.sh index a0a777e..424aacc 100755 --- a/scripts/check-release.sh +++ b/scripts/check-release.sh @@ -24,6 +24,38 @@ echo "" echo "═══ arcrun release 狀態檢查（release.feature 佐證）═══" echo "" +# ── 0. Git 同步（最關鍵：self-hosted 從 origin/main codeload 抓 worker）────── +# 壓測階段 6 抓到的漂移：CLI 新（npm）但 worker 舊（main 沒推 init-seed）→ acr init +# 從 main 抓到舊 cypher → 薄殼打不存在的 API → 404。 +# ∴ deploy 前 git 必須先 push main，否則 self-hosted 用戶裝到舊碼。 +echo "【0. Git 同步（deploy 前必過——self-hosted 從 origin/main 抓 worker 源）】" +GIT_BLOCK=0 +if git rev-parse --git-dir >/dev/null 2>&1; then + BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null) + DIRTY=$(git status --porcelain 2>/dev/null | grep -v '^?? ' | head -1) + if [ -n "$DIRTY" ]; then + err "工作目錄有未 commit 的變動 → deploy 前先 commit（否則部署的不是 GitHub 上的碼）" + GIT_BLOCK=1 + else + ok "工作目錄乾淨（無未 commit 追蹤檔變動）" + fi + # local main vs origin/main + git fetch origin "$BRANCH" --quiet 2>/dev/null || true + AHEAD=$(git rev-list --count "origin/$BRANCH..$BRANCH" 2>/dev/null || echo "?") + BEHIND=$(git rev-list --count "$BRANCH..origin/$BRANCH" 2>/dev/null || echo "?") + if [ "$AHEAD" = "0" ] && [ "$BEHIND" = "0" ]; then + ok "$BRANCH 與 origin/$BRANCH 同步（self-hosted codeload 會抓到最新 worker）" + elif [ "$AHEAD" != "0" ] && [ "$AHEAD" != "?" ]; then + err "$BRANCH 領先 origin/$BRANCH $AHEAD 個 commit 未 push → **deploy 前先 git push**（否則 self-hosted 裝到舊 worker，重演壓測階段 6 的 seed 404）" + GIT_BLOCK=1 + else + warn "$BRANCH vs origin/$BRANCH：ahead=$AHEAD behind=$BEHIND（確認狀態）" + fi +else + info "非 git repo，跳過 git 同步檢查" +fi +echo "" + # ── 1. CF Worker 部署單位（由 scripts/local-deploy.sh 掃描部署）────────── # 註：GH Actions 2026-05-16 停用、公開 repo 已移除 .github/，現行 deploy 走 local-deploy.sh。 echo "【CF Workers（scripts/local-deploy.sh 掃 wrangler.toml 後 wrangler deploy）】" @@ -87,5 +119,11 @@ else fi echo "" -echo "═══ 完成。⚠ = 需注意；· = 資訊；✗ = 失敗 ═══" +if [ "$GIT_BLOCK" = "1" ]; then + echo "═══ ✗ Git 未同步 — deploy 前必須先 commit + git push（見上「0. Git 同步」）═══" + echo " 流程見 RELEASE-CHECKLIST.md。push 完再跑本檢查確認全綠。" + echo "" + exit 1 +fi +echo "═══ ✓ 可 deploy。⚠ = 需注意；· = 資訊；✗ = 失敗。流程見 RELEASE-CHECKLIST.md ═══" echo "" diff --git a/scripts/local-deploy.sh b/scripts/local-deploy.sh index 5774c68..fb249db 100644 --- a/scripts/local-deploy.sh +++ b/scripts/local-deploy.sh @@ -149,6 +149,22 @@ if [[ "$DRY_RUN" == true ]]; then exit 0 fi +# ── 3.5 Git 同步前置閘（壓測階段 6 教訓：deploy-from-committed）──────────────── +# self-hosted `acr init` 從 origin/main codeload 抓 worker 源。若本機領先 main 未 push， +# 部署 prod 用的是新碼但 self-hosted 用戶抓到舊碼 → 薄殼打不存在的 API（seed 404）。 +# ∴ 實際 deploy 前強制 git 同步檢查；未過用 --skip-git-check 可強制略過（自負風險）。 +if [[ "${SKIP_GIT_CHECK:-false}" != "true" ]]; then + echo "" + echo "🔎 Git 同步前置檢查（deploy 前必過；要略過設 SKIP_GIT_CHECK=true）..." + if ! bash scripts/check-release.sh >/tmp/arcrun-release-check.txt 2>&1; then + grep -E "✗|⚠|領先|未 commit|Git 未同步" /tmp/arcrun-release-check.txt | sed 's/^/ /' + echo "❌ Git 未同步 → 先 commit + git push 再 deploy（見 RELEASE-CHECKLIST.md）。" + echo " （確定要在未 push 狀態 deploy？ SKIP_GIT_CHECK=true bash scripts/local-deploy.sh ...）" + exit 1 + fi + echo " ✓ Git 已同步，繼續 deploy" +fi + # ── 4. wrangler whoami 健康檢查 ────────────────────────────────────────────── # 隨便挑一個 worker dir 跑 whoami（pnpm 需要在 npm package 內）