@jira-deploy/core 1.0.2 → 1.0.3

package/tools/grayrelease.js

@@ -1,6 +1,10 @@
 /**
  * Gray Release 相關 tools
  *   - create_grayrelease_ticket
+ *   - link_stg_grayrelease
+ *   - auto_grayrelease (NEW)
+ *   - get_grayrelease_status (NEW)
+ *   - continue_grayrelease (NEW)
  */
 import {
   SYSTEM_CODES,
@@ -16,8 +20,62 @@ import {
   SIGN_VALUES,
   NOTES_TEMPLATES,
   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';
+
+// ── Flow Definition ──────────────────────────────────────────────
+
+/**
+ * GrayRelease 狀態流程定義
+ * 每個狀態定義其可能的下一步 transitions
+ */
+const GRAYRELEASE_FLOW_MAP = {
+  'PLANNING': {
+    transitions: ['Accept'],
+    desc: '接受需求開始執行',
+    nextState: 'WAIT FOR BUILD',
+  },
+  'WAIT FOR BUILD': {
+    transitions: ['GrayRelease Build'],
+    desc: 'Build 程式',
+    nextState: 'WAIT FOR BUILD', // build 完會回到同狀態
+    afterBuild: 'Apply to approval', // build 完後要切到簽核
+  },
+  'WAIT APPROVAL': {
+    transitions: ['Approve'],
+    desc: '等待主管簽核',
+    nextState: 'WAIT DEPLOY',
+    requiresApproval: true,
+  },
+  'WAIT DEPLOY': {
+    transitions: ['Switch Execution Node', 'GrayRelease Deploy', 'To Verify'],
+    desc: '部署程式',
+    nextState: 'WAIT DEPLOY', // deploy 完會回到同狀態
+    afterDeploy: 'To Verify', // deploy 完後切到驗證
+  },
+  'VERIFY': {
+    transitions: ['Verify Success', 'Verify fail'],
+    desc: '驗證部署結果',
+    onSuccess: 'MERGE CODE AND TAG',
+    onFail: 'WAIT FOR BUILD', // 失敗重新 build
+  },
+  'MERGE CODE AND TAG': {
+    transitions: ['To Done'],
+    desc: '合併程式碼並打 tag',
+    nextState: 'DONE',
+  },
+  'DONE': {
+    completed: true,
+    desc: '流程完成',
+  },
+};
+
+const SWITCH_EXECUTION_NODE_COMMENT_WINDOW_MS = 5 * 60 * 1000;
+const SWITCH_EXECUTION_NODE_SETTLE_MS = 3 * 60 * 1000;
 
 // ── Schema definitions ───────────────────────────────────────────
 export function getGrayReleaseToolDefinitions() {
@@ -81,6 +139,60 @@ export function getGrayReleaseToolDefinitions() {
         },
       },
     },
+    {
+      name: 'auto_grayrelease',
+      description:
+        '自動執行 GrayRelease 完整流程：PLANNING → Build → Approval → Deploy → Verify → Done。' +
+        '依環境自動處理簽核（DEV 跳過 / STG 組長簽核 / UAT 部長簽核）。支援 Build/Deploy 無限循環。',
+      inputSchema: {
+        type: 'object',
+        required: ['issueKey'],
+        properties: {
+          issueKey: {
+            type: 'string',
+            description: 'GrayRelease 單 issue key，例如 CID-822',
+          },
+          autoVerify: {
+            type: 'boolean',
+            description: '(選填) 是否自動執行 Verify Success（預設 false，需人工確認）',
+          },
+        },
+      },
+    },
+    {
+      name: 'get_grayrelease_status',
+      description:
+        '查詢 GrayRelease 單當前狀態，並給出下一步建議。用於了解流程進度或中斷後查看位置。',
+      inputSchema: {
+        type: 'object',
+        required: ['issueKey'],
+        properties: {
+          issueKey: {
+            type: 'string',
+            description: 'GrayRelease 單 issue key，例如 CID-822',
+          },
+        },
+      },
+    },
+    {
+      name: 'continue_grayrelease',
+      description:
+        '從 GrayRelease 單當前狀態繼續執行流程。適用於流程中斷或需要從中間開始的場景。',
+      inputSchema: {
+        type: 'object',
+        required: ['issueKey'],
+        properties: {
+          issueKey: {
+            type: 'string',
+            description: 'GrayRelease 單 issue key，例如 CID-822',
+          },
+          autoVerify: {
+            type: 'boolean',
+            description: '(選填) 是否自動執行 Verify Success（預設 false，需人工確認）',
+          },
+        },
+      },
+    },
   ];
 }
 
@@ -294,3 +406,672 @@ export async function handleLinkStgGrayRelease(args, {jira, notifier}) {
     return error(`無法建立關聯: ${err.message}`);
   }
 }
