IAzureDevOpsService.cs

using Viamus.Azure.Devops.Mcp.Server.Models;

namespace Viamus.Azure.Devops.Mcp.Server.Services;

/// <summary>
/// Interface for Azure DevOps operations.
/// </summary>
public interface IAzureDevOpsService
{
    /// <summary>
    /// Gets a work item by its ID.
    /// </summary>
    /// <param name="workItemId">The work item ID.</param>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The work item details.</returns>
    Task<WorkItemDto?> GetWorkItemAsync(int workItemId, string? project = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets multiple work items by their IDs.
    /// </summary>
    /// <param name="workItemIds">The work item IDs.</param>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>List of work items.</returns>
    Task<IReadOnlyList<WorkItemDto>> GetWorkItemsAsync(IEnumerable<int> workItemIds, string? project = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// Queries work items using WIQL (Work Item Query Language).
    /// </summary>
    /// <param name="wiqlQuery">The WIQL query string.</param>
    /// <param name="project">The project name (optional).</param>
    /// <param name="top">Maximum number of results to return.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>List of work items matching the query.</returns>
    Task<IReadOnlyList<WorkItemDto>> QueryWorkItemsAsync(string wiqlQuery, string? project = null, int top = 200, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets child work items of a parent work item.
    /// </summary>
    /// <param name="parentWorkItemId">The parent work item ID.</param>
    /// <param name="project">The project name (optional).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>List of child work items.</returns>
    Task<IReadOnlyList<WorkItemDto>> GetChildWorkItemsAsync(int parentWorkItemId, string? project = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// Queries work items using WIQL and returns paginated summary results.
    /// This is optimized for large result sets with reduced payload size.
    /// </summary>
    /// <param name="wiqlQuery">The WIQL query string.</param>
    /// <param name="project">The project name (optional).</param>
    /// <param name="page">Page number (1-based).</param>
    /// <param name="pageSize">Number of items per page.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Paginated list of work item summaries.</returns>
    Task<PaginatedResult<WorkItemSummaryDto>> QueryWorkItemsSummaryAsync(
        string wiqlQuery,
        string? project = null,
        int page = 1,
        int pageSize = 20,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Adds a comment to a work item.
    /// </summary>
    /// <param name="workItemId">The work item ID.</param>
    /// <param name="comment">The comment text.</param>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The created comment details.</returns>
    Task<WorkItemCommentDto> AddWorkItemCommentAsync(
        int workItemId,
        string comment,
        string? project = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the comments for a work item, pageable.
    /// </summary>
    /// <param name="workItemId">The work item ID.</param>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="top">Maximum number of comments to return per page.</param>
    /// <param name="continuationToken">Continuation token from a prior call to fetch the next page.</param>
    /// <param name="includeDeleted">Whether to include deleted comments.</param>
    /// <param name="order">Sort order: "asc" (oldest first) or "desc" (newest first).</param>
    /// <param name="includeRenderedText">If true, expand comments to include rendered HTML text.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A page of work item comments with pagination metadata.</returns>
    Task<WorkItemCommentsResultDto> GetWorkItemCommentsAsync(
        int workItemId,
        string? project = null,
        int? top = null,
        string? continuationToken = null,
        bool includeDeleted = false,
        string? order = null,
        bool includeRenderedText = false,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the attachments linked to a work item.
    /// </summary>
    /// <param name="workItemId">The work item ID.</param>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>List of attachments (filename, size, URL, timestamps).</returns>
    Task<IReadOnlyList<WorkItemAttachmentDto>> GetWorkItemAttachmentsAsync(
        int workItemId,
        string? project = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Downloads the content of a work item attachment by its ID and returns it inline.
    /// </summary>
    /// <param name="attachmentId">The attachment GUID (from <see cref="GetWorkItemAttachmentsAsync"/>).</param>
    /// <param name="fileName">Optional filename, used in the response.</param>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="maxBytes">Maximum bytes to download (default 10 MB). Larger attachments throw.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Attachment content as UTF-8 text or base64 bytes.</returns>
    Task<WorkItemAttachmentContentDto?> GetWorkItemAttachmentContentAsync(
        Guid attachmentId,
        string? fileName = null,
        string? project = null,
        long maxBytes = 10 * 1024 * 1024,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Creates a new work item in the specified project.
    /// </summary>
    /// <param name="project">The project name.</param>
    /// <param name="workItemType">The work item type (e.g., Bug, Task, User Story).</param>
    /// <param name="title">The work item title.</param>
    /// <param name="description">Optional description.</param>
    /// <param name="assignedTo">Optional user to assign to.</param>
    /// <param name="areaPath">Optional area path.</param>
    /// <param name="iterationPath">Optional iteration path.</param>
    /// <param name="state">Optional initial state.</param>
    /// <param name="priority">Optional priority (1-4).</param>
    /// <param name="parentId">Optional parent work item ID to link as child.</param>
    /// <param name="tags">Optional semicolon-separated tags.</param>
    /// <param name="additionalFields">Optional dictionary of additional field reference names and values.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The created work item.</returns>
    Task<WorkItemDto> CreateWorkItemAsync(
        string project,
        string workItemType,
        string title,
        string? description = null,
        string? assignedTo = null,
        string? areaPath = null,
        string? iterationPath = null,
        string? state = null,
        int? priority = null,
        int? parentId = null,
        string? tags = null,
        Dictionary<string, string>? additionalFields = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Updates an existing work item.
    /// </summary>
    /// <param name="workItemId">The work item ID to update.</param>
    /// <param name="title">Optional new title.</param>
    /// <param name="description">Optional new description.</param>
    /// <param name="assignedTo">Optional new assignee.</param>
    /// <param name="state">Optional new state.</param>
    /// <param name="areaPath">Optional new area path.</param>
    /// <param name="iterationPath">Optional new iteration path.</param>
    /// <param name="priority">Optional new priority (1-4).</param>
    /// <param name="tags">Optional new tags.</param>
    /// <param name="additionalFields">Optional dictionary of additional field reference names and values.</param>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The updated work item.</returns>
    Task<WorkItemDto> UpdateWorkItemAsync(
        int workItemId,
        string? title = null,
        string? description = null,
        string? assignedTo = null,
        string? state = null,
        string? areaPath = null,
        string? iterationPath = null,
        int? priority = null,
        string? tags = null,
        Dictionary<string, string>? additionalFields = null,
        string? project = null,
        CancellationToken cancellationToken = default);

    #region Git Operations

    /// <summary>
    /// Gets all repositories in a project.
    /// </summary>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>List of repositories.</returns>
    Task<IReadOnlyList<RepositoryDto>> GetRepositoriesAsync(string? project = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets a specific repository by name or ID.
    /// </summary>
    /// <param name="repositoryNameOrId">The repository name or ID.</param>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The repository details.</returns>
    Task<RepositoryDto?> GetRepositoryAsync(string repositoryNameOrId, string? project = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets all branches in a repository.
    /// </summary>
    /// <param name="repositoryNameOrId">The repository name or ID.</param>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>List of branches.</returns>
    Task<IReadOnlyList<BranchDto>> GetBranchesAsync(string repositoryNameOrId, string? project = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets items (files and folders) at a specific path in a repository.
    /// </summary>
    /// <param name="repositoryNameOrId">The repository name or ID.</param>
    /// <param name="path">The path to browse (default is root "/").</param>
    /// <param name="branchName">The branch name (optional, uses default branch if not specified).</param>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="recursionLevel">How deep to recurse (None, OneLevel, Full). Default is OneLevel.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>List of git items.</returns>
    Task<IReadOnlyList<GitItemDto>> GetItemsAsync(
        string repositoryNameOrId,
        string path = "/",
        string? branchName = null,
        string? project = null,
        string recursionLevel = "OneLevel",
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the content of a specific file in a repository.
    /// </summary>
    /// <param name="repositoryNameOrId">The repository name or ID.</param>
    /// <param name="filePath">The path to the file.</param>
    /// <param name="branchName">The branch name (optional, uses default branch if not specified).</param>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The file content.</returns>
    Task<GitFileContentDto?> GetFileContentAsync(
        string repositoryNameOrId,
        string filePath,
        string? branchName = null,
        string? project = null,
        CancellationToken cancellationToken = default);

    #endregion

    #region Pull Request Operations

    /// <summary>
    /// Gets pull requests for a repository with optional filters.
    /// </summary>
    /// <param name="repositoryNameOrId">The repository name or ID.</param>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="status">Filter by status: active, completed, abandoned, or all.</param>
    /// <param name="creatorId">Filter by creator's unique name or ID.</param>
    /// <param name="reviewerId">Filter by reviewer's unique name or ID.</param>
    /// <param name="sourceRefName">Filter by source branch (e.g., refs/heads/feature).</param>
    /// <param name="targetRefName">Filter by target branch (e.g., refs/heads/main).</param>
    /// <param name="top">Maximum number of results to return.</param>
    /// <param name="skip">Number of results to skip for pagination.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>List of pull requests matching the filters.</returns>
    Task<IReadOnlyList<PullRequestDto>> GetPullRequestsAsync(
        string repositoryNameOrId,
        string? project = null,
        string? status = null,
        string? creatorId = null,
        string? reviewerId = null,
        string? sourceRefName = null,
        string? targetRefName = null,
        int top = 50,
        int skip = 0,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets a specific pull request by ID within a repository.
    /// </summary>
    /// <param name="repositoryNameOrId">The repository name or ID.</param>
    /// <param name="pullRequestId">The pull request ID.</param>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The pull request details.</returns>
    Task<PullRequestDto?> GetPullRequestByIdAsync(
        string repositoryNameOrId,
        int pullRequestId,
        string? project = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets a specific pull request by ID only (project-level lookup, no repository required).
    /// </summary>
    /// <param name="pullRequestId">The pull request ID.</param>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The pull request details.</returns>
    Task<PullRequestDto?> GetPullRequestByIdOnlyAsync(
        int pullRequestId,
        string? project = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets comment threads for a pull request.
    /// </summary>
    /// <param name="repositoryNameOrId">The repository name or ID.</param>
    /// <param name="pullRequestId">The pull request ID.</param>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>List of comment threads.</returns>
    Task<IReadOnlyList<PullRequestThreadDto>> GetPullRequestThreadsAsync(
        string repositoryNameOrId,
        int pullRequestId,
        string? project = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Creates a new comment thread on a pull request.
    /// </summary>
    /// <param name="repositoryNameOrId">The repository name or ID.</param>
    /// <param name="pullRequestId">The pull request ID.</param>
    /// <param name="content">The initial comment text (Markdown supported).</param>
    /// <param name="filePath">Optional file path for an inline thread.</param>
    /// <param name="lineNumber">Optional line number for an inline thread.</param>
    /// <param name="endLineNumber">Optional ending line number for an inline thread range.</param>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The created comment thread.</returns>
    Task<PullRequestThreadDto> CreatePullRequestThreadAsync(
        string repositoryNameOrId,
        int pullRequestId,
        string content,
        string? filePath = null,
        int? lineNumber = null,
        int? endLineNumber = null,
        string? project = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Adds a comment to an existing comment thread on a pull request.
    /// </summary>
    /// <param name="repositoryNameOrId">The repository name or ID.</param>
    /// <param name="pullRequestId">The pull request ID.</param>
    /// <param name="threadId">The thread ID to comment on.</param>
    /// <param name="content">The comment text (Markdown supported).</param>
    /// <param name="parentCommentId">Optional parent comment ID when replying to a specific comment.</param>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The created comment.</returns>
    Task<PullRequestCommentDto> AddPullRequestThreadCommentAsync(
        string repositoryNameOrId,
        int pullRequestId,
        int threadId,
        string content,
        int? parentCommentId = null,
        string? project = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Searches pull requests by title or description.
    /// </summary>
    /// <param name="repositoryNameOrId">The repository name or ID.</param>
    /// <param name="searchText">Text to search for in title or description.</param>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="status">Filter by status: active, completed, abandoned, or all.</param>
    /// <param name="top">Maximum number of results to return.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>List of matching pull requests.</returns>
    Task<IReadOnlyList<PullRequestDto>> SearchPullRequestsAsync(
        string repositoryNameOrId,
        string searchText,
        string? project = null,
        string? status = null,
        int top = 50,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Creates a new pull request in the specified repository.
    /// </summary>
    /// <param name="repositoryNameOrId">The repository name or ID.</param>
    /// <param name="sourceRefName">The source branch (e.g., refs/heads/feature-branch).</param>
    /// <param name="targetRefName">The target branch (e.g., refs/heads/main).</param>
    /// <param name="title">The pull request title.</param>
    /// <param name="description">Optional pull request description.</param>
    /// <param name="isDraft">Whether to create the PR as a draft.</param>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="reviewerIds">Optional reviewer GUIDs.</param>
    /// <param name="workItemIds">Optional work item IDs to link.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The created pull request.</returns>
    Task<PullRequestDto> CreatePullRequestAsync(
        string repositoryNameOrId,
        string sourceRefName,
        string targetRefName,
        string title,
        string? description = null,
        bool isDraft = false,
        string? project = null,
        IEnumerable<string>? reviewerIds = null,
        IEnumerable<int>? workItemIds = null,
        CancellationToken cancellationToken = default);

    #endregion

    #region Pipeline/Build Operations

    /// <summary>
    /// Gets all pipelines (build definitions) in a project.
    /// </summary>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="name">Optional filter by pipeline name (supports wildcards).</param>
    /// <param name="folder">Optional filter by folder path.</param>
    /// <param name="top">Maximum number of results to return.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>List of pipelines.</returns>
    Task<IReadOnlyList<PipelineDto>> GetPipelinesAsync(
        string? project = null,
        string? name = null,
        string? folder = null,
        int top = 100,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets a specific pipeline by ID.
    /// </summary>
    /// <param name="pipelineId">The pipeline ID.</param>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The pipeline details.</returns>
    Task<PipelineDto?> GetPipelineAsync(
        int pipelineId,
        string? project = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets builds for a project with optional filters.
    /// </summary>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="definitions">Optional list of pipeline definition IDs to filter by.</param>
    /// <param name="branchName">Optional filter by source branch.</param>
    /// <param name="statusFilter">Optional filter by status: all, inProgress, completed, cancelling, postponed, notStarted, none.</param>
    /// <param name="resultFilter">Optional filter by result: succeeded, partiallySucceeded, failed, canceled, none.</param>
    /// <param name="requestedFor">Optional filter by who requested the build.</param>
    /// <param name="top">Maximum number of results to return.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>List of builds.</returns>
    Task<IReadOnlyList<BuildDto>> GetBuildsAsync(
        string? project = null,
        IEnumerable<int>? definitions = null,
        string? branchName = null,
        string? statusFilter = null,
        string? resultFilter = null,
        string? requestedFor = null,
        int top = 50,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets a specific build by ID.
    /// </summary>
    /// <param name="buildId">The build ID.</param>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The build details.</returns>
    Task<BuildDto?> GetBuildAsync(
        int buildId,
        string? project = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the logs for a build.
    /// </summary>
    /// <param name="buildId">The build ID.</param>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>List of build logs.</returns>
    Task<IReadOnlyList<BuildLogDto>> GetBuildLogsAsync(
        int buildId,
        string? project = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the content of a specific build log.
    /// </summary>
    /// <param name="buildId">The build ID.</param>
    /// <param name="logId">The log ID.</param>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The log content as a string.</returns>
    Task<string?> GetBuildLogContentAsync(
        int buildId,
        int logId,
        string? project = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the timeline (stages, jobs, tasks) for a build.
    /// </summary>
    /// <param name="buildId">The build ID.</param>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>List of timeline records.</returns>
    Task<IReadOnlyList<BuildTimelineRecordDto>> GetBuildTimelineAsync(
        int buildId,
        string? project = null,
        CancellationToken cancellationToken = default);

    #endregion

    #region Wiki Operations

    /// <summary>
    /// Gets all wikis in a project.
    /// </summary>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>List of wikis.</returns>
    Task<IReadOnlyList<WikiDto>> GetWikisAsync(string? project = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets a specific wiki by its identifier (name or ID).
    /// </summary>
    /// <param name="wikiIdentifier">The wiki name or ID.</param>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The wiki details.</returns>
    Task<WikiDto?> GetWikiAsync(string wikiIdentifier, string? project = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets a wiki page by path, including its content.
    /// </summary>
    /// <param name="wikiIdentifier">The wiki name or ID.</param>
    /// <param name="path">The page path (e.g., "/Home", "/Getting-Started/Installation").</param>
    /// <param name="includeContent">Whether to include the page content (Markdown).</param>
    /// <param name="version">Optional version/branch of the wiki.</param>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The wiki page details.</returns>
    Task<WikiPageDto?> GetWikiPageAsync(
        string wikiIdentifier,
        string path,
        bool includeContent = true,
        string? version = null,
        string? project = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the sub-pages of a wiki page (page tree).
    /// </summary>
    /// <param name="wikiIdentifier">The wiki name or ID.</param>
    /// <param name="path">The parent page path (default is root "/").</param>
    /// <param name="recursionLevel">How deep to recurse: "OneLevel" or "Full".</param>
    /// <param name="project">The project name (optional if default project is configured).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The wiki page with its sub-pages.</returns>
    Task<WikiPageDto?> GetWikiPageTreeAsync(
        string wikiIdentifier,
        string path = "/",
        string recursionLevel = "OneLevel",
        string? project = null,
        CancellationToken cancellationToken = default);

    #endregion
}