@jira-deploy/core 1.0.0

package/index.js

@@ -0,0 +1,6 @@
+export {JiraClient} from './jira-client.js';
+export {Notifier} from './notifier.js';
+export {Poller} from './poller.js';
+export {getPlatformConfig, PLATFORM_TO_SYSTEM_CODE, PLATFORMS} from './platform-config.js';
+export {getToolDefinitions, executeTool} from './tools/index.js';
+export {getClusterList, ok, error, today} from './tools/helpers.js';

package/jira-client.js

@@ -0,0 +1,313 @@
+import axios from 'axios';
+import https from 'https';
+
+const httpsAgent = new https.Agent({rejectUnauthorized: false});
+
+const DRY_RUN = process.env.DRY_RUN === 'true';
+
+export class JiraClient {
+  constructor() {
+    const {JIRA_BASE_URL, JIRA_API_TOKEN} = process.env;
+    if (!JIRA_BASE_URL || !JIRA_API_TOKEN) {
+      throw new Error('Missing required Jira env vars: JIRA_BASE_URL, JIRA_API_TOKEN');
+    }
+    this.http = axios.create({
+      baseURL: `${JIRA_BASE_URL}/rest/api/2`,
+      httpsAgent,
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+        Authorization: `Bearer ${JIRA_API_TOKEN}`,
+      },
+    });
+    this.dryRun = DRY_RUN;
+  }
+
+  // 建立 issue
+  async createIssue(fields) {
+    if (this.dryRun) {
+      console.log('[DRY RUN] JiraClient.createIssue', JSON.stringify(fields).slice(0, 1000));
+      return {id: 'DRY-RUN', key: 'DRY-RUN', self: ''};
+    }
+    const res = await this.http.post('/issue', {fields}).catch((err) => {
+      const detail = err.response?.data ? JSON.stringify(err.response.data) : err.message;
+      throw new Error(`Create issue failed: ${detail}`);
+    });
+    return res.data; // { id, key, self }
+  }
+
+  // 更新 issue 欄位
+  async updateIssue(issueKey, fields) {
+    if (this.dryRun) {
+      console.log(
+        '[DRY RUN] JiraClient.updateIssue',
+        issueKey,
+        JSON.stringify(fields).slice(0, 1000),
+      );
+      return {issueKey, updated: Object.keys(fields)};
+    }
+    await this.http.put(`/issue/${issueKey}`, {fields});
+    return {issueKey, updated: Object.keys(fields)};
+  }
+
+  // 更新 Assignee（使用專用 endpoint，Jira Server 相容）
+  async updateAssignee(issueKey, accountId) {
+    if (this.dryRun) {
+      console.log('[DRY RUN] JiraClient.updateAssignee', issueKey, accountId);
+      return {issueKey, accountId};
+    }
+    await this.http.put(`/issue/${issueKey}/assignee`, {name: accountId}).catch(async (err) => {
+      // 若 name 格式失敗，改試 accountId 格式（Jira Cloud）
+      if (err.response?.status === 400) {
+        await this.http.put(`/issue/${issueKey}/assignee`, {accountId}).catch((e) => {
+          const detail = e.response?.data ? JSON.stringify(e.response.data) : e.message;
+          throw new Error(`updateAssignee failed: ${detail}`);
+        });
+      } else {
+        const detail = err.response?.data ? JSON.stringify(err.response.data) : err.message;
+        throw new Error(`updateAssignee failed: ${detail}`);
+      }
+    });
+    return {issueKey, accountId};
+  }
+
+  // 查詢 issue 目前狀態
+  async getIssue(issueKey) {
+    const res = await this.http.get(`/issue/${issueKey}`, {
+      params: {fields: 'status,summary,assignee,comment'},
+    });
+    return res.data;
+  }
+
+  // 取得可執行的 transitions
+  async getTransitions(issueKey) {
+    const res = await this.http.get(`/issue/${issueKey}/transitions`);
+    return res.data.transitions; // [{ id, name, to: { name } }]
+  }
+
+  // 查詢 issue 的指定欄位（例如取得 CI 單的 CID_release_version）
+  async getIssueFields(issueKey, fields = []) {
+    const res = await this.http.get(`/issue/${issueKey}`, {
+      params: {fields: fields.join(',')},
+    });
+    return res.data.fields;
+  }
+
+  // 依 ID 直接切換狀態（不查名稱，適合 race condition 處理）
+  async transitionById(issueKey, transitionId) {
+    if (this.dryRun) {
+      console.log('[DRY RUN] JiraClient.transitionById', issueKey, transitionId);
+      return {issueKey, transitionId};
+    }
+    await this.http
+      .post(`/issue/${issueKey}/transitions`, {
+        transition: {id: transitionId},
+      })
+      .catch((err) => {
+        const detail = err.response?.data ? JSON.stringify(err.response.data) : err.message;
+        throw new Error(`Transition id=${transitionId} failed: ${detail}`);
+      });
+    return {issueKey, transitionId};
+  }
+
+  // 依名稱切換狀態（不用記 id）
+  async transitionByName(issueKey, transitionName) {
+    if (this.dryRun) {
+      console.log('[DRY RUN] JiraClient.transitionByName', issueKey, transitionName);
+      return {issueKey, transitioned: transitionName, toStatus: 'DRY'};
+    }
+    const transitions = await this.getTransitions(issueKey);
+    const match = transitions.find((t) => t.name.toLowerCase() === transitionName.toLowerCase());
+    if (!match) {
+      const available = transitions.map((t) => t.name).join(', ');
+      throw new Error(`Transition "${transitionName}" not found. Available: ${available}`);
+    }
+    await this.http
+      .post(`/issue/${issueKey}/transitions`, {
+        transition: {id: match.id},
+      })
+      .catch((err) => {
+        const detail = err.response?.data ? JSON.stringify(err.response.data) : err.message;
+        throw new Error(`Transition "${match.name}" failed: ${detail}`);
+      });
+    return {issueKey, transitioned: match.name, toStatus: match.to.name};
+  }
+
+  // 新增 issue link（relates to / blocks / is blocked by 等）
+  async linkIssue(inwardKey, outwardKey, linkTypeName = 'Relates') {
+    if (this.dryRun) {
+      console.log('[DRY RUN] JiraClient.linkIssue', inwardKey, outwardKey, linkTypeName);
+      return {inwardKey, outwardKey, linkType: linkTypeName};
+    }
+    await this.http.post('/issueLink', {
+      type: {name: linkTypeName},
+      inwardIssue: {key: inwardKey},
+      outwardIssue: {key: outwardKey},
+    });
+    return {inwardKey, outwardKey, linkType: linkTypeName};
+  }
+
+  // 新增 comment（/rest/api/2 用純文字 body）
+  async addComment(issueKey, text) {
+    if (this.dryRun) {
+      console.log('[DRY RUN] JiraClient.addComment', issueKey, text);
+      return {issueKey, body: text};
+    }
+    const res = await this.http.post(`/issue/${issueKey}/comment`, {
+      body: text,
+    });
+    return res.data;
+  }
+
+  // 新增 Web Link（remote link）到 issue
+  async addRemoteLink(issueKey, url, title) {
+    if (this.dryRun) {
+      console.log('[DRY RUN] JiraClient.addRemoteLink', issueKey, url, title);
+      return {issueKey, url, title};
+    }
+    const res = await this.http
+      .post(`/issue/${issueKey}/remotelink`, {
+        object: {url, title},
+      })
+      .catch((err) => {
+        const detail = err.response?.data ? JSON.stringify(err.response.data) : err.message;
+        throw new Error(`addRemoteLink failed: ${detail}`);
+      });
+    return res.data;
+  }
+
+  // 取得 Jira 專案的 versions（用於查找 LBPRJ release 版本頁面）
+  // 對應 UI 網址：/projects/LBPRJ?selectedItem=...release-page&status=unreleased&contains=cwa
+  //
+  // ⚠️ Jira Server 的 /project/{key}/version 分頁端點不支援 status/query 過濾
+  //    （僅 Jira Cloud 支援）。改用 /versions 取全量後在 client 端過濾。
+  //
+  // status: 'unreleased'
+  // query:  相當於 UI 的 contains 參數（版本名稱包含此字串，不分大小寫）
+  async getProjectVersions(projectKey, {name = {}}) {
+    const res = await this.http.get(`/project/${projectKey}/versions`);
+    let versions = res.data ?? [];
+
+    // Client-side 過濾（對齊 UI status=unreleased&contains=xxx）
+    const version = versions.find((v) => !v.released && !v.archived && v.name === name);
+
+    if (version) {
+      return version.id;
+    }
+
+    return ''; // 沒有找到符合條件的版本
+  }
+
+  // 取得 LBPRJ 所有 unreleased 版本列表（不含已 release 或已 archive 的）
+  async getUnreleasedVersionsList(projectKey) {
+    const res = await this.http.get(`/project/${projectKey}/versions`);
+    const versions = res.data ?? [];
+    return versions.filter((v) => !v.released && !v.archived);
+  }
+
+  // 取得 issue 的所有 comments
+  async getComments(issueKey) {
+    const res = await this.http.get(`/issue/${issueKey}/comment`).catch((err) => {
+      const detail = err.response?.data ? JSON.stringify(err.response.data) : err.message;
+      throw new Error(`getComments failed: ${detail}`);
+    });
+    return res.data?.comments ?? [];
+  }
+
+  // 取得 issue 的 sub-tasks（Deployment 單等）
+  async getSubTasks(issueKey) {
+    const res = await this.http
+      .get(`/issue/${issueKey}`, {
+        params: {fields: 'subtasks,issuetype'},
+      })
+      .catch((err) => {
+        const detail = err.response?.data ? JSON.stringify(err.response.data) : err.message;
+        throw new Error(`getSubTasks failed: ${detail}`);
+      });
+    return res.data.fields?.subtasks ?? [];
+  }
+
+  // JQL 搜尋，回傳 issues 陣列 [{ id, key, fields }]
+  async searchIssues(jql, fields = [], maxResults = 10) {
+    const res = await this.http
+      .get('/search', {
+        params: {jql, fields: fields.join(','), maxResults},
+      })
+      .catch((err) => {
+        const detail = err.response?.data ? JSON.stringify(err.response.data) : err.message;
+        throw new Error(`Search issues failed: ${detail}`);
+      });
+    return res.data.issues ?? [];
+  }
+
+  // 取得 Bitbucket repo 的原始檔案內容（Bitbucket REST API 1.0）
+  async getBitbucketFileContent(project, repo, filePath, branch) {
+    const BB_BASE = process.env.BITBUCKET_URL ?? 'https://bitbucket.linebank.com.tw';
+    const url = `${BB_BASE}/rest/api/1.0/projects/${project}/repos/${repo}/raw/${filePath}`;
+    const res = await axios
+      .get(url, {
+        httpsAgent,
+        headers: {
+          Accept: 'text/plain',
+          Authorization: `Bearer ${process.env.BITBUCKET_API_TOKEN}`,
+        },
+        params: {at: branch},
+        responseType: 'text',
+      })
+      .catch((err) => {
+        const detail = err.response?.data ? JSON.stringify(err.response.data) : err.message;
+        throw new Error(`getBitbucketFileContent(${repo}/${filePath}@${branch}) failed: ${detail}`);
+      });
+    return res.data;
+  }
+
+  // 取得 Bitbucket repo 的 tags（Bitbucket REST API 1.0）
+  async getBitbucketTags(
+    project,
+    repo,
+    {filterValue = '', orderBy = 'MODIFICATION', limit = 1} = {},
+  ) {
+    const BB_BASE = process.env.BITBUCKET_URL ?? 'https://bitbucket.linebank.com.tw';
+    const url = `${BB_BASE}/rest/api/1.0/projects/${project}/repos/${repo}/tags`;
+    const res = await axios
+      .get(url, {
+        httpsAgent,
+        headers: {
+          'Content-Type': 'application/json',
+          Accept: 'application/json',
+          Authorization: `Bearer ${process.env.BITBUCKET_API_TOKEN}`,
+        },
+        params: {filterValue, orderBy, limit},
+      })
+      .catch((err) => {
+        const detail = err.response?.data ? JSON.stringify(err.response.data) : err.message;
+        throw new Error(`getBitbucketTags failed: ${detail}`);
+      });
+    return res.data?.values ?? [];
+  }
+
+  // 取得 Bitbucket repo 的 branches（Bitbucket REST API 1.0）
+  async getBitbucketBranches(
+    project,
+    repo,
+    {filterValue = '', orderBy = 'MODIFICATION', limit = 1} = {},
+  ) {
+    const BB_BASE = process.env.BITBUCKET_URL ?? 'https://bitbucket.linebank.com.tw';
+    const url = `${BB_BASE}/rest/api/1.0/projects/${project}/repos/${repo}/branches`;
+    const res = await axios
+      .get(url, {
+        httpsAgent,
+        headers: {
+          'Content-Type': 'application/json',
+          Accept: 'application/json',
+          Authorization: `Bearer ${process.env.BITBUCKET_API_TOKEN}`,
+        },
+        params: {filterValue, orderBy, limit},
+      })
+      .catch((err) => {
+        const detail = err.response?.data ? JSON.stringify(err.response.data) : err.message;
+        throw new Error(`getBitbucketBranches failed: ${detail}`);
+      });
+    return res.data?.values ?? [];
+  }
+}

