@daghis/teamcity-mcp 0.1.2

package/src/teamcity/artifact-manager.ts

@@ -0,0 +1,362 @@
+/**
+ * ArtifactManager - Advanced artifact management for TeamCity builds
+ */
+import axios from 'axios';
+
+import { getTeamCityToken, getTeamCityUrl } from '@/config';
+
+export interface ArtifactInfo {
+  name: string;
+  path: string;
+  size: number;
+  modificationTime?: string;
+  downloadUrl: string;
+  isDirectory?: boolean;
+}
+
+export interface ArtifactListOptions {
+  nameFilter?: string;
+  pathFilter?: string;
+  extension?: string;
+  minSize?: number;
+  maxSize?: number;
+  includeNested?: boolean;
+  limit?: number;
+  offset?: number;
+  forceRefresh?: boolean;
+}
+
+export interface ArtifactDownloadOptions {
+  encoding?: 'base64' | 'text' | 'buffer';
+  maxSize?: number;
+}
+
+export interface ArtifactContent {
+  name: string;
+  path: string;
+  size: number;
+  content?: string | Buffer;
+  mimeType?: string;
+  error?: string;
+}
+
+interface CacheEntry {
+  artifacts: ArtifactInfo[];
+  timestamp: number;
+}
+
+interface ArtifactFile {
+  name?: string;
+  fullName?: string;
+  size?: number;
+  href?: string;
+  modificationTime?: string;
+  children?: ArtifactFileResponse;
+}
+
+interface ArtifactFileResponse {
+  file?: ArtifactFile[];
+}
+
+export class ArtifactManager {
+  private baseUrl: string;
+  private token: string;
+  private cache: Map<string, CacheEntry> = new Map();
+  private static readonly cacheTtlMs = 60000; // 1 minute
+  private static readonly defaultLimit = 100;
+  private static readonly maxLimit = 1000;
+
+  constructor() {
+    this.baseUrl = getTeamCityUrl();
+    this.token = getTeamCityToken();
+  }
+
+  /**
+   * List artifacts for a build
+   */
+  async listArtifacts(buildId: string, options: ArtifactListOptions = {}): Promise<ArtifactInfo[]> {
+    // Check cache unless force refresh
+    const cacheKey = this.getCacheKey(buildId, options);
+    if (!options.forceRefresh) {
+      const cached = this.getFromCache(cacheKey);
+      if (cached) {
+        return cached;
+      }
+    }
+
+    try {
+      // Fetch artifacts from API
+      const url = `${this.baseUrl}/app/rest/builds/id:${buildId}/artifacts`;
+      const response = await axios.get(url, {
+        headers: {
+          Authorization: `Bearer ${this.token}`,
+          Accept: 'application/json',
+        },
+      });
+
+      let artifacts = this.parseArtifacts(
+        response.data as ArtifactFileResponse,
+        buildId,
+        options.includeNested
+      );
+
+      // Apply filters
+      artifacts = this.applyFilters(artifacts, options);
+
+      // Apply pagination
+      if (options.limit ?? options.offset) {
+        artifacts = this.paginate(
+          artifacts,
+          options.offset ?? 0,
+          options.limit ?? ArtifactManager.defaultLimit
+        );
+      }
+
+      // Cache the result
+      this.cacheResult(cacheKey, artifacts);
+
+      return artifacts;
+    } catch (error) {
+      const err = error as { response?: { status?: number }; message?: string };
+      if (err.response?.status === 401) {
+        throw new Error('Authentication failed: Invalid TeamCity token');
+      }
+      if (err.response?.status === 404) {
+        throw new Error(`Build not found: ${buildId}`);
+      }
+      const errMsg = err.message ?? String(error);
+      throw new Error(`Failed to fetch artifacts: ${errMsg}`);
+    }
+  }
+
+  /**
+   * Download a specific artifact
+   */
+  async downloadArtifact(
+    buildId: string,
+    artifactPath: string,
+    options: ArtifactDownloadOptions = {}
+  ): Promise<ArtifactContent> {
+    // First, get artifact info to check size
+    const artifacts = await this.listArtifacts(buildId);
+    const artifact = artifacts.find((a) => a.path === artifactPath || a.name === artifactPath);
+
+    if (!artifact) {
+      throw new Error(`Artifact not found: ${artifactPath}`);
+    }
+
+    // Check size limit
+    if (options.maxSize && artifact.size > options.maxSize) {
+      throw new Error(
+        `Artifact size exceeds maximum allowed size: ${artifact.size} > ${options.maxSize}`
+      );
+    }
+
+    try {
+      const url = artifact.downloadUrl;
+      const response = await axios.get(url, {
+        headers: {
+          Authorization: `Bearer ${this.token}`,
+        },
+        responseType: options.encoding === 'text' ? 'text' : 'arraybuffer',
+      });
+
+      let content: string | Buffer;
+      if (options.encoding === 'base64') {
+        content = Buffer.from(response.data).toString('base64');
+      } else if (options.encoding === 'buffer') {
+        content = Buffer.from(response.data);
+      } else {
+        content = response.data;
+      }
+
+      return {
+        name: artifact.name,
+        path: artifact.path,
+        size: artifact.size,
+        content,
+        mimeType: response.headers['content-type'],
+      };
+    } catch (error) {
+      const errMsg = error instanceof Error ? error.message : 'Unknown error';
+      throw new Error(`Failed to download artifact: ${errMsg}`);
+    }
+  }
+
+  /**
+   * Download multiple artifacts
+   */
+  async downloadMultipleArtifacts(
+    buildId: string,
+    artifactPaths: string[],
+    options: ArtifactDownloadOptions = {}
+  ): Promise<ArtifactContent[]> {
+    // Default to base64 encoding if not specified
+    const downloadOptions = { encoding: 'base64' as const, ...options };
+
+    const results = await Promise.allSettled(
+      artifactPaths.map((path) => this.downloadArtifact(buildId, path, downloadOptions))
+    );
+
+    return results.map((result, index) => {
+      if (result.status === 'fulfilled') {
+        return result.value;
+      } else {
+        // Return partial result with error
+        const fallbackName = artifactPaths[index] ?? 'unknown';
+        return {
+          name: fallbackName,
+          path: fallbackName,
+          size: 0,
+          error: result.reason.message,
+        };
+      }
+    });
+  }
+
+  /**
+   * Parse artifacts from API response
+   */
+  private parseArtifacts(
+    data: ArtifactFileResponse,
+    buildId: string,
+    includeNested?: boolean
+  ): ArtifactInfo[] {
+    const artifacts: ArtifactInfo[] = [];
+    const files = data.file ?? [];
+
+    for (const file of files) {
+      // If it's a directory and has children
+      if (file.children && includeNested) {
+        // Recursively parse nested artifacts
+        const nested = this.parseArtifacts(file.children, buildId, includeNested);
+        artifacts.push(...nested);
+      } else if (!file.children) {
+        // It's a file, not a directory
+        artifacts.push({
+          name: file.name ?? '',
+          path: file.fullName ?? file.name ?? '',
+          size: file.size ?? 0,
+          modificationTime: file.modificationTime ?? '',
+          downloadUrl: `${this.baseUrl}/app/rest/builds/id:${buildId}/artifacts/content/${file.fullName ?? file.name ?? ''}`,
+          isDirectory: false,
+        });
+      }
+    }
+
+    return artifacts;
+  }
+
+  /**
+   * Apply filters to artifacts
+   */
+  private applyFilters(artifacts: ArtifactInfo[], options: ArtifactListOptions): ArtifactInfo[] {
+    let filtered = artifacts;
+
+    // Filter by name pattern
+    if (options.nameFilter) {
+      const regex = this.globToRegex(options.nameFilter);
+      filtered = filtered.filter((a) => regex.test(a.name));
+    }
+
+    // Filter by path pattern
+    if (options.pathFilter) {
+      const regex = this.globToRegex(options.pathFilter);
+      filtered = filtered.filter((a) => regex.test(a.path));
+    }
+
+    // Filter by extension
+    if (options.extension) {
+      const ext = options.extension.startsWith('.') ? options.extension : `.${options.extension}`;
+      filtered = filtered.filter((a) => a.name.endsWith(ext));
+    }
+
+    // Filter by size range
+    if (options.minSize !== undefined) {
+      const minSize = options.minSize as number;
+      filtered = filtered.filter((a) => a.size >= minSize);
+    }
+    if (options.maxSize !== undefined) {
+      const maxSize = options.maxSize as number;
+      filtered = filtered.filter((a) => a.size <= maxSize);
+    }
+
+    return filtered;
+  }
+
+  /**
+   * Convert glob pattern to regex
+   */
+  private globToRegex(pattern: string): RegExp {
+    const escaped = pattern
+      .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+      .replace(/\*/g, '.*')
+      .replace(/\?/g, '.');
+    return new RegExp(`^${escaped}$`);
+  }
+
+  /**
+   * Paginate results
+   */
+  private paginate(artifacts: ArtifactInfo[], offset: number, limit: number): ArtifactInfo[] {
+    const effectiveLimit = Math.min(limit, ArtifactManager.maxLimit);
+    return artifacts.slice(offset, offset + effectiveLimit);
+  }
+
+  /**
+   * Generate cache key
+   */
+  private getCacheKey(buildId: string, options: ArtifactListOptions): string {
+    const { forceRefresh: _forceRefresh, ...cacheOptions } = options;
+    return `${buildId}:${JSON.stringify(cacheOptions)}`;
+  }
+
+  /**
+   * Get from cache if valid
+   */
+  private getFromCache(key: string): ArtifactInfo[] | null {
+    const entry = this.cache.get(key);
+    if (!entry) {
+      return null;
+    }
+
+    const age = Date.now() - entry.timestamp;
+    if (age > ArtifactManager.cacheTtlMs) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    return entry.artifacts;
+  }
+
+  /**
+   * Cache artifacts
+   */
+  private cacheResult(key: string, artifacts: ArtifactInfo[]): void {
+    this.cache.set(key, {
+      artifacts,
+      timestamp: Date.now(),
+    });
+
+    // Clean old entries
+    this.cleanCache();
+  }
+
+  /**
+   * Remove expired cache entries
+   */
+  private cleanCache(): void {
+    const now = Date.now();
+    const expired: string[] = [];
+
+    for (const [key, entry] of this.cache.entries()) {
+      if (now - entry.timestamp > ArtifactManager.cacheTtlMs) {
+        expired.push(key);
+      }
+    }
+
+    for (const key of expired) {
+      this.cache.delete(key);
+    }
+  }
+}

