@jira-deploy/core 1.0.15 → 1.0.17

package/tools/jabber.js

@@ -7,6 +7,7 @@ import fs from 'fs';
 import path from 'path';
 import {fileURLToPath} from 'url';
 import {error, ok} from './helpers.js';
+import {getRuntimeConfigValue} from '../constants/config.js';
 
 const packageScriptPath = path.resolve(
   path.dirname(fileURLToPath(import.meta.url)),
@@ -32,8 +33,9 @@ export function resolveJabberNotifyScriptPath({
   execPath = process.execPath,
   cwd = process.cwd(),
 } = {}) {
-  if (env.JABBER_NOTIFY_SCRIPT) {
-    return env.JABBER_NOTIFY_SCRIPT;
+  const configuredScript = getRuntimeConfigValue('JABBER_NOTIFY_SCRIPT') ?? env.JABBER_NOTIFY_SCRIPT;
+  if (configuredScript) {
+    return configuredScript;
   }
 
   const resolvedExecPath = realpathOrNull(execPath);
@@ -91,14 +93,20 @@ export async function handleSendJabberMessage(args, _ctx) {
       sent: false,
       dryRun: true,
       message: args.message,
-      to: args.to ?? process.env.JABBER_TO ?? '(JABBER_TO not set)',
-      room: args.room ?? process.env.JABBER_ROOM,
-      preview: `[DRY RUN] 將發送 Jabber 給 ${args.to ?? process.env.JABBER_TO ?? '?'}: ${args.message}`,
+      to: args.to ?? getRuntimeConfigValue('JABBER_TO') ?? '(JABBER_TO not set)',
+      room: args.room ?? getRuntimeConfigValue('JABBER_ROOM'),
+      preview: `[DRY RUN] 將發送 Jabber 給 ${args.to ?? getRuntimeConfigValue('JABBER_TO') ?? '?'}: ${args.message}`,
     });
   }
 
   // 允許透過 tool 參數覆蓋 JABBER_TO / JABBER_ROOM
   const env = {...process.env};
+  for (const key of ['JABBER_SERVER', 'JABBER_USER', 'JABBER_DOMAIN', 'JABBER_KEYCHAIN_SERVICE', 'JABBER_KEYCHAIN_ACCOUNT', 'JABBER_TO', 'JABBER_ROOM', 'JABBER_PORT', 'JABBER_RESOURCE', 'JABBER_NICK']) {
+    const value = getRuntimeConfigValue(key);
+    if (value !== undefined) {
+      env[key] = value;
+    }
+  }
   if (args.to) env.JABBER_TO = args.to;
   if (args.room) env.JABBER_ROOM = args.room;
 

package/tools/library.js

@@ -1,26 +1,57 @@
 /**
  * Library Release 相關 tools
  *   - create_library_ticket
+ *   - build_library
  */
 import {
-  SYSTEM_CODES,
+  DEPT_CODES,
   ENV_CODES,
-  LIBRARY_MODULE_IDS,
+  FIELD_OPTIONS,
   ISSUE_TYPE_IDS,
   JIRA_PROJECT_ID,
   LIBRARY_FIELD_IDS,
-  SYSTEM_TO_DEPT_MAP,
-  DEPT_CODES,
-  SYSTEM_CODE_JIRA_IDS,
-  FIELD_OPTIONS,
-  MODULE_TO_REPO_MAP,
-  REPO_MAPS,
+  LIBRARY_MODULE_IDS,
   MODULE_MAP,
+  MODULE_TO_REPO_MAP,
   REPO_LABEL_MAP,
+  REPO_MAPS,
+  SYSTEM_CODE_JIRA_IDS,
+  SYSTEM_CODES,
+  SYSTEM_TO_DEPT_MAP,
 } from '../constants/index.js';
-import {error, ok, today} from './helpers.js';
+import {getRuntimeConfigValue} from '../constants/config.js';
+import { error, getPollIntervalMs, getPollTimeoutMs, ok, today } from './helpers.js';
+import { assertNoOpenPRBeforeCreate } from './branch-prs.js';
+import {
+  findAnyTransition as findAnyTransitionForIssue,
+  sleep,
+  waitForAnyTransition as waitForAnyTransitionForIssue,
+} from './transition-helpers.js';
+
+export { REPO_MAPS, MODULE_MAP, REPO_LABEL_MAP };
+
+// ── Flow Definition ──────────────────────────────────────────────
+
+/**
+ * Library Release 狀態流程定義
+ *
+ * 完整流程：
+ *   TO DO → (Upload Lib Report) → UPLOAD LIB REPORT
+ *   → (Apply for approval) → WAIT APPROVAL
+ *   → (Approved) → WAIT FOR LIB BUILD
+ *   → (Build) → RELEASED
+ *
+ * Jira Automation 可能在前置狀態推進後自動觸發 Jenkins，
+ * 此時不一定會出現手動 Build transition。
+ */
+const LIBRARY_BUILD_TRANSITIONS = ['Build'];
+const LIBRARY_PRE_BUILD_TRANSITIONS = ['Upload Lib Report', 'Apply for approval', 'Approved'];
 
-export {REPO_MAPS, MODULE_MAP, REPO_LABEL_MAP};
+function progress(ctx, event) {
+  if (typeof ctx.progress === 'function') {
+    ctx.progress(event);
+  }
+}
 
 // ── Schema definitions ───────────────────────────────────────────
 export function getLibraryToolDefinitions() {
@@ -62,6 +93,21 @@ export function getLibraryToolDefinitions() {
         },
       },
     },