package/notifier.js

@@ -0,0 +1,56 @@
+/**
+ * Notifier — 集中處理所有通知
+ *
+ * 目前支援：Jira comment
+ * 擴充 Slack：填入 .env 的 SLACK_BOT_TOKEN + SLACK_CHANNEL_ID 後，
+ *             把下方 notifySlack 的 TODO 實作即可，其他地方不用動。
+ */
+
+export class Notifier {
+  constructor(jiraClient) {
+    this.jira = jiraClient;
+    this.slackEnabled = !!process.env.SLACK_BOT_TOKEN && !!process.env.SLACK_CHANNEL_ID;
+    this.dryRun = process.env.DRY_RUN === 'true';
+  }
+
+  async notify(issueKey, message) {
+    const results = [];
+
+    if (this.dryRun) {
+      console.log(`[DRY RUN] Notifier.notify ${issueKey}: ${message}`);
+      // don't actually call Jira or Slack
+      results.push('dry_run');
+      return results;
+    }
+
+    // 永遠寫 Jira comment（失敗不中斷主流程）
+    try {
+      await this.jira.addComment(issueKey, `[Bot] ${message}`);
+      results.push('jira_comment');
+    } catch (err) {
+      console.error(`[Notifier] addComment failed for ${issueKey}: ${err.message}`);
+    }
+
+    // Slack（有設定就送）
+    if (this.slackEnabled) {
+      try {
+        await this.notifySlack(issueKey, message);
+        results.push('slack');
+      } catch (err) {
+        console.error(`[Notifier] slack notify failed: ${err.message}`);
+      }
+    }
+
+    return results;
+  }
+
+  async notifySlack(issueKey, message) {
+    // TODO: 擴充 Slack 通知
+    // const { SLACK_BOT_TOKEN, SLACK_CHANNEL_ID } = process.env;
+    // await axios.post('https://slack.com/api/chat.postMessage', {
+    //   channel: SLACK_CHANNEL_ID,
+    //   text: `*[${issueKey}]* ${message}`,
+    // }, { headers: { Authorization: `Bearer ${SLACK_BOT_TOKEN}` } });
+    console.log(`[Slack TODO] ${issueKey}: ${message}`);
+  }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@jira-deploy/core",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ap311036/jira-deploy-mcp.git",
+    "directory": "packages/jira-core"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./constants": "./constants/index.js",
+    "./jira-client": "./jira-client.js",
+    "./notifier": "./notifier.js",
+    "./poller": "./poller.js",
+    "./platform-config": "./platform-config.js",
+    "./tools": "./tools/index.js",
+    "./tools/helpers": "./tools/helpers.js",
+    "./tools/library": "./tools/library.js"
+  },
+  "files": [
+    "constants/**/*.js",
+    "tools/**/*.js",
+    "*.js"
+  ],
+  "dependencies": {
+    "axios": "^1.6.0",
+    "dotenv": "^16.3.0"
+  },
+  "scripts": {
+    "test": "node --test tools.test.js"
+  }
+}

