@jira-deploy/core 1.0.0

package/tools/index.js

@@ -0,0 +1,1119 @@
+import {Poller} from '../poller.js';
+import {
+  getLibraryToolDefinitions,
+  handleCreateLibraryTicket,
+  handleGetNextLibVersion,
+} from './library.js';
+import {getCIToolDefinitions, handleCreateCITicket, handleGetNextCIVersion} from './ci.js';
+import {
+  SYSTEM_CODES,
+  ENV_CODES,
+  CD_FIELD_IDS,
+  SUPPORTED_ENVS,
+  resolveAccountId,
+} from '../constants/index.js';
+import {getCDToolDefinitions, handleCreateCDTicket} from './cd.js';
+import {
+  getGrayReleaseToolDefinitions,
+  handleCreateGrayReleaseTicket,
+  handleLinkStgGrayRelease,
+} from './grayrelease.js';
+import {
+  getReleaseToolDefinitions,
+  handleGetUnreleasedVersions,
+  handleTransitionToWaitApproval,
+  handleGetReleaseManager,
+  handleWaitForComment,
+} from './release.js';
+import {getJabberToolDefinitions, handleSendJabberMessage} from './jabber.js';
+
+/**
+ * 回傳所有 tool 定義（schema）給 MCP Server 註冊
+ *
+ * ✨ 所有配置現已遷移至 src/constants/
+ * - field-ids.js: Jira customfield 映射
+ * - system-codes.js: 系統代碼及模組
+ * - environments.js: 環境代碼
+ * - server.js: 部署列表
+ * - issue-types.js: Issue 類型定義
+ * - modules.js: 模組 ID 映射
+ * - defaults.js: 預設值及範本
+ */
+export function getToolDefinitions() {
+  return [
+    ...getLibraryToolDefinitions(),
+    ...getCIToolDefinitions(),
+    ...getCDToolDefinitions(),
+    ...getGrayReleaseToolDefinitions(),
+    ...getReleaseToolDefinitions(),
+    ...getJabberToolDefinitions(),
+    {
+      name: 'transition_issue',
+      description: '切換 Jira issue 狀態，用名稱指定（不需要知道 transition ID）',
+      inputSchema: {
+        type: 'object',
+        required: ['issueKey', 'transitionName'],
+        properties: {
+          issueKey: {type: 'string', description: '例如 OPS-123'},
+          transitionName: {
+            type: 'string',
+            description: '狀態名稱，例如 "Pending Approval"、"Approved"、"In Progress"、"Done"',
+          },
+        },
+      },
+    },
+    {
+      name: 'wait_for_approval',
+      description:
+        '輪詢等待 issue 被主管 approve（狀態變為 Approved）。這個工具會持續輪詢直到狀態改變或超時。',
+      inputSchema: {
+        type: 'object',
+        required: ['issueKey'],
+        properties: {
+          issueKey: {type: 'string'},
+          targetStatus: {
+            type: 'string',
+            default: 'Approved',
+            description: '等待的目標狀態名稱（預設 Approved）',
+          },
+          pollIntervalMs: {
+            type: 'number',
+            description: '輪詢間隔毫秒（預設讀 env POLL_INTERVAL_MS）',
+          },
+          timeoutMs: {
+            type: 'number',
+            description: '最長等待毫秒（預設讀 env POLL_TIMEOUT_MS）',
+          },
+        },
+      },
+    },
+    {
+      name: 'get_issue_status',
+      description: '取得 issue 目前狀態與摘要',
+      inputSchema: {
+        type: 'object',
+        required: ['issueKey'],
+        properties: {
+          issueKey: {type: 'string'},
+        },
+      },
+    },
+    {
+      name: 'add_deploy_comment',
+      description: '在 issue 上新增留言（部署結果、build log 連結等）',
+      inputSchema: {
+        type: 'object',
+        required: ['issueKey', 'message'],
+        properties: {
+          issueKey: {type: 'string'},
+          message: {type: 'string', description: '留言內容'},
+        },
+      },
+    },
+    {
+      name: 'list_transitions',
+      description: '列出 issue 目前可執行的所有 transitions（debug 用）',
+      inputSchema: {
+        type: 'object',
+        required: ['issueKey'],
+        properties: {
+          issueKey: {type: 'string'},
+        },
+      },
+    },
+    {
+      name: 'link_issues',
+      description:
+        '在兩個 Jira issue 之間建立關聯。常用類型：Relates（互相關聯）、Hierarchy link (WBSGantt)（CI contains CD，outward=contains / inward=is contained in）',
+      inputSchema: {
+        type: 'object',
+        required: ['inwardKey', 'outwardKey'],
+        properties: {
+          inwardKey: {type: 'string', description: '被包含方 issue key，例如 CD 單 CID-1669'},
+          outwardKey: {type: 'string', description: '包含方 issue key，例如 CI 單 CID-1668'},
+          linkType: {
+            type: 'string',
+            description:
+              'Link 類型，預設 "Relates"，CI→CD 請用 "Hierarchy link (WBSGantt)"（outward=contains）',
+            default: 'Relates',
+          },
+        },
+      },
+    },
+    {
+      name: 'build_ticket',
+      description:
+        '觸發 Library 或 CI 上版單的 Jenkins Build。自動處理前置狀態切換與 Jira Automation 等待，不需要手動切換狀態。',
+      inputSchema: {
+        type: 'object',
+        required: ['issueKey'],
+        properties: {
+          issueKey: {
+            type: 'string',
+            description: '要 build 的 issue key，例如 CID-1668',
+          },
+        },
+      },
+    },
+    {
+      name: 'wait_to_stg',
+      description:
+        'CI 單 build 完成後，自動走完掃描流程切到 Wait To STG 狀態。流程：Compliance Scan → Upload Scan Report → Accept → Dev Done → Wait To STG',
+      inputSchema: {
+        type: 'object',
+        required: ['issueKey'],
+        properties: {
+          issueKey: {
+            type: 'string',
+            description: 'CI issue key，例如 CID-1668',
+          },
+        },
+      },
+    },
+    {
+      name: 'trigger_deployment',
+      description:
+        '在 CD 單的 Deployment sub-task 上依序觸發部署 transitions（To Pretask → To AutoDeploy → Trigger AutoDeploy）。接在 prepare_cd_deployment 之後使用。當使用者說「幫我 Deploy」、「上版」、「deploy」時優先使用這個 tool',
+      inputSchema: {
+        type: 'object',
+        required: ['cdIssueKey', 'environment'],
+        properties: {
+          cdIssueKey: {
+            type: 'string',
+            description: 'CD 單 issue key，例如 CID-1710',
+          },
+          environment: {
+            type: 'string',
+            enum: SUPPORTED_ENVS.cd,
+            description: `部署目標環境：${SUPPORTED_ENVS.cd.join(' / ')}`,
+          },
+          applyForClose: {
+            type: 'boolean',
+            description: '部署觸發後是否同步對 CD 單執行 Apply for close（預設 false）',
+          },
+        },
+      },
+    },
+    {
+      name: 'prepare_cd_deployment',
+      description:
+        '在 CD 單點擊「Prepare to Create Deployment」觸發部署。自動更新環境欄位並執行 transition，啟動 Jenkins 部署流程。',
+      inputSchema: {
+        type: 'object',
+        required: ['issueKey', 'environment'],
+        properties: {
+          issueKey: {
+            type: 'string',
+            description: 'CD 單 issue key，例如 CID-1697',
+          },
+          environment: {
+            type: 'string',
+            enum: SUPPORTED_ENVS.cd,
+            description: `部署目標環境：${SUPPORTED_ENVS.cd.join(' / ')}`,
+          },
+        },
+      },
+    },
+    {
+      name: 'cancel_release',
+      description:
+        '取消目前進行中的 CI 單，並回傳關聯的 Library 模組清單（含 gitBranch）與其他關聯 CI 單，供後續 reroll 流程使用。當使用者說「cancel IBK release」、「取消 IBK release」、「can 掉 IBK」時使用。',
+      inputSchema: {
+        type: 'object',
+        required: ['systemCode'],
+        properties: {
+          systemCode: {
+            type: 'string',
+            description: '系統代碼，例如 IBK、EIB、EVT',
+          },
+          ciIssueKey: {
+            type: 'string',
+            description: '若已知 CI 單 key，直接指定（不填則自動查最新進行中的 CI 單）',
+          },
+        },
+      },
+    },
+    {
+      name: 'get_release_status',
+      description:
+        '查詢指定系統代號的 Release 現況。以最新 CI 單為錨點，列出關聯的 Library 單、CD 單狀態與建議下一步。當使用者說「IBK 目前 release 到哪了」、「現在 CI 狀態怎樣」、「幫我看一下進度」時使用。',
+      inputSchema: {
+        type: 'object',
+        required: ['systemCode'],
+        properties: {
+          systemCode: {
+            type: 'string',
+            description: '系統代碼，例如 IBK、EIB、EVT、CWA、BOF',
+          },
+        },
+      },
+    },
+    {
+      name: 'update_assignee',
+      description:
+        '更新 Jira issue 的 Assignee。當使用者說「切單給 Solar」或「切單給 xxx(BK00129)」時使用。支援直接輸入名稱（會自動查找 accountId）或直接指定 accountId。',
+      inputSchema: {
+        type: 'object',
+        required: ['issueKey'],
+        properties: {
+          issueKey: {
+            type: 'string',
+            description: '要更新的 issue key，例如 CID-1718',
+          },
+          accountId: {
+            type: 'string',
+            description: 'Jira 用戶 accountId，例如 BK00129（與 displayName 擇一填寫即可）',
+          },
+          displayName: {
+            type: 'string',
+            description: '用戶顯示名稱或暱稱，例如 Solar（系統會自動查找對應的 accountId）',
+          },
+        },
+      },
+    },
+  ];
+}
+
+/**
+ * 執行 tool，回傳 { content: [{ type: 'text', text }] }
+ */
+export async function executeTool(name, args, {jira, notifier}) {
+  const poller = new Poller(jira);
+
+  switch (name) {
+    case 'transition_issue': {
+      try {
+        const result = await jira.transitionByName(args.issueKey, args.transitionName);
+        await notifier.notify(args.issueKey, `狀態已切換為：${result.toStatus}`);
+        return ok(result);
+      } catch (err) {
+        return error(`transition 失敗: ${err.message}`);
+      }
+    }
+
+    case 'wait_for_approval': {
+      const targetStatus = args.targetStatus ?? 'Approved';
+
+      await notifier.notify(args.issueKey, `等待主管 Approve（目標狀態：${targetStatus}）`);
+
+      const result = await poller.waitForStatus(args.issueKey, targetStatus, {
+        intervalMs: args.pollIntervalMs,
+        timeoutMs: args.timeoutMs,
+      });
+
+      await notifier.notify(
+        args.issueKey,
+        `已收到 Approve（${result.attempts} 次輪詢，耗時 ${Math.round(result.elapsedMs / 1000)}s）`,
+      );
+
+      return ok(result);
+    }
+
+    case 'get_issue_status': {
+      const issue = await jira.getIssue(args.issueKey);
+      return ok({
+        issueKey: args.issueKey,
+        status: issue.fields.status.name,
+        summary: issue.fields.summary,
+      });
+    }
+
+    case 'add_deploy_comment': {
+      await notifier.notify(args.issueKey, args.message);
+      return ok({issueKey: args.issueKey, commented: true});
+    }
+
+    case 'list_transitions': {
+      const transitions = await jira.getTransitions(args.issueKey);
+      return ok(transitions.map((t) => ({id: t.id, name: t.name, to: t.to.name})));
+    }
+
+    case 'create_library_ticket':
+      return handleCreateLibraryTicket(args, {jira, notifier});
+
+    case 'create_ci_ticket': {
+      return handleCreateCITicket(args, {jira, notifier});
+    }
+
+    case 'create_cd_ticket': {
+      return handleCreateCDTicket(args, {jira, notifier});
+    }
+
+    case 'create_grayrelease_ticket': {
+      return handleCreateGrayReleaseTicket(args, {jira, notifier});
+    }
+
+    case 'link_stg_grayrelease':
+      return handleLinkStgGrayRelease(args, {jira, notifier});
+
+    case 'get_unreleased_versions':
+      return handleGetUnreleasedVersions(args, {jira});
+
+    case 'transition_to_wait_approval':
+      return handleTransitionToWaitApproval(args, {jira, notifier});
+
+    case 'get_release_manager':
+      return handleGetReleaseManager(args, {});
+
+    case 'wait_for_comment':
+      return handleWaitForComment(args, {jira});
+
+    case 'send_jabber_message':
+      return handleSendJabberMessage(args, {});
+
+    case 'link_issues': {
+      try {
+        const linkType = args.linkType ?? 'Relates';
+        const result = await jira.linkIssue(args.inwardKey, args.outwardKey, linkType);
+        await notifier.notify(args.inwardKey, `已建立關聯至 ${args.outwardKey}（${linkType}）`);
+        return ok(result);
+      } catch (err) {
+        return error(`無法建立關聯: ${err.message}`);
+      }
+    }
+
+    case 'build_ticket': {
+      const {issueKey} = args;
+      const log = [];
+
+      /**
+       * CI Release 完整狀態流程：
+       *   TO DO → (Accept) → Wait for Build → (Build) → Compliance Scan
+       *   → (Upload Scan Report) → Upload Report → (Accept) → Wait To DEV
+       *   → (Dev Done) → Wait To STG → (STG Done) → Wait To UAT
+       *   → (UAT Done) → Wait For Upload → (Upload To Pre-Release)
+       *   → Wait For Upload → (Upload Done) → Wait To PRD/DR
+       *   → (PRD/DR Done)
+       *
+       * Library Release 完整狀態流程：
+       *   TO DO → (Upload Lib Report) → UPLOAD LIB REPORT → (Apply for approval) → Wait Approval → (Approved) → WAIT FOR LIB BUILD → (Build) → Released
+       *   或：TO DO → (Upload Lib Report) → UPLOAD LIB REPORT → Jira Automation 自動觸發 Jenkins（無手動 Build）
+       */
+
+        // 前置 transitions：若 "Build" 尚未出現，先觸發這些讓 Jira Automation 推進
+        // 'Upload Lib Report'：Library 票從 TO DO 的第一步（對應 UI 的 Upload Library Report）
+      const PRE_TRANSITIONS = ['Upload Lib Report', 'Apply for approval', 'Approved', 'Accept'];
+      const POLL_INTERVAL = 3000; // 3s
+      const MAX_WAIT_MS = 30000; // 最多等 30s（避免 MCP client timeout）
+
+      const findTransition = async (name) => {
+        const list = await jira.getTransitions(issueKey);
+        return list.find((t) => t.name.toLowerCase() === name.toLowerCase());
+      };
+
+      const waitForTransition = async (name) => {
+        const deadline = Date.now() + MAX_WAIT_MS;
+        while (Date.now() < deadline) {
+          const t = await findTransition(name);
+          if (t) return t;
+          await new Promise((r) => setTimeout(r, POLL_INTERVAL));
+        }
+        return null;
+      };
+
+      try {
+        // 記錄初始狀態（用於判斷是否有狀態推進）
+        const initIssue = await jira.getIssue(issueKey);
+        const initStatus = initIssue.fields.status.name;
+
+        // Step 1: 確認目前是否已有 Build transition
+        let buildTrans = await findTransition('Build');
+
+        // Step 2: 若沒有，逐步觸發前置 transitions
+        if (!buildTrans) {
+          log.push('未找到 Build transition，逐步觸發前置狀態...');
+          let preTriggered = false;
+
+          // 最多嘗試 PRE_TRANSITIONS.length 輪，每輪觸發一個可用的前置 transition
+          for (let step = 0; step < PRE_TRANSITIONS.length; step++) {
+            const transitions = await jira.getTransitions(issueKey);
+            const pre = transitions.find((t) =>
+              PRE_TRANSITIONS.some((name) => t.name.toLowerCase() === name.toLowerCase()),
+            );
+            if (!pre) break;
+
+            log.push(`  [step ${step + 1}] 觸發「${pre.name}」...`);
+            await jira.transitionById(issueKey, pre.id).catch(() => {
+            });
+            preTriggered = true;
+            // 等 Jira 更新狀態
+            await new Promise((r) => setTimeout(r, 2000));
+
+            buildTrans = await findTransition('Build');
+            if (buildTrans) {
+              log.push(`  已找到 Build transition`);
+              break;
+            }
+          }
+
+          // 若還沒出現，再給 Jira Automation 最多 30s
+          if (!buildTrans) {
+            log.push('  等待 Jira Automation 推進（最多 30s）...');
+            buildTrans = await waitForTransition('Build');
+          }
+
+          // 若仍未找到 Build transition，但有觸發前置 transition 且狀態已推進，
+          // 代表此 Library workflow 由 Jira Automation 自動觸發 Jenkins（無需手動 Build）
+          if (!buildTrans && preTriggered) {
+            const currentIssue = await jira.getIssue(issueKey);
+            const currentStatus = currentIssue.fields.status.name;
+            if (currentStatus !== initStatus) {
+              log.push(
+                `⚠️ 無手動 Build transition，但狀態已推進：${initStatus} → ${currentStatus}`,
+              );
+              log.push('  Jenkins Build 可能已由 Jira Automation 自動觸發');
+              await notifier.notify(
+                issueKey,
+                `Library Build 已觸發（Jira Auto）狀態：${initStatus} → ${currentStatus}`,
+              );
+              return ok({issueKey, status: currentStatus, steps: log, autoTriggered: true});
+            }
+          }
+        }
+
+        if (!buildTrans) {
+          const issue = await jira.getIssue(issueKey);
+          return error(`找不到 Build transition，目前狀態：${issue.fields.status.name}`);
+        }
+
+        // Step 4: 執行 Build
+        log.push(`執行 Build transition (id: ${buildTrans.id})...`);
+        await jira.transitionById(issueKey, buildTrans.id);
+
+        const issue = await jira.getIssue(issueKey);
+        const newStatus = issue.fields.status.name;
+        log.push(`✅ Build 已觸發，目前狀態：${newStatus}`);
+        await notifier.notify(issueKey, `Jenkins Build 已觸發（${newStatus}）`);
+
+        return ok({issueKey, status: newStatus, steps: log});
+      } catch (err) {
+        return error(`build_ticket 失敗: ${err.message}`);
+      }
+    }
+
+    case 'wait_to_stg': {
+      const {issueKey} = args;
+      const log = [];
+
+      // CI 掃描 → STG 的標準流程步驟
+      // 每個元素：{ transition: '名稱', targetStatus: '到達後的狀態名稱' }
+      const STEPS = [
+        {transition: 'Upload Scan Report', targetStatus: 'Upload Report'},
+        {transition: 'Accept', targetStatus: 'Wait To DEV'},
+        {transition: 'Dev Done', targetStatus: 'Wait To STG'},
+      ];
+
+      try {
+        for (const step of STEPS) {
+          const transitions = await jira.getTransitions(issueKey);
+          const t = transitions.find((t) => t.name.toLowerCase() === step.transition.toLowerCase());
+          if (!t) {
+            // 確認目前狀態是否已達目標，若是則跳過此步
+            const issue = await jira.getIssue(issueKey);
+            const current = issue.fields.status.name;
+            if (current.toLowerCase() === step.targetStatus.toLowerCase()) {
+              log.push(`  已是 ${current}，跳過「${step.transition}」`);
+              continue;
+            }
+            return error(`找不到 transition「${step.transition}」，目前狀態：${current}`);
+          }
+          log.push(`執行「${t.name}」→ ${step.targetStatus}`);
+          await jira.transitionById(issueKey, t.id);
+        }
+
+        const issue = await jira.getIssue(issueKey);
+        const finalStatus = issue.fields.status.name;
+        log.push(`✅ 完成，目前狀態：${finalStatus}`);
+        await notifier.notify(issueKey, `已切換至 ${finalStatus}，可進行 STG 部署`);
+
+        return ok({issueKey, status: finalStatus, steps: log});
+      } catch (err) {
+        return error(`wait_to_stg 失敗: ${err.message}`);
+      }
+    }
+
+    case 'trigger_deployment': {
+      const {cdIssueKey, environment} = args;
+      const log = [];
+
+      // 判斷環境是否屬於 PRD 群組（prd / dr / prd/dr / prd&dr）
+      const isPrdEnv = (env) =>
+        ['prd', 'dr', 'prd/dr', 'prd&dr'].includes(env.toLowerCase().trim());
+
+      // 查詢同系統最近一筆已完成的部署（CD 或 GrayRelease），回傳 'prd' | 'nonPrd' | null
+      const getLastDeployEnvGroup = async (systemCode, excludeKey) => {
+        const jql_cd = `project = CID AND issuetype = CD AND "System Code[Select List (single choice)]" = "${systemCode}" AND status = Done AND issueKey != "${excludeKey}" ORDER BY updated DESC`;
+        const jql_gr = `project = CID AND issuetype = GrayRelease AND "System Code[Select List (single choice)]" = "${systemCode}" AND status = Done ORDER BY updated DESC`;
+
+        const [cdResults, grResults] = await Promise.all([
+          jira.searchIssues(jql_cd, ['customfield_13436', 'updated'], 1).catch(() => []),
+          jira.searchIssues(jql_gr, ['updated'], 1).catch(() => []),
+        ]);
+
+        const cdIssue = cdResults[0] ?? null;
+        const grIssue = grResults[0] ?? null;
+
+        // 沒有任何記錄 → 保守執行
+        if (!cdIssue && !grIssue) return null;
+
+        // 若只有其中一筆，直接用那筆
+        // 若兩筆都有，取 updated 較新者
+        let lastIssue = null;
+        let lastIsGray = false;
+
+        if (cdIssue && grIssue) {
+          const cdUpdated = new Date(cdIssue.fields?.updated ?? 0);
+          const grUpdated = new Date(grIssue.fields?.updated ?? 0);
+          if (grUpdated > cdUpdated) {
+            lastIssue = grIssue;
+            lastIsGray = true;
+          } else {
+            lastIssue = cdIssue;
+          }
+        } else if (grIssue) {
+          lastIssue = grIssue;
+          lastIsGray = true;
+        } else {
+          lastIssue = cdIssue;
+        }
+
+        // GrayRelease 永遠是 nonPrd
+        if (lastIsGray) return 'nonPrd';
+
+        // CD：讀 customfield_13436.value 判斷群組
+        const envVal = lastIssue.fields?.customfield_13436?.value ?? '';
+        return isPrdEnv(envVal) ? 'prd' : 'nonPrd';
+      };
+
+      // 依序觸發的 Deployment transitions
+      // conditionalWait: true → 依 needSwitch 決定是否執行並等待 180s
+      const DEPLOY_TRANSITIONS = [
+        {name: 'To Pretask'},
+        {name: 'Swtich Execution Node', conditionalWait: true},
+        {name: 'To AutoDeploy'},
+        {name: 'Trigger AutoDeploy'},
+      ];
+      // 環境字串對照（用於 sub-task summary 比對）
+      const envUpper = environment.toUpperCase().replace('/', '').replace('&', '');
+
+      try {
+        // Step 1: 取得 CD 單的 sub-tasks
+        const subTasks = await jira.getSubTasks(cdIssueKey);
+        if (!subTasks.length) {
+          return error(
+            `CD 單 ${cdIssueKey} 目前沒有 Deployment sub-task，請先執行 prepare_cd_deployment`,
+          );
+        }
+
+        log.push(`找到 ${subTasks.length} 個 sub-task：${subTasks.map((t) => t.key).join(', ')}`);
+
+        // Step 2: 依環境篩選 Deployment sub-task（比對 summary 中的環境標籤）
+        // 支援格式：[STG]、[UAT]、[PRD]、[DR]、[PRD/DR]、PRDDR 等
+        const envVariants = [envUpper, `[${envUpper}]`];
+        let deploymentKey = null;
+
+        for (const st of subTasks) {
+          const summaryUpper = (st.fields?.summary ?? '').toUpperCase().replace(/[\s/]/g, '');
+          if (envVariants.some((v) => summaryUpper.includes(v.replace(/[\s/]/g, '')))) {
+            deploymentKey = st.key;
+            break;
+          }
+        }
+
+        // fallback：若沒有符合環境的，取第一個 sub-task
+        if (!deploymentKey) {
+          deploymentKey = subTasks[0].key;
+          log.push(
+            `  ⚠️ 未找到明確符合環境 ${environment} 的 sub-task，使用第一個：${deploymentKey}`,
+          );
+        } else {
+          log.push(`  對應環境 ${environment} 的 Deployment 單：${deploymentKey}`);
+        }
+
+        // Step 2.5: 判斷是否需要執行 Switch Execution Node
+        // 規則：上次部署環境群組（prd/nonPrd）與本次不同時才需要切換 Ansible instance
+        const thisGroup = isPrdEnv(environment) ? 'prd' : 'nonPrd';
+        let needSwitch = true; // 預設保守執行
+
+        try {
+          const cdFields = await jira.getIssueFields(cdIssueKey, ['customfield_13443']);
+          const systemCode = cdFields?.customfield_13443?.value;
+          if (systemCode) {
+            const lastGroup = await getLastDeployEnvGroup(systemCode, cdIssueKey);
+            if (lastGroup === null) {
+              log.push(`  ⚠️ 找不到 ${systemCode} 的歷史部署記錄，保守執行 Switch Execution Node`);
+            } else if (lastGroup === thisGroup) {
+              needSwitch = false;
+              log.push(`  ✅ 上次部署同為 ${lastGroup} 群組，跳過 Switch Execution Node`);
+            } else {
+              log.push(`  🔄 環境群組變更（${lastGroup} → ${thisGroup}），需執行 Switch Execution Node`);
+            }
+          } else {
+            log.push(`  ⚠️ 無法取得 systemCode，保守執行 Switch Execution Node`);
+          }
+        } catch (e) {
+          log.push(`  ⚠️ 判斷 Switch 條件失敗（${e.message}），保守執行`);
+        }
+
+        // Step 3: 依序執行 transitions
+        for (const step of DEPLOY_TRANSITIONS) {
+          // conditionalWait: 依 needSwitch 決定是否執行
+          if (step.conditionalWait && !needSwitch) {
+            log.push(`  ⏭️ 跳過「${step.name}」（同環境群組，無需切換 Ansible instance）`);
+            continue;
+          }
+
+          const transitions = await jira.getTransitions(deploymentKey);
+          const t = transitions.find((t) => t.name.toLowerCase() === step.name.toLowerCase());
+
+          if (!t) {
+            const issue = await jira.getIssue(deploymentKey);
+            const available = transitions.map((t) => t.name).join(', ');
+            // 若 transition 不存在但狀態已超前，跳過
+            log.push(
+              `  ⚠️ 找不到「${step.name}」（目前狀態：${issue.fields.status.name}，可用：${available || '無'}），跳過`,
+            );
+            continue;
+          }
+
+          log.push(`  執行「${t.name}」...`);
+          await jira.transitionById(deploymentKey, t.id);
+          await new Promise((r) => setTimeout(r, 2000));
+
+          if (step.conditionalWait) {
+            const SWITCH_WAIT_MS = 180_000;
+            const secs = SWITCH_WAIT_MS / 1000;
+            log.push(`  ⏳ 等待 ${secs}s（等待 Ansible instance 切換完成）...`);
+            await notifier.notify(deploymentKey, `⏳ 等待 ${secs}s 後繼續部署...`);
+            await new Promise((r) => setTimeout(r, SWITCH_WAIT_MS));
+            log.push(`  ✅ 等待完成，繼續執行`);
+          }
+        }
+
+        const finalIssue = await jira.getIssue(deploymentKey);
+        const finalStatus = finalIssue.fields.status.name;
+        log.push(`✅ Deployment 已觸发，目前狀態：${finalStatus}`);
+        await notifier.notify(
+          deploymentKey,
+          `Deployment 部署已觸發（環境：${environment.toUpperCase()}，狀態：${finalStatus}）`,
+        );
+
+        // 若 applyForClose=true，同步對 CD 單觸發 Apply for close
+        if (args.applyForClose) {
+          try {
+            const cdTransitions = await jira.getTransitions(cdIssueKey);
+            const closeT = cdTransitions.find((t) => t.name.toLowerCase() === 'apply for close');
+            if (closeT) {
+              log.push(`  對 CD 單 ${cdIssueKey} 執行「${closeT.name}」...`);
+              await jira.transitionById(cdIssueKey, closeT.id);
+              const cdIssue = await jira.getIssue(cdIssueKey);
+              log.push(`  CD 單狀態：${cdIssue.fields.status.name}`);
+              await notifier.notify(cdIssueKey, `CD 單已提交關閉申請（Apply for close）`);
+            } else {
+              const available = cdTransitions.map((t) => t.name).join(', ');
+              log.push(
+                `  ⚠️ CD 單找不到「Apply for close」transition（可用：${available || '無'}）`,
+              );
+            }
+          } catch (e) {
+            log.push(`  ⚠️ Apply for close 失敗：${e.message}`);
+          }
+        }
+
+        return ok({
+          cdIssueKey,
+          deploymentKey,
+          environment,
+          status: finalStatus,
+          steps: log,
+        });
+      } catch (err) {
+        return error(`trigger_deployment 失敗: ${err.message}`);
+      }
+    }
+
+    case 'prepare_cd_deployment': {
+      const {issueKey} = args;
+      // 正規化環境名稱（prd&dr → prd/dr）
+      const envCode = args.environment.toLowerCase().replace('&', '/');
+      const log = [];
+
+      // CD 部署前置 transitions（依序嘗試，直到找到部署 transition 或完成申請流程）
+      // STG 完整流程：
+      //   TO DO → (Accept) → Wait For Send Notice Email
+      //         → (Prepare to create deployment ticket) → Prepare For Deploy  ← 建立 Deployment sub-task
+      //         → (Apply for approval) → Wait Approval  ← 等 Reviewer 核准
+      //         → Wait Deploy  ← 核准後自動切換，再呼叫 trigger_deployment
+      // ⚠️ 不加 'Approved'：Approved 需要其他主管才能執行
+      const CD_PRE_TRANSITIONS = [
+        'Accept',
+        'Prepare to create deployment ticket',
+        'Apply for approval',
+        'To Wait Deploy',
+      ];
+
+      // 部署 transition 名稱（支援多種命名）
+      const DEPLOY_TRANSITION_NAMES = [
+        'Prepare to create deployment ticket', // 實際 Jira transition 名稱
+        'Prepare to Create Deployment',
+        'Prepare Deploy',
+        'Create Deployment',
+        'Deploy',
+        'Start Deploy',
+      ];
+
+      try {
+        // Step 1: 驗證環境是否合法
+        if (!SUPPORTED_ENVS.cd.includes(envCode)) {
+          return error(`不支援的 CD 部署環境：${envCode}，合法值：${SUPPORTED_ENVS.cd.join(', ')}`);
+        }
+
+        // Step 2: 更新 CD 單的環境欄位（customfield_13436）
+        if (CD_FIELD_IDS.env && ENV_CODES[envCode]) {
+          await jira.updateIssue(issueKey, {
+            [CD_FIELD_IDS.env]: {id: ENV_CODES[envCode]},
+          });
+          log.push(`✅ 環境欄位更新為 ${envCode.toUpperCase()}`);
+        }
+
+        // Step 3: 尋找部署 transition，若不存在則先觸發前置 transitions
+        const findDeployTrans = async () => {
+          const list = await jira.getTransitions(issueKey);
+          for (const name of DEPLOY_TRANSITION_NAMES) {
+            const t = list.find((t) => t.name.toLowerCase() === name.toLowerCase());
+            if (t) return t;
+          }
+          return null;
+        };
+
+        let deployTrans = await findDeployTrans();
+
+        if (!deployTrans) {
+          log.push('未找到部署 transition，逐步觸發前置狀態...');
+          for (const preName of CD_PRE_TRANSITIONS) {
+            const transitions = await jira.getTransitions(issueKey);
+            const pre = transitions.find((t) => t.name.toLowerCase() === preName.toLowerCase());
+            if (!pre) continue;
+
+            log.push(`  觸發「${pre.name}」...`);
+            await jira.transitionById(issueKey, pre.id);
+            await new Promise((r) => setTimeout(r, 2000));
+
+            deployTrans = await findDeployTrans();
+            if (deployTrans) {
+              log.push(`  找到部署 transition：「${deployTrans.name}」`);
+              break;
+            }
+          }
+        }
+
+        if (!deployTrans) {
+          const issue = await jira.getIssue(issueKey);
+          const transitions = await jira.getTransitions(issueKey);
+          const available = transitions.map((t) => t.name).join(', ');
+          return error(
+            `找不到部署 transition（嘗試：${DEPLOY_TRANSITION_NAMES.join(', ')}）\n` +
+            `目前狀態：${issue.fields.status.name}\n` +
+            `可用 transitions：${available || '（無）'}`,
+          );
+        }
+
+        // Step 4: 觸发部署 transition
+        log.push(`執行「${deployTrans.name}」transition（id: ${deployTrans.id}）...`);
+        await jira.transitionById(issueKey, deployTrans.id);
+
+        const issue = await jira.getIssue(issueKey);
+        const newStatus = issue.fields.status.name;
+        log.push(`✅ 部署已觸发，目前狀態：${newStatus}`);
+
+        await notifier.notify(
+          issueKey,
+          `CD 部署已觸發（環境: ${envCode.toUpperCase()}，狀態: ${newStatus}）`,
+        );
+
+        return ok({
+          issueKey,
+          environment: envCode,
+          status: newStatus,
+          steps: log,
+        });
+      } catch (err) {
+        return error(`prepare_cd_deployment 失敗: ${err.message}`);
+      }
+    }
+
+    case 'update_assignee': {
+      const {issueKey} = args;
+      let {accountId, displayName} = args;
+
+      // 若只提供 displayName（或名稱），嘗試從 USER_MAP 查找 accountId
+      if (!accountId && displayName) {
+        const resolved = resolveAccountId(displayName);
+        if (!resolved) {
+          return error(
+            `找不到使用者「${displayName}」的 accountId，請直接指定 accountId 或更新 USER_MAP`,
+          );
+        }
+        accountId = resolved;
+      }
+
+      if (!accountId) {
+        return error('請提供 accountId 或使用者名稱（displayName）');
+      }
+
+      try {
+        await jira.updateAssignee(issueKey, accountId);
+        return ok({
+          issueKey,
+          assignee: {accountId, displayName: displayName ?? accountId},
+          message: `✅ ${issueKey} Assignee 已更新為 ${displayName ? `${displayName}(${accountId})` : accountId}`,
+        });
+      } catch (err) {
+        return error(`update_assignee 失敗: ${err.message}`);
+      }
+    }
+
+    case 'cancel_release': {
+      const {systemCode} = args;
+      let ciIssueKey = args.ciIssueKey ?? null;
+
+      try {
+        // Step 1: 若未指定 CI key，查最新進行中的 CI 單
+        if (!ciIssueKey) {
+          const ciIssues = await jira.searchIssues(
+            `project = CID AND issuetype = CI AND cf[13443] = "${systemCode}" AND status NOT IN (Done, Cancelled) ORDER BY updated DESC`,
+            ['summary', 'status'],
+            1,
+          );
+          if (!ciIssues.length) {
+            return error(`找不到 ${systemCode} 進行中的 CI 單`);
+          }
+          ciIssueKey = ciIssues[0].key;
+        }
+
+        // Step 2: 讀 CI 單的 issuelinks（取 Library + 關聯 CI）
+        const ciFields = await jira.getIssueFields(ciIssueKey, [
+          'summary',
+          'status',
+          'issuelinks',
+        ]);
+
+        const allLinks = ciFields.issuelinks ?? [];
+
+        // 關聯 Library 單（Relates，issuetype = Library）
+        const libraryLinks = allLinks.filter((l) => {
+          const linked = l.inwardIssue ?? l.outwardIssue;
+          return linked?.fields?.issuetype?.name === 'Library';
+        });
+
+        // 關聯 CI 單（Relates，issuetype = CI，排除自己）
+        const relatedCiLinks = allLinks.filter((l) => {
+          const linked = l.inwardIssue ?? l.outwardIssue;
+          return (
+            linked?.fields?.issuetype?.name === 'CI' &&
+            l.type?.name === 'Relates' &&
+            linked.key !== ciIssueKey
+          );
+        });
+
+        // Step 3: 批次查每個 Library 單的 gitBranch
+        const libraryKeys = libraryLinks.map((l) => (l.inwardIssue ?? l.outwardIssue).key);
+        const libraryExtraFields = await Promise.all(
+          libraryKeys.map((key) =>
+            jira.getIssueFields(key, ['customfield_13431', 'customfield_13444']).catch(() => ({})),
+          ),
+        );
+
+        const libraries = libraryLinks.map((l, i) => {
+          const linked = l.inwardIssue ?? l.outwardIssue;
+          const gitBranch = libraryExtraFields[i]?.customfield_13431 ?? null;
+          const moduleField = libraryExtraFields[i]?.customfield_13444;
+          const moduleName =
+            (Array.isArray(moduleField) ? moduleField[0]?.value : moduleField?.value) ??
+            linked.fields.summary ?? linked.key;
+          return {
+            key: linked.key,
+            module: moduleName,
+            gitBranch,
+            status: linked.fields.status?.name ?? '',
+            summary: linked.fields.summary ?? '',
+          };
+        });
+
+        const relatedCiKeys = relatedCiLinks.map((l) => (l.inwardIssue ?? l.outwardIssue).key);
+
+        // Step 4: 執行 Cancel transition
+        const transitions = await jira.getTransitions(ciIssueKey);
+        const cancelT = transitions.find((t) => t.name.toLowerCase() === 'cancelled');
+        if (!cancelT) {
+          const available = transitions.map((t) => t.name).join(', ');
+          return error(
+            `${ciIssueKey} 找不到 Cancelled transition，目前狀態：${ciFields.status?.name}，可用：${available}`,
+          );
+        }
+        await jira.transitionById(ciIssueKey, cancelT.id);
+        await notifier.notify(ciIssueKey, `CI 單已取消（Release Reroll 流程啟動）`);
+
+        return ok({
+          cancelledCiKey: ciIssueKey,
+          relatedCiKeys,
+          libraries,
+          message: `✅ ${ciIssueKey} 已取消，找到 ${libraries.length} 個 Library 模組`,
+        });
+      } catch (err) {
+        return error(`cancel_release 失敗: ${err.message}`);
+      }
+    }
+
+    case 'get_release_status': {
+      const {systemCode} = args;
+
+      // 狀態 → 說明 + 建議下一步
+      const describeStatus = (issueType, status) => {
+        const s = status.toLowerCase();
+        if (issueType === 'Library') {
+          if (s === 'to do') return {emoji: '⏳', desc: '尚未開始', next: `執行 build_ticket`};
+          if (s === 'upload lib report') return {emoji: '⏳', desc: '等待上傳 Lib Report', next: `執行 build_ticket`};
+          if (s === 'wait approval') return {emoji: '⏳', desc: '等待主管核准', next: `wait_for_approval`};
+          if (s === 'wait for lib build') return {emoji: '🔨', desc: '等待 Jenkins Build', next: `執行 build_ticket`};
+          if (s === 'released') return {emoji: '✅', desc: '已完成', next: '可開 CI'};
+          if (s === 'cancelled') return {emoji: '❌', desc: '已取消', next: null};
+          return {emoji: '🔄', desc: status, next: null};
+        }
+        if (issueType === 'CI') {
+          if (s === 'to do') return {emoji: '⏳', desc: '尚未開始', next: '執行 build_ticket'};
+          if (s === 'wait for build') return {emoji: '⏳', desc: '等待 Jenkins Build', next: '執行 build_ticket'};
+          if (s === 'compliance scan') return {emoji: '🔍', desc: '掃描中', next: '執行 wait_to_stg'};
+          if (s === 'upload report') return {emoji: '📋', desc: '上傳掃描報告', next: '執行 wait_to_stg'};
+          if (s === 'wait to dev') return {emoji: '🔄', desc: 'Build 完成，等待 DEV', next: '執行 wait_to_stg'};
+          if (s === 'wait to stg') return {emoji: '✅', desc: 'Build 完成，等待 STG 部署', next: '可建 CD(STG) 並執行 prepare_cd_deployment'};
+          if (s === 'wait to uat') return {emoji: '✅', desc: 'STG 完成，等待 UAT', next: '可建 CD(UAT)'};
+          if (s === 'wait for upload') return {emoji: '📦', desc: '等待上傳 Pre-Release', next: null};
+          if (s === 'wait to prd/dr') return {emoji: '✅', desc: 'UAT 完成，等待 PRD/DR', next: '可建 CD(PRD/DR)'};
+          if (s === 'done') return {emoji: '✅', desc: '已完成', next: null};
+          if (s === 'cancelled') return {emoji: '❌', desc: '已取消', next: null};
+          return {emoji: '🔄', desc: status, next: null};
+        }
+        if (issueType === 'CD') {
+          if (s === 'to do') return {emoji: '⏳', desc: '尚未開始', next: '執行 prepare_cd_deployment'};
+          if (s === 'wait for send notice email') return {emoji: '⏳', desc: '等待通知信', next: '執行 prepare_cd_deployment'};
+          if (s === 'prepare for deploy') return {emoji: '⏳', desc: '部署單建立中', next: null};
+          if (s === 'wait approval') return {emoji: '⏳', desc: '等待主管核准', next: 'wait_for_approval'};
+          if (s === 'wait deploy') return {emoji: '✅', desc: '已核准，等待部署', next: '執行 trigger_deployment'};
+          if (s === 'deploying') return {emoji: '🚀', desc: '部署中', next: null};
+          if (s === 'done') return {emoji: '✅', desc: '部署完成', next: null};
+          if (s === 'cancelled') return {emoji: '❌', desc: '已取消', next: null};
+          return {emoji: '🔄', desc: status, next: null};
+        }
+        return {emoji: '🔄', desc: status, next: null};
+      };
+
+      try {
+        // Step 1: 查最新 CI 單
+        const ciIssues = await jira.searchIssues(
+          `project = CID AND issuetype = CI AND cf[13443] = "${systemCode}" ORDER BY updated DESC`,
+          ['summary', 'status', 'issuelinks', 'customfield_13438'],
+          1,
+        );
+
+        if (!ciIssues.length) {
+          return error(`找不到 ${systemCode} 的 CI 單`);
+        }
+
+        const ciIssue = ciIssues[0];
+        const ciStatus = describeStatus('CI', ciIssue.fields.status.name);
+        const ciVersion = ciIssue.fields.customfield_13438
+          ? (() => { try { return JSON.stringify(JSON.parse(ciIssue.fields.customfield_13438)); } catch { return ciIssue.fields.customfield_13438; } })()
+          : '（尚無版本）';
+
+        // Step 2: 從 CI issuelinks 找 Library 單（Relates），並平行查 gitBranch
+        const libraryLinks = (ciIssue.fields.issuelinks ?? []).filter((l) => {
+          const linked = l.inwardIssue ?? l.outwardIssue;
+          return linked?.fields?.issuetype?.name === 'Library';
+        });
+
+        const libraryExtraFields = await Promise.all(
+          libraryLinks.map((l) => {
+            const linked = l.inwardIssue ?? l.outwardIssue;
+            return jira
+              .getIssueFields(linked.key, ['customfield_13431'])
+              .catch(() => ({}));
+          }),
+        );
+
+        const libraryInfos = libraryLinks.map((l, i) => {
+          const linked = l.inwardIssue ?? l.outwardIssue;
+          const d = describeStatus('Library', linked.fields.status?.name ?? '');
+          const gitBranch = libraryExtraFields[i]?.customfield_13431 ?? '（無）';
+          return `  ${linked.key}  [${linked.fields.status?.name}] ${d.emoji} ${d.desc}${
+            d.next ? ` → ${d.next}(${linked.key})` : ''
+          }\n    branch: ${gitBranch}\n    ${linked.fields.summary ?? ''}`;
+        });
+
+        // Step 3: 查近期 CD 單（取 5 筆）
+        const cdIssues = await jira.searchIssues(
+          `project = CID AND issuetype = CD AND cf[13443] = "${systemCode}" ORDER BY updated DESC`,
+          ['summary', 'status', 'customfield_13436', 'customfield_14101', 'updated'],
+          5,
+        );
+
+        // 依環境分組（取每個環境最新一筆）
+        const cdByEnv = {};
+        for (const cd of cdIssues) {
+          const envVal = (cd.fields?.customfield_13436?.value ?? 'unknown').toLowerCase();
+          if (!cdByEnv[envVal]) cdByEnv[envVal] = cd;
+        }
+
+        const cdLines = Object.entries(cdByEnv).map(([env, cd]) => {
+          const d = describeStatus('CD', cd.fields.status.name);
+          return `  ${env.toUpperCase()}：${cd.key} [${cd.fields.status.name}] ${d.emoji} ${d.desc}${
+            d.next ? ` → ${d.next}` : ''
+          }`;
+        });
+
+        // Step 4: 組合輸出
+        const today = new Date().toISOString().slice(0, 10);
+        const lines = [
+          `📦 ${systemCode} Release 現況（${today}）`,
+          '',
+          '── CI ──────────────────────────────',
+          `  ${ciIssue.key}  [${ciIssue.fields.status.name}] ${ciStatus.emoji} ${ciStatus.desc}${
+            ciStatus.next ? ` → ${ciStatus.next}` : ''
+          }`,
+          `  版本：${ciVersion}`,
+          '',
+          '── Library（本次 CI 關聯）────────────',
+          ...(libraryInfos.length ? libraryInfos : ['  （無關聯 Library 單）']),
+          '',
+          '── CD ──────────────────────────────',
+          ...(cdLines.length ? cdLines : ['  （尚無 CD 單）']),
+        ];
+
+        return ok({summary: lines.join('\n'), ci: ciIssue.key, version: ciVersion});
+      } catch (err) {
+        return error(`get_release_status 失敗: ${err.message}`);
+      }
+    }
+
+    case 'get_next_lib_version':
+      return handleGetNextLibVersion(args, {jira});
+
+    case 'get_next_ci_version':
+      return handleGetNextCIVersion(args, {jira});
+
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+function ok(data) {
+  return {
+    content: [{type: 'text', text: JSON.stringify(data, null, 2)}],
+  };
+}
+
+function error(msg) {
+  return {
+    content: [{type: 'text', text: `❌ 錯誤: ${msg}`}],
+  };
+}