@daghis/teamcity-mcp 0.1.2

package/src/teamcity/index.ts

@@ -0,0 +1,266 @@
+/**
+ * TeamCity integration module
+ * Main entry point for TeamCity API operations
+ */
+import { info, warn } from '@/utils/logger';
+
+import { TeamCityClient } from './client';
+import {
+  type TeamCityFullConfig,
+  loadTeamCityConfig,
+  mergeConfig,
+  toClientConfig,
+  validateConfig,
+} from './config';
+
+// Re-export all public types and utilities
+export * from './client';
+export * from './auth';
+export * from './errors';
+export * from './circuit-breaker';
+export * from './pagination';
+export * from './config';
+
+// Re-export configuration
+export * from '@/teamcity-client/configuration';
+
+/**
+ * Global TeamCity client instance
+ */
+let globalClient: TeamCityClient | null = null;
+
+/**
+ * Initialize global TeamCity client
+ */
+export async function initializeTeamCity(
+  config?: Partial<TeamCityFullConfig>
+): Promise<TeamCityClient> {
+  // Load configuration from environment
+  const envConfig = loadTeamCityConfig();
+
+  // Merge with provided config
+  const fullConfig = config ? mergeConfig(envConfig, config) : envConfig;
+
+  // Validate configuration
+  const validation = validateConfig(fullConfig);
+  if (!validation.isValid) {
+    throw new Error(`Invalid TeamCity configuration: ${validation.errors.join(', ')}`);
+  }
+
+  // Convert to client config
+  const clientConfig = toClientConfig(fullConfig);
+
+  // Create client
+  globalClient = new TeamCityClient(clientConfig);
+
+  // Test connection
+  const isConnected = await globalClient.testConnection();
+  if (!isConnected) {
+    warn('Failed to connect to TeamCity server', {
+      baseUrl: clientConfig.baseUrl,
+    });
+  } else {
+    info('Successfully connected to TeamCity server', {
+      baseUrl: clientConfig.baseUrl,
+    });
+  }
+
+  return globalClient;
+}
+
+/**
+ * Get global TeamCity client instance
+ */
+export function getTeamCityClient(): TeamCityClient {
+  if (!globalClient) {
+    throw new Error('TeamCity client not initialized. Call initializeTeamCity() first.');
+  }
+  return globalClient;
+}
+
+/**
+ * Create a new TeamCity client instance
+ */
+export function createTeamCityClient(config?: Partial<TeamCityFullConfig>): TeamCityClient {
+  const envConfig = loadTeamCityConfig();
+  const fullConfig = config ? mergeConfig(envConfig, config) : envConfig;
+
+  const validation = validateConfig(fullConfig);
+  if (!validation.isValid) {
+    throw new Error(`Invalid TeamCity configuration: ${validation.errors.join(', ')}`);
+  }
+
+  const clientConfig = toClientConfig(fullConfig);
+  return new TeamCityClient(clientConfig);
+}
+
+/**
+ * Reset global TeamCity client (for testing)
+ */
+export function resetTeamCityClient(): void {
+  globalClient = null;
+}
+
+/**
+ * Example usage and helper functions
+ */
+
+interface BuildData {
+  id?: string;
+  number?: number;
+  status?: string;
+  state?: string;
+  branchName?: string;
+  buildType?: {
+    id: string;
+    name: string;
+  };
+}
+
+interface TestOccurrence {
+  id?: string;
+  name?: string;
+  status?: string;
+  ignored?: boolean;
+  details?: string;
+}
+
+/**
+ * Get all builds for a project
+ */
+export async function getProjectBuilds(projectId: string): Promise<BuildData[]> {
+  const client = getTeamCityClient();
+  const response = await client.builds.getAllBuilds(
+    `project:${projectId}`, // locator as string
+    undefined // fields
+  );
+  // Map Build[] to BuildData[]
+  const builds = response.data.build ?? [];
+  return builds.map(
+    (build: {
+      id?: string | number;
+      number?: string | number;
+      status?: string;
+      state?: string;
+      buildTypeId?: string;
+      branchName?: string;
+    }) => ({
+      id: build.id != null ? String(build.id) : undefined,
+      number: typeof build.number === 'string' ? parseInt(build.number, 10) : build.number,
+      status: build.status,
+      state: build.state,
+      buildTypeId: build.buildTypeId,
+      branchName: build.branchName,
+    })
+  );
+}
+
+/**
+ * Trigger a new build
+ */
+export async function triggerBuild(
+  buildTypeId: string,
+  branchName?: string,
+  comment?: string
+): Promise<BuildData> {
+  const client = getTeamCityClient();
+  const buildRequest = {
+    buildType: { id: buildTypeId },
+    branchName,
+    comment:
+      comment !== undefined && comment !== null && comment !== '' ? { text: comment } : undefined,
+  };
+
+  const response = await client.buildQueue.addBuildToQueue(
+    undefined, // moveToTop
+    buildRequest // body
+  );
+
+  // Map Build to BuildData
+  const build = response.data;
+  return {
+    id: build.id != null ? String(build.id) : undefined,
+    number: build.number != null ? parseInt(build.number) : undefined,
+    status: build.status,
+    state: build.state,
+    branchName: build.branchName,
+    buildType: build.buildTypeId != null ? { id: build.buildTypeId, name: '' } : undefined,
+  };
+}
+
+/**
+ * Cancel a running build
+ */
+export async function cancelBuild(buildId: number, comment?: string): Promise<void> {
+  const client = getTeamCityClient();
+  await client.builds.cancelBuild(
+    `id:${buildId}`, // buildLocator
+    undefined, // fields
+    { comment: comment ?? 'Cancelled via MCP' } // body
+  );
+}
+
+/**
+ * Get build status
+ */
+export async function getBuildStatus(buildId: number): Promise<{
+  state: string;
+  status: string;
+  statusText: string;
+}> {
+  const client = getTeamCityClient();
+  const response = await client.builds.getBuild(
+    `id:${buildId}`, // buildLocator
+    'state,status,statusText' // fields
+  );
+
+  return {
+    state: response.data.state ?? 'unknown',
+    status: response.data.status ?? 'unknown',
+    statusText: response.data.statusText ?? '',
+  };
+}
+
+/**
+ * Get test results for a build
+ */
+export async function getBuildTestResults(buildId: number): Promise<{
+  total: number;
+  passed: number;
+  failed: number;
+  ignored: number;
+  failures: TestOccurrence[];
+}> {
+  const client = getTeamCityClient();
+  const response = await client.testOccurrences.getAllTestOccurrences(
+    `build:${buildId}`, // locator
+    undefined // fields
+  );
+
+  const tests = response.data.testOccurrence ?? [];
+  const failures = tests.filter((t: TestOccurrence) => t.status === 'FAILURE');
+
+  return {
+    total: tests.length,
+    passed: tests.filter((t: TestOccurrence) => t.status === 'SUCCESS').length,
+    failed: failures.length,
+    ignored: tests.filter((t: TestOccurrence) => t.ignored === true).length,
+    failures,
+  };
+}
+
+/**
+ * Get build log
+ */
+export async function getBuildLog(buildId: number): Promise<string> {
+  const client = getTeamCityClient();
+  // Note: This is a simplified example. The actual API might require different approach
+  await client.builds.getBuild(
+    `id:${buildId}`, // buildLocator
+    'href' // fields
+  );
+
+  // Would need to fetch log from a different endpoint
+  // This is just a placeholder
+  return `Build log for ${buildId}`;
+}

