@jira-deploy/core 1.0.3 → 1.0.4

package/tools/grayrelease.js

@@ -2,9 +2,10 @@
  * Gray Release 相關 tools
  *   - create_grayrelease_ticket
  *   - link_stg_grayrelease
- *   - auto_grayrelease (NEW)
- *   - get_grayrelease_status (NEW)
- *   - continue_grayrelease (NEW)
+ *   - auto_grayrelease
+ *   - deploy_grayrelease
+ *   - get_grayrelease_status
+ *   - continue_grayrelease
  */
 import {
   SYSTEM_CODES,
@@ -22,16 +23,33 @@ import {
   JIRA_DEFAULTS,
   resolveAccountId,
 } from '../constants/index.js';
-import {error, ok, today, getServerList} from './helpers.js';
-import {Poller} from '../poller.js';
-import {handleGetReleaseManager, handleWaitForComment} from './release.js';
-import {handleSendJabberMessage} from './jabber.js';
+import { error, ok, today, getServerList } from './helpers.js';
+import { Poller } from '../poller.js';
+import { handleGetReleaseManager, handleWaitForComment } from './release.js';
+import { handleSendJabberMessage } from './jabber.js';
 
 // ── Flow Definition ──────────────────────────────────────────────
 
 /**
  * GrayRelease 狀態流程定義
  * 每個狀態定義其可能的下一步 transitions
+ *
+ * 完整流程：
+ *   PLANNING → (Accept) → WAIT FOR BUILD → (GrayRelease Build)
+ *   → WAIT FOR BUILD → (Apply to approval) → WAIT APPROVAL
+ *   → (Approve，依環境處理簽核) → WAIT DEPLOY
+ *   → (Switch Execution Node，視上次 CD 部署環境群組 prd/nonPrd 決定是否需要)
+ *   → WAIT DEPLOY → (GrayRelease Deploy) → WAIT DEPLOY → (To Verify)
+ *   → VERIFY → (Verify Success) → MERGE CODE AND TAG → (To Done) → DONE
+ *
+ * 簽核規則：
+ *   - DEV：直接 Approve
+ *   - STG：指派給當日 Release Manager，等待簽核
+ *   - UAT：指派 James Yu 等待留言，再轉給 Solar Chen 等待簽核
+ *
+ * Rebuild 規則：
+ *   VERIFY 狀態只有在使用者明確要求 build/rebuild 時，才可透過 build_ticket({rebuild: true})
+ *   執行 Verify fail 回到 PLANNING 後重新 GrayRelease Build。
  */
 const GRAYRELEASE_FLOW_MAP = {
   'PLANNING': {
@@ -74,8 +92,111 @@ const GRAYRELEASE_FLOW_MAP = {
   },
 };
 
-const SWITCH_EXECUTION_NODE_COMMENT_WINDOW_MS = 5 * 60 * 1000;
-const SWITCH_EXECUTION_NODE_SETTLE_MS = 3 * 60 * 1000;
+function normalizeStatusName(statusName) {
+  return String(statusName ?? '')
+    .trim()
+    .replace(/\s+/g, ' ')
+    .toUpperCase();
+}
+
+function getPollIntervalMs() {
+  return parseInt(process.env.POLL_INTERVAL_MS ?? '30000');
+}
+
+function getPollTimeoutMs() {
+  return parseInt(process.env.POLL_TIMEOUT_MS ?? '3600000');
+}
+
+function progress(ctx, event) {
+  if (typeof ctx.progress === 'function') {
+    ctx.progress(event);
+  }
+}
+
+function isPassingResult(value) {
+  return ['pass', 'passed', 'success', 'succeeded', 'done'].includes(
+    String(value ?? '').trim().toLowerCase(),
+  );
+}
+
+function isFailingResult(value) {
+  return ['fail', 'failed', 'failure', 'error'].includes(
+    String(value ?? '').trim().toLowerCase(),
+  );
+}
+
+async function findTransitionByName(issueKey, transitionName, jira) {
+  const transitions = await jira.getTransitions(issueKey);
+  return transitions.find((transition) => (
+    transition.name.toLowerCase() === transitionName.toLowerCase()
+  ));
+}
+
+async function waitForGrayReleaseResult(issueKey, fieldId, label, jira, onProgress = () => {}) {
+  const intervalMs = getPollIntervalMs();
+  const timeoutMs = getPollTimeoutMs();
+  const startedAt = Date.now();
+  const deadline = Date.now() + timeoutMs;
+  let attempts = 0;
+  let lastValue;
+
+  while (true) {
+    attempts++;
+    const fields = await jira.getIssueFields(issueKey, [fieldId]);
+    const raw = fields[fieldId];
+    lastValue = raw?.value ?? raw; // Jira Select List 回傳物件 {value:'pass',...}，純字串也相容
+    onProgress({
+      phase: 'polling',
+      title: `等待 ${label} 結果`,
+      detail: `${fieldId}: ${lastValue ?? 'empty'}`,
+      issueKey,
+      attempts,
+      elapsedMs: Date.now() - startedAt,
+      timeoutMs,
+      nextPollMs: intervalMs,
+    });
+
+    if (isPassingResult(lastValue)) {
+      return { issueKey, fieldId, result: lastValue, attempts };
+    }
+
+    if (isFailingResult(lastValue)) {
+      throw new Error(`${label} 失敗，${fieldId}: ${lastValue}`);
+    }
+
+    if (Date.now() >= deadline) {
+      throw new Error(`${label} 等待逾時，${fieldId}: ${lastValue ?? 'empty'}`);
+    }
+
+    await sleep(intervalMs);
+  }
+}
+
+function parseToolResult(result) {
+  if (!result || result.isError) {
+    return null;
+  }
+
+  if (result.success || result.data) {
+    return result.data ?? result;
+  }
+
+  const text = result.content
+    ?.filter((item) => item.type === 'text')
+    .map((item) => item.text)
+    .join('\n')
+    .trim();
+
+  if (!text) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
 
 // ── Schema definitions ───────────────────────────────────────────
 export function getGrayReleaseToolDefinitions() {
@@ -133,7 +254,7 @@ export function getGrayReleaseToolDefinitions() {
           },
           stgKeys: {
             type: 'array',
-            items: {type: 'string'},
+            items: { type: 'string' },
             description: '要關聯的 STG 灰度單 key 陣列，例如 ["CID-1234", "CID-1235"]',
           },
         },
@@ -152,6 +273,10 @@ export function getGrayReleaseToolDefinitions() {
             type: 'string',
             description: 'GrayRelease 單 issue key，例如 CID-822',
           },
+          maxBuildRetries: {
+            type: 'number',
+            description: '(選填) Build 失敗最大重試次數，預設 3',
+          },
           autoVerify: {
             type: 'boolean',
             description: '(選填) 是否自動執行 Verify Success（預設 false，需人工確認）',
@@ -159,6 +284,23 @@ export function getGrayReleaseToolDefinitions() {
         },
       },
     },
+    {
+      name: 'deploy_grayrelease',
+      description:
+        '部署既有 GrayRelease 單，與 CD 部署完全分離。使用者說 GrayRelease deploy、部署灰度單時優先使用此 tool；' +
+        '若上下文 issue 是 GrayRelease 且使用者只說 deploy/部署，應先確認是否部署該 GrayRelease 單。' +
+        '此 tool 不會建立 CD 單、不接受 CI 單、不會重新 build；若目前在 Wait for Build 且可 Apply to approval，會往簽核/部署前進，最後停在 VERIFY 等人工驗證。',
+      inputSchema: {
+        type: 'object',
+        required: ['issueKey'],
+        properties: {
+          issueKey: {
+            type: 'string',
+            description: 'GrayRelease 單 issue key，例如 CID-822',
+          },
+        },
+      },
+    },
     {
       name: 'get_grayrelease_status',
       description:
@@ -186,6 +328,10 @@ export function getGrayReleaseToolDefinitions() {
             type: 'string',
             description: 'GrayRelease 單 issue key，例如 CID-822',
           },
+          maxBuildRetries: {
+            type: 'number',
+            description: '(選填) Build 失敗最大重試次數，預設 3',
+          },
           autoVerify: {
             type: 'boolean',
             description: '(選填) 是否自動執行 Verify Success（預設 false，需人工確認）',
@@ -233,13 +379,13 @@ async function findUnlinkedStgGrayReleases(gitBranch, moduleId, jira) {
         return linked?.fields?.issuetype?.id === GR_ISSUE_TYPE;
       });
     })
-    .map((issue) => ({key: issue.key, summary: issue.fields?.summary ?? ''}));
+    .map((issue) => ({ key: issue.key, summary: issue.fields?.summary ?? '' }));
 }
 
 /**
  * 建立 Gray Release 上版單
  */