package/src/teamcity/auth.ts

@@ -0,0 +1,215 @@
+/**
+ * Authentication utilities for TeamCity API
+ */
+import type {
+  AxiosError,
+  AxiosRequestConfig,
+  AxiosResponse,
+  InternalAxiosRequestConfig,
+} from 'axios';
+import { v4 as uuidv4 } from 'uuid';
+
+import { info, error as logError } from '@/utils/logger';
+
+/**
+ * Generate a unique request ID for tracing
+ */
+export function generateRequestId(): string {
+  return uuidv4();
+}
+
+/**
+ * Add request ID to axios config
+ */
+export function addRequestId(config: InternalAxiosRequestConfig): InternalAxiosRequestConfig {
+  const requestId = generateRequestId();
+
+  // Add request ID to headers
+  config.headers['X-Request-ID'] = requestId;
+
+  // Store request ID in config for later use
+  const configWithId = config as AxiosRequestConfig & { requestId: string };
+  configWithId.requestId = requestId;
+
+  // Attach timing metadata
+  (config as unknown as { _tcMeta?: { start: number } })._tcMeta = { start: Date.now() };
+
+  // Log the request with ID
+  info('Starting TeamCity API request', {
+    requestId,
+    method: config.method?.toUpperCase(),
+    url: config.url,
+    headers: {
+      Authorization: config.headers['Authorization'] != null ? '[REDACTED]' : undefined,
+      'X-Request-ID': requestId,
+    },
+  });
+
+  return config;
+}
+
+/**
+ * Transform TeamCity API errors into consistent format
+ */
+export interface TeamCityAPIErrorData {
+  code: string;
+  message: string;
+  details?: string;
+  requestId?: string;
+  statusCode?: number;
+  originalError?: Error;
+}
+
+/**
+ * Extract error details from TeamCity API response
+ */
+export function extractErrorDetails(error: AxiosError): TeamCityAPIErrorData {
+  const requestId = (error.config as AxiosRequestConfig & { requestId?: string })?.requestId;
+
+  if (error.response != null) {
+    // The request was made and the server responded with a status code
+    // that falls out of the range of 2xx
+    const data = error.response.data as { code?: string; message?: string; details?: string };
+
+    return {
+      code: data?.code ?? `HTTP_${error.response.status}`,
+      message: data?.message ?? error.message,
+      details: data?.details ?? JSON.stringify(data),
+      requestId,
+      statusCode: error.response.status,
+      originalError: error,
+    };
+  } else if (error.request != null) {
+    // The request was made but no response was received
+    return {
+      code: 'NO_RESPONSE',
+      message: 'No response received from TeamCity server',
+      details: error.message,
+      requestId,
+      originalError: error,
+    };
+  } else {
+    // Something happened in setting up the request that triggered an Error
+    return {
+      code: 'REQUEST_SETUP_ERROR',
+      message: 'Error setting up the request',
+      details: error.message,
+      requestId,
+      originalError: error,
+    };
+  }
+}
+
+/**
+ * Log response with request ID
+ */
+export function logResponse(response: AxiosResponse): AxiosResponse {
+  const requestId = (response.config as AxiosRequestConfig & { requestId?: string })?.requestId;
+  const meta = (response.config as unknown as { _tcMeta?: { start: number } })._tcMeta;
+  // Prefer server-provided response time header when available
+  const headers = response.headers as Record<string, string | undefined> | undefined;
+  const headerDuration = headers?.['x-response-time'] ?? headers?.['x-response-duration'];
+  const duration = headerDuration ?? (meta?.start ? Date.now() - meta.start : undefined);
+
+  info('TeamCity API request completed', {
+    requestId,
+    method: response.config.method?.toUpperCase(),
+    url: response.config.url,
+    status: response.status,
+    duration,
+  });
+
+  return response;
+}
+
+/**
+ * Log error with request ID and transform
+ */
+export function logAndTransformError(error: AxiosError): Promise<never> {
+  const teamcityError = extractErrorDetails(error);
+  const meta = (error.config as unknown as { _tcMeta?: { start: number } })?._tcMeta;
+  const duration = meta?.start ? Date.now() - meta.start : undefined;
+
+  // Basic redaction/sanitization for logs
+  const sanitize = (val: unknown): unknown => {
+    const redact = (s: string) =>
+      s
+        .replace(/(token[=:\s]*)[^\s&]+/gi, '$1***')
+        .replace(/(password[=:\s]*)[^\s&]+/gi, '$1***')
+        .replace(/(apikey[=:\s]*)[^\s&]+/gi, '$1***')
+        .replace(/(authorization[=:\s:]*)[^\s&]+/gi, '$1***');
+    if (typeof val === 'string') return redact(val);
+    try {
+      const s = JSON.stringify(val);
+      return redact(s);
+    } catch {
+      return val;
+    }
+  };
+
+  logError('TeamCity API request failed', undefined, {
+    requestId: teamcityError.requestId,
+    code: teamcityError.code,
+    message: sanitize(teamcityError.message) as string,
+    statusCode: teamcityError.statusCode,
+    details: sanitize(teamcityError.details),
+    duration,
+  });
+
+  return Promise.reject(teamcityError);
+}
+
+/**
+ * Validate TeamCity token format
+ */
+export function validateToken(token: string): boolean {
+  // TeamCity tokens are typically:
+  // - Personal access tokens: alphanumeric strings
+  // - Basic auth: base64 encoded username:password
+
+  if (!token || token.length === 0) {
+    return false;
+  }
+
+  // Check if it's a valid token format (alphanumeric with possible special chars)
+  // TeamCity tokens can be JWT-style (with dots) or basic alphanumeric
+  const tokenPattern = /^[A-Za-z0-9+/=_\-.:]+$/;
+  return tokenPattern.test(token);
+}
+
+/**
+ * Validate TeamCity server URL
+ */
+export function validateServerUrl(url: string): boolean {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Pre-flight validation for TeamCity configuration
+ */
+export interface ValidationResult {
+  isValid: boolean;
+  errors: string[];
+}
+
+export function validateConfiguration(baseUrl: string, token: string): ValidationResult {
+  const errors: string[] = [];
+
+  if (!validateServerUrl(baseUrl)) {
+    errors.push('Invalid TeamCity server URL');
+  }
+
+  if (!validateToken(token)) {
+    errors.push('Invalid TeamCity authentication token');
+  }
+
+  return {
+    isValid: errors.length === 0,
+    errors,
+  };
+}