package/platform-config.js

@@ -0,0 +1,64 @@
+/**
+ * 平台配置（已遷移到 src/constants/）
+ *
+ * ⚠️ 此檔案已棄用，保留供向後相容性
+ * 新的配置請在 src/constants/ 目錄下管理
+ */
+
+import {SYSTEM_CODES, GRAY_RELEASE_MODULE_IDS} from './constants/index.js';
+import {getServerList} from './tools/helpers.js';
+
+/**
+ * 平台映射 - 將使用者友善的平台名稱對應到系統代碼
+ */
+export const PLATFORM_TO_SYSTEM_CODE = {
+  cwa: SYSTEM_CODES.CWA,
+  ibk: SYSTEM_CODES.IBK,
+  eib: SYSTEM_CODES.EIB,
+  evt: SYSTEM_CODES.EVT,
+  bof: SYSTEM_CODES.BOF,
+  npm: SYSTEM_CODES.NPM,
+};
+
+/**
+ * 取得平台設定 - 根據平台名稱回傳相關設定
+ * @param {string} platformName - 平台名稱 (例如 'cwa', 'ibk')
+ * @param {string} environment - 環境 (例如 'stg', 'prd')
+ * @returns {object} 平台設定
+ */
+export function getPlatformConfig(platformName, environment = 'stg') {
+  const systemCode = PLATFORM_TO_SYSTEM_CODE[platformName.toLowerCase()];
+
+  if (!systemCode) {
+    console.warn(`Unknown platform: ${platformName}, using defaults`);
+    return {
+      projectKey: process.env.JIRA_PROJECT_KEY ?? 'OPS',
+      systemCode: undefined,
+      clusters: [],
+      environment,
+    };
+  }
+
+  return {
+    systemCode,
+    environment,
+    clusters: getServerList(systemCode, environment),
+    supportedModules: Object.keys(GRAY_RELEASE_MODULE_IDS).filter(
+      (m) => GRAY_RELEASE_MODULE_IDS[m],
+    ),
+  };
+}
+
+/**
+ * @deprecated 保留供向後相容，新代碼請使用 getPlatformConfig()
+ */
+export const PLATFORMS = {
+  cwa: {
+    systemCode: SYSTEM_CODES.CWA,
+    issueType: 'GrayRelease',
+  },
+  ibk: {
+    systemCode: SYSTEM_CODES.IBK,
+    issueType: 'GrayRelease',
+  },
+};

