@jira-deploy/core 1.0.15 → 1.0.17

package/tools/deployment-helpers.js

@@ -0,0 +1,103 @@
+import {getPollIntervalMs} from './helpers.js';
+import {sleep} from './transition-helpers.js';
+
+export function normalizeDeploymentEnvironment(environment) {
+  return String(environment ?? '')
+    .trim()
+    .toLowerCase()
+    .replace('&', '/');
+}
+
+export function isPrdLikeEnv(environment) {
+  return ['prd', 'dr', 'prd/dr'].includes(normalizeDeploymentEnvironment(environment));
+}
+
+export function getDeploymentEnvGroup(environment) {
+  return isPrdLikeEnv(environment) ? 'prd' : 'nonPrd';
+}
+
+export async function needSwitchExecutionNode({
+  issueKey,
+  systemCode,
+  environment,
+  envGroup,
+  jira,
+  log = [],
+}) {
+  const thisGroup = envGroup ?? getDeploymentEnvGroup(environment);
+
+  if (await hasRecentSwitchExecutionNodeComment({issueKey, systemCode, envGroup: thisGroup, jira})) {
+    log.push(`  ✅ 已找到 ${thisGroup} execution node 切換成功留言，跳過 Switch Execution Node`);
+    return false;
+  }
+
+  const jql = `project = CID AND (issuetype = CD OR issuetype = GrayRelease) AND text ~ "${systemCode}" AND status = Done AND issueKey != "${issueKey}" ORDER BY updated DESC`;
+
+  try {
+    log.push('  查詢歷史 CD/GrayRelease 單，判斷是否需要切換 Execution Node');
+    const results = await jira.searchIssues(jql, ['customfield_13436', 'updated', 'issuetype'], 1);
+    const lastIssue = results[0] ?? null;
+
+    if (!lastIssue) {
+      log.push('  ⚠️ 找不到歷史部署記錄，保守執行 Switch Execution Node');
+      return true;
+    }
+
+    const issueTypeName = lastIssue.fields?.issuetype?.name ?? '';
+    const envValue = lastIssue.fields?.customfield_13436?.value ?? '';
+    const lastGroup = issueTypeName.toLowerCase() === 'grayrelease'
+      ? 'nonPrd'
+      : getDeploymentEnvGroup(envValue);
+
+    if (lastGroup === thisGroup) {
+      log.push(`  ✅ 上次部署同為 ${lastGroup} 群組，跳過 Switch Execution Node`);
+      return false;
+    }
+
+    log.push(`  🔄 環境群組變更（${lastGroup} → ${thisGroup}），需執行 Switch Execution Node`);
+    return true;
+  } catch (err) {
+    log.push(`  ⚠️ 判斷 Switch 條件失敗（${err.message}），保守執行`);
+    return true;
+  }
+}
+
+export async function waitForSwitchExecutionNode({issueKey, systemCode, envGroup = 'nonPrd', 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, envGroup, jira})) {
+      return true;
+    }
+
+    if (Date.now() >= deadline) {
+      return false;
+    }
+
+    await sleep(intervalMs);
+  }
+}
+
+async function hasRecentSwitchExecutionNodeComment({issueKey, systemCode, envGroup, jira}) {
+  if (!jira.getComments) {
+    return false;
+  }
+
+  try {
+    const comments = await jira.getComments(issueKey);
+    const lowerSystemCode = String(systemCode ?? '').toLowerCase();
+    const groupNeedle = envGroup === 'prd' ? 'prd_executionnode' : 'nonprd_executionnode';
+    return comments.some((comment) => {
+      const body = String(comment.body ?? '').toLowerCase();
+      const author = String(comment.author?.displayName ?? '').toLowerCase();
+      return author === 'cid jira worker'
+        && body.includes('instance_group')
+        && body.includes(groupNeedle)
+        && (!lowerSystemCode || body.includes(lowerSystemCode));
+    });
+  } catch {
+    return false;
+  }
+}

package/tools/deployment.js