+
+// ── Handlers (NEW) ───────────────────────────────────────────────
+
+/**
+ * 自動執行 GrayRelease 完整流程
+ */
+export async function handleAutoGrayRelease(args, ctx) {
+  const {issueKey} = args;
+  const {jira, notifier} = ctx;
+
+  try {
+    await notifier.notify(issueKey, '開始自動執行 GrayRelease 流程');
+
+    const result = await executeGrayReleaseFlow(
+      issueKey,
+      {
+        autoVerify: args.autoVerify ?? false,
+      },
+      ctx,
+    );
+
+    return ok(result);
+  } catch (err) {
+    await notifier.notify(issueKey, `GrayRelease 流程執行失敗: ${err.message}`);
+    return error(`auto_grayrelease 失敗: ${err.message}`);
+  }
+}
+
+/**
+ * 查詢 GrayRelease 單當前狀態並給出建議
+ */
+export async function handleGetGrayReleaseStatus(args, {jira}) {
+  try {
+    const status = await getGrayReleaseStatus(args.issueKey, jira);
+    return ok(status);
+  } catch (err) {
+    return error(`get_grayrelease_status 失敗: ${err.message}`);
+  }
+}
+
+/**
+ * 從當前狀態繼續執行 GrayRelease 流程
+ */
+export async function handleContinueGrayRelease(args, ctx) {
+  const {issueKey} = args;
+  const {jira, notifier} = ctx;
+
+  try {
+    const status = await getGrayReleaseStatus(issueKey, jira);
+
+    if (status.completed) {
+      return ok({
+        issueKey,
+        message: '此 GrayRelease 單已完成（狀態: DONE），無需繼續執行',
+        currentStatus: status.currentStatus,
+      });
+    }
+
+    await notifier.notify(
+      issueKey,
+      `從狀態 ${status.currentStatus} 繼續執行 GrayRelease 流程`,
+    );
+
+    const result = await executeGrayReleaseFlow(
+      issueKey,
+      {
+        autoVerify: args.autoVerify ?? false,
+      },
+      ctx,
+    );
+
+    return ok(result);
+  } catch (err) {
+    await notifier.notify(issueKey, `GrayRelease 流程執行失敗: ${err.message}`);
+    return error(`continue_grayrelease 失敗: ${err.message}`);
+  }
+}
+
+// ── Internal Helpers ─────────────────────────────────────────────
+
+/**
+ * 查詢 GrayRelease 單狀態並分析下一步
+ */
+async function getGrayReleaseStatus(issueKey, jira) {
+  const issue = await jira.getIssue(issueKey);
+  const currentStatus = issue.fields.status.name;
+  const summary = issue.fields.summary;
+
+  // 查詢環境欄位
+  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 ?? 'unknown';
+  const systemCode = fields[GRAY_RELEASE_FIELD_IDS.systemCode]?.value ?? 'unknown';
+
+  // 查詢可用 transitions
+  const transitions = await jira.getTransitions(issueKey);
+  const availableTransitions = transitions.map((t) => t.name);
+
+  // 根據當前狀態查找流程定義
+  const flowDef = GRAYRELEASE_FLOW_MAP[currentStatus];
+  const completed = flowDef?.completed === true;
+
+  let nextSteps = [];
+  let recommendation = '';
+
+  if (completed) {
+    recommendation = '✅ GrayRelease 流程已完成';
+  } else if (flowDef) {
+    nextSteps = flowDef.transitions ?? [];
+    recommendation = `${flowDef.desc}。可執行: ${nextSteps.join(' / ')}`;
+  } else {
+    recommendation = `⚠️ 未知狀態，請檢查 Jira 或手動處理。可用 transitions: ${availableTransitions.join(', ')}`;
+  }
+
+  return {
+    issueKey,
+    summary,
+    currentStatus,
+    environment,
+    systemCode,
+    completed,
+    flowDefinition: flowDef,
+    nextSteps,
+    availableTransitions,
+    recommendation,
+  };
+}
+
+/**
+ * 主執行流程：從當前狀態開始，自動執行到完成或需要人工介入
+ */
+async function executeGrayReleaseFlow(issueKey, options, ctx) {
+  const {jira, notifier} = ctx;
+  const log = [];
+  let buildAttempts = 0;
+
+  // 讀取環境和系統代碼
+  const fields = await jira.getIssueFields(issueKey, [
+    GRAY_RELEASE_FIELD_IDS.env,
+    GRAY_RELEASE_FIELD_IDS.systemCode,
+  ]);
+  const environment = normalizeGrayReleaseEnvironment(fields[GRAY_RELEASE_FIELD_IDS.env]);
+  const systemCode = fields[GRAY_RELEASE_FIELD_IDS.systemCode]?.value;
+
+  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];
+
+    log.push(`\n📍 當前狀態: ${currentStatus}`);
+
+    // 已完成
+    if (flowDef?.completed) {
+      log.push('✅ GrayRelease 流程完成！');
+      break;
+    }
+
+    // 未知狀態
+    if (!flowDef) {
+      log.push(`⚠️ 未知狀態: ${currentStatus}，停止自動執行`);
+      break;
+    }
+
+    // ── PLANNING → Accept ────────────────────────────────────
+    if (currentStatus === 'PLANNING') {
+      log.push('  執行: Accept');
+      await jira.transitionByName(issueKey, 'Accept');
+      await notifier.notify(issueKey, 'Accept 需求，進入 WAIT FOR BUILD');
+      continue;
+    }
+
+    // ── WAIT FOR BUILD → GrayRelease Build ───────────────────
+    if (currentStatus === 'WAIT FOR BUILD') {
+      buildAttempts++;
+
+      log.push(`  執行: GrayRelease Build (第 ${buildAttempts} 次)`);
+      await jira.transitionByName(issueKey, 'GrayRelease Build');
+      await notifier.notify(issueKey, `觸發 GrayRelease Build (第 ${buildAttempts} 次)`);
+
+      // 等待 build 完成（Jenkins 會更新 CID_build_result）
+      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',
+      });
+
+      log.push('  ✅ Build 完成');
+
+      // Build 完成後切到 WAIT APPROVAL
+      log.push('  執行: Apply to approval');
+      await jira.transitionByName(issueKey, 'Apply to approval');
+      await notifier.notify(issueKey, 'Build 完成，申請簽核');
+      continue;
+    }
+
+    // ── WAIT APPROVAL → Approve ───────────────────────────────
+    if (currentStatus === 'WAIT APPROVAL') {
+      log.push(`  處理簽核流程 (環境: ${environment})`);
+
+      const approvalResult = await handleGrayReleaseApproval(
+        issueKey,
+        environment,
+        systemCode,
+        ctx,
+      );
+
+      if (approvalResult.skipped) {
+        log.push(`  ✅ ${approvalResult.reason}`);
+        // DEV 環境直接執行 Approve
+        await jira.transitionByName(issueKey, 'Approve');
+        await notifier.notify(issueKey, 'DEV 環境無需簽核，直接 Approve');
+      } else {
+        log.push(`  ✅ 簽核完成 by ${approvalResult.by}`);
+      }
+      continue;
+    }
+
+    // ── 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`);
+      }
+
+      // 執行 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 (options.autoVerify) {
+        log.push('  ⚠️ autoVerify=true，自動執行 Verify Success');
+        await jira.transitionByName(issueKey, 'Verify Success');
+        await notifier.notify(issueKey, '自動驗證成功');
+        continue;
+      } else {
+        log.push('  ⏸️  需要人工驗證結果，停止自動執行');
+        log.push('     可執行: Verify Success（成功）/ Verify fail（失敗重新 build）');
+        break;
+      }
+    }
+
+    // ── MERGE CODE AND TAG → To Done ─────────────────────────
+    if (currentStatus === 'MERGE CODE AND TAG') {
+      log.push('  執行: To Done');
+      await jira.transitionByName(issueKey, 'To Done');
+      await notifier.notify(issueKey, 'GrayRelease 流程完成');
+      continue;
+    }
+
+    // 未處理的狀態
+    log.push(`⚠️ 狀態 ${currentStatus} 沒有自動處理邏輯，停止執行`);
+    break;
+  }
+
+  const finalIssue = await jira.getIssue(issueKey);
+  return {
+    issueKey,
+    finalStatus: finalIssue.fields.status.name,
+    buildAttempts,
+    log,
+  };
+}
+
+/**
+ * 處理簽核流程（依環境別）
+ */
+async function handleGrayReleaseApproval(issueKey, environment, systemCode, ctx) {
+  const {jira, notifier} = ctx;
+  const env = environment.toLowerCase();
+
+  // DEV: 跳過簽核
+  if (env === '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');
+
+    if (!managerData.found) {
+      throw new Error('無法查詢 STG 值班組長，請手動處理');
+    }
+
+    const managerName = managerData.name;
+    const accountId = resolveAccountId(managerName);
+
+    if (!accountId) {
+      throw new Error(`找不到 ${managerName} 的 accountId`);
+    }
+
+    // Assign 給組長
+    await jira.updateAssignee(issueKey, accountId);
+    await notifier.notify(issueKey, `已指派給 STG 值班組長 ${managerName}`);
+
+    // 發送 jabber 通知
+    const jabberTo = `${accountId}@linebank.com.tw`;
+    await handleSendJabberMessage(
+      {
+        to: jabberTo,
+        message: `[GrayRelease 簽核通知] ${issueKey} 需要您的簽核。環境: STG\n${process.env.JIRA_BASE_URL}/browse/${issueKey}`,
+      },
+      {},
+    );
+
+    // 輪詢等待 Approve（狀態變為 WAIT DEPLOY）
+    const poller = new Poller(jira);
+    await poller.waitForStatus(issueKey, 'WAIT DEPLOY', {
+      intervalMs: parseInt(process.env.POLL_INTERVAL_MS ?? '30000'),
+      timeoutMs: parseInt(process.env.POLL_TIMEOUT_MS ?? '3600000'),
+    });
+
+    return {approved: true, by: managerName};
+  }
+
+  // UAT: assign James Yu → 等待留言 → 轉 Solar Chen → 等待 approve
+  if (env === 'uat') {
+    const jamesAccountId = resolveAccountId('James Yu');
+    if (!jamesAccountId) {
+      throw new Error('找不到 James Yu 的 accountId');
+    }
+
+    // Assign 給 James Yu
+    await jira.updateAssignee(issueKey, jamesAccountId);
+    await notifier.notify(issueKey, '已指派給部長 James Yu，等待留言確認');
+
+    // 發送 jabber 通知給 James Yu
+    const jamesJabber = `${jamesAccountId}@linebank.com.tw`;
+    await handleSendJabberMessage(
+      {
+        to: jamesJabber,
+        message: `[GrayRelease 簽核通知] ${issueKey} 需要您的簽核並留言確認。環境: UAT\n${process.env.JIRA_BASE_URL}/browse/${issueKey}`,
+      },
+      {},
+    );
+
+    // 等待 James Yu 留言 "Approved"
+    const commentResult = await handleWaitForComment(
+      {
+        issueKey,
+        keyword: 'approved',
+        authorAccountId: jamesAccountId,
+        timeoutMs: parseInt(process.env.POLL_TIMEOUT_MS ?? '3600000'),
+        intervalMs: parseInt(process.env.POLL_INTERVAL_MS ?? '30000'),
+      },
+      {jira},
+    );
+    const commentData = parseMcpToolData(commentResult, 'wait_for_comment');
+
+    if (!commentData.found) {
+      throw new Error('等待 James Yu 留言超時');
+    }
+
+    await notifier.notify(issueKey, `James Yu 已留言確認: ${commentData.comment}`);
+
+    // 轉給 Solar Chen
+    const solarAccountId = resolveAccountId('Solar Chen');
+    if (!solarAccountId) {
+      throw new Error('找不到 Solar Chen 的 accountId');
+    }
+
+    await jira.updateAssignee(issueKey, solarAccountId);
+    await notifier.notify(issueKey, '已轉單給 Solar Chen，等待最終簽核');
+
+    // 發送 jabber 通知給 Solar Chen
+    const solarJabber = `${solarAccountId}@linebank.com.tw`;
+    await handleSendJabberMessage(
+      {
+        to: solarJabber,
+        message: `[GrayRelease 簽核通知] ${issueKey} 已由 James Yu 確認，需要您的最終簽核。環境: UAT\n${process.env.JIRA_BASE_URL}/browse/${issueKey}`,
+      },
+      {},
+    );
+
+    // 輪詢等待 Solar Approve（狀態變為 WAIT DEPLOY）
+    const poller = new Poller(jira);
+    await poller.waitForStatus(issueKey, 'WAIT DEPLOY', {
+      intervalMs: parseInt(process.env.POLL_INTERVAL_MS ?? '30000'),
+      timeoutMs: parseInt(process.env.POLL_TIMEOUT_MS ?? '3600000'),
+    });
+
+    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) {
+  // GrayRelease 永遠是 nonPrd 群組
+  const thisGroup = 'nonPrd';
+
+  // 只查詢 CD 單的部署歷史（不包含 GrayRelease）
+  const isPrdEnv = (env) => ['prd', 'dr', 'prd/dr', 'prd&dr'].includes(env?.toLowerCase()?.trim());
+
+  const jql_cd = `project = CID AND issuetype = CD AND "System Code[Select List (single choice)]" = "${systemCode}" AND status = Done AND issueKey != "${issueKey}" ORDER BY updated DESC`;
+
+  try {
+    const cdResults = await jira.searchIssues(jql_cd, ['customfield_13436', 'updated'], 1);
+    const cdIssue = cdResults[0] ?? null;
+
+    // 查不到歷史 → 保守執行 Switch
+    if (!cdIssue) {
+      return true;
+    }
+
+    // CD：讀 customfield_13436.value 判斷群組
+    const envVal = cdIssue.fields?.customfield_13436?.value ?? '';
+    const lastGroup = isPrdEnv(envVal) ? 'prd' : 'nonPrd';
+
+    // 群組不同 → 需要 Switch
+    return lastGroup !== thisGroup;
+  } catch {
+    // 查詢失敗 → 保守執行 Switch
+    return true;
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}