+    {
+      name: 'build_library',
+      description:
+        '觸發 Library Release 上版單的 Jenkins Build。自動處理 Upload Lib Report、Apply for approval、Approved 等 Library 前置狀態；CI 單請使用 build_ci。',
+      inputSchema: {
+        type: 'object',
+        required: ['issueKey'],
+        properties: {
+          issueKey: {
+            type: 'string',
+            description: 'Library Release 單 issue key，例如 CID-1708',
+          },
+        },
+      },
+    },
   ];
 }
 
@@ -70,8 +116,8 @@ export function getLibraryToolDefinitions() {
 /**
  * 計算下一個 Library Release 版號
  */
-export async function handleGetNextLibVersion(args, {jira}) {
-  const {module, branch} = args;
+async function handleGetNextLibVersion(args, { jira }) {
+  const { module, branch } = args;
 
   const repoName = MODULE_TO_REPO_MAP[module];
   if (!repoName) {
@@ -132,7 +178,7 @@ export async function handleGetNextLibVersion(args, {jira}) {
 /**
  * 建立 Library Release 上版單
  */
-export async function handleCreateLibraryTicket(args, {jira, notifier}) {
+export async function handleCreateLibraryTicket(args, { jira, notifier }) {
   try {
     const normalizedArgs = {
       ...args,
@@ -145,8 +191,8 @@ export async function handleCreateLibraryTicket(args, {jira, notifier}) {
     if (!childId) return error(`找不到模組 "${normalizedArgs.module}" 的 Library ID`);
 
     const nextVersionResult = await handleGetNextLibVersion(
-      {module: normalizedArgs.module, branch: normalizedArgs.gitBranch},
-      {jira},
+      { module: normalizedArgs.module, branch: normalizedArgs.gitBranch },
+      { jira },
     );
     const nextVersionText = nextVersionResult.content[0].text;
     let summaryVersion;
@@ -160,30 +206,30 @@ export async function handleCreateLibraryTicket(args, {jira, notifier}) {
     } else {
       summaryVersion = JSON.parse(nextVersionText).summaryVersion;
     }
-    const autoSummary =
-      normalizedArgs.summary ?? `[${normalizedArgs.systemCode}][Lib] Release for ${summaryVersion}`;
+    const autoSummary = `[${normalizedArgs.systemCode}-${normalizedArgs.module}][Lib] Release for ${summaryVersion}`;
+    const summary = normalizedArgs.summary ?? autoSummary;
 
     const fields = {
-      project: {key: JIRA_PROJECT_ID},
-      issuetype: {id: ISSUE_TYPE_IDS.Library},
-      summary: autoSummary,
+      project: { key: JIRA_PROJECT_ID },
+      issuetype: { id: ISSUE_TYPE_IDS.Library },
+      summary,
       duedate: today(),
       [LIBRARY_FIELD_IDS.libModuleParent]: {
         id: parentId,
-        child: {id: childId},
+        child: { id: childId },
       },
     };
 
     // env（預設 stg）
     const envCode = args.environment?.toLowerCase() ?? 'stg';
     if (LIBRARY_FIELD_IDS.env && ENV_CODES[envCode]) {
-      fields[LIBRARY_FIELD_IDS.env] = {id: ENV_CODES[envCode]};
+      fields[LIBRARY_FIELD_IDS.env] = { id: ENV_CODES[envCode] };
     }
 
     // dept_code（由 systemCode 推導）
     const deptStr = SYSTEM_TO_DEPT_MAP[normalizedArgs.systemCode];
     if (LIBRARY_FIELD_IDS.deptCode && deptStr && DEPT_CODES[deptStr]) {
-      fields[LIBRARY_FIELD_IDS.deptCode] = {id: DEPT_CODES[deptStr]};
+      fields[LIBRARY_FIELD_IDS.deptCode] = { id: DEPT_CODES[deptStr] };
     }
 
     // fortify_scan：預設 scanned
@@ -205,7 +251,14 @@ export async function handleCreateLibraryTicket(args, {jira, notifier}) {
       fields[LIBRARY_FIELD_IDS.gitBranch] = normalizedArgs.gitBranch;
     }
 
-    if (args.dryRun) return ok({dryRun: true, summary: autoSummary, fields});
+    await assertNoOpenPRBeforeCreate({
+      ticketType: 'library',
+      systemCode: normalizedArgs.systemCode,
+      module: normalizedArgs.module,
+      branch: normalizedArgs.gitBranch,
+    }, { jira });
+
+    if (args.dryRun) return ok({ dryRun: true, summary, fields });
 
     const issue = await jira.createIssue(fields);
     await notifier.notify(
@@ -215,7 +268,7 @@ export async function handleCreateLibraryTicket(args, {jira, notifier}) {
     return ok({
       issueKey: issue.key,
       issueId: issue.id,
-      url: `${process.env.JIRA_BASE_URL}/browse/${issue.key}`,
+      url: `${getRuntimeConfigValue('JIRA_BASE_URL')}/browse/${issue.key}`,
       type: 'Library Release',
       system: normalizedArgs.systemCode,
       module: normalizedArgs.module,
@@ -224,3 +277,146 @@ export async function handleCreateLibraryTicket(args, {jira, notifier}) {
     return error(`無法建立 Library 單: ${err.message}`);
   }
 }
+
+export async function handleBuildLibrary(args, ctx) {
+  const { issueKey } = args;
+
+  try {
+    const result = await executeLibraryBuildFlow(issueKey, ctx);
+    return ok(result);
+  } catch (err) {
+    return error(`build_library 失敗: ${err.message}`);
+  }
+}
+
+async function executeLibraryBuildFlow(issueKey, ctx) {
+  const { jira, notifier } = ctx;
+  const log = [];
+  const pollIntervalMs = getPollIntervalMs();
+  const maxWaitMs = getPollTimeoutMs();
+
+  const findAnyTransition = (names) => findAnyTransitionForIssue({ jira, issueKey, names });
+
+  const waitForAnyTransition = (names) => waitForAnyTransitionForIssue({
+    jira,
+    issueKey,
+    names,
+    intervalMs: pollIntervalMs,
+    timeoutMs: maxWaitMs,
+  });
+
+  const initIssue = await jira.getIssue(issueKey);
+  const initStatus = initIssue.fields.status.name;
+  progress(ctx, {
+    phase: 'action',
+    title: '開始 Library Build 流程',
+    issueKey,
+    currentStatus: initStatus,
+  });
+
+  const resolution = await resolveLibraryBuildTransition({
+    issueKey,
+    jira,
+    log,
+    initStatus,
+    findAnyTransition,
+    waitForAnyTransition,
+  });
+
+  if (resolution.autoTriggered) {
+    await notifier.notify(
+      issueKey,
+      `Library Build 已觸發（Jira Auto）狀態：${initStatus} → ${resolution.status}`,
+    );
+    return { issueKey, status: resolution.status, steps: log, autoTriggered: true };
+  }
+
+  const buildTrans = resolution.buildTransition;
+
+  if (!buildTrans) {
+    const issue = await jira.getIssue(issueKey);
+    throw new Error(`找不到 Build transition，目前狀態：${issue.fields.status.name}`);
+  }
+
+  log.push(`執行 ${buildTrans.name} transition (id: ${buildTrans.id})...`);
+  await jira.transitionById(issueKey, buildTrans.id);
+
+  const issue = await jira.getIssue(issueKey);
+  const newStatus = issue.fields.status.name;
+  log.push(`✅ ${buildTrans.name} 已觸發，目前狀態：${newStatus}`);
+  await notifier.notify(issueKey, `Jenkins ${buildTrans.name} 已觸發（${newStatus}）`);
+
+  return { issueKey, status: newStatus, steps: log };
+}
+
+async function resolveLibraryBuildTransition({
+  issueKey,
+  jira,
+  log,
+  initStatus,
+  findAnyTransition,
+  waitForAnyTransition,
+}) {
+  const buildTransition = await findAnyTransition(LIBRARY_BUILD_TRANSITIONS);
+  if (buildTransition) {
+    return { buildTransition };
+  }
+
+  log.push('未找到 Build transition，逐步觸發 Library 前置狀態...');
+  const preBuildResult = await runLibraryPreBuildTransitions({
+    issueKey,
+    jira,
+    log,
+    findAnyTransition,
+  });
+
+  if (preBuildResult.buildTransition) {
+    return { buildTransition: preBuildResult.buildTransition };
+  }
+
+  log.push(`  等待 Jira Automation 推進（最多 ${getPollTimeoutMs() / 1000}s）...`);
+  const automationBuildTransition = await waitForAnyTransition(LIBRARY_BUILD_TRANSITIONS);
+  if (automationBuildTransition) {
+    return { buildTransition: automationBuildTransition };
+  }
+
+  if (preBuildResult.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 自動觸發');
+      return { autoTriggered: true, status: currentStatus };
+    }
+  }
+
+  return { buildTransition: null };
+}
+
+async function runLibraryPreBuildTransitions({ issueKey, jira, log, findAnyTransition }) {
+  let preTriggered = false;
+
+  for (let step = 0; step < LIBRARY_PRE_BUILD_TRANSITIONS.length; step++) {
+    const preTransition = await findAnyTransition(LIBRARY_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(LIBRARY_BUILD_TRANSITIONS);
+    if (buildTransition) {
+      log.push(`  已找到 ${buildTransition.name} transition`);
+      return { buildTransition, preTriggered };
+    }
+  }
+
+  return { buildTransition: null, preTriggered };
+}

package/tools/release.js

@@ -7,8 +7,9 @@
  */
 import https from 'https';
 import http from 'http';
-import { error, getModuleName, ok } from './helpers.js';
+import {error, getModuleName, ok} from './helpers.js';
 import {getDeployConfig, getReleaseProjectKey, SYSTEM_CODES, SYSTEM_MODULES} from '../constants/index.js';
+import {getRuntimeConfigNumber, getRuntimeConfigValue} from '../constants/config.js';
 
 // ── Schema definitions ───────────────────────────────────────────
 export function getReleaseToolDefinitions() {
@@ -100,7 +101,7 @@ export function getReleaseToolDefinitions() {
 
 // ── Handlers ─────────────────────────────────────────────────────
 
-export async function handleGetUnreleasedVersions(args, { jira }) {
+export async function handleGetUnreleasedVersions(args, {jira}) {
   try {
     const projectKey = args.projectKey ?? getReleaseProjectKey();
     const versions = await jira.getUnreleasedVersionsList(projectKey);
@@ -109,7 +110,7 @@ export async function handleGetUnreleasedVersions(args, { jira }) {
       return ok({
         projectKey,
         total: versions.length,
-        versions: versions.map((v) => ({ id: v.id, name: v.name })),
+        versions: versions.map((v) => ({id: v.id, name: v.name})),
       });
     }
 
@@ -135,13 +136,13 @@ export async function handleGetUnreleasedVersions(args, { jira }) {
       };
     });
 
-    return ok({ projectKey, systemCode: args.systemCode, total: parsed.length, versions: parsed });
+    return ok({projectKey, systemCode: args.systemCode, total: parsed.length, versions: parsed});
   } catch (err) {
     return error(`無法查詢 unreleased versions: ${err.message}`);
   }
 }
 
-export async function handleTransitionToWaitApproval(args, { jira, notifier }) {
+export async function handleTransitionToWaitApproval(args, {jira, notifier}) {
   try {
     await jira.transitionByName(args.cdIssueKey, 'Apply for approval');
     await notifier.notify(args.cdIssueKey, '已切換到 Wait Approval，等待主管簽核');
@@ -155,46 +156,42 @@ export async function handleTransitionToWaitApproval(args, { jira, notifier }) {
   }
 }
 
-export async function handleGetReleaseManager(args, _ctx) {
+export async function handleGetReleaseManager(args = {}) {
   try {
 
-    const date = new Date().toISOString();
+    const date = normalizeCalendarDate(args.date ?? new Date());
+    const endDate = addDays(date, 1);
+    const releaseConfig = getDeployConfig().release;
 
     // dryRun 模式：回傳 mock 資料
     if (args.dryRun) {
       return ok({
         date,
         found: true,
-        name: getDeployConfig().release.dryRunManager.name,
+        name: releaseConfig.dryRunManager.name,
+        substituted: false,
+        substitutionChecked: false,
         dryRun: true,
         event: {
           what: 'Sign off staff',
-          who: `${getDeployConfig().release.dryRunManager.name} (${getDeployConfig().release.dryRunManager.accountId})`,
         },
       });
     }
 
-    const CONF_BASE_URL = process.env.CONF_BASE_URL;
-    const CONF_TOKEN = process.env.CONF_TOKEN;
+    const CONF_BASE_URL = getRuntimeConfigValue('CONF_BASE_URL');
+    const CONF_TOKEN = getRuntimeConfigValue('CONF_TOKEN');
     if (!CONF_BASE_URL || !CONF_TOKEN) {
       return error('缺少環境變數 CONF_BASE_URL 或 CONF_TOKEN');
     }
 
-    const SUB_CALENDAR_ID = process.env.CONF_RELEASE_MANAGER_SUB_CALENDAR_ID
-      ?? getDeployConfig().release.managerSubCalendarId;
+    const SUB_CALENDAR_ID = getRuntimeConfigValue('CONF_RELEASE_MANAGER_SUB_CALENDAR_ID')
+      ?? releaseConfig.managerSubCalendarId;
     if (!SUB_CALENDAR_ID) {
       return error('缺少環境變數 CONF_RELEASE_MANAGER_SUB_CALENDAR_ID 或 release.managerSubCalendarId config');
     }
 
-    const nextDay = new Date(date);
-    nextDay.setDate(nextDay.getDate() + 1);
-    const endDate = nextDay.toISOString();
-
     const path =
-      `/rest/calendar-services/1.0/calendar/events.json` +
-      `?subCalendarId=${encodeURIComponent(SUB_CALENDAR_ID)}` +
-      `&start=${encodeURIComponent(date)}&end=${encodeURIComponent(endDate)}` +
-      `&userTimeZoneId=Asia%2FTaipei`;
+      `/rest/calendar-services/1.0/calendar/events.json?subCalendarId=${encodeURIComponent(SUB_CALENDAR_ID)}&start=${encodeURIComponent(date)}&end=${encodeURIComponent(endDate)}&userTimeZoneId=Asia%2FTaipei`;
 
     const data = await calendarRequest(CONF_BASE_URL, path, CONF_TOKEN);
     const events = data.events ?? [];
@@ -202,8 +199,7 @@ export async function handleGetReleaseManager(args, _ctx) {
     // 找 event title/what 欄位包含 "Sign off staff" 的事件。
     const signOffEvent = events.find(
       (e) =>
-        (e.title ?? '').toLowerCase().includes('sign off staff') ||
-        (e.what ?? '').toLowerCase().includes('sign off staff'),
+        (e.title ?? '').toLowerCase().includes('sign off staff')
     );
 
     if (!signOffEvent) {
@@ -212,8 +208,6 @@ export async function handleGetReleaseManager(args, _ctx) {
         found: false,
         allEvents: events.map((e) => ({
           title: e.title,
-          what: e.what,
-          who: e.who,
         })),
         message: `${date} 找不到 Sign off staff 事件，請手動確認值班組長`,
       });
@@ -221,18 +215,32 @@ export async function handleGetReleaseManager(args, _ctx) {
 
     // 回傳值班人員資訊
     const invitee = signOffEvent.invitees?.[0];
-    const legacyWho = signOffEvent.who ?? '';
-    const legacyName = legacyWho.replace(/\s*\([^)]*\)\s*$/, '').trim();
-    const legacyAccountId = legacyWho.match(/\(([^)]+)\)/)?.[1];
-    const managerName = (invitee?.displayName ?? legacyName)
-      || signOffEvent.title
-      || signOffEvent.what
-      || 'Unknown';
+    const managerName = (invitee?.displayName) || 'Unknown';
+
+    const substitution = await resolveManagerSubstitution({
+      managerName,
+      baseUrl: CONF_BASE_URL,
+      token: CONF_TOKEN,
+      startDate: date,
+      endDate,
+      releaseConfig,
+    });
+
+    if (substitution.error) {
+      return error(substitution.error);
+    }
+
     return ok({
       date,
       found: true,
-      name: managerName,
-      authorAccountId: invitee?.name ?? legacyAccountId ?? 'Unknown',
+      name: substitution.name ?? managerName,
+      originalName: substitution.substituted ? managerName : undefined,
+      substituted: substitution.substituted,
+      substitutionChecked: substitution.checked,
+      substitutionSkippedReason: substitution.skippedReason,
+      leaveReason: substitution.leaveReason,
+      leaveEvent: substitution.leaveEvent,
+      authorAccountId: invitee?.name ?? 'Unknown',
       event: signOffEvent,
     });
   } catch (err) {
@@ -240,7 +248,10 @@ export async function handleGetReleaseManager(args, _ctx) {
   }
 }
 
-export async function handleWaitForComment(args, { jira, progress = () => {} }) {
+export async function handleWaitForComment(args, {
+  jira, progress = () => {
+  }
+}) {
   // dryRun 模式：直接回傳 mock 結果
   if (args.dryRun) {
     return ok({
@@ -255,8 +266,8 @@ export async function handleWaitForComment(args, { jira, progress = () => {} })
     });
   }
 
-  const intervalMs = args.intervalMs ?? parseInt(process.env.POLL_INTERVAL_MS ?? '30000');
-  const timeoutMs = args.timeoutMs ?? parseInt(process.env.POLL_TIMEOUT_MS ?? '3600000');
+  const intervalMs = args.intervalMs ?? getRuntimeConfigNumber('POLL_INTERVAL_MS', 30000);
+  const timeoutMs = args.timeoutMs ?? getRuntimeConfigNumber('POLL_TIMEOUT_MS', 3600000);
   const startTime = Date.now();
   let attempts = 0;
 
@@ -324,7 +335,7 @@ function calendarRequest(baseUrl, path, token) {
         path: url.pathname + url.search,
         method: 'GET',
         rejectUnauthorized: false,
-        headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
+        headers: {Authorization: `Bearer ${token}`, Accept: 'application/json'},
       },
       (res) => {
         let data = '';
@@ -351,3 +362,91 @@ function calendarRequest(baseUrl, path, token) {
     req.end();
   });
 }
+
+async function resolveManagerSubstitution({managerName, baseUrl, token, startDate, endDate, releaseConfig}) {
+  const calendarIds = [releaseConfig.birthdayCalendarId, releaseConfig.leaveCalendarId].filter(Boolean);
+
+  if (calendarIds.length === 0) {
+    return {
+      checked: false,
+      substituted: false,
+      skippedReason: '未設定 release.birthdayCalendarId 或 release.leaveCalendarId',
+    };
+  }
+
+  const eventGroups = await Promise.all(calendarIds.map(async (calendarId) => {
+    const path =
+      `/rest/calendar-services/1.0/calendar/events.json?subCalendarId=${encodeURIComponent(calendarId)}&start=${encodeURIComponent(startDate)}&end=${encodeURIComponent(endDate)}&userTimeZoneId=Asia%2FTaipei`;
+    const data = await calendarRequest(baseUrl, path, token);
+    return data.events ?? [];
+  }));
+
+  const leaveEvent = eventGroups.flat().find((event) => eventMatchesPerson(event, managerName));
+  if (!leaveEvent) {
+    return {checked: true, substituted: false};
+  }
+
+  const substituteName = resolveSubstituteName(managerName, leaveEvent, releaseConfig.managerSubstitutes ?? {});
+  if (!substituteName) {
+    return {
+      checked: true,
+      substituted: false,
+      error: `值班組長 ${managerName} 今日請假，但無法解析代理人，請設定 release.managerSubstitutes`,
+    };
+  }
+
+  return {
+    checked: true,
+    substituted: true,
+    name: substituteName,
+    leaveReason: leaveEvent.shortTitle ?? leaveEvent.description ?? leaveEvent.title ?? '',
+    leaveEvent,
+  };
+}
+
+function resolveSubstituteName(managerName, leaveEvent, substitutes) {
+  const configured = findConfiguredSubstitute(managerName, substitutes);
+  if (configured) return configured;
+
+  const text = `${leaveEvent.description ?? ''} ${leaveEvent.shortTitle ?? ''}`;
+  const match = text.match(/-\s*([^\-:：]+?)\s*代理/);
+  return match?.[1]?.trim() || null;
+}
+
+function findConfiguredSubstitute(managerName, substitutes) {
+  const entries = Object.entries(substitutes);
+  const exact = entries.find(([name]) => samePerson(name, managerName));
+  return exact?.[1] ?? null;
+}
+
+function eventMatchesPerson(event, personName) {
+  const title = String(event.title ?? '');
+  return samePerson(title, personName);
+}
+
+function samePerson(left, right) {
+  const a = normalizePersonName(left);
+  const b = normalizePersonName(right);
+  return Boolean(a && b && (a.includes(b) || b.includes(a)));
+}
+
+function normalizePersonName(value) {
+  return String(value ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function normalizeCalendarDate(value) {
+  if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    return value;
+  }
+  return new Date(value).toISOString().slice(0, 10);
+}
+
+function addDays(dateString, days) {
+  const date = new Date(`${dateString}T00:00:00.000Z`);
+  date.setUTCDate(date.getUTCDate() + days);
+  return date.toISOString().slice(0, 10);
+}

package/tools/transition-helpers.js

@@ -0,0 +1,22 @@
+export function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function findAnyTransition({ jira, issueKey, names }) {
+  const list = await jira.getTransitions(issueKey);
+  return list.find((transition) => (
+    names.some((name) => transition.name.toLowerCase() === name.toLowerCase())
+  ));
+}
+
+export async function waitForAnyTransition({ jira, issueKey, names, intervalMs, timeoutMs }) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const transition = await findAnyTransition({ jira, issueKey, names });
+    if (transition) {
+      return transition;
+    }
+    await sleep(intervalMs);
+  }
+  return null;
+}