package/src/teamcity/pagination.ts

@@ -0,0 +1,209 @@
+/**
+ * Pagination utilities for TeamCity API
+ */
+import { info } from '@/utils/logger';
+
+export interface PaginationParams {
+  count?: number;
+  start?: number;
+}
+
+export interface PaginatedResponse<T> {
+  items: T[];
+  count: number;
+  total?: number;
+  nextHref?: string;
+  prevHref?: string;
+}
+
+export interface PaginationOptions {
+  pageSize?: number;
+  maxPages?: number;
+  fetchAll?: boolean;
+}
+
+interface ApiResponse<T = unknown> {
+  data: T & {
+    nextHref?: string;
+    prevHref?: string;
+  };
+}
+
+/**
+ * Async iterator for paginated results
+ */
+export class PaginatedIterator<T> {
+  private currentPage = 0;
+  private hasMore = true;
+  private readonly pageSize: number;
+  private readonly maxPages?: number;
+  private readonly fetchFn: (params: PaginationParams) => Promise<PaginatedResponse<T>>;
+
+  constructor(
+    fetchFn: (params: PaginationParams) => Promise<PaginatedResponse<T>>,
+    options: PaginationOptions = {}
+  ) {
+    this.fetchFn = fetchFn;
+    this.pageSize = options.pageSize ?? 100;
+    this.maxPages = options.maxPages;
+  }
+
+  /**
+   * Async iterator implementation
+   */
+  async *[Symbol.asyncIterator](): AsyncIterator<T> {
+    while (this.hasMore && (!this.maxPages || this.currentPage < this.maxPages)) {
+      const start = this.currentPage * this.pageSize;
+      // Sequential page fetch; preserves order and avoids overfetching
+      // eslint-disable-next-line no-await-in-loop
+      const response = await this.fetchFn({
+        count: this.pageSize,
+        start,
+      });
+
+      for (const item of response.items) {
+        yield item;
+      }
+
+      this.currentPage++;
+      this.hasMore = response.nextHref !== undefined || response.items.length === this.pageSize;
+
+      if (response.items.length < this.pageSize) {
+        this.hasMore = false;
+      }
+    }
+  }
+
+  /**
+   * Collect all items into array
+   */
+  async toArray(): Promise<T[]> {
+    const items: T[] = [];
+    for await (const item of this) {
+      items.push(item);
+    }
+    return items;
+  }
+
+  /**
+   * Get a single page
+   */
+  async getPage(pageNumber: number): Promise<T[]> {
+    const start = pageNumber * this.pageSize;
+    const response = await this.fetchFn({
+      count: this.pageSize,
+      start,
+    });
+    return response.items;
+  }
+}
+
+/**
+ * Create paginated fetcher function
+ */
+export function createPaginatedFetcher<T>(
+  baseFetch: (params: PaginationParams) => Promise<unknown>,
+  extractItems: (response: unknown) => T[],
+  extractTotal?: (response: unknown) => number | undefined
+): (params: PaginationParams) => Promise<PaginatedResponse<T>> {
+  return async (params: PaginationParams) => {
+    const response = (await baseFetch({
+      count: params.count,
+      start: params.start,
+    })) as ApiResponse;
+
+    const items = extractItems(response.data);
+    const total = extractTotal?.(response.data);
+
+    return {
+      items,
+      count: items.length,
+      total,
+      nextHref: response.data?.nextHref,
+      prevHref: response.data?.prevHref,
+    };
+  };
+}
+
+/**
+ * Fetch all pages automatically
+ */
+export async function fetchAllPages<T>(
+  fetchFn: (params: PaginationParams) => Promise<PaginatedResponse<T>>,
+  options: PaginationOptions = {}
+): Promise<T[]> {
+  const allItems: T[] = [];
+  let hasMore = true;
+  let currentPage = 0;
+  const pageSize = options.pageSize ?? 100;
+  const maxPages = options.maxPages;
+
+  info('Starting paginated fetch', { pageSize, maxPages });
+
+  while (hasMore && (!maxPages || currentPage < maxPages)) {
+    const start = currentPage * pageSize;
+    // Sequential page fetch; keeps memory and requests bounded
+    // eslint-disable-next-line no-await-in-loop
+    const response = await fetchFn({
+      count: pageSize,
+      start,
+    });
+
+    allItems.push(...response.items);
+    currentPage++;
+
+    hasMore = response.nextHref !== undefined || response.items.length === pageSize;
+
+    if (response.items.length < pageSize) {
+      hasMore = false;
+    }
+
+    info(`Fetched page ${currentPage}`, {
+      itemsInPage: response.items.length,
+      totalItems: allItems.length,
+      hasMore,
+    });
+  }
+
+  info('Paginated fetch complete', {
+    totalPages: currentPage,
+    totalItems: allItems.length,
+  });
+
+  return allItems;
+}
+
+/**
+ * Parse TeamCity locator string for pagination
+ */
+export function parseLocator(locator: string): PaginationParams {
+  const params: PaginationParams = {};
+
+  const parts = locator.split(',');
+  for (const part of parts) {
+    const [key, value] = part.split(':');
+    if (key === 'start' && value !== undefined) {
+      params.start = parseInt(value, 10);
+    } else if (key === 'count' && value !== undefined) {
+      params.count = parseInt(value, 10);
+    }
+  }
+
+  return params;
+}
+
+/**
+ * Build TeamCity locator string for pagination
+ */
+export function buildLocator(params: PaginationParams): string {
+  const parts: string[] = [];
+
+  if (params.start !== undefined) {
+    parts.push(`start:${params.start}`);
+  }
+  if (params.count !== undefined) {
+    parts.push(`count:${params.count}`);
+  }
+
+  return parts.join(',');
+}