@@ -0,0 +1,269 @@
+import {
+  error,
+  getPollIntervalMs,
+  getPollTimeoutMs,
+  isFailingResult,
+  isPassingResult,
+  ok,
+} from './helpers.js';
+import {sleep} from './transition-helpers.js';
+import {CD_FIELD_IDS, GRAY_RELEASE_FIELD_IDS} from '../constants/index.js';
+import {
+  getDeploymentEnvGroup,
+  isPrdLikeEnv,
+  needSwitchExecutionNode,
+  normalizeDeploymentEnvironment,
+  waitForSwitchExecutionNode,
+} from './deployment-helpers.js';
+
+const DEPLOY_RESULT_FIELD_ID = GRAY_RELEASE_FIELD_IDS.deployResult;
+
+export function getDeploymentToolDefinitions() {
+  return [
+    {
+      name: 'trigger_deployment',
+      description:
+        '在 CD 單的 Deployment sub-task 上依序觸發部署 transitions（To Pretask → Switch Execution Node 視 prd/nonPrd 群組決定 → To AutoDeploy → Trigger AutoDeploy），並等待 CID_deploy_result(customfield_13433) pass。接在 prepare_cd_deployment 之後使用。',
+      inputSchema: {
+        type: 'object',
+        required: ['cdIssueKey', 'environment'],
+        properties: {
+          cdIssueKey: {
+            type: 'string',
+            description: 'CD 單 issue key',
+          },
+          environment: {
+            type: 'string',
+            enum: ['dev', 'stg', 'uat', 'prd/dr', 'prd', 'dr'],
+            description: '部署目標環境：dev / stg / uat / prd/dr / prd / dr',
+          },
+          applyForClose: {
+            type: 'boolean',
+            description: '部署結果 pass 後是否同步對 CD 單執行 Apply for close（預設 false；正式 release flow 不會自動關單）',
+          },
+        },
+      },
+    },
+  ];
+}
+
+export async function handleTriggerDeployment(args, ctx) {
+  const {jira, notifier} = ctx;
+  const {cdIssueKey} = args;
+  const environment = normalizeDeploymentEnvironment(args.environment);
+  const log = [];
+
+  try {
+    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((task) => task.key).join(', ')}`);
+    const deploymentKey = selectDeploymentSubtask(subTasks, environment, log);
+    const systemCode = await getCDSystemCode(cdIssueKey, jira);
+    const envGroup = getDeploymentEnvGroup(environment);
+    const shouldSwitch = await needSwitchExecutionNode({
+      issueKey: cdIssueKey,
+      systemCode,
+      environment,
+      envGroup,
+      jira,
+      log,
+    });
+
+    const deploySteps = [
+      {names: ['To Pretask']},
+      {names: ['Switch Execution Node', 'Swtich Execution Node'], conditionalWait: true},
+      {names: ['To AutoDeploy'], required: true},
+      {names: ['Trigger AutoDeploy'], required: true},
+    ];
+
+    for (const step of deploySteps) {
+      if (step.conditionalWait && !shouldSwitch) {
+        log.push('  ⏭️ 跳過「Switch Execution Node」（同環境群組，無需切換 Ansible instance）');
+        continue;
+      }
+
+      const transition = await findAnyTransition(deploymentKey, step.names, jira);
+      if (!transition) {
+        const issue = await jira.getIssue(deploymentKey);
+        const transitions = await jira.getTransitions(deploymentKey);
+        const available = transitions.map((item) => item.name).join(', ');
+        const displayName = step.names[0];
+        if (step.required) {
+          return error(`找不到必要部署 transition「${displayName}」，目前狀態：${issue.fields.status.name}，可用：${available || '無'}`);
+        }
+        log.push(`  ⚠️ 找不到「${displayName}」（目前狀態：${issue.fields.status.name}，可用：${available || '無'}），跳過`);
+        continue;
+      }
+
+      log.push(`  執行「${transition.name}」...`);
+      await jira.transitionById(deploymentKey, transition.id);
+      await sleep(2000);
+
+      if (step.conditionalWait) {
+        const switched = await waitForSwitchExecutionNode({
+          issueKey: cdIssueKey,
+          systemCode,
+          envGroup,
+          jira,
+        });
+        log.push(switched
+          ? '  ✅ 已確認 Ansible instance 切換完成'
+          : '  ⚠️ 未在等待時間內確認切換留言，繼續執行部署');
+      }
+    }
+
+    const deployResult = await waitForDeploymentResult(deploymentKey, environment, ctx, log);
+    const finalIssue = await jira.getIssue(deploymentKey);
+    const finalStatus = finalIssue.fields.status.name;
+    await notifier.notify(
+      deploymentKey,
+      `Deployment 部署結果已通過（環境：${environment.toUpperCase()}，狀態：${finalStatus}），請檢查 CD 單狀況`,
+    );
+
+    if (args.applyForClose) {
+      await applyForCloseIfRequested(cdIssueKey, jira, notifier, log);
+    }
+
+    return ok({
+      cdIssueKey,
+      deploymentKey,
+      environment,
+      status: finalStatus,
+      deployResult,
+      deployResultFieldId: DEPLOY_RESULT_FIELD_ID,
+      closeNotificationSuggestion: await buildCloseNotificationSuggestion(environment),
+      steps: log,
+    });
+  } catch (err) {
+    return error(`trigger_deployment 失敗: ${err.message}`);
+  }
+}
+
+async function waitForDeploymentResult(deploymentKey, environment, ctx, log) {
+  const {jira} = ctx;
+  const waitMs = Math.min(getPollTimeoutMs(), 10 * 60 * 1000);
+  const pollMs = Math.min(getPollIntervalMs(), 3 * 60 * 1000);
+  const startedAt = Date.now();
+  const deadline = Date.now() + waitMs;
+  let attempts = 0;
+  let lastValue;
+
+  log.push('  ⏳ 等待 Deployment 結果 pass（最多 10 分鐘）...');
+  while (true) {
+    attempts++;
+    const issue = await jira.getIssue(deploymentKey);
+    const fields = await jira.getIssueFields(deploymentKey, [DEPLOY_RESULT_FIELD_ID]);
+    const raw = fields[DEPLOY_RESULT_FIELD_ID];
+    lastValue = raw?.value ?? raw;
+
+    if (typeof ctx.progress === 'function') {
+      ctx.progress({
+        phase: 'polling',
+        title: '等待 CD Deployment deploy 結果',
+        detail: `${DEPLOY_RESULT_FIELD_ID}: ${lastValue ?? 'empty'}`,
+        issueKey: deploymentKey,
+        environment,
+        currentStatus: issue.fields.status.name,
+        attempts,
+        elapsedMs: Date.now() - startedAt,
+        timeoutMs: waitMs,
+        nextPollMs: pollMs,
+      });
+    }
+
+    if (isPassingResult(lastValue)) {
+      log.push(`  ✅ Deployment 結果 pass，${DEPLOY_RESULT_FIELD_ID}: ${lastValue}`);
+      return lastValue;
+    }
+
+    if (isFailingResult(lastValue)) {
+      throw new Error(`Deployment Deploy 失敗，${DEPLOY_RESULT_FIELD_ID}: ${lastValue}`);
+    }
+
+    if (Date.now() >= deadline) {
+      throw new Error(`Deployment Deploy 等待逾時，${DEPLOY_RESULT_FIELD_ID}: ${lastValue ?? 'empty'}`);
+    }
+
+    await sleep(pollMs);
+  }
+}
+
+function selectDeploymentSubtask(subTasks, environment, log) {
+  const envUpper = environment.toUpperCase().replace('/', '').replace('&', '');
+  const envVariants = [envUpper, `[${envUpper}]`];
+  const matched = subTasks.find((subTask) => {
+    const summaryUpper = String(subTask.fields?.summary ?? '').toUpperCase().replace(/[\s/]/g, '');
+    return envVariants.some((variant) => summaryUpper.includes(variant.replace(/[\s/]/g, '')));
+  });
+
+  if (matched) {
+    log.push(`  對應環境 ${environment} 的 Deployment 單：${matched.key}`);
+    return matched.key;
+  }
+
+  const fallback = subTasks[0].key;
+  log.push(`  ⚠️ 未找到明確符合環境 ${environment} 的 sub-task，使用第一個：${fallback}`);
+  return fallback;
+}
+
+async function getCDSystemCode(cdIssueKey, jira) {
+  try {
+    const fields = await jira.getIssueFields(cdIssueKey, [CD_FIELD_IDS.systemCode]);
+    return fields?.[CD_FIELD_IDS.systemCode]?.value ?? fields?.[CD_FIELD_IDS.systemCode] ?? '';
+  } catch {
+    return '';
+  }
+}
+
+async function findAnyTransition(issueKey, names, jira) {
+  const transitions = await jira.getTransitions(issueKey);
+  return transitions.find((transition) => (
+    names.some((name) => transition.name.toLowerCase() === name.toLowerCase())
+  ));
+}
+
+async function applyForCloseIfRequested(cdIssueKey, jira, notifier, log) {
+  try {
+    const transitions = await jira.getTransitions(cdIssueKey);
+    const closeTransition = transitions.find((transition) => transition.name.toLowerCase() === 'apply for close');
+    if (!closeTransition) {
+      const available = transitions.map((transition) => transition.name).join(', ');
+      log.push(`  ⚠️ CD 單找不到「Apply for close」transition（可用：${available || '無'}）`);
+      return;
+    }
+
+    log.push(`  對 CD 單 ${cdIssueKey} 執行「${closeTransition.name}」...`);
+    await jira.transitionById(cdIssueKey, closeTransition.id);
+    const cdIssue = await jira.getIssue(cdIssueKey);
+    log.push(`  CD 單狀態：${cdIssue.fields.status.name}`);
+    await notifier.notify(cdIssueKey, 'CD 單已提交關閉申請（Apply for close）');
+  } catch (err) {
+    log.push(`  ⚠️ Apply for close 失敗：${err.message}`);
+  }
+}
+
+async function buildCloseNotificationSuggestion(environment) {
+  const env = normalizeDeploymentEnvironment(environment);
+  if (env === 'stg') {
+    return {
+      environment: env,
+      message: 'Deployment 已 pass。是否通知 STG 簽核人檢查並關單？',
+      approverLookupTool: 'get_release_manager',
+      notifyTool: 'send_jabber_message',
+    };
+  }
+
+  if (env === 'uat' || isPrdLikeEnv(env)) {
+    return {
+      environment: env,
+      message: `Deployment 已 pass。是否通知 James 檢查 ${env.toUpperCase()} CD 單並關單？`,
+      approverAlias: 'James',
+      notifyTool: 'send_jabber_message',
+    };
+  }
+
+  return null;
+}