package/poller.js

@@ -0,0 +1,64 @@
+/**
+ * Poller — 輪詢等待 Jira issue 達到目標狀態
+ *
+ * 使用方式：
+ *   const poller = new Poller(jiraClient);
+ *   const result = await poller.waitForStatus('OPS-123', 'Approved', {
+ *     intervalMs: 30000,
+ *     timeoutMs: 3600000,
+ *   });
+ */
+
+export class Poller {
+  constructor(jiraClient) {
+    this.jira = jiraClient;
+  }
+
+  /**
+   * 輪詢直到 issue 狀態 === targetStatus
+   * @returns {{ issueKey, status, elapsedMs, attempts }}
+   */
+  async waitForStatus(issueKey, targetStatus, options = {}) {
+    const intervalMs = options.intervalMs ?? parseInt(process.env.POLL_INTERVAL_MS ?? '30000');
+    const timeoutMs = options.timeoutMs ?? parseInt(process.env.POLL_TIMEOUT_MS ?? '3600000');
+
+    const startTime = Date.now();
+    let attempts = 0;
+
+    console.error(
+      `[Poller] Waiting for "${issueKey}" → "${targetStatus}" ` +
+      `(interval ${intervalMs / 1000}s, timeout ${timeoutMs / 1000}s)`,
+    );
+
+    while (true) {
+      attempts++;
+      const issue = await this.jira.getIssue(issueKey);
+      const currentStatus = issue.fields.status.name;
+
+      console.error(`[Poller] attempt #${attempts} — current: "${currentStatus}"`);
+
+      if (currentStatus.toLowerCase() === targetStatus.toLowerCase()) {
+        return {
+          issueKey,
+          status: currentStatus,
+          elapsedMs: Date.now() - startTime,
+          attempts,
+        };
+      }
+
+      const elapsed = Date.now() - startTime;
+      if (elapsed >= timeoutMs) {
+        throw new Error(
+          `Timeout waiting for "${issueKey}" to reach "${targetStatus}". ` +
+          `Last status: "${currentStatus}" after ${attempts} attempts.`,
+        );
+      }
+
+      await sleep(intervalMs);
+    }
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}