@daghis/teamcity-mcp 0.1.2

package/src/teamcity/project-navigator.ts

@@ -0,0 +1,664 @@
+/**
+ * ProjectNavigator - Advanced project discovery and navigation for TeamCity
+ */
+import { TeamCityAPI } from '@/api-client';
+import type { Project } from '@/teamcity-client/models/project';
+import { warn } from '@/utils/logger';
+
+export interface ProjectNavigatorParams {
+  mode?: 'list' | 'hierarchy' | 'ancestors' | 'descendants';
+  projectId?: string;
+  rootProjectId?: string;
+  filters?: {
+    namePattern?: string;
+    archived?: boolean;
+    hasBuilds?: boolean;
+    parentProjectId?: string;
+    maxDepth?: number;
+  };
+  pagination?: {
+    page?: number;
+    pageSize?: number;
+  };
+  sort?: {
+    by?: 'name' | 'id' | 'level';
+    order?: 'asc' | 'desc';
+  };
+  includeStatistics?: boolean;
+  maxDepth?: number;
+}
+
+export interface ProjectNavigatorResult {
+  success: boolean;
+  data?: {
+    mode: string;
+    projects?: Array<{
+      id: string;
+      name: string;
+      description?: string;
+      parentProjectId?: string;
+      parentProjectName?: string;
+      archived: boolean;
+      level: number;
+      href?: string;
+      webUrl?: string;
+      statistics?: {
+        buildConfigurationCount?: number;
+        vcsRootCount?: number;
+        subprojectCount?: number;
+        lastActivity?: string;
+      };
+    }>;
+    hierarchy?: HierarchyNode;
+    ancestors?: Array<ProjectInfo>;
+    descendants?: Array<ProjectInfo>;
+    totalCount?: number;
+    page?: number;
+    pageSize?: number;
+    hasMore?: boolean;
+    maxDepthReached?: boolean;
+    executionTime?: number;
+    cached?: boolean;
+  };
+  error?: string;
+}
+
+interface HierarchyNode {
+  id: string;
+  name: string;
+  description?: string;
+  archived: boolean;
+  children?: HierarchyNode[];
+  statistics?: ProjectStatistics;
+}
+
+interface ProjectInfo {
+  id: string;
+  name: string;
+  description?: string;
+  archived?: boolean;
+  level?: number;
+  parentProjectId?: string;
+}
+
+interface ProjectStatistics {
+  buildConfigurationCount?: number;
+  vcsRootCount?: number;
+  subprojectCount?: number;
+  lastActivity?: string;
+}
+
+interface CacheEntry {
+  data: ProjectNavigatorResult['data'];
+  timestamp: number;
+}
+
+type NavigatorResult = Partial<ProjectNavigatorResult['data']>;
+
+interface HierarchyNodeInternal {
+  project: {
+    id: string;
+    name: string;
+    description?: string;
+    archived: boolean;
+    buildTypesCount?: number;
+    subprojectsCount?: number;
+  };
+  children: HierarchyNodeInternal[];
+}
+
+export class ProjectNavigator {
+  private api: TeamCityAPI;
+  private cache: Map<string, CacheEntry>;
+  private readonly cacheTtl = 120000; // 120 seconds
+
+  constructor() {
+    this.api = TeamCityAPI.getInstance();
+    this.cache = new Map();
+  }
+
+  async listProjects(params: ProjectNavigatorParams = {}): Promise<ProjectNavigatorResult> {
+    const startTime = Date.now();
+    const mode = params.mode ?? 'list';
+
+    try {
+      // Validate parameters
+      const validationError = this.validateParams(params);
+      if (validationError) {
+        return { success: false, error: validationError };
+      }
+
+      // Check cache
+      const cacheKey = this.getCacheKey(params);
+      const cachedResult = this.getCachedResult(cacheKey);
+      if (cachedResult != null) {
+        return {
+          success: true,
+          data: {
+            mode: cachedResult.mode ?? 'list',
+            ...cachedResult,
+            cached: true,
+            executionTime: Date.now() - startTime,
+          } as ProjectNavigatorResult['data'],
+        };
+      }
+
+      let result: NavigatorResult;
+
+      switch (mode) {
+        case 'hierarchy':
+          result = await this.getHierarchy(params);
+          break;
+        case 'ancestors':
+          result = await this.getAncestors(params);
+          break;
+        case 'descendants':
+          result = await this.getDescendants(params);
+          break;
+        case 'list':
+        default:
+          result = await this.getList(params);
+          break;
+      }
+
+      if (!result) {
+        throw new Error('Failed to compute project navigation result');
+      }
+      result.mode = mode;
+      result.cached = false;
+      result.executionTime = Date.now() - startTime;
+
+      // Cache the result
+      this.setCachedResult(cacheKey, result);
+
+      return {
+        success: true,
+        data: { mode: mode || 'list', ...result } as ProjectNavigatorResult['data'],
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: this.formatError(error),
+      };
+    }
+  }
+
+  private async getList(params: ProjectNavigatorParams): Promise<NavigatorResult> {
+    // Build locator string for API filtering
+    const locatorParts: string[] = [];
+
+    if (params.filters?.namePattern) {
+      locatorParts.push(`name:${params.filters.namePattern}`);
+    }
+
+    if (params.filters?.archived !== undefined) {
+      locatorParts.push(`archived:${params.filters.archived}`);
+    }
+
+    if (params.filters?.parentProjectId) {
+      locatorParts.push(`parentProject:(id:${params.filters.parentProjectId})`);
+    }
+
+    // Add pagination to locator
+    if (params.pagination) {
+      const page = params.pagination.page ?? 1;
+      const pageSize = params.pagination.pageSize ?? 100;
+      const start = (page - 1) * pageSize;
+
+      locatorParts.push(`count:${pageSize}`);
+      if (start > 0) {
+        locatorParts.push(`start:${start}`);
+      }
+    }
+
+    const locator = locatorParts.length > 0 ? locatorParts.join(',') : undefined;
+    const fields = params.includeStatistics
+      ? '$long,buildTypes(count),subprojects(count)'
+      : '$long';
+
+    // Use the projects API to list all projects
+    const response = await this.api.projects.getAllProjects(locator, fields);
+
+    // Get projects from response
+    let projects = response.data.project ?? [];
+
+    // Apply sorting if requested
+    if (params.sort?.by) {
+      projects = this.sortProjects(projects, params.sort.by, params.sort.order ?? 'asc');
+    }
+
+    // Don't apply client-side pagination if we already did server-side
+    const page = params.pagination?.page ?? 1;
+    const pageSize = params.pagination?.pageSize ?? 100;
+    const paginatedProjects = projects; // Already paginated by API
+
+    return {
+      projects: paginatedProjects.map((p: Project) => ({
+        id: p.id ?? '',
+        name: p.name ?? '',
+        description: p.description,
+        parentProjectId: p.parentProjectId,
+        archived: p.archived ?? false,
+        level: 0, // Would need to calculate based on hierarchy
+        href: p.href,
+        webUrl: p.webUrl,
+        statistics: params.includeStatistics
+          ? {
+              buildConfigurationCount: p.buildTypes?.count,
+              subprojectCount: p.projects?.count,
+              vcsRootCount: p.vcsRoots?.count,
+            }
+          : undefined,
+      })),
+      totalCount: response.data.count ?? projects.length,
+      page,
+      pageSize,
+      hasMore: paginatedProjects.length === pageSize,
+    };
+  }
+
+  private async getHierarchy(params: ProjectNavigatorParams): Promise<NavigatorResult> {
+    const rootId = params.rootProjectId ?? '_Root';
+    const maxDepth = params.maxDepth ?? 5;
+
+    // Recursive function to build hierarchy
+    const buildHierarchy = async (
+      projectId: string,
+      currentDepth = 0,
+      visited = new Set<string>()
+    ): Promise<HierarchyNodeInternal> => {
+      // Prevent circular references
+      if (visited.has(projectId)) {
+        return {
+          project: {
+            id: projectId,
+            name: `[Circular Reference: ${projectId}]`,
+            description: 'Circular reference detected',
+            archived: false,
+            buildTypesCount: 0,
+            subprojectsCount: 0,
+          },
+          children: [],
+        };
+      }
+
+      visited.add(projectId);
+
+      try {
+        const response = await this.api.projects.getProject(projectId);
+        const project = response.data;
+
+        const node = {
+          project: {
+            id: project.id ?? projectId,
+            name: project.name ?? `Unknown Project ${projectId}`,
+            description: project.description,
+            archived: project.archived ?? false,
+            buildTypesCount: project.buildTypes?.count ?? 0,
+            subprojectsCount: project.projects?.count ?? 0,
+          },
+          children: [] as HierarchyNodeInternal[],
+        };
+
+        // Load children if not at max depth and has children
+        if (currentDepth < maxDepth && project.projects?.project?.length) {
+          const childVisited = new Set(visited);
+          for (const child of project.projects.project) {
+            if (child.id && !visited.has(child.id)) {
+              // Sequential recursion to avoid uncontrolled concurrency and maintain order
+              // eslint-disable-next-line no-await-in-loop
+              const childNode = await buildHierarchy(child.id, currentDepth + 1, childVisited);
+              node.children.push(childNode);
+            }
+          }
+        }
+
+        return node;
+      } catch (error) {
+        // Handle non-existent or inaccessible projects
+        return {
+          project: {
+            id: projectId,
+            name: `[Error: ${projectId}]`,
+            description: 'Project not accessible or does not exist',
+            archived: false,
+            buildTypesCount: 0,
+            subprojectsCount: 0,
+          },
+          children: [],
+        };
+      }
+    };
+
+    const hierarchyNode = await buildHierarchy(rootId, 0);
+    const hierarchy = this.transformHierarchyNode(hierarchyNode);
+
+    return {
+      hierarchy,
+      maxDepthReached: params.maxDepth
+        ? this.checkMaxDepthReached(hierarchyNode, params.maxDepth)
+        : false,
+    };
+  }
+
+  private async getAncestors(params: ProjectNavigatorParams): Promise<NavigatorResult> {
+    if (!params.projectId) {
+      throw new Error('projectId is required for ancestors mode');
+    }
+
+    const ancestors: ProjectInfo[] = [];
+    let currentProjectId = params.projectId;
+    const visited = new Set<string>();
+
+    // First verify the target project exists and save it
+    let targetProject: Project;
+    try {
+      const targetResponse = await this.api.projects.getProject(currentProjectId);
+      if (targetResponse.data == null) {
+        throw new Error(`Project not found: ${params.projectId}`);
+      }
+      targetProject = targetResponse.data;
+      currentProjectId = targetResponse.data.parentProjectId ?? '_Root';
+    } catch (error) {
+      throw new Error(`Project not found: ${params.projectId}`);
+    }
+
+    // Always add root project first
+    ancestors.push({
+      id: '_Root',
+      name: '<Root project>',
+      description: 'Root project',
+      archived: false,
+      level: 0,
+      parentProjectId: undefined,
+    });
+
+    // Walk up the parent chain (excluding root since we already added it)
+    while (currentProjectId && currentProjectId !== '_Root' && !visited.has(currentProjectId)) {
+      visited.add(currentProjectId);
+
+      try {
+        // Sequential parent traversal up the chain
+        // eslint-disable-next-line no-await-in-loop
+        const response = await this.api.projects.getProject(currentProjectId);
+        const project = response.data;
+
+        if (project != null) {
+          ancestors.push({
+            id: project.id ?? currentProjectId,
+            name: project.name ?? `Unknown Project ${currentProjectId}`,
+            description: project.description,
+            archived: project.archived ?? false,
+            level: ancestors.length,
+            parentProjectId: project.parentProjectId,
+          });
+
+          currentProjectId = project.parentProjectId ?? '_Root';
+        } else {
+          break;
+        }
+      } catch (error) {
+        // Stop if we can't find a parent
+        break;
+      }
+    }
+
+    // Add the target project itself at the end
+    ancestors.push({
+      id: targetProject.id ?? params.projectId,
+      name: targetProject.name ?? `Unknown Project ${params.projectId}`,
+      description: targetProject.description,
+      archived: targetProject.archived ?? false,
+      level: ancestors.length,
+      parentProjectId: targetProject.parentProjectId,
+    });
+
+    return { ancestors };
+  }
+
+  private async getDescendants(params: ProjectNavigatorParams): Promise<NavigatorResult> {
+    if (!params.projectId) {
+      throw new Error('projectId is required for descendants mode');
+    }
+
+    const maxDepth = params.maxDepth ?? 5;
+    const descendants: ProjectInfo[] = [];
+    const visited = new Set<string>();
+
+    // First verify the target project exists
+    try {
+      const targetResponse = await this.api.projects.getProject(params.projectId);
+      if (targetResponse.data == null) {
+        throw new Error(`Project not found: ${params.projectId}`);
+      }
+    } catch (error) {
+      throw new Error(`Project not found: ${params.projectId}`);
+    }
+
+    // Recursive function to collect all descendants
+    const collectDescendants = async (
+      projectId: string,
+      currentDepth = 0,
+      parentLevel = 0
+    ): Promise<void> => {
+      if (currentDepth >= maxDepth || visited.has(projectId)) {
+        return;
+      }
+
+      visited.add(projectId);
+
+      try {
+        const response = await this.api.projects.getProject(projectId);
+        const project = response.data;
+
+        if (project?.projects?.project?.length) {
+          for (const child of project.projects.project) {
+            if (child.id && !visited.has(child.id)) {
+              try {
+                // Get full child project details
+                // eslint-disable-next-line no-await-in-loop
+                const childResponse = await this.api.projects.getProject(child.id);
+                const childProject = childResponse.data;
+
+                if (childProject != null) {
+                  descendants.push({
+                    id: childProject.id ?? child.id,
+                    name: childProject.name ?? child.name ?? `Unknown Project ${child.id}`,
+                    description: childProject.description,
+                    archived: childProject.archived ?? false,
+                    level: parentLevel + 1,
+                    parentProjectId: projectId,
+                  });
+
+                  // Recursively collect children of this child
+                  // eslint-disable-next-line no-await-in-loop
+                  await collectDescendants(child.id, currentDepth + 1, parentLevel + 1);
+                }
+              } catch (childError) {
+                // Skip children we can't access, but don't stop the whole operation
+                warn(`Could not access child project ${child.id}:`, { error: childError });
+              }
+            }
+          }
+        }
+      } catch (error) {
+        // Skip projects we can't access
+        warn(`Could not access project ${projectId}:`, { error });
+      }
+    };
+
+    await collectDescendants(params.projectId, 0, 0);
+
+    return {
+      descendants,
+      maxDepthReached: maxDepth > 0 && descendants.some((p) => p.level === maxDepth),
+    };
+  }
+
+  /**
+   * Transform domain hierarchy node to navigator format
+   */
+  private transformHierarchyNode(node: HierarchyNodeInternal): HierarchyNode {
+    const transformed: HierarchyNode = {
+      id: node.project.id,
+      name: node.project.name,
+      description: node.project.description,
+      archived: node.project.archived,
+      children: [], // Always include children array
+    };
+
+    if (node.project.buildTypesCount ?? node.project.subprojectsCount) {
+      transformed.statistics = {
+        buildConfigurationCount: node.project.buildTypesCount,
+        subprojectCount: node.project.subprojectsCount,
+      };
+    }
+
+    // Add children if they exist
+    if (node.children != null && node.children.length > 0) {
+      transformed.children = node.children.map((child) => this.transformHierarchyNode(child));
+    }
+
+    return transformed;
+  }
+
+  /**
+   * Transform domain project to project info format
+   */
+  private transformToProjectInfo(project: Project & { level?: number }): ProjectInfo {
+    return {
+      id: project.id ?? '',
+      name: project.name ?? '',
+      description: project.description,
+      archived: project.archived,
+      level: project.level,
+      parentProjectId: project.parentProjectId,
+    };
+  }
+
+  /**
+   * Check if max depth was reached in hierarchy
+   */
+  private checkMaxDepthReached(
+    node: HierarchyNodeInternal,
+    maxDepth: number,
+    currentDepth = 0
+  ): boolean {
+    if (currentDepth >= maxDepth) {
+      return true;
+    }
+    if (node.children != null && node.children.length > 0) {
+      return node.children.some((child) =>
+        this.checkMaxDepthReached(child, maxDepth, currentDepth + 1)
+      );
+    }
+    return false;
+  }
+
+  private validateParams(params: ProjectNavigatorParams): string | null {
+    if (params.pagination) {
+      if (params.pagination.page && params.pagination.page < 1) {
+        return 'Invalid pagination: page must be >= 1';
+      }
+      if (params.pagination.pageSize) {
+        if (params.pagination.pageSize < 1 || params.pagination.pageSize > 1000) {
+          return 'Invalid pagination: pageSize must be between 1 and 1000';
+        }
+      }
+    }
+
+    if (params.mode === 'ancestors' && !params.projectId) {
+      return 'projectId is required for ancestors mode';
+    }
+
+    if (params.mode === 'descendants' && !params.projectId) {
+      return 'projectId is required for descendants mode';
+    }
+
+    return null;
+  }
+
+  private getCacheKey(params: ProjectNavigatorParams): string {
+    return JSON.stringify(params);
+  }
+
+  private getCachedResult(key: string): NavigatorResult | null {
+    const entry = this.cache.get(key);
+    if (!entry) {
+      return null;
+    }
+
+    const age = Date.now() - entry.timestamp;
+    if (age > this.cacheTtl) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    return entry.data;
+  }
+
+  private setCachedResult(key: string, data: NavigatorResult): void {
+    this.cache.set(key, {
+      data: data as ProjectNavigatorResult['data'],
+      timestamp: Date.now(),
+    });
+
+    // Clean old entries
+    if (this.cache.size > 100) {
+      const entries = Array.from(this.cache.entries());
+      entries.sort((a, b) => a[1].timestamp - b[1].timestamp);
+      for (let i = 0; i < 50 && i < entries.length; i++) {
+        this.cache.delete(entries[i]?.[0] ?? '');
+      }
+    }
+  }
+
+  private sortProjects<T extends { name?: string; id?: string; level?: number }>(
+    projects: T[],
+    sortBy: string,
+    order: 'asc' | 'desc'
+  ): T[] {
+    const sorted = [...projects];
+
+    sorted.sort((a, b) => {
+      let comparison = 0;
+
+      switch (sortBy) {
+        case 'name':
+          comparison = (a.name ?? '').localeCompare(b.name ?? '');
+          break;
+        case 'id':
+          comparison = (a.id ?? '').localeCompare(b.id ?? '');
+          break;
+        case 'level':
+          comparison = (a.level ?? 0) - (b.level ?? 0);
+          break;
+        default:
+          comparison = 0;
+      }
+
+      return order === 'desc' ? -comparison : comparison;
+    });
+
+    return sorted;
+  }
+
+  private formatError(error: unknown): string {
+    if (typeof error === 'object' && error !== null) {
+      const err = error as { response?: { status?: number }; message?: string };
+      if (err.response?.status === 401) {
+        return 'Authentication failed: Please check your TeamCity token';
+      }
+      if (err.response?.status === 403) {
+        return "Permission denied: You don't have access to these projects";
+      }
+      if (err.response?.status === 404) {
+        return 'Not found: The requested project does not exist';
+      }
+      if (err.message) {
+        return err.message;
+      }
+    }
+    return 'An unexpected error occurred';
+  }
+}