-export async function handleCreateGrayReleaseTicket(args, {jira, notifier}) {
+export async function handleCreateGrayReleaseTicket(args, { jira, notifier }) {
   try {
     const normalizedArgs = {
       ...args,
@@ -280,14 +426,14 @@ export async function handleCreateGrayReleaseTicket(args, {jira, notifier}) {
     const serverList = getServerList(normalizedArgs.systemCode, envCode, false, normalizedArgs.module) || [];
 
     const fields = {
-      project: {key: JIRA_PROJECT_ID},
-      issuetype: {id: ISSUE_TYPE_IDS.GrayRelease},
+      project: { key: JIRA_PROJECT_ID },
+      issuetype: { id: ISSUE_TYPE_IDS.GrayRelease },
       summary: normalizedArgs.summary ?? autoSummary,
       duedate: today(),
     };
 
     // systemCode
-    fields[GRAY_RELEASE_FIELD_IDS.systemCode] = {value: normalizedArgs.systemCode};
+    fields[GRAY_RELEASE_FIELD_IDS.systemCode] = { value: normalizedArgs.systemCode };
 
     // sign fields
     fields[GRAY_RELEASE_FIELD_IDS.deptManagerSign] = SIGN_VALUES.deptManagerSign;
@@ -296,17 +442,17 @@ export async function handleCreateGrayReleaseTicket(args, {jira, notifier}) {
 
     // env
     if (ENV_CODES[envCode]) {
-      fields[GRAY_RELEASE_FIELD_IDS.env] = {value: envCode};
+      fields[GRAY_RELEASE_FIELD_IDS.env] = { value: envCode };
     }
 
     // dept code
     if (deptStr && DEPT_CODES[deptStr]) {
-      fields[GRAY_RELEASE_FIELD_IDS.deptCode] = {value: deptStr};
+      fields[GRAY_RELEASE_FIELD_IDS.deptCode] = { value: deptStr };
     }
 
     // system module
     if (moduleId) {
-      fields[GRAY_RELEASE_FIELD_IDS.systemModule] = {id: moduleId};
+      fields[GRAY_RELEASE_FIELD_IDS.systemModule] = { id: moduleId };
     }
 
     // jenkins branch
@@ -320,7 +466,7 @@ export async function handleCreateGrayReleaseTicket(args, {jira, notifier}) {
     fields[GRAY_RELEASE_FIELD_IDS.grayReleaseVersion] = grayReleaseVersion;
 
     // cluster deploy (always true)
-    fields[GRAY_RELEASE_FIELD_IDS.clusterDeploy] = {id: FIELD_OPTIONS.clusterDeploy.true};
+    fields[GRAY_RELEASE_FIELD_IDS.clusterDeploy] = { id: FIELD_OPTIONS.clusterDeploy.true };
 
     // cluster list
     fields[GRAY_RELEASE_FIELD_IDS.clusterList] = serverList.join('\n');
@@ -329,7 +475,7 @@ export async function handleCreateGrayReleaseTicket(args, {jira, notifier}) {
     fields[GRAY_RELEASE_FIELD_IDS.grayReleaseNotes] = NOTES_TEMPLATES.grayRelease;
 
     if (normalizedArgs.dryRun) {
-      return ok({dryRun: true, summary: fields.summary, grayReleaseVersion, fields});
+      return ok({ dryRun: true, summary: fields.summary, grayReleaseVersion, fields });
     }
 
     const issue = await jira.createIssue(fields);
@@ -370,9 +516,9 @@ export async function handleCreateGrayReleaseTicket(args, {jira, notifier}) {
 /**
  * 將 STG 灰度單關聯（relates to）到 UAT 灰度單
  */
-export async function handleLinkStgGrayRelease(args, {jira, notifier}) {
+export async function handleLinkStgGrayRelease(args, { jira, notifier }) {
   try {
-    const {uatKey, stgKeys} = args;
+    const { uatKey, stgKeys } = args;
     if (!Array.isArray(stgKeys) || stgKeys.length === 0) {
       return error('stgKeys 不可為空');
     }
@@ -385,7 +531,7 @@ export async function handleLinkStgGrayRelease(args, {jira, notifier}) {
         await jira.linkIssue(stgKey, uatKey, 'Relates');
         linked.push(stgKey);
       } catch (e) {
-        failed.push({key: stgKey, reason: e.message});
+        failed.push({ key: stgKey, reason: e.message });
       }
     }
 
@@ -413,15 +559,21 @@ export async function handleLinkStgGrayRelease(args, {jira, notifier}) {
  * 自動執行 GrayRelease 完整流程
  */
 export async function handleAutoGrayRelease(args, ctx) {
-  const {issueKey} = args;
-  const {jira, notifier} = ctx;
+  const { issueKey } = args;
+  const { jira, notifier } = ctx;
 
   try {
+    progress(ctx, {
+      phase: 'action',
+      title: '開始 GrayRelease 自動流程',
+      issueKey,
+    });
     await notifier.notify(issueKey, '開始自動執行 GrayRelease 流程');
 
     const result = await executeGrayReleaseFlow(
       issueKey,
       {
+        maxBuildRetries: args.maxBuildRetries ?? 3,
         autoVerify: args.autoVerify ?? false,
       },
       ctx,
@@ -437,7 +589,7 @@ export async function handleAutoGrayRelease(args, ctx) {
 /**
  * 查詢 GrayRelease 單當前狀態並給出建議
  */
-export async function handleGetGrayReleaseStatus(args, {jira}) {
+export async function handleGetGrayReleaseStatus(args, { jira }) {
   try {
     const status = await getGrayReleaseStatus(args.issueKey, jira);
     return ok(status);
@@ -446,17 +598,45 @@ export async function handleGetGrayReleaseStatus(args, {jira}) {
   }
 }
 
+/**
+ * 執行 GrayRelease 部署流程，不觸發 rebuild。
+ */
+export async function handleDeployGrayRelease(args, ctx) {
+  const { issueKey } = args;
+  const { jira, notifier } = ctx;
+
+  try {
+    progress(ctx, {
+      phase: 'action',
+      title: '開始 GrayRelease deploy 流程',
+      issueKey,
+    });
+    const result = await executeGrayReleaseDeployFlow(issueKey, ctx);
+    await notifier.notify(issueKey, `GrayRelease deploy 流程結束，目前狀態：${result.finalStatus}`);
+    return ok(result);
+  } catch (err) {
+    await notifier.notify(issueKey, `GrayRelease deploy 失敗: ${err.message}`);
+    return error(`deploy_grayrelease 失敗: ${err.message}`);
+  }
+}
+
 /**
  * 從當前狀態繼續執行 GrayRelease 流程
  */
 export async function handleContinueGrayRelease(args, ctx) {
-  const {issueKey} = args;
-  const {jira, notifier} = ctx;
+  const { issueKey } = args;
+  const { jira, notifier } = ctx;
 
   try {
     const status = await getGrayReleaseStatus(issueKey, jira);
 
     if (status.completed) {
+      progress(ctx, {
+        phase: 'done',
+        title: 'GrayRelease 已完成',
+        issueKey,
+        currentStatus: status.currentStatus,
+      });
       return ok({
         issueKey,
         message: '此 GrayRelease 單已完成（狀態: DONE），無需繼續執行',
@@ -468,10 +648,17 @@ export async function handleContinueGrayRelease(args, ctx) {
       issueKey,
       `從狀態 ${status.currentStatus} 繼續執行 GrayRelease 流程`,
     );
+    progress(ctx, {
+      phase: 'action',
+      title: '繼續 GrayRelease 流程',
+      issueKey,
+      currentStatus: status.currentStatus,
+    });
 
     const result = await executeGrayReleaseFlow(
       issueKey,
       {
+        maxBuildRetries: args.maxBuildRetries ?? 3,
         autoVerify: args.autoVerify ?? false,
       },
       ctx,
@@ -492,6 +679,7 @@ export async function handleContinueGrayRelease(args, ctx) {
 async function getGrayReleaseStatus(issueKey, jira) {
   const issue = await jira.getIssue(issueKey);
   const currentStatus = issue.fields.status.name;
+  const normalizedStatus = normalizeStatusName(currentStatus);
   const summary = issue.fields.summary;
 
   // 查詢環境欄位
@@ -507,7 +695,7 @@ async function getGrayReleaseStatus(issueKey, jira) {
   const availableTransitions = transitions.map((t) => t.name);
 
   // 根據當前狀態查找流程定義
-  const flowDef = GRAYRELEASE_FLOW_MAP[currentStatus];
+  const flowDef = GRAYRELEASE_FLOW_MAP[normalizedStatus];
   const completed = flowDef?.completed === true;
 
   let nextSteps = [];
@@ -526,6 +714,7 @@ async function getGrayReleaseStatus(issueKey, jira) {
     issueKey,
     summary,
     currentStatus,
+    normalizedStatus,
     environment,
     systemCode,
     completed,
@@ -536,11 +725,113 @@ async function getGrayReleaseStatus(issueKey, jira) {
   };
 }
 
+async function executeGrayReleaseDeployFlow(issueKey, ctx) {
+  const { jira, notifier } = ctx;
+  const log = [];
+  const fields = await jira.getIssueFields(issueKey, [
+    GRAY_RELEASE_FIELD_IDS.env,
+    GRAY_RELEASE_FIELD_IDS.systemCode,
+  ]);
+  const environment = fields[GRAY_RELEASE_FIELD_IDS.env]?.value;
+  const systemCode = fields[GRAY_RELEASE_FIELD_IDS.systemCode]?.value;
+
+  if (!environment) {
+    throw new Error('無法讀取 GrayRelease 環境欄位');
+  }
+
+  log.push(`🚀 開始執行 GrayRelease Deploy - 環境: ${environment.toUpperCase()}`);
+
+  while (true) {
+    const issue = await jira.getIssue(issueKey);
+    const currentStatus = issue.fields.status.name;
+    const normalizedStatus = normalizeStatusName(currentStatus);
+    const flowDef = GRAYRELEASE_FLOW_MAP[normalizedStatus];
+
+    log.push(`\n📍 當前狀態: ${currentStatus}`);
+    progress(ctx, {
+      phase: 'action',
+      title: '檢查 GrayRelease deploy 狀態',
+      issueKey,
+      currentStatus,
+    });
+
+    if (flowDef?.completed) {
+      log.push('✅ GrayRelease 流程已完成，無需 deploy');
+      break;
+    }
+
+    if (!flowDef) {
+      log.push(`⚠️ 未知狀態: ${currentStatus}，停止 deploy`);
+      break;
+    }
+
+    if (normalizedStatus === 'PLANNING') {
+      log.push('  執行: Accept');
+      await jira.transitionByName(issueKey, 'Accept');
+      await notifier.notify(issueKey, 'Accept 需求，準備進入部署流程');
+      continue;
+    }
+
+    if (normalizedStatus === 'WAIT FOR BUILD') {
+      const applyTransition = await findTransitionByName(issueKey, 'Apply to approval', jira);
+      if (!applyTransition) {
+        log.push('  ⏸️ 目前仍需 build，deploy_grayrelease 不會觸發 rebuild');
+        break;
+      }
+      log.push('  執行: Apply to approval');
+      await jira.transitionByName(issueKey, 'Apply to approval');
+      await notifier.notify(issueKey, '進入 GrayRelease 部署簽核流程');
+      continue;
+    }
+
+    if (normalizedStatus === 'WAIT APPROVAL') {
+      log.push(`  處理簽核流程 (環境: ${environment})`);
+      const approvalResult = await handleGrayReleaseApproval(issueKey, environment, systemCode, ctx);
+      if (approvalResult.skipped) {
+        log.push(`  ✅ ${approvalResult.reason}`);
+        await jira.transitionByName(issueKey, 'Approve');
+        await notifier.notify(issueKey, 'DEV 環境無需簽核，直接 Approve');
+      } else {
+        log.push(`  ✅ 簽核完成 by ${approvalResult.by}`);
+      }
+      continue;
+    }
+
+    if (normalizedStatus === 'WAIT DEPLOY') {
+      const deployCompleted = await runGrayReleaseDeployStep(issueKey, systemCode, ctx, log);
+      if (!deployCompleted) {
+        break;
+      }
+      continue;
+    }
+
+    if (normalizedStatus === 'VERIFY') {
+      log.push('  ⏸️ 已進入 VERIFY，請人工驗證；若需重 build 請明確執行 build/rebuild');
+      break;
+    }
+
+    if (normalizedStatus === 'MERGE CODE AND TAG') {
+      log.push('  ✅ 已完成部署與驗證，等待合併程式碼與打 tag');
+      break;
+    }
+
+    log.push(`⚠️ 狀態 ${currentStatus} 沒有 deploy 處理邏輯，停止執行`);
+    break;
+  }
+
+  const finalIssue = await jira.getIssue(issueKey);
+  return {
+    issueKey,
+    finalStatus: finalIssue.fields.status.name,
+    log,
+  };
+}
+
 /**
  * 主執行流程：從當前狀態開始，自動執行到完成或需要人工介入
  */
 async function executeGrayReleaseFlow(issueKey, options, ctx) {
-  const {jira, notifier} = ctx;
+  const { jira, notifier } = ctx;
   const log = [];
   let buildAttempts = 0;
 
@@ -549,17 +840,28 @@ async function executeGrayReleaseFlow(issueKey, options, ctx) {
     GRAY_RELEASE_FIELD_IDS.env,
     GRAY_RELEASE_FIELD_IDS.systemCode,
   ]);
-  const environment = normalizeGrayReleaseEnvironment(fields[GRAY_RELEASE_FIELD_IDS.env]);
+  const environment = fields[GRAY_RELEASE_FIELD_IDS.env]?.value;
   const systemCode = fields[GRAY_RELEASE_FIELD_IDS.systemCode]?.value;
 
+  if (!environment) {
+    throw new Error('無法讀取 GrayRelease 環境欄位');
+  }
+
   log.push(`🚀 開始執行 GrayRelease 流程 - 環境: ${environment.toUpperCase()}`);
 
   while (true) {
     const issue = await jira.getIssue(issueKey);
     const currentStatus = issue.fields.status.name;
-    const flowDef = GRAYRELEASE_FLOW_MAP[currentStatus];
+    const normalizedStatus = normalizeStatusName(currentStatus);
+    const flowDef = GRAYRELEASE_FLOW_MAP[normalizedStatus];
 
     log.push(`\n📍 當前狀態: ${currentStatus}`);
+    progress(ctx, {
+      phase: 'action',
+      title: '檢查 GrayRelease 狀態',
+      issueKey,
+      currentStatus,
+    });
 
     // 已完成
     if (flowDef?.completed) {
@@ -574,7 +876,7 @@ async function executeGrayReleaseFlow(issueKey, options, ctx) {
     }
 
     // ── PLANNING → Accept ────────────────────────────────────
-    if (currentStatus === 'PLANNING') {
+    if (normalizedStatus === 'PLANNING') {
       log.push('  執行: Accept');
       await jira.transitionByName(issueKey, 'Accept');
       await notifier.notify(issueKey, 'Accept 需求，進入 WAIT FOR BUILD');
@@ -582,20 +884,26 @@ async function executeGrayReleaseFlow(issueKey, options, ctx) {
     }
 
     // ── WAIT FOR BUILD → GrayRelease Build ───────────────────
-    if (currentStatus === 'WAIT FOR BUILD') {
+    if (normalizedStatus === 'WAIT FOR BUILD') {
       buildAttempts++;
+      if (buildAttempts > options.maxBuildRetries) {
+        log.push(`⚠️ Build 已達最大重試次數 (${options.maxBuildRetries})，停止執行`);
+        break;
+      }
 
       log.push(`  執行: GrayRelease Build (第 ${buildAttempts} 次)`);
       await jira.transitionByName(issueKey, 'GrayRelease Build');
       await notifier.notify(issueKey, `觸發 GrayRelease Build (第 ${buildAttempts} 次)`);
 
-      // 等待 build 完成（Jenkins 會更新 CID_build_result）
+      // 等待 build 完成
       log.push('  ⏳ 等待 Jenkins Build 完成...');
-      await waitForResultField(issueKey, GRAY_RELEASE_FIELD_IDS.buildResult, 'pass', jira, {
-        intervalMs: parseInt(process.env.POLL_INTERVAL_MS ?? '30000'),
-        timeoutMs: parseInt(process.env.POLL_TIMEOUT_MS ?? '3600000'),
-        label: 'CID_build_result',
-      });
+      await waitForGrayReleaseResult(
+        issueKey,
+        GRAY_RELEASE_FIELD_IDS.buildResult,
+        'GrayRelease Build',
+        jira,
+        ctx.progress,
+      );
 
       log.push('  ✅ Build 完成');
 
@@ -607,7 +915,7 @@ async function executeGrayReleaseFlow(issueKey, options, ctx) {
     }
 
     // ── WAIT APPROVAL → Approve ───────────────────────────────
-    if (currentStatus === 'WAIT APPROVAL') {
+    if (normalizedStatus === 'WAIT APPROVAL') {
       log.push(`  處理簽核流程 (環境: ${environment})`);
 
       const approvalResult = await handleGrayReleaseApproval(
@@ -629,57 +937,16 @@ async function executeGrayReleaseFlow(issueKey, options, ctx) {
     }
 
     // ── WAIT DEPLOY → Switch / Deploy ─────────────────────────
-    if (currentStatus === 'WAIT DEPLOY') {
-      let switchComment = await findRecentSwitchExecutionNodeComment(issueKey, systemCode, jira);
-
-      if (switchComment) {
-        log.push('  ✅ 偵測到 5 分鐘內 cid jira worker 已完成 Switch Execution Node');
-      } else {
-        // 檢查是否需要 Switch Execution Node
-        const needSwitch = await needSwitchExecutionNode(issueKey, systemCode, jira);
-
-        if (needSwitch) {
-          log.push('  執行: Switch Execution Node');
-          await jira.transitionByName(issueKey, 'Switch Execution Node');
-          await notifier.notify(issueKey, '切換 Ansible instance');
-
-          log.push('  ⏳ 等待 cid jira worker 留下 Switch Execution Node 成功 comment...');
-          switchComment = await waitForRecentSwitchExecutionNodeComment(issueKey, systemCode, jira, {
-            intervalMs: parseInt(process.env.POLL_INTERVAL_MS ?? '30000'),
-            timeoutMs: SWITCH_EXECUTION_NODE_COMMENT_WINDOW_MS,
-          });
-        }
-      }
-
-      if (switchComment) {
-        const waitedMs = await waitForSwitchExecutionNodeSettle(switchComment);
-        log.push(`  ✅ Switch Execution Node 已確認，等待 ${Math.round(waitedMs / 1000)}s 後執行 Deploy`);
+    if (normalizedStatus === 'WAIT DEPLOY') {
+      const deployCompleted = await runGrayReleaseDeployStep(issueKey, systemCode, ctx, log);
+      if (!deployCompleted) {
+        break;
       }
-
-      // 執行 GrayRelease Deploy
-      log.push('  執行: GrayRelease Deploy');
-      await jira.transitionByName(issueKey, 'GrayRelease Deploy');
-      await notifier.notify(issueKey, '觸發 GrayRelease Deploy');
-
-      // 等待 deploy 完成（Jenkins 會更新 CID_deploy_result）
-      log.push('  ⏳ 等待部署完成...');
-      await waitForResultField(issueKey, GRAY_RELEASE_FIELD_IDS.deployResult, 'pass', jira, {
-        intervalMs: parseInt(process.env.POLL_INTERVAL_MS ?? '30000'),
-        timeoutMs: parseInt(process.env.POLL_TIMEOUT_MS ?? '3600000'),
-        label: 'CID_deploy_result',
-      });
-
-      log.push('  ✅ Deploy 完成');
-
-      // Deploy 完成後切到 VERIFY
-      log.push('  執行: To Verify');
-      await jira.transitionByName(issueKey, 'To Verify');
-      await notifier.notify(issueKey, 'Deploy 完成，進入驗證階段');
       continue;
     }
 
     // ── VERIFY → 需要人工決定 ─────────────────────────────────
-    if (currentStatus === 'VERIFY') {
+    if (normalizedStatus === 'VERIFY') {
       if (options.autoVerify) {
         log.push('  ⚠️ autoVerify=true，自動執行 Verify Success');
         await jira.transitionByName(issueKey, 'Verify Success');
@@ -693,7 +960,7 @@ async function executeGrayReleaseFlow(issueKey, options, ctx) {
     }
 
     // ── MERGE CODE AND TAG → To Done ─────────────────────────
-    if (currentStatus === 'MERGE CODE AND TAG') {
+    if (normalizedStatus === 'MERGE CODE AND TAG') {
       log.push('  執行: To Done');
       await jira.transitionByName(issueKey, 'To Done');
       await notifier.notify(issueKey, 'GrayRelease 流程完成');
@@ -714,24 +981,125 @@ async function executeGrayReleaseFlow(issueKey, options, ctx) {
   };
 }
 
+async function runGrayReleaseDeployStep(issueKey, systemCode, ctx, log) {
+  const { jira, notifier } = ctx;
+  const needSwitch = await needSwitchExecutionNode(issueKey, systemCode, jira);
+
+  if (needSwitch) {
+    log.push('  執行: Switch Execution Node');
+    progress(ctx, {
+      phase: 'action',
+      title: '切換 GrayRelease execution node',
+      issueKey,
+    });
+    await jira.transitionByName(issueKey, 'Switch Execution Node');
+    await notifier.notify(issueKey, '切換 Ansible instance');
+    await waitForSwitchExecutionNode(issueKey, systemCode, jira);
+  }
+
+  log.push('  執行: GrayRelease Deploy');
+  progress(ctx, {
+    phase: 'action',
+    title: '觸發 GrayRelease Deploy',
+    issueKey,
+  });
+  await jira.transitionByName(issueKey, 'GrayRelease Deploy');
+  await notifier.notify(issueKey, '觸發 GrayRelease Deploy');
+
+  // 等待部署完成：優先輪詢 deploy result、VERIFY 狀態，
+  // 或「To Verify」transition 是否出現。
+  // 最多等待 3 分鐘（避免 MCP client timeout），
+  // 若超時則回傳「部署中」訊息，請使用者稍後繼續。
+  const DEPLOY_WAIT_MS = Math.min(getPollTimeoutMs(), 3 * 60 * 1000);
+  const DEPLOY_POLL_MS = Math.min(getPollIntervalMs(), 10_000);
+  const deployDeadline = Date.now() + DEPLOY_WAIT_MS;
+  let deployCompleted = false;
+  let attempts = 0;
+
+  log.push('  ⏳ 等待部署完成（最多 3 分鐘）...');
+  while (Date.now() <= deployDeadline) {
+    attempts++;
+    const issue = await jira.getIssue(issueKey);
+    const statusNow = normalizeStatusName(issue.fields.status.name);
+    const fields = await jira.getIssueFields(issueKey, [GRAY_RELEASE_FIELD_IDS.deployResult]);
+    const rawDeployResult = fields[GRAY_RELEASE_FIELD_IDS.deployResult];
+    const deployResult = rawDeployResult?.value ?? rawDeployResult;
+    progress(ctx, {
+      phase: 'polling',
+      title: '等待 GrayRelease deploy 完成',
+      detail: `${GRAY_RELEASE_FIELD_IDS.deployResult}: ${deployResult ?? 'empty'}`,
+      issueKey,
+      currentStatus: issue.fields.status.name,
+      targetStatus: 'VERIFY',
+      attempts,
+      elapsedMs: DEPLOY_WAIT_MS - Math.max(0, deployDeadline - Date.now()),
+      timeoutMs: DEPLOY_WAIT_MS,
+      nextPollMs: DEPLOY_POLL_MS,
+    });
+
+    if (statusNow === 'VERIFY') {
+      // Jira automation 或 Jenkins 已自動切到 VERIFY
+      deployCompleted = true;
+      log.push('  ✅ 狀態已進入 VERIFY（自動切換），跳過手動 To Verify');
+      break;
+    }
+
+    if (isFailingResult(deployResult)) {
+      throw new Error(`GrayRelease Deploy 失敗，${GRAY_RELEASE_FIELD_IDS.deployResult}: ${deployResult}`);
+    }
+
+    const transitions = await jira.getTransitions?.(issueKey) ?? [];
+    const toVerifyTrans = transitions.find(
+      (t) => t.name.toLowerCase() === 'to verify',
+    );
+    if (isPassingResult(deployResult) || toVerifyTrans) {
+      log.push('  ✅ Deploy 完成，執行: To Verify');
+      if (toVerifyTrans?.id && jira.transitionById) {
+        await jira.transitionById(issueKey, toVerifyTrans.id);
+      } else {
+        await jira.transitionByName(issueKey, 'To Verify');
+      }
+      await notifier.notify(issueKey, 'Deploy 完成，進入驗證階段');
+      deployCompleted = true;
+      break;
+    }
+
+    if (Date.now() >= deployDeadline) {
+      break;
+    }
+
+    await sleep(DEPLOY_POLL_MS);
+  }
+
+  if (!deployCompleted) {
+    log.push('  ⚠️ 3 分鐘內未看到部署結果，部署可能仍在進行中');
+    log.push('  請稍後使用 get_grayrelease_status 或 deploy_grayrelease 繼續');
+    await notifier.notify(issueKey, '部署仍在進行中，請稍後查詢狀態');
+    return false;
+  }
+
+  await notifier.notify(issueKey, 'Deploy 完成，進入驗證階段');
+  return true;
+}
+
 /**
  * 處理簽核流程（依環境別）
  */
 async function handleGrayReleaseApproval(issueKey, environment, systemCode, ctx) {
-  const {jira, notifier} = ctx;
+  const { jira, notifier } = ctx;
   const env = environment.toLowerCase();
 
   // DEV: 跳過簽核
   if (env === 'dev') {
-    return {skipped: true, reason: 'DEV 環境無需簽核'};
+    return { skipped: true, reason: 'DEV 環境無需簽核' };
   }
 
   // STG: 查 wiki 值班組長 → assign → 發 jabber → 等待 approve
   if (env === 'stg') {
     const managerResult = await handleGetReleaseManager({}, {});
-    const managerData = parseMcpToolData(managerResult, 'get_release_manager');
+    const managerData = parseToolResult(managerResult);
 
-    if (!managerData.found) {
+    if (!managerData?.found) {
       throw new Error('無法查詢 STG 值班組長，請手動處理');
     }
 
@@ -743,11 +1111,23 @@ async function handleGrayReleaseApproval(issueKey, environment, systemCode, ctx)
     }
 
     // Assign 給組長
+    progress(ctx, {
+      phase: 'action',
+      title: '指派 GrayRelease 簽核人',
+      detail: `STG 值班組長 ${managerName}`,
+      issueKey,
+    });
     await jira.updateAssignee(issueKey, accountId);
     await notifier.notify(issueKey, `已指派給 STG 值班組長 ${managerName}`);
 
     // 發送 jabber 通知
     const jabberTo = `${accountId}@linebank.com.tw`;
+    progress(ctx, {
+      phase: 'waiting',
+      title: '發送 GrayRelease 簽核通知',
+      detail: `to ${managerName} (${jabberTo})`,
+      issueKey,
+    });
     await handleSendJabberMessage(
       {
         to: jabberTo,
@@ -761,9 +1141,10 @@ async function handleGrayReleaseApproval(issueKey, environment, systemCode, ctx)
     await poller.waitForStatus(issueKey, 'WAIT DEPLOY', {
       intervalMs: parseInt(process.env.POLL_INTERVAL_MS ?? '30000'),
       timeoutMs: parseInt(process.env.POLL_TIMEOUT_MS ?? '3600000'),
+      onProgress: ctx.progress,
     });
 
-    return {approved: true, by: managerName};
+    return { approved: true, by: managerName };
   }
 
   // UAT: assign James Yu → 等待留言 → 轉 Solar Chen → 等待 approve
@@ -774,11 +1155,23 @@ async function handleGrayReleaseApproval(issueKey, environment, systemCode, ctx)
     }
 
     // Assign 給 James Yu
+    progress(ctx, {
+      phase: 'action',
+      title: '指派 GrayRelease 簽核人',
+      detail: '部長 James Yu',
+      issueKey,
+    });
     await jira.updateAssignee(issueKey, jamesAccountId);
     await notifier.notify(issueKey, '已指派給部長 James Yu，等待留言確認');
 
     // 發送 jabber 通知給 James Yu
     const jamesJabber = `${jamesAccountId}@linebank.com.tw`;
+    progress(ctx, {
+      phase: 'waiting',
+      title: '發送 GrayRelease 簽核通知',
+      detail: `to James Yu (${jamesJabber})`,
+      issueKey,
+    });
     await handleSendJabberMessage(
       {
         to: jamesJabber,
@@ -796,11 +1189,11 @@ async function handleGrayReleaseApproval(issueKey, environment, systemCode, ctx)
         timeoutMs: parseInt(process.env.POLL_TIMEOUT_MS ?? '3600000'),
         intervalMs: parseInt(process.env.POLL_INTERVAL_MS ?? '30000'),
       },
-      {jira},
+      { jira, progress: ctx.progress },
     );
-    const commentData = parseMcpToolData(commentResult, 'wait_for_comment');
+    const commentData = parseToolResult(commentResult);
 
-    if (!commentData.found) {
+    if (!commentData?.found) {
       throw new Error('等待 James Yu 留言超時');
     }
 
@@ -812,11 +1205,23 @@ async function handleGrayReleaseApproval(issueKey, environment, systemCode, ctx)
       throw new Error('找不到 Solar Chen 的 accountId');
     }
 
+    progress(ctx, {
+      phase: 'action',
+      title: '指派 GrayRelease 簽核人',
+      detail: 'Solar Chen',
+      issueKey,
+    });
     await jira.updateAssignee(issueKey, solarAccountId);
     await notifier.notify(issueKey, '已轉單給 Solar Chen，等待最終簽核');
 
     // 發送 jabber 通知給 Solar Chen
     const solarJabber = `${solarAccountId}@linebank.com.tw`;
+    progress(ctx, {
+      phase: 'waiting',
+      title: '發送 GrayRelease 簽核通知',
+      detail: `to Solar Chen (${solarJabber})`,
+      issueKey,
+    });
     await handleSendJabberMessage(
       {
         to: solarJabber,
@@ -830,219 +1235,25 @@ async function handleGrayReleaseApproval(issueKey, environment, systemCode, ctx)
     await poller.waitForStatus(issueKey, 'WAIT DEPLOY', {
       intervalMs: parseInt(process.env.POLL_INTERVAL_MS ?? '30000'),
       timeoutMs: parseInt(process.env.POLL_TIMEOUT_MS ?? '3600000'),
+      onProgress: ctx.progress,
     });
 
-    return {approved: true, by: 'James Yu → Solar Chen'};
+    return { approved: true, by: 'James Yu → Solar Chen' };
   }
 
   throw new Error(`不支援的環境: ${environment}`);
 }
 
-function parseMcpToolData(result, toolName) {
-  const text = result?.content?.[0]?.text;
-
-  if (result?.isError || text?.startsWith('❌')) {
-    throw new Error(text?.replace(/^❌ 錯誤:\s*/, '') ?? `${toolName} 回傳錯誤`);
-  }
-
-  if (!text) {
-    throw new Error(`${toolName} 回傳空內容`);
-  }
-
-  try {
-    return JSON.parse(text);
-  } catch (err) {
-    throw new Error(`${toolName} 回傳格式不是 JSON: ${err.message}`);
-  }
-}
-
-async function waitForResultField(issueKey, fieldName, expectedValue, jira, options = {}) {
-  const intervalMs = options.intervalMs ?? parseInt(process.env.POLL_INTERVAL_MS ?? '30000');
-  const timeoutMs = options.timeoutMs ?? parseInt(process.env.POLL_TIMEOUT_MS ?? '3600000');
-  const label = options.label ?? fieldName;
-  const fieldId = await resolveJiraFieldId(fieldName, jira);
-  const expected = normalizeResultValue(expectedValue);
-  const failedValues = new Set(['fail', 'failed', 'failure', 'error']);
-  const startTime = Date.now();
-  let attempts = 0;
-
-  while (true) {
-    attempts++;
-    const fields = await jira.getIssueFields(issueKey, [fieldId]);
-    const rawValue = fields[fieldId] ?? fields[fieldName];
-    const value = normalizeResultValue(rawValue);
-
-    if (value === expected) {
-      return {issueKey, field: label, value, attempts, elapsedMs: Date.now() - startTime};
-    }
-
-    if (failedValues.has(value)) {
-      throw new Error(`${label}=${formatResultValue(rawValue)}，Jenkins 結果失敗`);
-    }
-
-    const elapsed = Date.now() - startTime;
-    if (elapsed >= timeoutMs) {
-      throw new Error(
-        `Timeout waiting for ${label} to become ${expectedValue}. ` +
-        `Last value: ${formatResultValue(rawValue)} after ${attempts} attempts.`,
-      );
-    }
-
-    await sleep(intervalMs);
-  }
-}
-
-async function resolveJiraFieldId(fieldName, jira) {
-  if (typeof jira.getFieldIdByName !== 'function') {
-    return fieldName;
-  }
-  return jira.getFieldIdByName(fieldName);
-}
-
-function normalizeResultValue(value) {
-  if (value && typeof value === 'object') {
-    return String(value.value ?? value.name ?? value.id ?? '').trim().toLowerCase();
-  }
-  return String(value ?? '').trim().toLowerCase();
-}
-
-function formatResultValue(value) {
-  if (value === undefined || value === null || value === '') {
-    return '(empty)';
-  }
-  if (typeof value === 'object') {
-    return JSON.stringify(value);
-  }
-  return String(value);
-}
-
-function normalizeGrayReleaseEnvironment(value) {
-  const environment = normalizeResultValue(value);
-
-  if (!environment) {
-    throw new Error('無法讀取 GrayRelease 環境欄位，請確認 Jira 單欄位是否正確填寫');
-  }
-
-  if (!SUPPORTED_ENVS.grayRelease.includes(environment)) {
-    throw new Error(
-      `GrayRelease 環境欄位不合法: ${formatResultValue(value)}，僅支援 ${SUPPORTED_ENVS.grayRelease.join(' / ')}`,
-    );
-  }
-
-  return environment;
-}
-
-async function waitForRecentSwitchExecutionNodeComment(issueKey, systemCode, jira, options = {}) {
-  const intervalMs = options.intervalMs ?? parseInt(process.env.POLL_INTERVAL_MS ?? '30000');
-  const timeoutMs = options.timeoutMs ?? SWITCH_EXECUTION_NODE_COMMENT_WINDOW_MS;
-  const startTime = Date.now();
-  let attempts = 0;
-
-  while (true) {
-    attempts++;
-    const match = await findRecentSwitchExecutionNodeComment(issueKey, systemCode, jira);
-
-    if (match) {
-      return {...match, attempts, elapsedMs: Date.now() - startTime};
-    }
-
-    const elapsed = Date.now() - startTime;
-    if (elapsed >= timeoutMs) {
-      throw new Error(
-        `Timeout waiting for cid jira worker Switch Execution Node comment in ${issueKey} after ${attempts} attempts.`,
-      );
-    }
-
-    await sleep(intervalMs);
-  }
-}
-
-async function findRecentSwitchExecutionNodeComment(issueKey, systemCode, jira) {
-  if (typeof jira.getComments !== 'function') {
-    return null;
-  }
-
-  const comments = await jira.getComments(issueKey);
-  const now = Date.now();
-
-  return comments.find((comment) => {
-    if (!isCidJiraWorkerComment(comment)) {
-      return false;
-    }
-
-    if (!isSwitchExecutionNodeSuccessComment(comment, systemCode)) {
-      return false;
-    }
-
-    const timestamp = getCommentTimestamp(comment);
-    if (!timestamp) {
-      return false;
-    }
-
-    const ageMs = now - timestamp;
-    return ageMs >= 0 && ageMs <= SWITCH_EXECUTION_NODE_COMMENT_WINDOW_MS;
-  }) ?? null;
-}
-
-async function waitForSwitchExecutionNodeSettle(comment) {
-  const waitMs = parseInt(
-    process.env.SWITCH_EXECUTION_NODE_WAIT_MS ?? String(SWITCH_EXECUTION_NODE_SETTLE_MS),
-  );
-  const timestamp = getCommentTimestamp(comment);
-  const elapsedSinceCommentMs = timestamp ? Date.now() - timestamp : 0;
-  const remainingMs = Math.max(0, waitMs - elapsedSinceCommentMs);
-
-  if (remainingMs > 0) {
-    await sleep(remainingMs);
-  }
-
-  return remainingMs;
-}
-
-function isCidJiraWorkerComment(comment) {
-  const authorFields = [
-    comment?.author?.displayName,
-    comment?.author?.name,
-    comment?.author?.emailAddress,
-    comment?.author?.accountId,
-    comment?.author?.key,
-  ];
-
-  return authorFields
-    .map((value) => String(value ?? '').trim().toLowerCase())
-    .some((value) => value.includes('cid jira worker'));
-}
-
-function isSwitchExecutionNodeSuccessComment(comment, systemCode) {
-  const body = getCommentBody(comment).toLowerCase();
-  const system = String(systemCode ?? '').trim().toLowerCase();
-
-  return (
-    system &&
-    body.includes(`trigger update ${system}'s instance_group to [ing]nonprd_executionnode success`)
-  );
-}
-
-function getCommentBody(comment) {
-  const body = comment?.body ?? '';
-  if (typeof body === 'string') {
-    return body;
-  }
-  return JSON.stringify(body);
-}
-
-function getCommentTimestamp(comment) {
-  const rawTimestamp = comment?.created ?? comment?.updated;
-  const timestamp = Date.parse(rawTimestamp ?? '');
-  return Number.isNaN(timestamp) ? 0 : timestamp;
-}
-
 /**
  * 判斷是否需要執行 Switch Execution Node
  * 規則：查詢同系統上次 CD 部署的環境群組，若與本次不同則需切換
  * 注意：不查詢 GrayRelease 歷史，因為 GrayRelease 永遠是 nonPrd
  */
 async function needSwitchExecutionNode(issueKey, systemCode, jira) {
+  if (await hasRecentSwitchExecutionNodeComment(issueKey, systemCode, jira)) {
+    return false;
+  }
+
   // GrayRelease 永遠是 nonPrd 群組
   const thisGroup = 'nonPrd';
 
@@ -1072,6 +1283,45 @@ async function needSwitchExecutionNode(issueKey, systemCode, jira) {
   }
 }
 
+async function waitForSwitchExecutionNode(issueKey, systemCode, jira) {
+  const waitMs = parseInt(process.env.SWITCH_EXECUTION_NODE_WAIT_MS ?? '180000');
+  const intervalMs = getPollIntervalMs();
+  const deadline = Date.now() + waitMs;
+
+  while (true) {
+    if (await hasRecentSwitchExecutionNodeComment(issueKey, systemCode, jira)) {
+      return;
+    }
+
+    if (Date.now() >= deadline) {
+      return;
+    }
+
+    await sleep(intervalMs);
+  }
+}
+
+async function hasRecentSwitchExecutionNodeComment(issueKey, systemCode, jira) {
+  if (!jira.getComments) {
+    return false;
+  }
+
+  try {
+    const comments = await jira.getComments(issueKey);
+    const lowerSystemCode = String(systemCode ?? '').toLowerCase();
+    return comments.some((comment) => {
+      const body = String(comment.body ?? '').toLowerCase();
+      const author = String(comment.author?.displayName ?? comment.author?.name ?? '').toLowerCase();
+      return author === 'cid jira worker'
+        && body.includes('instance_group')
+        && body.includes('nonprd_executionnode')
+        && (!lowerSystemCode || body.includes(lowerSystemCode));
+    });
+  } catch {
+    return false;
+  }
+}
+
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }