@jira-deploy/core 1.0.14 → 1.0.16

package/tools/ci.js

@@ -1,8 +1,14 @@
 /**
  * CI Golden Image 相關 tools
  *   - create_ci_ticket
+ *   - build_ci
  */
-import {error, ok, today} from './helpers.js';
+import { error, getPollIntervalMs, getPollTimeoutMs, isFailingResult, isPassingResult, ok, today, } from './helpers.js';
+import {
+  findAnyTransition as findAnyTransitionForIssue,
+  sleep,
+  waitForAnyTransition as waitForAnyTransitionForIssue,
+} from './transition-helpers.js';
 import {
   CI_FIELD_IDS,
   DEPT_CODES,
@@ -16,6 +22,32 @@ import {
   SYSTEM_TO_CI_REPO_MAP,
   SYSTEM_TO_DEPT_MAP,
 } from '../constants/index.js';
+import { assertNoOpenPRBeforeCreate } from './branch-prs.js';
+
+// ── Flow Definition ──────────────────────────────────────────────
+
+/**
+ * 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)
+ *
+ * build_ci 負責觸發前段 Jenkins Build：
+ *   TO DO → (Accept) → Wait for Build → (Build) → Compliance Scan
+ *
+ * Build 後續的 Wait To DEV/STG/UAT/PRD/DR 等狀態，
+ * 由 wait_to_dev、wait_to_stg、wait_to_uat、wait_to_prd_dr 接續處理。
+ *
+ * Jira Automation 可能在前置狀態推進後自動觸發 Jenkins，
+ * 此時不一定會出現手動 Build transition。
+ */
+const CI_BUILD_TRANSITIONS = ['Build'];
+const CI_PRE_BUILD_TRANSITIONS = ['Accept'];
 
 // ── Schema definitions ───────────────────────────────────────────
 export function getCIToolDefinitions() {
@@ -46,23 +78,13 @@ export function getCIToolDefinitions() {
             enum: Object.keys(ENV_CODES),
             description: '(選填) 部署環境，預設 stg',
           },
-          summary: {
-            type: 'string',
-            description:
-              '（選填）自訂 Ticket 標題，不填則自動生成，格式：[IBK][CI] IBK & WEALTH & SSR & A11Y for 0.0.1',
-          },
-          goldenImageVersion: {
-            type: 'string',
-            description:
-              'Golden Image 版本號，例如 0.0.1（用於 summary：[IBK][CI] IBK & WEALTH for 0.0.1）',
-          },
           antiScanRequired: {
             type: 'boolean',
             description: '是否需要反掃描檢測（選填，預設 true）',
           },
           relatesTo: {
             type: 'array',
-            items: {type: 'string'},
+            items: { type: 'string' },
             description:
               '關聯的 Library 單 issue key，有可能多個，例如 CID-1178 CID-1182（建立後自動加上 relates to link）',
           },
@@ -73,50 +95,358 @@ export function getCIToolDefinitions() {
         },
       },
     },
+    {
+      name: 'build_ci',
+      description:
+        '觸發 CI 上版單的 Jenkins Build。自動處理 CI 前置狀態切換與 Jira Automation 等待；Library 單請使用 build_library，GrayRelease 單請使用 build_grayrelease。',
+      inputSchema: {
+        type: 'object',
+        required: ['issueKey'],
+        properties: {
+          issueKey: {
+            type: 'string',
+            description: '要 build 的 CI issue key',
+          },
+        },
+      },
+    },
+    {
+      name: 'wait_to_dev',
+      description:
+        'CI 單 build 完成後，自動走完掃描流程切到 Wait To DEV 狀態。流程：Compliance Scan → Upload Scan Report → Accept → Wait To DEV（不執行 Dev Done）',
+      inputSchema: {
+        type: 'object',
+        required: ['issueKey'],
+        properties: {
+          issueKey: {
+            type: 'string',
+            description: 'CI issue key',
+          },
+        },
+      },
+    },
+    {
+      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',
+          },
+        },
+      },
+    },
+    {
+      name: 'wait_to_uat',
+      description:
+        'CI 單 STG 部署完成後切到 Wait To UAT 狀態。流程：必要時補到 Wait To STG → STG Done → Wait To UAT。',
+      inputSchema: {
+        type: 'object',
+        required: ['issueKey'],
+        properties: {
+          issueKey: {
+            type: 'string',
+            description: 'CI issue key',
+          },
+        },
+      },
+    },
+    {
+      name: 'wait_to_prd_dr',
+      description:
+        'CI 單 UAT 完成後進入 PRD/DR 前置狀態。流程：必要時補到 Wait To UAT → UAT Done → Wait For Upload → Upload To Pre-Release → 等 CID_upload_result(customfield_13452) pass → Upload Done → Wait To PRD/DR。',
+      inputSchema: {
+        type: 'object',
+        required: ['issueKey'],
+        properties: {
+          issueKey: {
+            type: 'string',
+            description: 'CI issue key',
+          },
+        },
+      },
+    },
   ];
 }
 
+export async function handleBuildCI(args, ctx) {
+  const { issueKey } = args;
+
+  try {
+    const result = await executeCIBuildFlow(issueKey, ctx);
+    return ok(result);
+  } catch (err) {
+    return error(`build_ci 失敗: ${err.message}`);
+  }
+}
+
+export async function handleWaitToDev(args, ctx) {
+  try {
+    const result = await runCITransitionSteps({
+      issueKey: args.issueKey,
+      ctx,
+      finalTargetStatus: 'Wait To DEV',
+      steps: [
+        { transition: 'Upload Scan Report', targetStatus: 'Upload Report' },
+        { transition: 'Accept', targetStatus: 'Wait To DEV' },
+      ],
+      notifyMessage: '已切換至 Wait To DEV，可進行 DEV 部署',
+    });
+    return ok(result);
+  } catch (err) {
+    return error(`wait_to_dev 失敗: ${err.message}`);
+  }
+}
+
+export async function handleWaitToStg(args, ctx) {
+  try {
+    const result = await runCITransitionSteps({
+      issueKey: args.issueKey,
+      ctx,
+      finalTargetStatus: 'Wait To STG',
+      steps: CI_STEPS_TO_STG,
+      notifyMessage: '已切換至 Wait To STG，可進行 STG 部署',
+    });
+    return ok(result);
+  } catch (err) {
+    return error(`wait_to_stg 失敗: ${err.message}`);
+  }
+}
+
+export async function handleWaitToUat(args, ctx) {
+  try {
+    const result = await runCITransitionSteps({
+      issueKey: args.issueKey,
+      ctx,
+      finalTargetStatus: 'Wait To UAT',
+      steps: CI_STEPS_TO_UAT,
+      notifyMessage: '已切換至 Wait To UAT，可進行 UAT 部署',
+    });
+    return ok(result);
+  } catch (err) {
+    return error(`wait_to_uat 失敗: ${err.message}`);
+  }
+}
+
+export async function handleWaitToPrdDr(args, ctx) {
+  const { issueKey } = args;
+  const { jira, notifier } = ctx;
+  const log = [];
+
+  try {
+    const initialIssue = await jira.getIssue(issueKey);
+    const initialStatus = initialIssue.fields.status.name;
+    if (sameStatus(initialStatus, 'Wait To PRD/DR')) {
+      log.push(`  已是 ${initialStatus}，流程已完成`);
+      return ok({ issueKey, status: initialStatus, steps: log });
+    }
+
+    const toUpload = await runCITransitionSteps({
+      issueKey,
+      ctx,
+      finalTargetStatus: 'Wait For Upload',
+      steps: CI_STEPS_TO_UPLOAD,
+      log,
+    });
+
+    const currentIssue = await jira.getIssue(issueKey);
+    const currentStatus = currentIssue.fields.status.name;
+    if (sameStatus(currentStatus, 'Wait To PRD/DR')) {
+      log.push(`  已是 ${currentStatus}，流程已完成`);
+      return ok({ issueKey, status: currentStatus, steps: log });
+    }
+
+    const uploadTransition = await findTransitionByName(issueKey, 'Upload To Pre-Release', jira);
+    if (uploadTransition) {
+      log.push(`執行「${uploadTransition.name}」→ Wait For Upload`);
+      await jira.transitionById(issueKey, uploadTransition.id);
+    } else if (!sameStatus(toUpload.status, 'Wait For Upload')) {
+      throw new Error(`找不到 transition「Upload To Pre-Release」，目前狀態：${toUpload.status}`);
+    } else {
+      log.push('  未找到「Upload To Pre-Release」，視為已觸發或正在等待 upload 結果');
+    }
+
+    const uploadResult = await waitForCIUploadResult(issueKey, ctx, log);
+
+    const uploadDoneTransition = await findTransitionByName(issueKey, 'Upload Done', jira);
+    if (!uploadDoneTransition) {
+      const issue = await jira.getIssue(issueKey);
+      const finalStatus = issue.fields.status.name;
+      if (sameStatus(finalStatus, 'Wait To PRD/DR')) {
+        log.push(`  已是 ${finalStatus}，流程已完成`);
+        return ok({ issueKey, status: finalStatus, uploadResult, steps: log });
+      }
+      throw new Error(`找不到 transition「Upload Done」，目前狀態：${finalStatus}`);
+    }
+
+    log.push(`執行「${uploadDoneTransition.name}」→ Wait To PRD/DR`);
+    await jira.transitionById(issueKey, uploadDoneTransition.id);
+
+    const finalIssue = await jira.getIssue(issueKey);
+    const finalStatus = finalIssue.fields.status.name;
+    log.push(`✅ 完成，目前狀態：${finalStatus}`);
+    await notifier.notify(issueKey, `已切換至 ${finalStatus}，可進行 PRD/DR 部署`);
+    return ok({ issueKey, status: finalStatus, uploadResult, steps: log });
+  } catch (err) {
+    return error(`wait_to_prd_dr 失敗: ${err.message}`);
+  }
+}
+
+export async function ensureCIReadyForCD({ issueKey, environment }, ctx) {
+  const env = normalizeEnvironment(environment);
+  if (!issueKey) {
+    return null;
+  }
+
+  if (env === 'dev') {
+    return assertToolOk(await handleWaitToDev({ issueKey }, ctx), 'wait_to_dev');
+  }
+
+  if (env === 'stg') {
+    return assertToolOk(await handleWaitToStg({ issueKey }, ctx), 'wait_to_stg');
+  }
+
+  if (env === 'uat') {
+    return assertToolOk(await handleWaitToUat({ issueKey }, ctx), 'wait_to_uat');
+  }
+
+  if (['prd', 'dr', 'prd/dr'].includes(env)) {
+    return assertToolOk(await handleWaitToPrdDr({ issueKey }, ctx), 'wait_to_prd_dr');
+  }
+
+  throw new Error(`不支援的 CD 部署環境：${environment}`);
+}
+
+async function executeCIBuildFlow(issueKey, ctx) {
+  const { jira, notifier } = ctx;
+  const log = [];
+
+  const findAnyTransition = (names) => findAnyTransitionForIssue({ jira, issueKey, names });
+
+  const waitForAnyTransition = (names) => waitForAnyTransitionForIssue({
+    jira,
+    issueKey,
+    names,
+    intervalMs: getPollIntervalMs(),
+    timeoutMs: getPollTimeoutMs(),
+  });
+
+  let buildTransition = await findAnyTransition(CI_BUILD_TRANSITIONS);
+
+  if (!buildTransition) {
+    log.push('未找到 Build transition，逐步觸發 CI 前置狀態...');
+
+    const preBuildResult = await runCIPreBuildTransitions({
+      issueKey,
+      jira,
+      log,
+      findAnyTransition,
+    });
+    buildTransition = preBuildResult.buildTransition;
+
+    if (!buildTransition) {
+      log.push(`  等待 Jira Automation 推進（最多 ${getPollTimeoutMs() / 1000}s）...`);
+      buildTransition = await waitForAnyTransition(CI_BUILD_TRANSITIONS);
+    }
+  }
+
+  if (!buildTransition) {
+    const issue = await jira.getIssue(issueKey);
+    throw new Error(`找不到 Build transition，目前狀態：${issue.fields.status.name}`);
+  }
+
+  log.push(`執行 ${buildTransition.name} transition (id: ${buildTransition.id})...`);
+  await jira.transitionById(issueKey, buildTransition.id);
+
+  const issue = await jira.getIssue(issueKey);
+  const newStatus = issue.fields.status.name;
+  log.push(`✅ ${buildTransition.name} 已觸發，目前狀態：${newStatus}`);
+  await notifier.notify(issueKey, `Jenkins ${buildTransition.name} 已觸發（${newStatus}）`);
+
+  return { issueKey, status: newStatus, steps: log };
+}
+
+async function runCIPreBuildTransitions({ issueKey, jira, log, findAnyTransition }) {
+  let preTriggered = false;
+
+  for (let step = 0; step < CI_PRE_BUILD_TRANSITIONS.length; step++) {
+    const preTransition = await findAnyTransition(CI_PRE_BUILD_TRANSITIONS);
+    if (!preTransition) {
+      break;
+    }
+
+    log.push(`  [step ${step + 1}] 觸發「${preTransition.name}」...`);
+    try {
+      await jira.transitionById(issueKey, preTransition.id);
+    } catch (err) {
+      log.push(`  ⚠️ ${preTransition.name} transition 失敗: ${err.message}`);
+    }
+    preTriggered = true;
+    await sleep(2000);
+
+    const buildTransition = await findAnyTransition(CI_BUILD_TRANSITIONS);
+    if (buildTransition) {
+      log.push(`  已找到 ${buildTransition.name} transition`);
+      return { buildTransition, preTriggered };
+    }
+  }
+
+  return { buildTransition: null, preTriggered };
+}
+
 /**
  * 建立 CI Golden Image 上版單
  */
-export async function handleCreateCITicket(args, {jira, notifier}) {
+export async function handleCreateCITicket(args, { jira, notifier }) {
   try {
+    const systemCode = String(args.systemCode ?? '').trim().toUpperCase();
     const branch = args.branch || 'master';
     const envCode = (args.environment ?? 'stg').toLowerCase();
+    await assertNoOpenPRBeforeCreate({
+      ticketType: 'ci',
+      systemCode,
+      branch: 'master',
+    }, { jira });
+
+    const goldenImageVersion = await resolveGoldenImageVersion({ systemCode, branch }, { jira });
     // Summary 格式對齊 Confluence：[IBK][CI] Wealth & SSR & IBK & A11y for 0.0.1
     const modules = Array.isArray(args.modules)
       ? args.modules
       : typeof args.modules === 'string'
         ? args.modules.split(',').map((module) => module.trim()).filter(Boolean)
-        : SYSTEM_MODULES[args.systemCode];
+        : SYSTEM_MODULES[systemCode];
     const modulesStr = modules.map((m) => m.toUpperCase()).join(' & ');
 
-    const versionSuffix = args.goldenImageVersion ? ` for ${args.goldenImageVersion}` : '';
-    const autoSummary = args.summary ?? `[${args.systemCode}][CI] ${modulesStr}${versionSuffix}`;
+    const versionSuffix = goldenImageVersion ? ` for ${goldenImageVersion}` : '';
+    const autoSummary = `[${systemCode}][CI] ${modulesStr}${versionSuffix}`;
 
     const fields = {
-      project: {key: JIRA_PROJECT_ID},
-      issuetype: {id: ISSUE_TYPE_IDS.CI},
+      project: { key: JIRA_PROJECT_ID },
+      issuetype: { id: ISSUE_TYPE_IDS.CI },
       summary: autoSummary,
       duedate: today(),
     };
 
     // systemCode
     if (CI_FIELD_IDS.systemCode) {
-      fields[CI_FIELD_IDS.systemCode] = {value: args.systemCode};
+      fields[CI_FIELD_IDS.systemCode] = { value: systemCode };
     }
     // env (必填)
     if (CI_FIELD_IDS.env && ENV_CODES[envCode]) {
-      fields[CI_FIELD_IDS.env] = {id: ENV_CODES[envCode]};
+      fields[CI_FIELD_IDS.env] = { id: ENV_CODES[envCode] };
     }
     // dept_code (必填，由 systemCode 推導)
-    const deptStr = SYSTEM_TO_DEPT_MAP[args.systemCode];
+    const deptStr = SYSTEM_TO_DEPT_MAP[systemCode];
     if (CI_FIELD_IDS.deptCode && deptStr && DEPT_CODES[deptStr]) {
-      fields[CI_FIELD_IDS.deptCode] = {id: DEPT_CODES[deptStr]};
+      fields[CI_FIELD_IDS.deptCode] = { id: DEPT_CODES[deptStr] };
     }
     // system_module (必填，預設 assembly)
     if (CI_FIELD_IDS.systemModule) {
-      fields[CI_FIELD_IDS.systemModule] = {id: FIELD_OPTIONS.systemModule.assembly};
+      fields[CI_FIELD_IDS.systemModule] = { id: FIELD_OPTIONS.systemModule.assembly };
     }
     // git branch → customfield_13431 (14702 不在 CI screen)
     if (CI_FIELD_IDS.gitBranch && branch) {
@@ -131,7 +461,7 @@ export async function handleCreateCITicket(args, {jira, notifier}) {
     };
 
     if (args.dryRun)
-      return ok({dryRun: true, summary: autoSummary, fields, relatesTo: args.relatesTo ?? []});
+      return ok({ dryRun: true, summary: autoSummary, fields, relatesTo: args.relatesTo ?? [] });
 
     const issue = await jira.createIssue(fields);
 
@@ -153,19 +483,156 @@ export async function handleCreateCITicket(args, {jira, notifier}) {
       issueId: issue.id,
       url: `${process.env.JIRA_BASE_URL}/browse/${issue.key}`,
       type: 'CI Release',
-      system: args.systemCode,
-      ...(relatesTo.length > 0 && {relatesTo}),
+      system: systemCode,
+      goldenImageVersion,
+      ...(relatesTo.length > 0 && { relatesTo }),
     });
   } catch (err) {
     return error(`無法建立 CI 單: ${err.message}`);
   }
 }
 
+const CI_STEPS_TO_STG = [
+  { transition: 'Upload Scan Report', targetStatus: 'Upload Report' },
+  { transition: 'Accept', targetStatus: 'Wait To DEV' },
+  { transition: 'Dev Done', targetStatus: 'Wait To STG' },
+];
+
+const CI_STEPS_TO_UAT = [
+  ...CI_STEPS_TO_STG,
+  { transition: 'STG Done', targetStatus: 'Wait To UAT' },
+];
+
+const CI_STEPS_TO_UPLOAD = [
+  ...CI_STEPS_TO_UAT,
+  { transition: 'UAT Done', targetStatus: 'Wait For Upload' },
+];
+
+async function runCITransitionSteps({ issueKey, ctx, steps, finalTargetStatus, notifyMessage, log = [] }) {
+  const { jira, notifier } = ctx;
+
+  for (const [index, step] of steps.entries()) {
+    const issue = await jira.getIssue(issueKey);
+    const current = issue.fields.status.name;
+
+    if (sameStatus(current, finalTargetStatus)) {
+      log.push(`  已是 ${current}，流程已完成`);
+      break;
+    }
+
+    const reachedStepIndex = steps.findIndex((candidate) => sameStatus(current, candidate.targetStatus));
+    if (reachedStepIndex >= index) {
+      log.push(`  目前是 ${current}，跳過「${step.transition}」`);
+      continue;
+    }
+
+    const transition = await findTransitionByName(issueKey, step.transition, jira);
+    if (!transition) {
+      throw new Error(`找不到 transition「${step.transition}」，目前狀態：${current}`);
+    }
+
+    log.push(`執行「${transition.name}」→ ${step.targetStatus}`);
+    await jira.transitionById(issueKey, transition.id);
+  }
+
+  const finalIssue = await jira.getIssue(issueKey);
+  const finalStatus = finalIssue.fields.status.name;
+  log.push(`✅ 完成，目前狀態：${finalStatus}`);
+
+  if (notifyMessage) {
+    await notifier.notify(issueKey, notifyMessage.replace(finalTargetStatus, finalStatus));
+  }
+
+  return { issueKey, status: finalStatus, steps: log };
+}
+
+async function findTransitionByName(issueKey, transitionName, jira) {
+  const transitions = await jira.getTransitions(issueKey);
+  return transitions.find((transition) => transition.name.toLowerCase() === transitionName.toLowerCase());
+}
+
+async function waitForCIUploadResult(issueKey, ctx, log) {
+  const { jira } = ctx;
+  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, [CI_FIELD_IDS.uploadResult]);
+    const raw = fields[CI_FIELD_IDS.uploadResult];
+    lastValue = raw?.value ?? raw;
+
+    if (typeof ctx.progress === 'function') {
+      ctx.progress({
+        phase: 'polling',
+        title: '等待 CI Upload To Pre-Release 結果',
+        detail: `${CI_FIELD_IDS.uploadResult}: ${lastValue ?? 'empty'}`,
+        issueKey,
+        attempts,
+        elapsedMs: Date.now() - startedAt,
+        timeoutMs,
+        nextPollMs: intervalMs,
+      });
+    }
+
+    if (isPassingResult(lastValue)) {
+      log.push(`  ✅ Upload To Pre-Release 完成，${CI_FIELD_IDS.uploadResult}: ${lastValue}`);
+      return lastValue;
+    }
+
+    if (isFailingResult(lastValue)) {
+      throw new Error(`Upload To Pre-Release 失敗，${CI_FIELD_IDS.uploadResult}: ${lastValue}`);
+    }
+
+    if (Date.now() >= deadline) {
+      throw new Error(`Upload To Pre-Release 等待逾時，${CI_FIELD_IDS.uploadResult}: ${lastValue ?? 'empty'}`);
+    }
+
+    await sleep(intervalMs);
+  }
+}
+
+async function resolveGoldenImageVersion({ systemCode, branch }, { jira }) {
+  const result = await handleGetNextCIVersion({ systemCode, branch }, { jira });
+  const data = assertToolOk(result, 'get_next_ci_version');
+  return data.summaryVersion;
+}
+
+function assertToolOk(result, toolName) {
+  const text = result?.content?.[0]?.text ?? '';
+  if (result?.isError || text.startsWith('❌')) {
+    throw new Error(text.replace(/^❌ 錯誤: /, '') || `${toolName} failed`);
+  }
+  return JSON.parse(text);
+}
+
+function sameStatus(left, right) {
+  return normalizeStatusName(left) === normalizeStatusName(right);
+}
+
+function normalizeStatusName(statusName) {
+  return String(statusName ?? '')
+    .trim()
+    .replace(/\s+/g, ' ')
+    .toLowerCase();
+}
+
+function normalizeEnvironment(environment) {
+  return String(environment ?? '')
+    .trim()
+    .toLowerCase()
+    .replace('&', '/');
+}
+
 /**
  * 計算下一個 Golden Image Release 版號
  */
-export async function handleGetNextCIVersion(args, {jira}) {
-  const {systemCode, branch} = args;
+export async function handleGetNextCIVersion(args, { jira }) {
+  const { systemCode, branch } = args;
 
   const repoName = SYSTEM_TO_CI_REPO_MAP[systemCode];
   if (!repoName) {